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