Section 6.1. xnu Source

6.1. xnu Source

In Chapter 5, we visited various parts of the kernel as we traced the execution of kernel code during system startup. Let us now take a brief tour of the xnu kernel source to better understand how the source is organized. Since the xnu package contains close to 3000 files, it is impractical to visit each file. We will only look at major directories in the xnu source tree to enumerate the components implemented within.

In this section, file and directory names are listed relative to the top-level directory in the xnu source archive. For example, given that the xnu-<version>.tar.gz Darwin package will unpack into a top-level directory called xnu-<version>, we refer to a file xnu-<version>/foo/bar as foo/bar.

At the topmost level, xnu contains the directories listed in Table 61. Besides these, there exist a few other miscellaneous files and directories that are not important in the current discussion. We will look at some of them later in this chapter in the context of kernel compilation (Section 6.10).

Table 61. Primary Components of the xnu Kernel Source

Directory	Component
bsd/	The BSD kernel
config/	Lists of per-subsystem exported functions, property list files for pseudo-extensions
iokit/	The I/O Kit kernel runtime
libkern/	The kernel library
libsa/	The stand-alone library
osfmk/	The Mach kernel
pexpert/	The Platform Expert

Table 62 lists some contents of the bsd/ directory. Section 2.4.2 provides an overview of the functionality implemented in the kernel's BSD portion.

Table 62. Primary Contents of the bsd/ Directory

Directory	Description
bsd/bsm/	Basic Security Module (BSM) headers used by the kernel's auditing mechanism. BSM is both a security audit format and an API used to track security-related events in the operating system.
bsd/crypto/	Various cipher and hash implementations: AES (Rijndael), Blowfish, CAST-128, DES, MD5, RC4, SHA-1, and SHA-2.
bsd/dev/memdev.c	A RAM disk driver (for /dev/mdX devices).
bsd/dev/ppc/	BSD drivers for entities such as /dev/console, /dev/mem, /dev/kmem, /dev/null, /dev/zero, and a BSD driver wrapper for the NVRAM. The latter calls Platform Expert functions to perform the actual work. The BSD device switch tables for block and character devices are also initialized here. Also present are some machine-dependent functions used in the BSD subsystem, such as unix_syscall(), unix_syscall_return(), ppc_gettimeofday(), and signal-handling functions.
bsd/dev/random/	An implementation of the Yarrow[a] pseudorandom number generator (PRNG) and the /dev/random device.
bsd/dev/unix_startup.c	Functions that initialize various BSD-related data structures during system startup.
bsd/dev/vn/	The vnode disk driver, which provides block and character interfaces to a vnode, allowing files to be treated as disks. The /usr/libexec/vndevice utility is used to control the driver.
bsd/hfs/	The HFS and HFS Plus file systems.
bsd/isofs/	The ISO 9660 file system for read-only optical discs.
bsd/kern/	The core of xnu's BSD component. It contains implementations of asynchronous I/O calls, the kauth mechanism, the audit mechanism, process-related system calls, sysctl calls, POSIX IPC, System V IPC, the unified buffer cache, sockets, mbufs, and various other system calls.
bsd/libkern/	Utility routines such as bcd(), bcmp(), inet_ntoa(), rindex(), and strtol().
bsd/miscfs/	Miscellaneous file systems: the dead file system for vnodes whose underlying file system has been dissociated (deadfs), the device file system (devfs), the file descriptor file system (fdesc), the fifo file system (fifofs), the null mount file system (nullfs), the file system for device-special files (specfs), the in-memory synthfs used for synthesizing mount points, the union mount file system (union), and the volume ID file system (volfs).
bsd/net/	Networking: the Berkeley packet filter (BPF), bridging, data link interface layer (DLIL), Ethernet, ARP, PPP, routing, IEEE 802.1q (VLAN), IEEE 802.3ad (Link Aggregation), etc.
bsd/netat/	AppleTalk Networking.
bsd/netinet/	IPv4 Networking: BOOTP, DHCP, ICMP, TCP, UDP, IP, the "dummynet" bandwidth limiter, and divert sockets.
bsd/netinet6/	IPv6 Networking.
bsd/netkey/	PF_KEY Key Management API (RFC 2367).
bsd/nfs/	NFS client and the kernel portion of the NFS server.
bsd/ufs/	An implementation of UFS based on the fast file system (ffs).
bsd/uxkern/	A Mach exception handler that translates Mach exceptions into Unix signals.
bsd/vfs/	The BSD virtual file system layer.
bsd/vm/	Vnode pager (swap to/from vnodes, demand paging from files), shared memory server calls.

