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