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