^[a] Yarrow gets its name from a flowering plant with distinctive flat flower heads and lacy leaves. In China, its stalks have been used as a randomizer in divination since the second millennium B.C.

Table 63 lists some contents of the iokit/ directory. Section 2.4.3 provides an overview of the I/O Kit's functionality.

Table 63. Primary Contents of the iokit/ Directory

Directory	Description
iokit/Drivers/platform/	Implementations of I/O Kit classes listed in the KernelConfigTables arraye.g., AppleCPU, AppleNMI, and AppleNVRAM. As we will see in Chapter 10, the I/O Catalog is initialized with the contents of this array.
iokit/Families/IONVRAM/	Subclass of the NVRAM controller classsimply calls the Platform Expert to register the NVRAM controller, which publishes the "IONVRAM" resource in the I/O Kit.
iokit/Families/IOSystemManagement/	Watchdog timer.
iokit/IOKit/	I/O Kit header files.
iokit/Kernel/	Implementations of core I/O Kit classes and utility functions.
iokit/KernelConfigTables.cpp	Declarations of the list of "fake" kernel extensions and the KernelConfigTables array.
iokit/bsddev/	Support functions for BSDe.g., the di_root_image() netboot hook called by BSD to mount a disk image as the root device, and several other functions used by BSD while searching for a root device.

Table 64 lists some contents of the libkern/ directory. Section 2.4.4 provides an overview of libkern's functionality.

Table 64. Primary Contents of the libkern/ Directory

Directory	Description
libkern/c++/	Implementations of various libkern classes (see Table 65).
libkern/gen/	High-level-language wrappers around assembly functions for atomic operations, miscellaneous debugging functions.
libkern/kmod/	Start and stop routines for the kernel's C++ and C language runtime environments.
libkern/libkern/	libkern header files.
libkern/mach-o/	A header describing the format of Mach-O files (loader.h), and another header containing definitions for accessing Mach-O headers (mach_header.h).
libkern/ppc/	Implementations of PowerPC-specific bcmp(), memcmp(), strlen(), and atomic increment/decrement functions.
libkern/stdio/	An implementation of scanf().
libkern/uuid/	Routines for parsing and generating universally unique identifiers (UUIDs) based on the first Ethernet device's hardware address and the current time.

libkern is part of the Kernel framework (Kernel.framework), which is exposed to the developer. Its headers are located in /System/Library/Frameworks/Kernel.framework/Headers/libkern/. Table 65 shows the important classes contained in this library.

Table 65. libkern Classes and Routines

Base and Abstract Classes
OSObject	The abstract base class for the Mac OS X kernel. It derives from the true root class OSMetaClassBase. It implements basic functionality such as allocation primitives, reference counting, and type-safe object casting.
OSMetaClass	A peer class to OSObject. It derives from the true root class OSMetaClassBase. An instance of this class represents one class that is known by the I/O Kit's RTTI system.
OSCollection	The abstract superclass for all collections.
OSIterator	The abstract superclass for iterator classes.
Collection Classes
OSArray	A class for maintaining lists of object references.
OSDictionary	A class for maintaining dictionaries of object references.
OSOrderedSet	A class for maintaining and sorting sets of OSMetaClassBase-derived objects.
OSSet	A class for storing OSMetaClassBase-derived objects.
OSCollectionIterator	A class that provides a mechanism to iterate over OSCollection-derived collections.
Container Classes
OSBoolean	A class for Boolean values.
OSData	A class for managing byte arrays.
OSNumber	A class for numeric values.
OSString	A class for managing strings.
OSSymbol	A class for representing unique string values.
OSSerialize	A class used by the container classes to serialize their instance data.
OSUnserializeXML	A class that recreates a container object from its serialized instance data in an XML buffer.

Table 66 lists some contents of the libsa/ directory. Section 2.4.5 provides an overview of libsa's functionality.

Table 66. Primary Contents of the libsa/Directory

File	Description
libsa/bootstrap.cpp	Constructor and destructor functions for libsa.
libsa/bsearch.c, libsa/dgraph.c, libsa/sort.c	Functions for binary searching, directed graphs, and heap sortused for supporting kernel extension loading.
libsa/c++rem3.c	Symbol remangler for code compiled with version 2.95 of the GNU C++ compilerinvoked during symbol table parsing when a Mach-O object file (typically a kernel extension) is mapped.
libsa/catalogue.cpp	I/O Catalog routines, such as those for accessing and manipulating kernel extension dictionaries, accessing mkext caches, and recording boot-time kernel extensions into dictionaries.
libsa/kext.cpp, libsa/kld_patch.c, libsa/kmod.cpp, libsa/load.c	The core of libsa's functionality: routines for resolving kernel extension dependencies, retrieving kernel extension versions, loading kernel extensions, patching vtables, etc.
libsa/malloc.c	Simple implementations of malloc() and realloc().
libsa/mkext.c	Routines for LZSS compression/decompression, and for computing 32-bit Adler checksums.
libsa/strrchr.c, libsa/strstr.c	String functions.
libsa/vers_rsrc.c	Routines for parsing and generating version strings.

