XNU source guide

This guide explains the xnu-12377.121.6 source snapshot stored in Platydoc's platydoc-data/xnu/ input: which subsystem owns which state, how operations cross subsystem boundaries, and where to read the implementation. Start with the architecture, then choose a concrete operation. Reading the tree alphabetically is much less useful.

The complete table of contents lists every chapter and its main sections.

The key-structures section follows allocation, access, updates and reclamation, starting with proc and its protected data, task and the shared RO record, and how writes to protected fields reach memory. It connects concrete process/task callers to the existing zone and SMR explanations.

Continue through thread, uthread and thread_ro, credential storage and replacement, and MAC label ownership. Then follow a Mach capability through IPC spaces and entries into ports and kernel-object associations. These companions connect field maps and exact source excerpts to construction, lookup, protected writes, references, synchronization, failure and final release; the reading exercises join them into complete paths.

Continue into VM maps and entries, objects and backing, page descriptors and resident storage, and ARM64 pmap/table storage. Finish with named memory entries and VM copy containers, which connect memory ownership to Mach capabilities. The VM structure route separates metadata, physical bytes, translations and transferred references.

The file and signature structure route follows descriptor tables, fileprocs and shared fileglobs, vnode storage and identity, UBC and vnode pagers, and protected code-signature blobs. It connects descriptor reuse and shared offsets to cached backing, signed-byte views and staged reclamation.

The message and network structure route follows IPC kmsg buffers, socket attachments, socket-buffer records, Internet PCB and TCP storage, and mbuf views and shared clusters. It connects representation changes and queue publication to references, capacity accounting, partial failures and final release.

The IPsec, MPTCP and process-inspection route connects IPsec virtual-interface lifetime, multipath sessions and TCP subflows, and proc_info queries and snapshots to the existing packet, transport and process chapters.

The exec-stack, executable-I/O and scheduler-placement route continues three existing topics through their next operations: argument bytes into an ARM64 user stack, executable pages into UPL backing, and thread-group changes into accounting and cluster placement.

The executable-memory, synchronization and packet-policy route connects JIT/protection changes, semaphores/eventlinks, work intervals/thread groups, flow diversion, deeper PF TCP/NAT and IPsec IPv6/chains, and a worked ARM64 build/MIG trace.

For a source-focused route through argument handling, authority and object lifetime, follow the eight-part implementation reading route. It connects command dispatch, VM validation, concurrent operations, IOKit calls, exec identity, message/register integrity, instrumentation and packet processing.

The Platydoc project layout separates the handbook and its tools from the read-only XNU input.

Build the local HTML book with python3 make_docs.py from the Platydoc project root (the directory containing platydoc-data/), then open docs-ai-html/index.html. The build guide covers offline search, the alphabetical index, SVG diagrams, highlighted source previews and regeneration after Markdown or source changes.

Start here

1. Architecture and object relationships: the kernel's main components and their interfaces.
2. Source map: directories, supporting components, and where to look for a feature.
3. Reading guide: a staged route through structures and execution paths.
4. Operations across subsystem boundaries: file access, mapped memory, IPC, networking, process creation, and driver requests.
5. Executable loading: how Mach-O commands become mappings and initial execution state.
6. Ownership and synchronization: how to reason about references, locks, deferred work, and teardown.
7. SMR and pointer publication: read-side protection, grace periods, sleepable readers, callback queues and barriers.
8. Completion, cancellation and partial failure: where ownership moves, what errors preserve, and when teardown can release storage.

Subsystem guides

Each subsystem index links to focused implementation guides, names the principal structures and entry points, and records what was inspected and what remains outside the analysis.

Development and observation

• Build, configuration, and tests explains how files and interfaces are selected or generated, and which test environments exist.
• Tracing, accounting, debugging, and diagnostics connects kdebug, kperf, Recount, stackshot, kcdata, LLDB, and sanitizers to the objects they inspect.
• Stackshot and kcdata, corpses and process core dumps, and ARM64 panic records explain diagnostic artifact creation, ownership and publication.
• Vocabulary and object index gives short definitions of the terms used throughout the code.
• Source-reference index maps each cited source file back to the guides that use it.

Detailed IPC and exception paths

