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_VM_KERNEL` 123----------------------- 124 125### Description 126 127Denotes that the early kernel VM is initialized. 128 129### Rank usage 130 131N/A. 132 133 134`STARTUP_SUB_KMEM` 135------------------ 136 137### Description 138 139Denotes that `kernel_memory_allocate` is now usable. 140 141### Rank usage 142 143N/A. 144 145 146`STARTUP_SUB_ZALLOC` 147-------------------- 148 149### Description 150 151Initializes the zone allocator. 152 153- `ZONE_DEFINE`, `ZONE_INIT`: automatically initialized permanent zones. 154- `ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`: zone and kalloc heap views. 155 156 157### Rank usage 158 159- Rank 1: `zone_init`: setup the zone subsystem, this allows for the already 160 created VM/pmap zones to become dynamic. 161 162- Rank 2: `vm_page_module_init`: create the "vm pages" zone. 163 The `vm_page_zone` must be created prior to `kalloc_init`; that routine can 164 trigger `zalloc()`s (for e.g. mutex statistic structure initialization). 165 166 The `vm_page_zone` must exist to satisfy fictitious page allocations 167 (which are used for guard pages by the guard mode zone allocator). 168 169- Rank 3: Initialize kalloc. 170 171- Rank 4: Enable zone caching & logging (uses kalloc) 172 173- Middle: for any initialization that only requires kalloc/zalloc 174 runs `ZONE_DEFINE` and `ZONE_INIT`. 175 176- Last: zone and kalloc heaps (`ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`). 177 178 179`STARTUP_SUB_PERCPU` 180-------------------- 181 182### Description 183 184Initializes the percpu subsystem. 185 186### Rank usage 187 188Rank 1: allocates the percpu memory, `percpu_foreach_base` and `percpu_foreach` 189 become usable. 190 191Rank 2: sets up static percpu counters. 192 193 194`STARTUP_SUB_LOCKS` 195------------------- 196 197### Description 198 199Initializes kernel locks that might require allocations (due to statistics and 200tracing features). Available hooks are: 201 202- `LCK_MTX_DECLARE`: automatically initialized mutex, 203 204 205### Rank usage 206 207- Rank 1: `LCK_MTX_DECLARE`. 208 209`STARTUP_SUB_CODESIGNING` 210------------------------- 211 212### Description 213 214Initializes the codesigning subsystem. 215 216### Rank usage 217 218- Rank 1: calls the module initializer (`cs_init`). 219 220 221`STARTUP_SUB_OSLOG` 222------------------- 223 224### Description 225 226Initializes the `os_log` facilities. 227 228### Rank usage 229 230- Rank 1: Calls the module initializer (`oslog_init`). 231 232 233`STARTUP_SUB_MACH_IPC` 234---------------------- 235 236### Description 237 238Initializes the Mach IPC subsystem. 239 240### Rank usage 241 242- Rank 1: Initializes IPC submodule globals (ipc tables, voucher hashes, ...) 243- Rank last: Final IPC initialization. 244 245 246`STARTUP_SUB_THREAD_CALL` 247------------------------- 248 249### Description 250 251Initializes the Thread call subsystem (and dependent subsystems). 252 253### Rank usage 254 255- Rank 1: Initiailizes the thread call subsystem 256- Rank Middle: Initialize modules needing thread calls 257 258 259`STARTUP_SUB_SYSCTL` 260-------------------- 261 262### Description 263 264Initializes the sysctl kernel subsystem 265 266### Rank usage 267 268- Rank 1: automatic `SYSCTL_NODE` registration. 269- Rank 2: automatic `SYSCTL_OID` registration. 270- Middle: other manual early registrations. 271- Last: registrations of dummy nodes in the constant nodes to allow extension. 272 273 274`STARTUP_SUB_EARLY_BOOT` 275------------------------ 276 277### Description 278 279Denotes that subsystems that expect to operate with 280interrupts or preemption enabled may begin enforcement. 281 282### Rank usage 283 284- Rank 1: Initialize some BSD globals 285- Middle: Initialize some early BSD subsystems 286 287 288`STARTUP_SUB_LOCKDOWN` 289---------------------- 290 291### Description 292 293Denotes that the kernel is locking down, this phase should never be hooked. 294When the kernel locks down: 295 296- data marked `__startup_data` and code marked `__startup_func` is unmapped, 297- data marked `__security_const_late` or `SECURITY_READ_ONLY_LATE` becomes 298 read-only. 299 300### Rank usage 301 302N/A. 303