Platform, boot, and machine execution

Guide index · Architecture

This subsystem makes a compiled XNU kernel run on a particular CPU and platform: it establishes initial execution state, starts common kernel services, translates hardware exceptions into kernel operations, switches CPU context, and manages hardware address translations. Platform Expert (pexpert) connects boot arguments and device descriptions to early kernel setup and I/O Kit callbacks. The code is distributed across architecture directories rather than contained in one module. files.arm64, startup.c, pe_init.c.

Mermaid source

flowchart TD
    Boot[Bootloader / monitor entry] --> MD[Architecture bootstrap]
    MD --> Common[Common startup and first kernel thread]
    Common --> IO[Platform Expert and I/O Kit initialization]
    Common --> BSD[BSD initialization and PID 1]
    CPU[CPU exceptions and interrupts] --> Entry[Assembly vectors and saved state]
    Entry --> Dispatch[Trap / syscall / fault / interrupt dispatch]
    Dispatch --> VM[VM fault and pmap]
    Dispatch --> IPC[Mach IPC or kernel trap]
    Dispatch --> Proc[BSD syscall and signals]
    Dispatch --> Run[Scheduler and timers]
    Run --> Switch[Machine context switch]
    Switch --> VM
    IO --> HW[Platform CPU / device callbacks]

The arrows summarize interfaces, not one universal build configuration. ARM64 PPL and SPTM builds select different early boot and pmap implementations. x86_64 has separate entry, page-table, and power paths; osfmk/i386 contains much of its implementation despite the directory name. ARM build selection, x86 bootstrap.

Reading route

For a selector-by-selector view of system calls, use the machine entry-point catalog. It connects ARM64 SVC/platform/time paths and x86 syscall classes to the complete BSD and Mach catalogs. The AST chapters explain deferred work before those entries return.

1. Boot to PID 1: follow one configured machine from its assembly entry through startup phases, I/O Kit lockdown, root mounting, and launchd loading. Continue with bootstrap memory and lockdown for physical reservations, temporary tables/stacks, early allocation, canonical-page creation and deferred release into VM. Its MTE sections follow boot-policy patching, CPU controls, generator seeding/reseeding, early tagged zones and checking-state preservation; the VM companion follows allocation and fault enforcement.
2. Exceptions, interrupts, and CPU execution: start with the execution map, then follow ARM64 exception entry and ARM64 exception return through exact assembly/C paths and source excerpts. The overview also covers CPU bringup and context-switch boundaries.
3. EL1, EL2, and protected execution: distinguish guest hvc calls, SPTM hooks and interrupted-domain resumption, legacy PPL fragments, and implementation supplied outside this tree.
4. Hardware mappings and pmap backends: compare PPL, SPTM, and x86 while tracking reverse mappings, physical addresses, and TLB completion.
5. Platform services, power, and shared interfaces: connect device-tree data, CPU callbacks, sleep/hibernate, commpage, and virtualization interfaces.
6. CPU startup, offline, idle, and system sleep: follow ARM64 transition serialization, scheduler versus interrupt readiness, timer/IPI departure, saved idle-thread context, and absolute-time restoration.
7. Hibernation image creation: trace preparation, page selection/discard, metadata compaction, image encoding, encryption boundaries, and polling-driver transfers. Continue with hibernation restore for physical collisions, temporary mappings, SPTM handoff, VM rebuild, late-page read, and cleanup.
8. x86 sleep and resume: follow ACPI callback boundaries, assembly context save/restore, temporary CR3, TSC rebasing, deep idle, and secondary CPU restart. Read system sleep and wake for root-domain policy and device coordination.

For one complete fault path, read EL0 exception entry, Mach exception delivery, then exception return. The first establishes the interrupted CPU state, the second follows the handler's port/reply or Unix signal, and the third restores validated state and resumes execution.

For kernel accesses to user pointers, read ARM64 copyin, copyout and fault recovery. It connects range validation, PAN/MTE selection, assembly recovery tables, VM faults, saved-state changes and partial-copy errors.

For instruction-level explanations, follow ARM64 assembly walkthroughs through the exception vectors, register spills, stack changes, dispatch and return. Then read thread switching, entry and exit for cswitch.s, manufactured first-dispatch state, saved kernel contexts, continuations, stack handoff and deferred destruction. These connect to the scheduler and pmap chapters without treating a thread switch as an exception-level transition.

Use runtime for scheduling decisions and wait/lock primitives, VM for address-space policy and page ownership, IPC for message transport and exception RPCs, processes for BSD lifecycle/syscalls, drivers for matching and power-management policy, and security for monitor policy and Exclaves. Here, the focus is the machine transition connecting those layers.

Sources inspected and limits

This is a static review of selected paths in this checkout. No kernel image was built or booted, and no hardware behavior was measured. Conditional code describes supported source paths, not a verified configuration of a particular Apple product.

The SPTM interface header includes externally supplied sptm/sptm_xnu.h; its implementation is not in this tree. Legacy pmap comments also refer to doc/arm/PPL.md, which is absent here. Follow the available call sites without treating those missing components as inspected implementation. sptm.h, pmap_ppl_interface.c.

The protected-security expansion adds detailed SPTM/TXM call and policy lifetimes, Exclaves scheduler/upcall execution, physical ownership and service boundaries. Use it alongside the machine-transition descriptions here.