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