1XNU startup sequence 2==================== 3 4Adding code to run during early boot. 5 6### General Principles 7 8XNU Startup sequence is driven by the `<kern/startup.h>` module. 9 10The startup sequence is made of individual subsystems (the `STARTUP_SUB_*` 11values of the `startup_subsystem_id_t` type) that get initialized in sequence. 12 13A subsystem can use ranks to order the various initializers that make up its 14initialization sequence. Usage of ranks is custom to each subsystem and must be 15documented in this file. 16 17The subsystem module will basically run hooks in that order: 18 19``` 20for (subsystem 0 -> N) { 21 for (rank 0 -> N) { 22 // run in no particular order for a given rank in the given subsystem 23 init(subsystem, rank); 24 } 25} 26``` 27 28### Extending the startup sequence 29 30When extending the startup sequence: 31 321. add a new value to the `startup_subsystem_id_t` enum in the right order 332. document what services this phase provides, and how it uses ranks in this 34 file. 35 36 37When hooking with a given subsystem, consult this documentation to use the 38proper rank for your callback. 39 40If a new rank needs to be used, update this documentation in the proper section. 41 42--------------------------------------------------------------------------------- 43 44 45`STARTUP_SUB_TUNABLES` 46---------------------- 47 48### Description 49 50Initializes various globals that alter the behavior of the kernel, lookup 51tables, ... Available hooks are: 52 53- `TUNABLES`: parses a boot arg into a global that will become read-only at 54 lockdown time, 55- `TUNABLE_WRITEABLE`: same as `TUNABLE` but the global will not be locked down. 56 57### Rank usage 58 59- Rank 1: `TUNABLE`, `TUNABLE_WRITEABLE` 60- Middle: globals that require complex initialization (e.g. SFI classes). 61 62 63`STARTUP_SUB_TIMEOUTS` 64---------------------- 65 66## Description 67 68Initializes machine timeouts, which are device-tree/boot-args 69configurable timeouts for low level machine code. 70 71See the comments for the MACHINE_TIMEOUT macro on how they are used in 72detail. 73 74- Rank 1: `MACHINE_TIMEOUT` 75- Middle: global lock timeouts that are derived from machine timeouts. 76 77`STARTUP_SUB_LOCKS` 78------------------- 79 80### Description 81 82Initializes early locks that do not require any memory allocations to be 83initialized. Available hooks are: 84 85- `LCK_GRP_DECLARE*`: automatically initialized lock groups, 86- `LCK_ATTR_DECLARE`: automatically initialized lock attributes, 87- `LCK_SPIN_DECLARE*`: automatically initialized spinlocks, 88- `LCK_RW_DECLARE`: automatically initialized reader/writer lock, 89- `LCK_MTX_DECLARE`: automatically initialized mutex, 90- `SIMPLE_LOCK_DECLARE*`: automatically initialized simple locks. 91 92### Rank usage 93 94- Rank 1: Initializes the module (`lck_mod_init`), 95- Rank 2: `LCK_ATTR_DECLARE`, `LCK_GRP_DECLARE*` 96- Rank 3: compact lock group table init 97- Rank 4: `LCK_SPIN_DECLARE*`, `LCK_MTX_DECLARE*`, 98 `LCK_RW_DECLARE`, `SIMPLE_LOCK_DECLARE*`. 99 100 101`STARTUP_SUB_KPRINTF` 102--------------------- 103 104### Description 105 106Initializes the kprintf subsystem. 107 108### Rank usage 109 110- Rank 1: calls the module initializer (`PE_init_kprintf`). 111 112 113`STARTUP_SUB_PMAP_STEAL` 114------------------------ 115 116### Description 117 118Allows for subsystems to steal early memory. 119 120### Rank usage 121 122N/A. 123 124 125`STARTUP_SUB_KMEM` 126------------------ 127 128### Description 129 130Denotes that `kmem_alloc` is now usable. 131 132### Rank usage 133 134N/A. 135 136`STARTUP_SUB_ZALLOC` 137-------------------- 138 139### Description 140 141Initializes the zone allocator. 142 143- `ZONE_DEFINE`, `ZONE_INIT`: automatically initialized permanent zones. 144- `ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`: zone and kalloc heap views. 145 146 147### Rank usage 148 149- Rank 1: `zone_init`: setup the zone subsystem, this allows for the already 150 created VM/pmap zones to become dynamic. 151 152- Rank 2: `vm_page_module_init`: create the "vm pages" zone. 153 The `vm_page_zone` must be created prior to `kalloc_init`; that routine can 154 trigger `zalloc()`s (for e.g. mutex statistic structure initialization). 155 156 The `vm_page_zone` must exist to satisfy fictitious page allocations 157 (which are used for guard pages by the guard mode zone allocator). 158 159- Rank 3: Initialize kalloc. 160 161- Rank 4: Handle `ZONE_DEFINE` and `ZONE_INIT`. 162 163- Middle: zone and kalloc heaps (`ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`). 164 165`STARTUP_SUB_KTRACE` 166-------------------- 167 168### Description 169 170Initializes kdebug and kperf and starts tracing if requested with boot-args. 171 172### Rank usage 173 174N/A. 175 176`STARTUP_SUB_PERCPU` 177-------------------- 178 179### Description 180 181Initializes the percpu subsystem. 182 183### Rank usage 184 185Rank 1: allocates the percpu memory, `percpu_foreach_base` and `percpu_foreach` 186 become usable. 187 188Rank 2: sets up static percpu counters. 189 190 191### Rank usage 192 193- Rank 1: `LCK_MTX_DECLARE`. 194 195`STARTUP_SUB_CODESIGNING` 196------------------------- 197 198### Description 199 200Initializes the codesigning subsystem. 201 202### Rank usage 203 204- Rank 1: calls the module initializer (`cs_init`). 205 206`STARTUP_SUB_OSLOG` 207------------------- 208 209### Description 210 211Initializes the `os_log` facilities. 212 213### Rank usage 214 215- Rank 1: Calls the module initializer (`oslog_init`). 216 217 218`STARTUP_SUB_MACH_IPC` 219---------------------- 220 221### Description 222 223Initializes the Mach IPC subsystem. 224 225### Rank usage 226 227- Rank 1: Initializes IPC submodule globals (ipc tables, voucher hashes, ...) 228- Rank last: Final IPC initialization. 229 230 231`STARTUP_SUB_THREAD_CALL` 232------------------------- 233 234### Description 235 236Initializes the Thread call subsystem (and dependent subsystems). 237 238### Rank usage 239 240- Rank 1: Initiailizes the thread call subsystem 241- Rank Middle: Initialize modules needing thread calls 242 243 244`STARTUP_SUB_SYSCTL` 245-------------------- 246 247### Description 248 249Initializes the sysctl kernel subsystem 250 251### Rank usage 252 253- Rank 1: automatic `SYSCTL_NODE` registration. 254- Rank 2: automatic `SYSCTL_OID` registration. 255- Middle: other manual early registrations. 256- Last: registrations of dummy nodes in the constant nodes to allow extension. 257 258 259`STARTUP_SUB_EARLY_BOOT` 260------------------------ 261 262### Description 263 264Denotes that subsystems that expect to operate with 265interrupts or preemption enabled may begin enforcement. 266 267### Rank usage 268 269- Rank 1: Initialize some BSD globals 270- Middle: Initialize some early BSD subsystems 271 272 273`STARTUP_SUB_EXCLAVES` 274------------------------ 275 276### Description 277 278Early exclaves initialization. 279 280### Rank usage 281 282- Rank 1: Determine run-time support for exclaves 283- Middle: Initialize tightbeam runtime 284 285 286`STARTUP_SUB_LOCKDOWN` 287---------------------- 288 289### Description 290 291Denotes that the kernel is locking down, this phase should never be hooked. 292When the kernel locks down: 293 294- data marked `__startup_data` or `__startup_const`, and code marked 295 `__startup_func`, is unmapped; 296- data marked `__security_const_late` or `SECURITY_READ_ONLY_LATE` becomes 297 read-only. 298 299### Rank usage 300 301N/A. 302