This text was published in the may 2002 issue of the DaemonNews magazine.


Open Source Hackers' Guide Through The Galaxy
A Tour through the NetBSD Source Tree
Part III - Kernel
Hubert Feyrer, January 2002

Part III - Kernel

This is the third part of our tour through the NetBSD source tree. After we have talked about the various components that build up the userland, we will concentrate on the kernel source now. It is located in /usr/src/sys, with the /sys symlink being a well-known abbreviation to reach the system's kernel source.

Let's remember what happens when building a kernel: after editing the kernel config file located in /sys/arch/<arch>/conf and running config(8) on it, a number of files are created in /sys/arch/<arch>/compile/KERNELNAME. The header files contain data about what and how many devices to include, as well as other data for the system's configuration. Besides that, a Makefile is created, that is used to build the kernel from source. The interesting point to note here is that there is only one Makefile that will locate and compile all the needed sources and place the object files in the .../compile/KERNELNAME directory. In NetBSD, there is no recursive tree-walk of the whole source tree utilizing several Makefiles to build the various sub-trees of the kernel source. This allows building kernels for several configurations and platforms from the same source, without different builds tripping across each other.

Still, the various parts of the NetBSD kernel are placed in various subdirectories that we will have a closer look at now. Under /usr/src/sys, there are:

adosfs, coda, filecorefs, isofs, msdosfs, nfs, ntfs:
These are various filesystems used directly by NetBSD to access data. Some of the filesystems' primary goal is to help in exchanging data between the machine's native operating system (AmigaOS's adosfs, Acorn Computers RISC OS's filecorefs, ...), while others implement filesystems that can be found on many systems (isofs, nfs, ...).

ufs:
The Unix (User) File System is the base of the native filesystem used in NetBSD. Ancient (AT&T) Unix filesystems only allowed up to 14 chars long filenames, there were no symlinks etc. The problems were solved by the Berkely computer scientists implementing BSD Unix. Their filesystem implementation serves as a base for several filesystems based on it these days, using various ways of data layout on the disk.

The filesystems are stored in the "ufs" subdirectory, filesystems contained in there include

miscfs:
This directory contains further filesystems that aren'd directly related to physical storage. Instead they implement various layered filesystems for services like data translation or routines for implementing kernel features. Using the virtual filesystem operations table, it is easy to change behaviour of a operation upon certain conditions, e.g. mapping operations to deadfs on a file who's filedescriptors were revoke(2)'d.

The filesystems included here are:

compat:
This directory contains code for emulating binary compatibility with various non-NetBSD operating systems as well as with old NetBSD binaries. It includes:

conf:
The /sys/conf directory contains the main list of files to include into kernel builds as well as scripts and files used to update the OS version and compile it into the kernel. The operating system's version is stored in the "osrelease.sh" script, which is used from a number of places to determine the OS version.

crypto:
This directory contains code for various data encryption standards (arc4, blowfish, DES, Rijndael etc.) that is subject to crypto export regulations. The code is use by the IPsec kernel subsystem.

ddb:
The DDB kernel debugger that can be used to do post mortem debugging is found here. The debugger is used on all NetBSD ports.

dev:
This directory contains device drivers that use the machine independent bus_dma(9) and bus_space(9) interfaces and that work on all platforms that support the necessary bus glue routines. There are several subdirectories grouping drivers by various categories:

The directory structure is mostly oriented towards the bus system that a hardware device attaches to, not towards the functionality it provides. There are no special categories for things like audio, network etc. - these are in their bus-specific directories like pci, isa etc. containing (only) the bus-specific attachment routines.

If a chip implements some functionality like audio, network or scsi, it is often used on several cards that all have the same chip, but different bus interfaces - ISA, PCI, etc. To prevent maintaining several drivers that have identical core functionality, NetBSD drivers are seperated into bus-glue code kept in the bus-specific directories mentioned above, and the core functionality of the integrated circuit. Naming conventions help identifying e.g. network cards (if_*), but aren't implemented throughoutly, unfortunately.

The drivers for the core functionality are stored in the "ic" subdirectory, with the file names indicating the IC's chip numbers:

% ls /sys/dev/ic
CVS                 cac.c               isp_target.c        pckbc.c
Makefile            cacreg.h            isp_target.h        pckbcvar.h
README.ncr5380sbc   cacvar.h            isp_tpublic.h       pdq.c
ac97.c              cd1190reg.h         ispmbox.h           pdq_ifsubr.c
ac97reg.h           cd1400reg.h         ispreg.h            pdqreg.h 
...

ipkdb:
An IP-based debugger interface to a remote machine. Another way to debug the NetBSD besides the DDB kernel debugger and gdb, which can be used for debugging both userland and kernel.

kern:
This directory contains the core kernel code including a number of facilities:

lib:
Throughout the NetBSD kernel, there are many tasks that are used from many places, and that are stored within a few libraries that are used only in the kernel:

stand:
This directory contains source for several standalone programs that aren't used by NetBSD currently.

lkm:
NetBSD supports loadable kernel modules, and the sources are in this directory. LKMs include a floppy driver for mac68k, various binary emulations, IPfilter logging and several filesystems.

net:
NetBSD's networking framework contains many routines that are independent of a special protocol, and that are used by several networking protocols/stacks. The components are included in this directory, functions include packet filtering (BPF), access routines for all hardware cards (arcnet, ATM, ethernet, fddi, IEEE 802.11, PPP, token ring etc.) that hand device access to drivers in the /sys/dev directory, routing code etc.

netatalk:
The code in this directory implements the kernel part of the Appletalk protocol stack. The userland part is not included in NetBSD, it can be installed from pkgsrc/net/netatalk(-sun).

netccitt, netiso:
Not in widespread use these days, NetBSD compes with an ISO/OSI protocol stack which is located in these directories.

netinet:
Internet stuff - the NetBSD TCP/IP (v4) stack. Documentation on this is available in section 9 of the NetBSD manual pages as well as in Richard Steven's "TCP/IP Illustrated" books.

netinet6:
Internet, next generation - this directory contains the KAME IPv6 stack that is shipping with NetBSD. See http://www.kame.net/ for further information.

netkey:
Key management for IPsec - see the ipsec(4) manpage for more details.

netnatm:
The code in this directory implements native mode ATM to transport other protocols like IP.

netns:
NetBSD has support for the Xerox network service protocol, which can be found in this directory. Not in widespread use any more today, the protocol is described in the first edition of Richard Stevens' "TCP/IP Network Programming" book.

sys:
This directory contains only header files that get installed into /usr/include/sys.

uvm:
The code in this directory implements NetBSD' New Virtual Memory system that replaced the old Mach-based VM system some time ago. See the uvm(4) manpage for more information.

vm:
This directory has only the header files of the old Mach based virtual memory system left, for use with various programs. The VM system itself is not used any longer.

arch:
Code specific to one hardware platform is collected under this directory. Directories are present for each port as well as for CPU-specific functions that are shared by several ports that use the same CPU, avoiding redundancy.

Port-specific directories contain several subdirectories, with the following ones being present for all ports:

Further directories may exist in the arch specific directories that contain bus-specific/non-machine independent device drivers which don't fit into /sys/dev as they work on one port only. Ideally, a port only uses machine independent drivers, of course.

We have now described all the important directories that are available in the NetBSD source tree. To get used to the directory structure, it is recommented that you browse the directories and have a look at the various files to fully explore things.


(c) Copyright 20020110 Hubert Feyrer
$Id: tour-de-source-3kernel.html,v 1.2 2002/01/29 00:59:29 feyrer Exp $