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
 193 `STARTUP_SUB_LOCKS`
 194 -------------------
 195
 196 ### Description
 197
 198 Initializes kernel locks that might require allocations (due to statistics and
 199 tracing features). Available hooks are:
 200
 201 - `LCK_MTX_DECLARE`: automatically initialized mutex,
 202
 203
 204 ### Rank usage
 205
 206 - Rank 1: `LCK_MTX_DECLARE`.
 207
 208
 209 `STARTUP_SUB_CODESIGNING`
 210 -------------------------
 211
 212 ### Description
 213
 214 Initializes the codesigning subsystem.
 215
 216 ### Rank usage
 217
 218 - Rank 1: calls the module initializer (`cs_init`).
 219
 220
 221 `STARTUP_SUB_OSLOG`
 222 -------------------
 223
 224 ### Description
 225
 226 Initializes the `os_log` facilities.
 227
 228 ### Rank usage
 229
 230 - Rank 1: Calls the module initializer (`oslog_init`).
 231
 232
 233 `STARTUP_SUB_MACH_IPC`
 234 -------------------
 235
 236 ### Description
 237
 238 Initializes the Mach IPC subsystem.
 239
 240 ### Rank usage
 241
 242 - Rank 1: Initializes IPC submodule globals (ipc tables, voucher hashes, ...)
 243 - Rank last: Final IPC initialization.
 244
 245
 246 `STARTUP_SUB_EARLY_BOOT`
 247 ------------------------
 248
 249 ### Description
 250
 251 Denotes that subsystems that expect to operate with
 252 interrupts or preemption enabled may begin enforcement.
 253
 254 ### Rank usage
 255
 256 N/A.
 257
 258
 259 `STARTUP_SUB_LOCKDOWN`
 260 ----------------------
 261
 262 ### Description
 263
 264 Denotes that the kernel is locking down, this phase should never be hooked.
 265 When the kernel locks down:
 266
 267 - data marked `__startup_data` and code marked `__startup_func` is unmapped,
 268 - data marked `__security_const_late` or `SECURITY_READ_ONLY_LATE` becomes
 269   read-only.
 270
 271 ### Rank usage
 272
 273 N/A.
 274
 275