Recall from Chapter 2 that the libsa stand-alone library is used only for loading kernel extensions during system startup. In a typical booting scenario, when the kernel extension daemon (kextd) is started, it sends a kIOCatalogRemoveKernelLinker message to the I/O Catalog in the kernel. This message notifies the I/O Catalog that kextd is ready to handle the loading of kernel extensions from user space. Moreover, the message triggers the I/O Catalog to invoke destructors for the kernel's __KLD segment and to deallocate it. The __KLD segment contains libsa's code. The kernel's __LINKEDIT segment is also deallocated.

Section 2.4.1 provides an overview of the functionality implemented in the Mach portion of xnu. Table 67 lists the important components of the osfmk/ directory.

Table 67. Primary Contents of the osfmk/Directory

Directory or File	Description
osfmk/UserNotification/	Kernel portion of the Kernel User Notification Center (KUNC) mechanism, which can be used by software running in the kernel to execute user-space programs and to display notices or alert messages. The /usr/libexec/kuncd daemon is the user-space agent that processes such requests from the kernel.
osfmk/console/i386/	VGA text console, x86 serial console.
osfmk/console/iso_font.c	Data for the ISO Latin-1 font.
osfmk/console/panic_dialog.c	Panic user-interface routines, including routines for drawing, managing, and testing the panic dialog.
osfmk/console/panic_image.c	Pixel data for the default panic imagean 8-bit, 472x255 image.
osfmk/console/panic_ui/	Panic image files and utilities to convert them into a kernel-usable format.
osfmk/console/ppc/	Fast video scrolling, PowerPC serial console.
osfmk/console/rendered_numbers.c	Pixel data for hexadecimal digits 0 through F and the colon character.
osfmk/console/video_console.c	Hardware-independent portion of the video console.
osfmk/ddb/	Built-in kernel debugger.
osfmk/default_pager/	Default pager, including the back-end for managing swap files.
osfmk/device/	Mach support for the I/O Kit, including device representation through Mach ports. The I/O Kit master port is also set here.
osfmk/ipc/	The core of Mach's IPC facility implementation.
osfmk/kdp/	A kernel debugging protocol called KDP that uses a TFTP-like UDP-based transfer mechanism.
osfmk/kern/	The core Mach kernel: implementations of abstractions such as processors, processor sets, tasks, threads, memory allocation, and timers. IPC interfaces are also implemented here.
osfmk/mach/	Mach headers and MIG definition files.
osfmk/mach-o/	Functions for accessing Mach-O headers.
osfmk/mach_debug/	Mach debugging headers and MIG definition files.
osfmk/machine/	Headers that are wrappers for machine-dependent headers.
osfmk/ppc/	PowerPC-specific code: machine startup, exception vectors, trap handling, low-level context-switching code, low-level memory management, diagnostic calls, Classic support functions, machine-dependent debugger components, virtual machine monitor, kernel components for Apple's CHUD Tools, etc.
osfmk/profiling/	Kernel profiling support, which must be explicitly compiled in. The kgmon utility is used to control the profiling mechanism: It can stop or start the collection of kernel profiling data, dump the contents of the profile buffers, reset all the profile buffers, and retrieve specific named values from the kernel.
osfmk/sys/	Miscellaneous headers.
osfmk/vm/	Mach virtual memory subsystem, including the in-kernel shared memory server.

Section 2.4.6 provides an overview of the functionality of the Platform Expert. Table 68 lists the important components of the pexpert/ directory.

Table 68. Primary Contents of the pexpert/ Directory

Directory or File	Description
pexpert/gen/bootargs.c	Boot-argument parsing routines.
pexpert/gen/device_tree.c	Routines for accessing device tree entries and their properties.
pexpert/gen/pe_gen.c	Miscellaneous functions, including an 8-bit color lookup table used during bootstrapping.
pexpert/i386/	Machine identification, debugging output support, keyboard driver, generic interrupt handler, polled-mode serial port driver, and other platform-dependent routines such as for reading the timestamp counter, setting and clearing interrupts, generating a fake device tree, etc.
pexpert/pexpert/	Miscellaneous platform headers, including those containing image data for the rotating gearwheel image shown at startup to indicate boot progress.
pexpert/ppc/	Machine identification, debugging output support, clock speed determination by running timed loops, timebase value retrieval, and other platform functions.