\chapter{The Linux Kernel Sources}
\label{sources-chapter}
\includegraphics{logos/sit3-bw-tran.1.eps}

\ChapterDescription{
This chapter describes where in the Linux kernel sources you should
start looking for particular kernel functions.
}

This book does not depend on a knowledge of the 'C' programming
language or require that you have the Linux kernel sources available in
order to understand how the Linux kernel works.
That said, it is a fruitful exercise to look at the kernel sources
to get an in-depth understanding of the Linux operating system.
This chapter gives an overview of the kernel sources; how
they are arranged and where you might start to look for particular
code.

\section*{Where to Get The Linux Kernel Sources}
All of the major Linux distributions ({\textsf Craftworks}, {\textsf Debian},
\textsf{Slackware}, \textsf{Red Hat} etcetera) include the kernel sources in them.
Usually the Linux kernel that got installed on your Linux system
was built from those sources.
By their very nature these sources tend to be a little out of date so
you may want to get the latest sources from one of the web sites
mentioned in chapter~\ref{www-appendix}.
They are kept on \fn{ftp://ftp.cs.helsinki.fi}
and all of the other web sites shadow them.
This makes the Helsinki web site the most up to date, but sites like
MIT and Sunsite are never very far behind.

If you do not have access to the web, there are many CD ROM vendors who
offer snapshots of the world's major web sites at a very reasonable
cost.  Some even offer a subscription service with quarterly or even
monthly updates.  
Your local Linux User Group is also a good source of sources.

The Linux kernel sources have a very simple numbering system. 
Any even number kernel (for example \texttt{2.0.30}) is a stable, released,
kernel and any odd numbered kernel (for example \texttt{2.1.42} is a 
development kernel.
This book is based on the stable \texttt{2.0.30} source tree.
Development kernels have all of the latest features and support
all of the latest devices. 
Although they can be unstable, which may not be exactly what you want it,
is important that the Linux community tries the latest kernels.
That way they are tested for the whole community.
Remember that it is {\em always} worth backing up your system thoroughly if you do 
try out non-production kernels.

Changes to the kernel sources are distributed as \eg{patch} files.  The \eg{patch}
utility is used to apply a series of edits to a set of source files.  
So, for example, if you have the 2.0.29 kernel source tree and you wanted to move
to the 2.0.30 source tree, you would obtain the 2.0.30 patch file and apply the
patches (edits) to that source tree:
\begin{verbatim}

$ cd /usr/src/linux
$ patch -p1 < patch-2.0.30
\end{verbatim}
This saves copying whole source trees, perhaps over slow serial connections.
A good source of kernel patches (official and unofficial) is 
the \fn{http://www.linuxhq.com} web site.

\section*{How The Kernel Sources Are Arranged}
At the very top level of the source tree \fn{/usr/\-src/\-linux} you will
see a number of directories:
\begin{description}
	\item [arch] The \fn{arch} subdirectory contains all of the 
		architecture specific kernel code.  It has further 
		subdirectories, one per supported architecture, for
		example \fn{i386} and \fn{alpha}.
	\item [include] The \fn{include} subdirectory contains most of
		the include files needed to build the kernel code.  It too
		has further subdirectories including one for every architecture
		supported.  The \fn{include/asm} subdirectory is a 
		soft link to the real include directory needed for this
		architecture, for example \fn{include/\-asm-i386}.
		To change architectures you need to edit the kernel makefile
		and rerun the Linux kernel configuration program.
	\item [init] This directory contains the initialization code
		for the kernel and it is a very good place to start looking
		at how the kernel works.
	\item [mm] This directory contains all of the memory management
		code.  The architecture specific memory management code lives
		down in \fn{arch/\-*/\-mm/}, for example \fn{arch/\-i386/\-mm/\-fault.c}.
	\item [drivers] All of the system's device drivers live in this
		directory.  They are further sub-divided into classes of
		device driver, for example \fn{block}.
	\item [ipc] This directory contains the kernels inter-process 
		communications code.
	\item [modules] This is simply a directory used to hold built
		modules.
	\item [fs] All of the file system code.  This is further sub-divided
		into directories, one per supported file system, for example
		\fn{vfat} and \fn{ext2}.
	\item [kernel] The main kernel code.  Again, the architecture 
		specific kernel code is in \fn{arch/\-*/\-kernel}.
	\item [net] The kernel's networking code.
	\item [lib] This directory contains the kernel's library code.
	The architecture specific library code can be found in 
		\fn{arch/\-*/\-lib/}.
	\item [scripts] This directory contains the 
		scripts (for example \eg{awk} and \eg{tk} scripts) 
		that are used when the kernel is configured.
\end{description}

\section*{Where to Start Looking}
A large complex program like the Linux kernel can be rather daunting
to look at.
It is rather like a large ball of string with no end showing.
Looking at one part of the kernel often leads to looking at several
other related files and before long you have forgotten what you were
looking for.
The next subsections give you a hint as to where in the source tree the
best place to look is for a given subject.

\subsection*{System Startup and Initialization}
On an Intel based system, the kernel starts  when either loadlin.exe
or LILO has loaded the kernel into memory and passed control to it.
Look in \fn{arch/\-i386/\-kernel/\-head.S} for this part.
\fn{Head.S} does some architecture specific setup and then jumps
to the \fn{main()} routine in \fn{init/\-main.c}.

\subsection*{Memory Management}
This code is mostly in \fn{mm} but the architecture specific code is in
\fn{arch/\-*/\-mm}.
The page fault handling code is in \fn{mm/\-memory.c} and the memory mapping and
page cache code is in \fn{mm/\-filemap.c}.
The buffer cache is implemented in \fn{mm/\-buffer.c} and the swap cache in
\fn{mm/\-swap\_state.c} and \fn{mm/\-swapfile.c}.

\subsection*{Kernel}
Most of the relevent generic code is in \fn{kernel} with the architecture
specific code in \fn{arch/\-*/\-kernel}.
The scheduler is in \fn{kernel/\-sched.c} and the fork code is in \fn{kernel/\-fork.c}.
The bottom half handling code is in \fn{include/\-linux/\-interrupt.h}.
The \ds{task\_struct} data structure can be found in \fn{include/\-linux/\-sched.h}.

\subsection*{PCI}
The PCI pseudo driver is in \fn{drivers/\-pci/\-pci.c} with the system wide
definitions in \fn{include/\-linux/\-pci.h}.
Each architecture has some specific PCI BIOS code, \axp's is in 
\fn{arch/\-alpha/\-kernel/\-bios32.c}.

\subsection*{Interprocess Communication}
This is all in \fn{ipc}.
All System V IPC objects include an \ds{ipc\_perm} data structure and this can be found
in \fn{include/\-linux/\-ipc.h}.
System V messages are implemented in \fn{ipc/\-msg.c}, shared memory in \fn{ipc/\-shm.c} and
semaphores in \fn{ipc/\-sem.c}.
Pipes are implemented in \fn{ipc/\-pipe.c}.

\subsection*{Interrupt Handling}
The kernel's interrupt handling code is almost all microprocessor (and often platform)
specific.  The Intel interrupt handling code is in \fn{arch/\-i386/\-kernel/\-irq.c} and
its definitions in \fn{include/\-asm-i386/\-irq.h}.

\subsection*{Device Drivers}
Most of the lines of the Linux kernel's source code are in its device drivers.
All of Linux's device driver sources are held in \fn{drivers} but these
are further broken out by type:
\begin{description}
	\item [/block] block device drivers such as ide (in \fn{ide.c}).
	If you want to look at how all of the devices that could possibly
	contain file systems are initialized then you should look at 
	\fn{device\_setup()} in \fn{drivers/\-block/\-genhd.c}.  It not only
	initializes the hard disks but also the network as you need a network
	to  mount \fn{nfs} file systems.  Block devices include both IDE and
	SCSI based devices.

	\item [/char] This the place to look for character based devices such
	as \fn{ttys}, serial ports and mice.

	\item [/cdrom] All of the CDROM code for Linux.  It is here that the
	special CDROM devices (such as Soundblaster CDROM) can be found.  Note
	that the ide CD driver is \fn{ide-cd.c} in \fn{drivers/\-block} and that
	the SCSI CD driver is in \fn{scsi.c} in \fn{drivers/\-scsi}.

	\item [/pci] This are the sources for the PCI pseudo-driver.  A good place
	to look at how the PCI subsystem is mapped and initialized.  The \axp\ 
	PCI fixup code is also worth looking at in \fn{arch/\-alpha/\-kernel/\-bios32.c}.

	\item [/scsi]  This is where to find all of the SCSI code as well as all of the
	drivers for the scsi devices supported by Linux.

	\item [/net] This is where to look to find the network device drivers such as
	the DECChip 21040 PCI ethernet driver which is in \fn{tulip.c}.

	\item [/sound] This is where all of the sound card drivers are.

\end{description}

\subsection*{File Systems}
The sources for the \texttt{EXT2} file system are all in the \fn{fs/\-ext2/\-} directory with
data structure definitions in \fn{include/\-linux/\-ext2\_fs.h, ext2\_fs\_i.h} 
and \fn{ext2\_fs\_sb.h}.
The Virtual File System data structures are described in \fn{include/\-linux/\-fs.h} and the
code is in \fn{fs/\-*}.
The buffer cache is implemented in \fn{fs/\-buffer.c} along with the \texttt{update} kernel
daemon.

\subsection*{Network}
The networking code is kept in \fn{net} with most of the include files in \fn{include/\-net}.
The BSD socket code is in \fn{net/\-socket.c} and 
the IP version 4 INET socket code is in \fn{net/\-ipv4/\-af\_inet.c}.
The generic protocol support code (including the \ds{sk\_buff} handling routines) is in \fn{net/\-core}
with the TCP/\-IP networking code in \fn{net/\-ipv4}.
The network device drivers are in \fn{drivers/\-net}.

\subsection*{Modules}
The kernel module code is partially in the kernel and partially in the \fn{modules}
package.
The kernel code is all in \fn{kernel/\-modules.c} with the data structures and 
kernel demon \texttt{kerneld} messages in \fn{include/\-linux/\-module.h} and
\fn{include/\-linux/\-kerneld.h} respectively.
You may want to look at the structure of an \texttt{ELF} object file in 
\fn{include/\-linux/\-elf.h}.



