What is XNU?

XNU kernel is part of the Darwin operating system for use in macOS and iOS operating systems. XNU is an acronym for X is Not Unix. XNU is a hybrid kernel combining the Mach kernel developed at Carnegie Mellon University with components from FreeBSD and a C++ API for writing drivers called IOKit. XNU runs on x86_64 for both single processor and multi-processor configurations.

XNU Source Tree

• config - configurations for exported apis for supported architecture and platform
• SETUP - Basic set of tools used for configuring the kernel, versioning and kextsymbol management.
• EXTERNAL_HEADERS - Headers sourced from other projects to avoid dependency cycles when building. These headers should be regularly synced when source is updated.
• libkern - C++ IOKit library code for handling of drivers and kexts.
• libsa - kernel bootstrap code for startup
• libsyscall - syscall library interface for userspace programs
• libkdd - source for user library for parsing kernel data like kernel chunked data.
• makedefs - top level rules and defines for kernel build.
• osfmk - Mach kernel based subsystems
• pexpert - Platform specific code like interrupt handling, atomics etc.
• security - Mandatory Access Check policy interfaces and related implementation.
• bsd - BSD subsystems code
• tools - A set of utilities for testing, debugging and profiling kernel.

How to build XNU

Building DEVELOPMENT kernel

The xnu make system can build kernel based on KERNEL_CONFIGS & ARCH_CONFIGS variables as arguments. Here is the syntax:

make SDKROOT=<sdkroot> ARCH_CONFIGS=<arch> KERNEL_CONFIGS=<variant>

Where:

• <sdkroot>: path to macOS SDK on disk. (defaults to /)
• <variant>: can be debug, development, release, profile and configures compilation flags and asserts throughout kernel code.
• <arch> : can be valid arch to build for. (E.g. X86_64)

To build a kernel for the same architecture as running OS, just type

$ make
$ make SDKROOT=macosx.internal

Additionally, there is support for configuring architectures through ARCH_CONFIGS and kernel configurations with KERNEL_CONFIGS.

$ make SDKROOT=macosx.internal ARCH_CONFIGS=X86_64 KERNEL_CONFIGS=DEVELOPMENT
$ make SDKROOT=macosx.internal ARCH_CONFIGS=X86_64 KERNEL_CONFIGS="RELEASE DEVELOPMENT DEBUG"

Note:

• By default, architecture is set to the build machine architecture, and the default kernel config is set to build for DEVELOPMENT.

This will also create a bootable image, kernel.[config], and a kernel binary with symbols, kernel.[config].unstripped.

• To build with RELEASE kernel configuration

  make KERNEL_CONFIGS=RELEASE SDKROOT=/path/to/SDK
  

Building FAT kernel binary

Define architectures in your environment or when running a make command.

$ make ARCH_CONFIGS="X86_64" exporthdrs all

Other makefile options

• $ make MAKEJOBS=-j8 # this will use 8 processes during the build. The default is 2x the number of active CPUS.
• $ make -j8 # the standard command-line option is also accepted
• $ make -w # trace recursive make invocations. Useful in combination with VERBOSE=YES
• $ make BUILD_LTO=0 # build without LLVM Link Time Optimization
• $ make REMOTEBUILD=user@remotehost # perform build on remote host
• $ make BUILD_JSON_COMPILATION_DATABASE=1 # Build Clang JSON Compilation Database

The XNU build system can optionally output color-formatted build output. To enable this, you can either set the XNU_LOGCOLORS environment variable to y, or you can pass LOGCOLORS=y to the make command.

Debug information formats

By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named kernel.development.<variant>.dSYM To select the older STABS debug information format (where debug information is embedded in the kernel.development.unstripped image), set the BUILD_STABS environment variable.

$ export BUILD_STABS=1
$ make

Building KernelCaches

To test the xnu kernel, you need to build a kernelcache that links the kexts and kernel together into a single bootable image. To build a kernelcache you can use the following mechanisms:

• Using automatic kernelcache generation with kextd. The kextd daemon keeps watching for changing in /System/Library/Extensions directory. So you can setup new kernel as

  $ cp BUILD/obj/DEVELOPMENT/X86_64/kernel.development /System/Library/Kernels/
  $ touch /System/Library/Extensions
  $ ps -e | grep kextd
  

