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`STARTUP_SUB_TIMEOUTS` 61---------------------- 62 63## Description 64 65Initializes machine timeouts, which are device-tree/boot-args 66configurable timeouts for low level machine code. 67 68See the comments for the MACHINE_TIMEOUT macro on how they are used in 69detail. 70 71- Rank 1: `MACHINE_TIMEOUT` 72 73`STARTUP_SUB_LOCKS_EARLY` 74------------------------- 75 76### Description 77 78Initializes early locks that do not require any memory allocations to be 79initialized. Available hooks are: 80 81- `LCK_GRP_DECLARE*`: automatically initialized lock groups, 82- `LCK_ATTR_DECLARE`: automatically initialized lock attributes, 83- `LCK_SPIN_DECLARE*`: automatically initialized spinlocks, 84- `LCK_RW_DECLARE`: automatically initialized reader/writer lock, 85- `LCK_MTX_EARLY_DECLARE*`: automatically initialized mutexes, with statically 86 allocated buffers for statistics/tracing, 87- `SIMPLE_LOCK_DECLARE*`: automatically initialized simple locks. 88 89### Rank usage 90 91- Rank 1: Initializes the module (`lck_mod_init`), 92- Rank 2: `LCK_ATTR_DECLARE`, 93- Rank 3: `LCK_GRP_DECLARE*` 94- Rank 4: `LCK_SPIN_DECLARE*`, `LCK_MTX_EARLY_DECLARE*`, 95 `LCK_RW_DECLARE`, `SIMPLE_LOCK_DECLARE*`. 96 97 98`STARTUP_SUB_KPRINTF` 99--------------------- 100 101### Description 102 103Initializes the kprintf subsystem. 104 105### Rank usage 106 107- Rank 1: calls the module initializer (`PE_init_kprintf`). 108 109 110`STARTUP_SUB_PMAP_STEAL` 111------------------------ 112 113### Description 114 115Allows for subsystems to steal early memory. 116 117### Rank usage 118 119N/A. 120 121 122`STARTUP_SUB_KMEM` 123------------------ 124 125### Description 126 127Denotes that `kmem_alloc` is now usable. 128 129### Rank usage 130 131N/A. 132 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: Enable zone caching & logging (uses kalloc) 160 161- Middle: for any initialization that only requires kalloc/zalloc 162 runs `ZONE_DEFINE` and `ZONE_INIT`. 163 164- Last: zone and kalloc heaps (`ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`). 165 166 167`STARTUP_SUB_PERCPU` 168-------------------- 169 170### Description 171 172Initializes the percpu subsystem. 173 174### Rank usage 175 176Rank 1: allocates the percpu memory, `percpu_foreach_base` and `percpu_foreach` 177 become usable. 178 179Rank 2: sets up static percpu counters. 180 181 182`STARTUP_SUB_LOCKS` 183------------------- 184 185### Description 186 187Initializes kernel locks that might require allocations (due to statistics and 188tracing features). Available hooks are: 189 190- `LCK_MTX_DECLARE`: automatically initialized mutex, 191 192 193### Rank usage 194 195- Rank 1: `LCK_MTX_DECLARE`. 196 197`STARTUP_SUB_CODESIGNING` 198------------------------- 199 200### Description 201 202Initializes the codesigning subsystem. 203 204### Rank usage 205 206- Rank 1: calls the module initializer (`cs_init`). 207 208 209`STARTUP_SUB_OSLOG` 210------------------- 211 212### Description 213 214Initializes the `os_log` facilities. 215 216### Rank usage 217 218- Rank 1: Calls the module initializer (`oslog_init`). 219 220 221`STARTUP_SUB_MACH_IPC` 222---------------------- 223 224### Description 225 226Initializes the Mach IPC subsystem. 227 228### Rank usage 229 230- Rank 1: Initializes IPC submodule globals (ipc tables, voucher hashes, ...) 231- Rank last: Final IPC initialization. 232 233 234`STARTUP_SUB_THREAD_CALL` 235------------------------- 236 237### Description 238 239Initializes the Thread call subsystem (and dependent subsystems). 240 241### Rank usage 242 243- Rank 1: Initiailizes the thread call subsystem 244- Rank Middle: Initialize modules needing thread calls 245 246 247`STARTUP_SUB_SYSCTL` 248-------------------- 249 250### Description 251 252Initializes the sysctl kernel subsystem 253 254### Rank usage 255 256- Rank 1: automatic `SYSCTL_NODE` registration. 257- Rank 2: automatic `SYSCTL_OID` registration. 258- Middle: other manual early registrations. 259- Last: registrations of dummy nodes in the constant nodes to allow extension. 260 261 262`STARTUP_SUB_EARLY_BOOT` 263------------------------ 264 265### Description 266 267Denotes that subsystems that expect to operate with 268interrupts or preemption enabled may begin enforcement. 269 270### Rank usage 271 272- Rank 1: Initialize some BSD globals 273- Middle: Initialize some early BSD subsystems 274 275 276`STARTUP_SUB_LOCKDOWN` 277---------------------- 278 279### Description 280 281Denotes that the kernel is locking down, this phase should never be hooked. 282When the kernel locks down: 283 284- data marked `__startup_data` and code marked `__startup_func` is unmapped, 285- data marked `__security_const_late` or `SECURITY_READ_ONLY_LATE` becomes 286 read-only. 287 288### Rank usage 289 290N/A. 291