1XNU startup sequence 2==================== 3 4### General Principles 5 6XNU Startup sequence is driven by the `<kern/startup.h>` module. 7 8The startup sequence is made of individual subsystems (the `STARTUP_SUB_*` 9values of the `startup_subsystem_id_t` type) that get initialized in sequence. 10 11A subsystem can use ranks to order the various initializers that make up its 12initialization sequence. Usage of ranks is custom to each subsystem and must be 13documented in this file. 14 15The subsystem module will basically run hooks in that order: 16 17``` 18for (subsystem 0 -> N) { 19 for (rank 0 -> N) { 20 // run in no particular order for a given rank in the given subsystem 21 init(subsystem, rank); 22 } 23} 24``` 25 26### Extending the startup sequence 27 28When extending the startup sequence: 29 301. add a new value to the `startup_subsystem_id_t` enum in the right order 312. document what services this phase provides, and how it uses ranks in this 32 file. 33 34 35When hooking with a given subsystem, consult this documentation to use the 36proper rank for your callback. 37 38If a new rank needs to be used, update this documentation in the proper section. 39 40--------------------------------------------------------------------------------- 41 42 43`STARTUP_SUB_TUNABLES` 44---------------------- 45 46### Description 47 48Initializes various globals that alter the behavior of the kernel, lookup 49tables, ... Available hooks are: 50 51- `TUNABLES`: parses a boot arg into a global that will become read-only at 52 lockdown time, 53- `TUNABLE_WRITEABLE`: same as `TUNABLE` but the global will not be locked down. 54 55### Rank usage 56 57- Rank 1: `TUNABLE`, `TUNABLE_WRITEABLE` 58- Middle: globals that require complex initialization (e.g. SFI classes). 59 60 61`STARTUP_SUB_TIMEOUTS` 62---------------------- 63 64## Description 65 66Initializes machine timeouts, which are device-tree/boot-args 67configurable timeouts for low level machine code. 68 69See the comments for the MACHINE_TIMEOUT macro on how they are used in 70detail. 71 72- Rank 1: `MACHINE_TIMEOUT` 73- Middle: global lock timeouts that are derived from machine timeouts. 74 75`STARTUP_SUB_LOCKS` 76------------------- 77 78### Description 79 80Initializes early locks that do not require any memory allocations to be 81initialized. Available hooks are: 82 83- `LCK_GRP_DECLARE*`: automatically initialized lock groups, 84- `LCK_ATTR_DECLARE`: automatically initialized lock attributes, 85- `LCK_SPIN_DECLARE*`: automatically initialized spinlocks, 86- `LCK_RW_DECLARE`: automatically initialized reader/writer lock, 87- `LCK_MTX_DECLARE`: automatically initialized mutex, 88- `SIMPLE_LOCK_DECLARE*`: automatically initialized simple locks. 89 90### Rank usage 91 92- Rank 1: Initializes the module (`lck_mod_init`), 93- Rank 2: `LCK_ATTR_DECLARE`, `LCK_GRP_DECLARE*` 94- Rank 3: compact lock group table init 95- Rank 4: `LCK_SPIN_DECLARE*`, `LCK_MTX_DECLARE*`, 96 `LCK_RW_DECLARE`, `SIMPLE_LOCK_DECLARE*`. 97 98 99`STARTUP_SUB_KPRINTF` 100--------------------- 101 102### Description 103 104Initializes the kprintf subsystem. 105 106### Rank usage 107 108- Rank 1: calls the module initializer (`PE_init_kprintf`). 109 110 111`STARTUP_SUB_PMAP_STEAL` 112------------------------ 113 114### Description 115 116Allows for subsystems to steal early memory. 117 118### Rank usage 119 120N/A. 121 122 123`STARTUP_SUB_KMEM` 124------------------ 125 126### Description 127 128Denotes that `kmem_alloc` is now usable. 129 130### Rank usage 131 132N/A. 133 134`STARTUP_SUB_ZALLOC` 135-------------------- 136 137### Description 138 139Initializes the zone allocator. 140 141- `ZONE_DEFINE`, `ZONE_INIT`: automatically initialized permanent zones. 142- `ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`: zone and kalloc heap views. 143 144 145### Rank usage 146 147- Rank 1: `zone_init`: setup the zone subsystem, this allows for the already 148 created VM/pmap zones to become dynamic. 149 150- Rank 2: `vm_page_module_init`: create the "vm pages" zone. 151 The `vm_page_zone` must be created prior to `kalloc_init`; that routine can 152 trigger `zalloc()`s (for e.g. mutex statistic structure initialization). 153 154 The `vm_page_zone` must exist to satisfy fictitious page allocations 155 (which are used for guard pages by the guard mode zone allocator). 156 157- Rank 3: Initialize kalloc. 158 159- Rank 4: Handle `ZONE_DEFINE` and `ZONE_INIT`. 160 161- Middle: Enable zone caching & logging 162 163- Last: 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_LOCKDOWN` 274---------------------- 275 276### Description 277 278Denotes that the kernel is locking down, this phase should never be hooked. 279When the kernel locks down: 280 281- data marked `__startup_data` and code marked `__startup_func` is unmapped, 282- data marked `__security_const_late` or `SECURITY_READ_ONLY_LATE` becomes 283 read-only. 284 285### Rank usage 286 287N/A. 288