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: zone and kalloc heaps (`ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`). 162 163`STARTUP_SUB_KTRACE` 164-------------------- 165 166### Description 167 168Initializes kdebug and kperf and starts tracing if requested with boot-args. 169 170### Rank usage 171 172N/A. 173 174`STARTUP_SUB_PERCPU` 175-------------------- 176 177### Description 178 179Initializes the percpu subsystem. 180 181### Rank usage 182 183Rank 1: allocates the percpu memory, `percpu_foreach_base` and `percpu_foreach` 184 become usable. 185 186Rank 2: sets up static percpu counters. 187 188 189### Rank usage 190 191- Rank 1: `LCK_MTX_DECLARE`. 192 193`STARTUP_SUB_CODESIGNING` 194------------------------- 195 196### Description 197 198Initializes the codesigning subsystem. 199 200### Rank usage 201 202- Rank 1: calls the module initializer (`cs_init`). 203 204`STARTUP_SUB_OSLOG` 205------------------- 206 207### Description 208 209Initializes the `os_log` facilities. 210 211### Rank usage 212 213- Rank 1: Calls the module initializer (`oslog_init`). 214 215 216`STARTUP_SUB_MACH_IPC` 217---------------------- 218 219### Description 220 221Initializes the Mach IPC subsystem. 222 223### Rank usage 224 225- Rank 1: Initializes IPC submodule globals (ipc tables, voucher hashes, ...) 226- Rank last: Final IPC initialization. 227 228 229`STARTUP_SUB_THREAD_CALL` 230------------------------- 231 232### Description 233 234Initializes the Thread call subsystem (and dependent subsystems). 235 236### Rank usage 237 238- Rank 1: Initiailizes the thread call subsystem 239- Rank Middle: Initialize modules needing thread calls 240 241 242`STARTUP_SUB_SYSCTL` 243-------------------- 244 245### Description 246 247Initializes the sysctl kernel subsystem 248 249### Rank usage 250 251- Rank 1: automatic `SYSCTL_NODE` registration. 252- Rank 2: automatic `SYSCTL_OID` registration. 253- Middle: other manual early registrations. 254- Last: registrations of dummy nodes in the constant nodes to allow extension. 255 256 257`STARTUP_SUB_EARLY_BOOT` 258------------------------ 259 260### Description 261 262Denotes that subsystems that expect to operate with 263interrupts or preemption enabled may begin enforcement. 264 265### Rank usage 266 267- Rank 1: Initialize some BSD globals 268- Middle: Initialize some early BSD subsystems 269 270 271`STARTUP_SUB_LOCKDOWN` 272---------------------- 273 274### Description 275 276Denotes that the kernel is locking down, this phase should never be hooked. 277When the kernel locks down: 278 279- data marked `__startup_data` and code marked `__startup_func` is unmapped, 280- data marked `__security_const_late` or `SECURITY_READ_ONLY_LATE` becomes 281 read-only. 282 283### Rank usage 284 285N/A. 286