doc/startup.md

   1 XNU startup sequence
   2 ====================
   3
   4 ### General Principles
   5
   6 XNU Startup sequence is driven by the `<kern/startup.h>` module.
   7
   8 The startup sequence is made of individual subsystems (the `STARTUP_SUB_*`
   9 values of the `startup_subsystem_id_t` type) that get initialized in sequence.
  10
  11 A subsystem can use ranks to order the various initializers that make up its
  12 initialization sequence. Usage of ranks is custom to each subsystem and must be
  13 documented in this file.
  14
  15 The subsystem module will basically run hooks in that order:
  16
  17 ```
  18 for (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
  28 When extending the startup sequence:
  29
  30 1. add a new value to the `startup_subsystem_id_t` enum in the right order
  31 2. document what services this phase provides, and how it uses ranks in this
  32    file.
  33
  34
  35 When hooking with a given subsystem, consult this documentation to use the
  36 proper rank for your callback.
  37
  38 If 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
  48 Initializes various globals that alter the behavior of the kernel, lookup
  49 tables, ... 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_LOCKS_EARLY`
  62 -------------------------
  63
  64 ### Description
  65
  66 Initializes early locks that do not require any memory allocations to be
  67 initialized. Available hooks are:
  68
  69 - `LCK_GRP_DECLARE*`: automatically initialized lock groups,
  70 - `LCK_GRP_ATTR_DECLARE`: automatically initialized lock group attributes,
  71 - `LCK_ATTR_DECLARE`: automatically initialized lock attributes,
  72 - `LCK_SPIN_DECLARE*`: automatically initialized spinlocks,
  73 - `LCK_RW_DECLARE`: automatically initialized reader/writer lock,
  74 - `LCK_MTX_EARLY_DECLARE*`: automatically initialized mutexes, with statically
  75   allocated buffers for statistics/tracing,
  76 - `SIMPLE_LOCK_DECLARE*`: automatically initialized simple locks.
  77
  78 ### Rank usage
  79
  80 - Rank 1: Initializes the module (`lck_mod_init`),
  81 - Rank 2: `LCK_GRP_ATTR_DECLARE`, `LCK_ATTR_DECLARE`,
  82 - Rank 3: `LCK_GRP_DECLARE*`
  83 - Rank 4: `LCK_SPIN_DECLARE*`, `LCK_MTX_EARLY_DECLARE*`,
  84   `LCK_RW_DECLARE`, `SIMPLE_LOCK_DECLARE*`.
  85
  86
  87 `STARTUP_SUB_KPRINTF`
  88 ---------------------
  89
  90 ### Description
  91
  92 Initializes the kprintf subsystem.
  93
  94 ### Rank usage
  95
  96 - Rank 1: calls the module initializer (`PE_init_kprintf`).
  97
  98
  99 `STARTUP_SUB_PMAP_STEAL`
 100 ------------------------
 101
 102 ### Description
 103
 104 Allows for subsystems to steal early memory.
 105
 106 ### Rank usage
 107
 108 N/A.
 109
 110
 111 `STARTUP_SUB_VM_KERNEL`
 112 -----------------------
 113
 114 ### Description
 115
 116 Denotes that the early kernel VM is initialized.
 117
 118 ### Rank usage
 119
 120 N/A.
 121
 122
 123 `STARTUP_SUB_KMEM`
 124 ------------------
 125
 126 ### Description
 127
 128 Denotes that `kernel_memory_allocate` is now usable.
 129
 130 ### Rank usage
 131
 132 N/A.
 133
 134
 135 `STARTUP_SUB_KMEM_ALLOC`
 136 ------------------------
 137
 138 ### Description
 139
 140 Denotes that `kmem_alloc` is now usable.
 141
 142 ### Rank usage
 143
 144 N/A.
 145
 146
 147 `STARTUP_SUB_ZALLOC`
 148 --------------------
 149
 150 ### Description
 151
 152 Initializes the zone allocator.
 153
 154 - `ZONE_DECLARE`, `ZONE_INIT`: automatically initialized permanent zones.
 155 - `ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`: zone and kalloc heap views.
 156
 157
 158 ### Rank usage
 159
 160 - Rank 1: `zone_init`: setup the zone subsystem, this allows for the already
 161   created VM/pmap zones to become dynamic.
 162
 163 - Rank 2: `vm_page_module_init`: create the "vm pages" zone.
 164   The `vm_page_zone` must be created prior to `kalloc_init`; that routine can
 165   trigger `zalloc()`s (for e.g. mutex statistic structure initialization).
 166
 167   The `vm_page_zone` must exist to satisfy fictitious page allocations
 168   (which are used for guard pages by the guard mode zone allocator).
 169
 170 - Rank 3: Initialize kalloc.
 171
 172 - Rank 4: Enable zone caching (uses kalloc)
 173
 174 - Middle: for any initialization that only requires kalloc/zalloc
 175           runs `ZONE_DECLARE` and `ZONE_INIT`.
 176
 177 - Last:   zone and kalloc heaps (`ZONE_VIEW_DEFINE`, `KALLOC_HEAP_DEFINE`).
 178
 179
 180 `STARTUP_SUB_PERCPU`
 181 --------------------
 182
 183 ### Description
 184
 185 Initializes the percpu subsystem.
 186
 187 ### Rank usage
 188
 189 Rank 1: allocates the percpu memory, `percpu_foreach_base` and `percpu_foreach`
 190         become usable.
 191
 192 Rank 2: sets up static percpu counters.
 193
 194
 195 `STARTUP_SUB_LOCKS`
 196 -------------------
 197
 198 ### Description
 199
 200 Initializes kernel locks that might require allocations (due to statistics and
 201 tracing features). Available hooks are:
 202
 203 - `LCK_MTX_DECLARE`: automatically initialized mutex,
 204
 205
 206 ### Rank usage
 207
 208 - Rank 1: `LCK_MTX_DECLARE`.
 209
 210 `STARTUP_SUB_CODESIGNING`
 211 -------------------------
 212
 213 ### Description
 214
 215 Initializes the codesigning subsystem.
 216
 217 ### Rank usage
 218
 219 - Rank 1: calls the module initializer (`cs_init`).
 220
 221
 222 `STARTUP_SUB_OSLOG`
 223 -------------------
 224
 225 ### Description
 226
 227 Initializes the `os_log` facilities.
 228
 229 ### Rank usage
 230
 231 - Rank 1: Calls the module initializer (`oslog_init`).
 232
 233
 234 `STARTUP_SUB_MACH_IPC`
 235 -------------------
 236
 237 ### Description
 238
 239 Initializes the Mach IPC subsystem.
 240
 241 ### Rank usage
 242
 243 - Rank 1: Initializes IPC submodule globals (ipc tables, voucher hashes, ...)
 244 - Rank last: Final IPC initialization.
 245
 246
 247 `STARTUP_SUB_SYSCTL`
 248 -------------------------
 249
 250 ### Description
 251
 252 Initializes the sysctl kernel subsystem
 253
 254 ### Rank usage
 255
 256 - Rank 1: automatic `SYSCTL_NODE` registration.
 257 - Rank 2: automatic `SYSCTL_OID` registration.
 258 - Middle: other manual early registrations.
 259 - Last: registrations of dummy nodes in the constant nodes to allow extension.
 260
 261
 262 `STARTUP_SUB_EARLY_BOOT`
 263 ------------------------
 264
 265 ### Description
 266
 267 Denotes that subsystems that expect to operate with
 268 interrupts or preemption enabled may begin enforcement.
 269
 270 ### Rank usage
 271
 272 N/A.
 273
 274
 275 `STARTUP_SUB_LOCKDOWN`
 276 ----------------------
 277
 278 ### Description
 279
 280 Denotes that the kernel is locking down, this phase should never be hooked.
 281 When the kernel locks down:
 282
 283 - data marked `__startup_data` and code marked `__startup_func` is unmapped,
 284 - data marked `__security_const_late` or `SECURITY_READ_ONLY_LATE` becomes
 285   read-only.
 286
 287 ### Rank usage
 288
 289 N/A.