• Manually invoking kextcache to build new kernelcache.

  $ kextcache -q -z -a x86_64 -l -n -c /var/tmp/kernelcache.test -K /var/tmp/kernel.test /System/Library/Extensions
  

Running KernelCache on Target machine

The development kernel and iBoot supports configuring boot arguments so that we can safely boot into test kernel and, if things go wrong, safely fall back to previously used kernelcache. Following are the steps to get such a setup:

1. Create kernel cache using the kextcache command as /kernelcache.test

2. Copy exiting boot configurations to alternate file

   $ cp /Library/Preferences/SystemConfiguration/com.apple.Boot.plist /next_boot.plist
   

3. Update the kernelcache and boot-args for your setup

   $ plutil -insert "Kernel Cache" -string "kernelcache.test" /next_boot.plist
   $ plutil -replace "Kernel Flags" -string "debug=0x144 -v kernelsuffix=test " /next_boot.plist
   

4. Copy the new config to /Library/Preferences/SystemConfiguration/

   $ cp /next_boot.plist /Library/Preferences/SystemConfiguration/boot.plist
   

5. Bless the volume with new configs.

   $ sudo -n bless  --mount / --setBoot --nextonly --options "config=boot"
   

   The --nextonly flag specifies that use the boot.plist configs only for one boot. So if the kernel panic's you can easily power reboot and recover back to original kernel.

Creating tags and cscope

Set up your build environment and from the top directory, run:

$ make tags     # this will build ctags and etags on a case-sensitive volume, only ctags on case-insensitive
$ make TAGS     # this will build etags
$ make cscope   # this will build cscope database

Code Style

Source files can be reformatted to comply with the xnu code style using the "restyle" make target invoked from the top-level project directory.

$ make restyle # re-format all source files to be xnu code style conformant.

Compliance can be checked using the "checkstyle" make target.

$ make checkstyle # Check all relevant source files for xnu code style conformance.

How to install a new header file from XNU

To install IOKit headers, see additional comments in iokit/IOKit/Makefile.

XNU installs header files at the following locations -

a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers
b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders
c. $(DSTROOT)/usr/include/
d. $(DSTROOT)/System/DriverKit/usr/include/
e. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders

Kernel.framework is used by kernel extensions.
The System.framework and /usr/include are used by user level applications.
/System/DriverKit/usr/include is used by userspace drivers.
The header files in framework's PrivateHeaders are only available for ** Apple Internal Development **.

The directory containing the header file should have a Makefile that creates the list of files that should be installed at different locations. If you are adding the first header file in a directory, you will need to create Makefile similar to xnu/bsd/sys/Makefile.

Add your header file to the correct file list depending on where you want to install it. The default locations where the header files are installed from each file list are -

a. `DATAFILES` : To make header file available in user level -
   `$(DSTROOT)/usr/include`

b. `DRIVERKIT_DATAFILES` : To make header file available to DriverKit userspace drivers -
   `$(DSTROOT)/System/DriverKit/usr/include`

c. `PRIVATE_DATAFILES` : To make header file available to Apple internal in
   user level -
   `$(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders`

d. `KERNELFILES` : To make header file available in kernel level -
   `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers`
   `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders`

e. `PRIVATE_KERNELFILES` : To make header file available to Apple internal
   for kernel extensions -
   `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders`

The Makefile combines the file lists mentioned above into different install lists which are used by build system to install the header files. There are two types of install lists: machine-dependent and machine-independent. These lists are indicated by the presence of MD and MI in the build setting, respectively. If your header is architecture-specific, then you should use a machine-dependent install list (e.g. INSTALL_MD_LIST). If your header should be installed for all architectures, then you should use a machine-independent install list (e.g. INSTALL_MI_LIST).

If the install list that you are interested does not exist, create it by adding the appropriate file lists. The default install lists, its member file lists and their default location are described below -

a. `INSTALL_MI_LIST` : Installs header file to a location that is available to everyone in user level.
    Locations -
       $(DSTROOT)/usr/includ