1XNU startup sequence 2==================== 3 4Adding code to run during early boot. 5 6### General Principles 7 8XNU Startup sequence is driven by the `<kern/startup.h>` module. 9 10The startup sequence is made of individual subsystems (the `STARTUP_SUB_*` 11values of the `startup_subsystem_id_t` type) that get initialized in sequence. 12 13A subsystem can use ranks to order the various initializers that make up its 14initialization sequence. Usage of ranks is custom to each subsystem and must be 15documented in this file. 16 17The subsystem module will basically run hooks in that order: 18 19``` 20for (subsystem 0 -> N) { 21 for (rank 0 -> N) { 22 // run in no particular order for a given rank in the given subsystem 23 init(subsystem, rank); 24 } 25} 26``` 27 28### Extending the startup sequence 29 30When extending the startup sequence: 31 321. add a new value to the `startup_subsystem_id_t` enum in the right order 332. document what services this phase provides, and how it uses ranks in this 34 file. 35 36 37When hooking with a given subsystem, consult this documentation to use the 38proper rank for your callback. 39 40If a new rank needs to be used, update this documentation in the proper section. 41 42--------------------------------------------------------------------------------- 43 44 45`STARTUP_SUB_TUNABLES` 46---------------------- 47 48### Description 49 50Initializes various globals that alter the behavior of the kernel, lookup 51tables, ... Available hooks are: 52 53- `TUNABLES`: parses a boot arg into a global that will become read-only at 54 lockdown time, 55- `TUNABLE_WRITEABLE`: same as `TUNABLE` but the global will not be locked down. 56 57### Rank usage 58 59- Rank 1: 60 - All uses of `TUNABLE`, `TUNABLE_WRITEABLE` 61 - CSR configuration from DeviceTree or boot-args 62 - CTRR configuration from DeviceTree 63 - SMR initialization 64- Middle: globals that require complex initialization (e.g. SFI classes). 65 66 67`STARTUP_SUB_TIMEOUTS` 68---------------------- 69 70## Description 71 72Initializes machine timeouts, which are device-tree/boot-args 73configurable timeouts for low level machine code. 74 75See the comments for the MACHINE_TIMEOUT macro on how they are used in 76detail. 77 78- Rank 1: `MACHINE_TIMEOUT` specifications. 79- Rank 2: `ml_io_timeouts_init` for scheduler hygiene. 80- Middle: Global lock timeouts that are derived from machine timeouts. 81 82`STARTUP_SUB_LOCKS` 83------------------- 84 85### Description 86 87Initializes early locks that do not require any memory allocations to be 88initialized. Available hooks are: 89 90- `LCK_GRP_DECLARE*`: automatically initialized lock groups, 91- `LCK_ATTR_DECLARE`: automatically initialized lock attributes, 92- `LCK_SPIN_DECLARE*`: automatically initialized spinlocks, 93- `LCK_RW_DECLARE`: automatically initialized reader/writer lock, 94- `LCK_MTX_DECLARE`: automatically initialized mutex, 95- `SIMPLE_LOCK_DECLARE*`: automatically initialized simple locks. 96 97### Rank usage 98 99- Rank 1: Initializes the module (`lck_mod_init`), 100- Rank 2: `LCK_ATTR_DECLARE`, `LCK_GRP_DECLARE*` 101- Rank 3: compact lock group table init 102- Rank 4: `LCK_SPIN_DECLARE*`, `LCK_MTX_DECLARE*`, 103 `LCK_RW_DECLARE`, `SIMPLE_LOCK_DECLARE*`. 104 105 106`STARTUP_SUB_KPRINTF` 107--------------------- 108 109### Description 110 111Initializes the kprintf subsystem. 112 113### Rank usage 114 115- Rank 1: calls the module initializer (`PE_init_kprintf`). 116 117 118`STARTUP_SUB_PMAP_STEAL` 119------------------------ 120 121### Description 122 123Allows for subsystems to steal early memory. 124 125### Rank usage 126 127- First rank: 128 - `cpu_data_startup_init`: Allocate per-CPU memory that needs to be accessible with MMU disabled 129 - `socd_client_init`: Steal memory for SoC diagnostics 130 - `vm_map_steal_memory`: Allocate bootstrap VM maps prior to the zone allocator coming up 131 132- Last rank: 133 - `init_ecc_bad_pages`: Exclude frames detected as bad from frame allocator 134 135`STARTUP_SUB_KMEM` 136------------------ 137 138### Description 139 140Denotes that `kmem_alloc` is now usable. 141 142### Rank usage 143 144- First rank: 145 - `zone_set_map_sizes`: Select physical limits for zone map 146 - `vm_compressor_set_size`: Reserve VA for the compressor submap 147 148- Rank 2: 149 - `kmem_range_startup_init`: Initialize data structures associated wiht ranges registered via 150 the `KMEM_RANGE_REGISTER_[STATIC|DYNAMIC]` mechanisms. 151 152- Rank 3: 153 - `kmem_range_init`: Shuffle and initialize ranges that have been registered up to now 154 155- Last rank: 156 - `io_map_init`: Creates an early `kernel_map` carve-out for mapping memory shared with devices 157 158`STARTUP_SUB_ZALLOC` 159-------------------- 160 161### Description 162 163Initializes the zone allocator. 164 165- `ZONE_DEFINE`, `ZONE_INIT`: automatically initialized permanent zones. 166- `ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`: zone and kalloc heap views. 167 168 169### Rank usage 170 171- Rank 1: `zone_init`: setup the zone subsystem, this allows for the already 172 created VM/pmap zones to become dynamic. 173 174- Rank 2: `vm_page_module_init`: create the "vm pages" zone. 175 The `vm_page_zone` must be created prior to `kalloc_init`; that routine can 176 trigger `zalloc()`s (for e.g. mutex statistic structure initialization). 177 178 The `vm_page_zone` must exist to satisfy fictitious page allocations 179 (which are used for guard pages by the guard mode zone allocator). 180 181- Rank 3: Initialize kalloc. 182 183- Rank 4: Handle `ZONE_DEFINE` and `ZONE_INIT`. 184 185- Middle: zone and kalloc heaps (`ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`). 186 187`STARTUP_SUB_KTRACE` 188-------------------- 189 190### Description 191 192Initializes kdebug and kperf and starts tracing if requested with boot-args. 193 194### Rank usage 195 196N/A. 197 198`STARTUP_SUB_PERCPU` 199-------------------- 200 201### Description 202 203Initializes the percpu subsystem. 204 205### Rank usage 206 207Rank 1: allocates the percpu memory, `percpu_foreach_base` and `percpu_foreach` 208 become usable. 209 210Rank 2: sets up static percpu counters. 211 212 213### Rank usage 214 215- Rank 1: `LCK_MTX_DECLARE`. 216 217`STARTUP_SUB_CODESIGNING` 218------------------------- 219 220### Description 221 222Initializes the codesigning subsystem. 223 224### Rank usage 225 226- Rank 1: calls the module initializer (`cs_init`). 227 228`STARTUP_SUB_OSLOG` 229------------------- 230 231### Description 232 233Initializes the `os_log` facilities. 234 235### Rank usage 236 237- Rank 1: Calls the module initializer (`oslog_init`). 238 239 240`STARTUP_SUB_MACH_IPC` 241---------------------- 242 243### Description 244 245Initializes the Mach IPC subsystem. 246 247### Rank usage 248 249- Rank 1: Initializes IPC submodule globals (ipc tables, voucher hashes, ...) 250- Rank last: Final IPC initialization. 251 252 253`STARTUP_SUB_THREAD_CALL` 254------------------------- 255 256### Description 257 258Initializes the Thread call subsystem (and dependent subsystems). 259 260### Rank usage 261 262- Rank 1: Initiailizes the thread call subsystem 263- Rank Middle: Initialize modules needing thread calls 264 265 266`STARTUP_SUB_SYSCTL` 267-------------------- 268 269### Description 270 271Initializes the sysctl kernel subsystem 272 273### Rank usage 274 275- Rank 1: automatic `SYSCTL_NODE` registration. 276- Rank 2: automatic `SYSCTL_OID` registration. 277- Middle: other manual early registrations. 278- Last: registrations of dummy nodes in the constant nodes to allow extension. 279 280 281`STARTUP_SUB_EARLY_BOOT` 282------------------------ 283 284### Description 285 286Denotes that subsystems that expect to operate with 287interrupts or preemption enabled may begin enforcement. 288 289### Rank usage 290 291- Rank 1: Initialize some BSD globals 292- Middle: Initialize some early BSD subsystems and tightbeam runtime 293 294 295`STARTUP_SUB_EXCLAVES` 296------------------------ 297 298### Description 299 300Early exclaves initialization. 301 302### Rank usage 303 304- Rank 1: Determine run-time support for exclaves 305- Middle: Compute exclaves carveout size 306 307`STARTUP_SUB_LOCKDOWN` 308---------------------- 309 310### Description 311 312Denotes that the kernel is locking down, this phase should never be hooked. 313When the kernel locks down: 314 315- data marked `__startup_data` or `__startup_const`, and code marked 316 `__startup_func`, is unmapped; 317- data marked `__security_const_late` or `SECURITY_READ_ONLY_LATE` becomes 318 read-only. 319 320### Rank usage 321 322N/A. 323