1What is XNU? 2=========== 3 4XNU 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. 5XNU 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. 6XNU runs on x86_64 for both single processor and multi-processor configurations. 7 8XNU Source Tree 9=============== 10 11 * `config` - configurations for exported apis for supported architecture and platform 12 * `SETUP` - Basic set of tools used for configuring the kernel, versioning and kextsymbol management. 13 * `EXTERNAL_HEADERS` - Headers sourced from other projects to avoid dependency cycles when building. These headers should be regularly synced when source is updated. 14 * `libkern` - C++ IOKit library code for handling of drivers and kexts. 15 * `libsa` - kernel bootstrap code for startup 16 * `libsyscall` - syscall library interface for userspace programs 17 * `libkdd` - source for user library for parsing kernel data like kernel chunked data. 18 * `makedefs` - top level rules and defines for kernel build. 19 * `osfmk` - Mach kernel based subsystems 20 * `pexpert` - Platform specific code like interrupt handling, atomics etc. 21 * `security` - Mandatory Access Check policy interfaces and related implementation. 22 * `bsd` - BSD subsystems code 23 * `tools` - A set of utilities for testing, debugging and profiling kernel. 24 25How to build XNU 26================ 27 28Building `DEVELOPMENT` kernel 29----------------------------- 30 31The xnu make system can build kernel based on `KERNEL_CONFIGS` & `ARCH_CONFIGS` variables as arguments. 32Here is the syntax: 33 34 make SDKROOT=<sdkroot> ARCH_CONFIGS=<arch> KERNEL_CONFIGS=<variant> 35 36Where: 37 38 * \<sdkroot>: path to macOS SDK on disk. (defaults to `/`) 39 * \<variant>: can be `debug`, `development`, `release`, `profile` and configures compilation flags and asserts throughout kernel code. 40 * \<arch> : can be valid arch to build for. (E.g. `X86_64`) 41 42To build a kernel for the same architecture as running OS, just type 43 44 $ make 45 $ make SDKROOT=macosx.internal 46 47Additionally, there is support for configuring architectures through `ARCH_CONFIGS` and kernel configurations with `KERNEL_CONFIGS`. 48 49 $ make SDKROOT=macosx.internal ARCH_CONFIGS=X86_64 KERNEL_CONFIGS=DEVELOPMENT 50 $ make SDKROOT=macosx.internal ARCH_CONFIGS=X86_64 KERNEL_CONFIGS="RELEASE DEVELOPMENT DEBUG" 51 52 53Note: 54 * By default, architecture is set to the build machine architecture, and the default kernel 55 config is set to build for DEVELOPMENT. 56 57 58This will also create a bootable image, kernel.[config], and a kernel binary 59with symbols, kernel.[config].unstripped. 60 61To intall the kernel into a DSTROOT, use the `install_kernels` target: 62 63 $ make install_kernels DSTROOT=/tmp/xnu-dst 64 65Hint: 66For a more satisfying kernel debugging experience, with access to all 67local variables and arguments, but without all the extra check of the 68DEBUG kernel, add something like: 69 CFLAGS_DEVELOPMENTARM64="-O0 -g -DKERNEL_STACK_MULTIPLIER=2" 70 CXXFLAGS_DEVELOPMENTARM64="-O0 -g -DKERNEL_STACK_MULTIPLIER=2" 71to your make command. 72Replace DEVELOPMENT and ARM64 with the appropriate build and platform. 73 74 75 * To build with RELEASE kernel configuration 76 77 make KERNEL_CONFIGS=RELEASE SDKROOT=/path/to/SDK 78 79 80Building FAT kernel binary 81-------------------------- 82 83Define architectures in your environment or when running a make command. 84 85 $ make ARCH_CONFIGS="X86_64" exporthdrs all 86 87Other makefile options 88---------------------- 89 90 * $ make MAKEJOBS=-j8 # this will use 8 processes during the build. The default is 2x the number of active CPUS. 91 * $ make -j8 # the standard command-line option is also accepted 92 * $ make -w # trace recursive make invocations. Useful in combination with VERBOSE=YES 93 * $ make BUILD_LTO=0 # build without LLVM Link Time Optimization 94 * $ make BOUND_CHECKS=0 # disable -fbound-attributes for this build 95 * $ make REMOTEBUILD=user@remotehost # perform build on remote host 96 * $ make BUILD_JSON_COMPILATION_DATABASE=1 # Build Clang JSON Compilation Database 97 98The XNU build system can optionally output color-formatted build output. To enable this, you can either 99set the `XNU_LOGCOLORS` environment variable to `y`, or you can pass `LOGCOLORS=y` to the make command. 100 101Customize xnu version 102--------------------- 103 104The xnu version is derived from the SDK or KDK by reading the `CFBundleVersion` 105of their `System/Library/Extensions/System.kext/Info.plist` file. 106This can be customized by setting the `RC_DARWIN_KERNEL_VERSION` variable in 107the environment or on the `make` command line. 108 109 110See doc/xnu_version.md for more details. 111 112Debug information formats 113========================= 114 115By default, a DWARF debug information repository is created during the install phase; this is a "bundle" named kernel.development.\<variant>.dSYM 116To select the older STABS debug information format (where debug information is embedded in the kernel.development.unstripped image), set the BUILD_STABS environment variable. 117 118 $ export BUILD_STABS=1 119 $ make 120 121 122Building KernelCaches 123===================== 124 125To test the xnu kernel, you need to build a kernelcache that links the kexts and 126kernel together into a single bootable image. 127To build a kernelcache you can use the following mechanisms: 128 129 * Using automatic kernelcache generation with `kextd`. 130 The kextd daemon keeps watching for changing in `/System/Library/Extensions` directory. 131 So you can setup new kernel as 132 133 $ cp BUILD/obj/DEVELOPMENT/X86_64/kernel.development /System/Library/Kernels/ 134 $ touch /System/Library/Extensions 135 $ ps -e | grep kextd 136 137 * Manually invoking `kextcache` to build new kernelcache. 138 139 $ kextcache -q -z -a x86_64 -l -n -c /var/tmp/kernelcache.test -K /var/tmp/kernel.test /System/Library/Extensions 140 141 142 143Running KernelCache on Target machine 144===================================== 145 146The 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. 147Following are the steps to get such a setup: 148 149 1. Create kernel cache using the kextcache command as `/kernelcache.test` 150 2. Copy exiting boot configurations to alternate file 151 152 $ cp /Library/Preferences/SystemConfiguration/com.apple.Boot.plist /next_boot.plist 153 154 3. Update the kernelcache and boot-args for your setup 155 156 $ plutil -insert "Kernel Cache" -string "kernelcache.test" /next_boot.plist 157 $ plutil -replace "Kernel Flags" -string "debug=0x144 -v kernelsuffix=test " /next_boot.plist 158 159 4. Copy the new config to `/Library/Preferences/SystemConfiguration/` 160 161 $ cp /next_boot.plist /Library/Preferences/SystemConfiguration/boot.plist 162 163 5. Bless the volume with new configs. 164 165 $ sudo -n bless --mount / --setBoot --nextonly --options "config=boot" 166 167 The `--nextonly` flag specifies that use the `boot.plist` configs only for one boot. 168 So if the kernel panic's you can easily power reboot and recover back to original kernel. 169 170 171 172 173Creating tags and cscope 174======================== 175 176Set up your build environment and from the top directory, run: 177 178 $ make tags # this will build ctags and etags on a case-sensitive volume, only ctags on case-insensitive 179 $ make TAGS # this will build etags 180 $ make cscope # this will build cscope database 181 182 183How to install a new header file from XNU 184========================================= 185 186XNU installs header files at the following locations - 187 188 a. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 189 b. $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 190 c. $(DSTROOT)/usr/include/ 191 d. $(DSTROOT)/usr/local/include/ 192 e. $(DSTROOT)/System/DriverKit/usr/include/ 193 f. $(DSTROOT)/System/Library/Frameworks/IOKit.framework/Headers 194 g. $(DSTROOT)/System/Library/Frameworks/IOKit.framework/PrivateHeaders 195 h. $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 196 197`Kernel.framework` is used by kernel extensions.\ 198The `System.framework`, `/usr/include` and `/usr/local/include` are used by user level applications. \ 199`IOKit.framework` is used by IOKit userspace clients. \ 200`/System/DriverKit/usr/include` is used by userspace drivers. \ 201The header files in framework's `PrivateHeaders` are only available for ** Apple Internal Development **. 202 203The directory containing the header file should have a Makefile that 204creates the list of files that should be installed at different locations. 205If you are adding the first header file in a directory, you will need to 206create Makefile similar to `xnu/bsd/sys/Makefile`. 207 208Add your header file to the correct file list depending on where you want 209to install it. The default locations where the header files are installed 210from each file list are - 211 212 a. `DATAFILES` : To make header file available in user level - 213 `$(DSTROOT)/usr/include` 214 `$(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders` 215 216 b. `DRIVERKIT_DATAFILES` : To make header file available to DriverKit userspace drivers - 217 `$(DSTROOT)/System/DriverKit/usr/include` 218 219 c. `PRIVATE_DATAFILES` : To make header file available to Apple internal in 220 user level - 221 `$(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders` 222 223 d. `EMBEDDED_PRIVATE_DATAFILES` : To make header file available in user 224 level for macOS as `EXTRA_DATAFILES`, but Apple internal in user level 225 for embedded OSes as `EXTRA_PRIVATE_DATAFILES` - 226 `$(DSTROOT)/usr/include` (`EXTRA_DATAFILES`) 227 `$(DSTROOT)/usr/local/include` (`EXTRA_PRIVATE_DATAFILES`) 228 229 e. `KERNELFILES` : To make header file available in kernel level - 230 `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers` 231 `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders` 232 233 f. `PRIVATE_KERNELFILES` : To make header file available to Apple internal 234 for kernel extensions - 235 `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders` 236 237 g. `MODULEMAPFILES` : To make module map file available in user level - 238 `$(DSTROOT)/usr/include` 239 240 h. `PRIVATE_MODULEMAPFILES` : To make module map file available to Apple 241 internal in user level - 242 `$(DSTROOT)/usr/local/include` 243 244 i. `LIBCXX_DATAFILES` : To make header file available to in-kernel libcxx clients: 245 `$(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders/kernel_sdkroot` 246 247 j. `EXCLAVEKIT_DATAFILES` : To make header file available to Apple internal 248 ExclaveKit SDK - 249 `$(DSTROOT)/System/ExclaveKit/usr/include` 250 251 k. `EXCLAVECORE_DATAFILES` : To make header file available to Apple internal 252 ExclaveCore SDK - 253 `$(DSTROOT)/System/ExclaveCore/usr/include` 254 255The Makefile combines the file lists mentioned above into different 256install lists which are used by build system to install the header files. There 257are two types of install lists: machine-dependent and machine-independent. 258These lists are indicated by the presence of `MD` and `MI` in the build 259setting, respectively. If your header is architecture-specific, then you should 260use a machine-dependent install list (e.g. `INSTALL_MD_LIST`). If your header 261should be installed for all architectures, then you should use a 262machine-independent install list (e.g. `INSTALL_MI_LIST`). 263 264If the install list that you are interested does not exist, create it 265by adding the appropriate file lists. The default install lists, its 266member file lists and their default location are described below - 267 268 a. `INSTALL_MI_LIST`, `INSTALL_MODULEMAP_MI_LIST` : Installs header and module map 269 files to a location that is available to everyone in user level. 270 Locations - 271 $(DSTROOT)/usr/include 272 Definition - 273 INSTALL_MI_LIST = ${DATAFILES} 274 INSTALL_MODULEMAP_MI_LIST = ${MODULEMAPFILES} 275 276 b. `INSTALL_DRIVERKIT_MI_LIST` : Installs header file to a location that is 277 available to DriverKit userspace drivers. 278 Locations - 279 $(DSTROOT)/System/DriverKit/usr/include 280 Definition - 281 INSTALL_DRIVERKIT_MI_LIST = ${DRIVERKIT_DATAFILES} 282 283 c. `INSTALL_MI_LCL_LIST`, `INSTALL_MODULEMAP_MI_LCL_LIST` : Installs header and 284 module map files to a location that is available for Apple internal in user level. 285 Locations - 286 $(DSTROOT)/usr/local/include 287 Definition - 288 INSTALL_MI_LCL_LIST = 289 INSTALL_MODULEMAP_MI_LCL_LIST = ${PRIVATE_MODULEMAPFILES} 290 291 d. `INSTALL_IF_MI_LIST` : Installs header file to location that is available 292 to everyone for IOKit userspace clients. 293 Locations - 294 $(DSTROOT)/System/Library/Frameworks/IOKit.framework/Headers 295 Definition - 296 INSTALL_IF_MI_LIST = ${DATAFILES} 297 298 e. `INSTALL_IF_MI_LCL_LIST` : Installs header file to location that is 299 available to Apple internal for IOKit userspace clients. 300 Locations - 301 $(DSTROOT)/System/Library/Frameworks/IOKit.framework/PrivateHeaders 302 Definition - 303 INSTALL_IF_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES} 304 305 f. `INSTALL_SF_MI_LCL_LIST` : Installs header file to a location that is available 306 for Apple internal in user level. 307 Locations - 308 $(DSTROOT)/System/Library/Frameworks/System.framework/PrivateHeaders 309 Definition - 310 INSTALL_SF_MI_LCL_LIST = ${DATAFILES} ${PRIVATE_DATAFILES} 311 312 g. `INSTALL_KF_MI_LIST` : Installs header file to location that is available 313 to everyone for kernel extensions. 314 Locations - 315 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 316 Definition - 317 INSTALL_KF_MI_LIST = ${KERNELFILES} 318 319 h. `INSTALL_KF_MI_LCL_LIST` : Installs header file to location that is 320 available for Apple internal for kernel extensions. 321 Locations - 322 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 323 Definition - 324 INSTALL_KF_MI_LCL_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES} 325 326 i. `EXPORT_MI_LIST` : Exports header file to all of xnu (bsd/, osfmk/, etc.) 327 for compilation only. Does not install anything into the SDK. 328 Definition - 329 EXPORT_MI_LIST = ${KERNELFILES} ${PRIVATE_KERNELFILES} 330 331 j. `INSTALL_KF_LIBCXX_MI_LIST` : Installs header file for in-kernel libc++ support. 332 Locations - 333 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders/kernel_sdkroot 334 Definition - 335 INSTALL_KF_LIBCXX_MI_LIST = ${LIBCXX_DATAFILES} 336 337 k. `INSTALL_EXCLAVEKIT_MI_LIST` : Installs header file to location that is 338 available for Apple internal for ExclaveKit. 339 Locations - 340 $(DSTROOT)/System/ExclaveKit/usr/include 341 Definition - 342 INSTALL_EXCLAVEKIT_MI_LIST = ${EXCLAVEKIT_DATAFILES} 343 344 l. `INSTALL_EXCLAVECORE_MI_LIST` : Installs header file to location that is 345 available for Apple internal for ExclaveCore. 346 Locations - 347 $(DSTROOT)/System/ExclaveCore/usr/include 348 Definition - 349 INSTALL_EXCLAVECORE_MI_LIST = ${EXCLAVECORE_DATAFILES} 350 351If you want to install the header file in a sub-directory of the paths 352described in (1), specify the directory name using two variables 353`INSTALL_MI_DIR` and `EXPORT_MI_DIR` as follows - 354 355 INSTALL_MI_DIR = dirname 356 EXPORT_MI_DIR = dirname 357 358If you want to install the module map file in a sub-directory, specify the 359directory name using the variable `INSTALL_MODULEMAP_MI_DIR` as follows - 360 361 INSTALL_MODULEMAP_MI_DIR = dirname 362 363A single header file can exist at different locations using the steps 364mentioned above. However it might not be desirable to make all the code 365in the header file available at all the locations. For example, you 366want to export a function only to kernel level but not user level. 367 368 You can use C language's pre-processor directive (#ifdef, #endif, #ifndef) 369 to control the text generated before a header file is installed. The kernel 370 only includes the code if the conditional macro is TRUE and strips out 371 code for FALSE conditions from the header file. 372 373 Some pre-defined macros and their descriptions are - 374 375 a. `PRIVATE` : If defined, enclosed definitions are considered System 376 Private Interfaces. These are visible within xnu and 377 exposed in user/kernel headers installed within the AppleInternal 378 "PrivateHeaders" sections of the System and Kernel frameworks. 379 b. `KERNEL_PRIVATE` : If defined, enclosed code is available to all of xnu 380 kernel and Apple internal kernel extensions and omitted from user 381 headers. 382 c. `BSD_KERNEL_PRIVATE` : If defined, enclosed code is visible exclusively 383 within the xnu/bsd module. 384 d. `MACH_KERNEL_PRIVATE`: If defined, enclosed code is visible exclusively 385 within the xnu/osfmk module. 386 e. `XNU_KERNEL_PRIVATE`: If defined, enclosed code is visible exclusively 387 within xnu. 388 f. `KERNEL` : If defined, enclosed code is available within xnu and kernel 389 extensions and is not visible in user level header files. Only the 390 header files installed in following paths will have the code - 391 392 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/Headers 393 $(DSTROOT)/System/Library/Frameworks/Kernel.framework/PrivateHeaders 394 g. `DRIVERKIT`: If defined, enclosed code is visible exclusively in the 395 DriverKit SDK headers used by userspace drivers. 396 h. `EXCLAVEKIT`: If defined, enclosed code is visible exclusively in the 397 ExclaveKit SDK headers. 398 i. `EXCLAVECORE`: If defined, enclosed code is visible exclusively in the 399 ExclaveCore SDK headers. 400 401Module map file name convention 402=============================== 403 404In the simple case, a subdirectory of `usr/include` or `usr/local/include` 405can be represented by a standalone module. Where this is the case, set 406`INSTALL_MODULEMAP_MI_DIR` to `INSTALL_MI_DIR` and install a `module.modulemap` 407file there. `module.modulemap` is used even for private modules in 408`usr/local/include`; `module.private.modulemap` is not used. Caveat: in order 409to stay in the simple case, the module name needs to be exactly the same as 410the directory name. If that's not possible, then the following method will 411need to be applied. 412 413`xnu` contributes to the modules defined in CoreOSModuleMaps by installing 414module map files that are sourced from `usr/include/module.modulemap` and 415`usr/local/include/module.modulemap`. The naming convention for the `xnu` 416module map files are as follows. 417 418 a. Ideally the module map file covers an entire directory. A module map 419 file covering `usr/include/a/b/c` would be named `a_b_c.modulemap`. 420 `usr/local/include/a/b/c` would be `a_b_c_private.modulemap`. 421 b. Some headers are special and require their own module. In that case, 422 the module map file would be named after the module it defines. 423 A module map file defining the module `One.Two.Three` would be named 424 `one_two_three.modulemap`. 425 426Conditional compilation 427======================= 428 429`xnu` offers the following mechanisms for conditionally compiling code: 430 431 a. *CPU Characteristics* If the code you are guarding has specific 432 characterstics that will vary only based on the CPU architecture being 433 targeted, use this option. Prefer checking for features of the 434 architecture (e.g. `__LP64__`, `__LITTLE_ENDIAN__`, etc.). 435 b. *New Features* If the code you are guarding, when taken together, 436 implements a feature, you should define a new feature in `config/MASTER` 437 and use the resulting `CONFIG` preprocessor token (e.g. for a feature 438 named `config_virtual_memory`, check for `#if CONFIG_VIRTUAL_MEMORY`). 439 This practice ensures that existing features may be brought to other 440 platforms by simply changing a feature switch. 441 c. *Existing Features* You can use existing features if your code is 442 strongly tied to them (e.g. use `SECURE_KERNEL` if your code implements 443 new functionality that is exclusively relevant to the trusted kernel and 444 updates the definition/understanding of what being a trusted kernel means). 445 446It is recommended that you avoid compiling based on the target platform. `xnu` 447does not define the platform macros from `TargetConditionals.h` 448(`TARGET_OS_OSX`, `TARGET_OS_IOS`, etc.). 449 450 451Debugging xnu 452============= 453 454By default, the kernel reboots in the event of a panic. 455This behavior can be overriden by the `debug` boot-arg -- `debug=0x14e` will cause a panic to wait for a debugger to attach. 456To boot a kernel so it can be debugged by an attached machine, override the `kdp_match_name` boot-arg with the appropriate `ifconfig` interface. 457Ethernet, Thunderbolt, and serial debugging are supported, depending on the hardware. 458 459Use LLDB to debug the kernel: 460 461 ; xcrun -sdk macosx lldb <path-to-unstripped-kernel> 462 (lldb) gdb-remote [<host-ip>:]<port> 463 464The debug info for the kernel (dSYM) comes with a set of macros to support kernel debugging. 465To load these macros automatically when attaching to the kernel, add the following to `~/.lldbinit`: 466 467 settings set target.load-script-from-symbol-file true 468 469`tools/lldbmacros` contains the source for these commands. 470See the README in that directory for their usage, or use the built-in LLDB help with: 471 472 (lldb) help showcurrentstacks 473 474