For Mach IPC, follow names and rights → port lifecycle → message representation → send and receive → kernel RPC/MIG. These pages track the same objects across namespace lookup, rights transfer, message delivery, reply, and cleanup, with inline source excerpts.

For ARM64 exceptions, follow EL0 → EL1 entry → Mach exception delivery → EL1 → EL0 return. The separate EL2 and protected-execution guide traces guest hypercalls, SPTM entry/exit hooks, protected-domain interrupt resumption, and legacy PPL boundaries.

ASTs and the system-call surface

Start with AST publication and dispatch, then use the flavor catalog to find each bit's producers, consumer, execution context, clearing rules and configuration. The chapters connect CPU and thread masks to preemption, signals, suspension, guards, accounting, tracing and safe return to userspace.

The entry-point map separates instruction entry, BSD syscall numbers, Mach trap numbers and Mach message IDs. Follow its machine dispatch chapter, BSD catalog, Mach trap catalog, and MIG message catalog. Each catalog retains holes and conditional alternatives and links declared interfaces to local implementations or an explicit missing receiver. Dispatcher selectors and downstream driver, protocol and policy namespaces are identified separately.

Detailed VM and hardware-mapping paths

Start with mapping walkthroughs, then follow virtual address maps → objects and pages → fault resolution. These track anonymous allocation, mapped files, shared/private backing, COW, protection changes, and unmapping from API to physical-page ownership.

For hardware translation, follow ARM64 pmap structures and table geometry → mapping and table lifetimes → ASIDs, TLBs, and caches. The x86_64 pmap guide covers its separate roots, PV lists, PCIDs, and shootdown protocol. Continue with wiring and memory entries, pagers and UPLs, reclaim/compression/swap, and kernel allocation. Each path names its structures, synchronization, cleanup, and source-visible limits.

Detailed kernel allocation and type isolation

The allocator overview connects zone elements/caches/reclaim, kalloc size/heap routing, and kernel VM allocation/guards. For type isolation, read the dedicated compiler metadata and assignment guide: it traces fixed signature groups and zone budgets, variable heaps, initial shared allocations, and what matching frees actually validate. Read-only and special zones and IOKit/C++/BSD interfaces cover the additional protection and lifetime contracts.

Detailed SPTM, TXM, and Exclaves boundaries

For protected execution, start with the SPTM, TXM, and Exclaves entry/exit map. Continue into SPTM, TXM, and Exclaves execution, then resources and physical ownership and service integration. These chapters distinguish normal calls, upcalls and interrupted-domain resumption, with explicit boundaries around code supplied outside this checkout.

Conventions and limits

Markdown links resolve relative to each chapter and reach the separate kernel input through platydoc-data/xnu/. Kernel paths written in prose, such as osfmk/vm/vm_map.c, and source-inventory metadata are XNU-relative unless stated otherwise; kernel build/debug commands run from platydoc-data/xnu/ unless their instructions say otherwise, and documentation commands run from the Platydoc project root. Platydoc files and generated artifacts remain outside the kernel checkout. A link ending in #L123 identifies a line in the inspected snapshot; renderers without source-line navigation can still open the file and search for the named symbol. Names and source paths are the durable navigation keys. Diagrams use Mermaid and describe selected relationships or paths; they do not imply every branch or lock operation is shown.

Copied source excerpts carry their original file and line range. The documentation checker compares marked excerpts against those exact lines, including indentation; explanatory examples are identified separately. Rerun it after changing the checkout or extending a guide.

This is source analysis, not a report of running or booting the kernel. Architecture, platform, build variant, and feature configuration change compiled behavior. The original supplied folder identified the snapshot as xnu-12377.121.6; no usable Git history was available during that source analysis for pinning it to a commit. Moving the input to platydoc-data/xnu/ does not itself revalidate the handbook against a different release. The build can obtain its version from an SDK/KDK or an override, as explained in the repository's version documentation.

The tree contains kernel mechanisms and many interfaces to components built elsewhere. It does not contain the complete macOS or iOS system, every hardware driver, or every security policy implementation. The guides identify those boundaries instead of filling them with assumed implementations. Existing Apple-authored documentation remains useful alongside this guide.