xnu

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 and ARM64 for both single processor and multi-processor configurations. The 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 a 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 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, the architecture is set to the build machine's 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 install the kernel into a DSTROOT, use the install_kernels target: make install_kernels DSTROOT=/tmp/xnu-dst For a more satisfying kernel debugging experience, with access to all local variables and arguments, but without all the extra check of the DEBUG kernel, add something like the following to your make command: CFLAGS_DEVELOPMENTARM64="-O0 -g -DKERNEL_STACK_MULTIPLIER=2" CXXFLAGS_DEVELOPMENTARM64="-O0 -g -DKERNEL_STACK_MULTIPLIER=2" Remember to replace DEVELOPMENT and ARM64 with the appropriate build and platform. Extra Flags: You can pass additional flags to the C compiler at the command line with the EXTRA_CFLAGS build setting. These flags are appended to the base CFLAGS, and the default value for the setting is an empty string. This setting allows you to e.g. selectively turn on debugging code that is guarded by a preprocessor macro. Example usage... make SDKROOT=macosx.internal PRODUCT_CONFIGS=j314s EXTRA_CFLAGS='-DKERNEL_STACK_MULTIPLIER=2' 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 BOUND_CHECKS=0 # disable -fbound-attributes for this build $ make REMOTEBUILD=user@remotehost # perform build on remote host $ make BUILD_CODE_COVERAGE=1 # build with support for collecting code coverage information 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. Customize the XNU Version The xnu version is derived from the SDK or KDK by reading the CFBundleVersion of their System/Library/Extensions/System.kext/Info.plist file. This can be customized by setting the RC_DARWIN_KERNEL_VERSION variable in the environment or on the make command line. See doc/building/xnu_version.md for more details. 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 Booting a KernelCache on a Target machine The development kernel and iBoot supports confi