Key structures: allocation, access and lifetime

This section follows a kernel structure from the allocator that supplies its storage to the last operation that releases it in xnu-12377.121.6. Start with process and task identity, continue through thread identity and credentials, then follow Mach capabilities, VM structures, file descriptors, messages and network endpoints into their backing storage. The aim is to connect a field declaration to actual callers: how a pointer is obtained, what makes it valid, which reads are permitted, how an update reaches memory, and what survives logical teardown.

Handbook home · Architecture · Reading guide

Use the structure layout browser to inspect sizes and nested field offsets in the HTML handbook. Its coverage table identifies available structures and explains unavailable ones for each supplied iOS ARM64e configuration. Preprocessing directives are inspectable and editable; the structure chapters explain storage and lifetime beyond the browser's finite inventory.

Direct layout routes include thread machine state, ARM64 saved registers and IPv6 packet headers. The IPv6 guide connects the packet layouts to socket options, routes, neighbor discovery and multicast state.

Start with the process and task pair

The existing process lifecycle, process transitions, runtime objects and task capabilities explain larger operations. These structure chapters give those operations a concrete storage and access model.

Continue through thread identity and Mach capabilities

These chapters explain the structures behind the existing credential and policy lifetime, port and right lifecycle, and thread execution paths. Read an operation chapter alongside its structure companion: one explains why control reaches the next function, the other explains what that function may read, retain, update or release.

Follow virtual memory into backing and translation storage

Read these alongside the VM operation route. A map entry can exist before an object has resident pages or the pmap has a leaf translation. A page descriptor is metadata about a frame; allocating metadata alone does not fill that frame. A named memory handle can outlive its source mapping, and an established destination mapping can outlive the handle. Each companion identifies the allocation and ownership steps behind those distinctions.

Follow descriptors into file and signature storage

Read these with the descriptor operation chapter, VFS route and signature attachment lifecycle. An fd number, fileproc I/O hold, shared fileglob reference, vnode identity and borrowed signature pointer name different resources. Closing one descriptor need not destroy file backing; keeping vnode storage alive need not preserve its filesystem identity through reclaim.

Follow messages and packets into their storage

Read these beside the Mach message route and networking operations. A kernel message can own capabilities and VM copies; a socket owns protocol state and queues; an mbuf names a view of packet bytes. Queue membership, reference ownership and storage capacity answer different questions in each family.

Two writable structures and one protected companion

For an ordinary BSD process created through forkproc(), there are two relevant allocations. The proc_task zone supplies one element containing the process followed by an aligned task. A separate proc_ro zone element holds process and task association/security fields. The whole process or task is not placed in the RO zone. Combined-zone construction, process allocation, RO-zone definition.

Mermaid source

flowchart TD
    Z["One proc_task zone element"] -->|"first part"| P["struct proc: writable BSD state"]
    Z -->|"aligned second part"| T["struct task: writable Mach state"]
    P -->|"p_proc_ro"| R["Separate proc_ro zone element"]
    T -->|"bsd_info_ro"| R
    R -->|"proc_data group"| PD["Identity, credential pointer, signing and syscall-filter fields"]
    R -->|"task_data group"| TD["Task flags, control-port options and optional filter pointers"]

The first two arrows describe layout; the others describe pointer links or field groups, not additional allocations. The RO object also carries pr_proc and pr_task backreferences. proc_ro_data and task_ro_data are groups inside struct proc_ro; there is no separate task_ro allocation on this path. Fork initializes the process side, then task creation fills the task side of the same object. RO layout, process-side initialization, task-side attachment.

This diagram deliberately selects the ordinary process-creation path. A corpse can have a task without an initialized BSD process. Kernel bootstrap first creates the kernel task with no supplied RO object, then BSD initialization separately allocates the kernel process's RO object. Follow those bodies rather than extending the shared-object diagram to every case. Process initialization boundary, kernel task creation, kernel process RO creation. The two structure chapters trace these variants.

Follow one field through all of its operations

The chapters use these stages to explain selected fields rather than reproduce every member of the large declarations. Each worked path states the relevant references, locks and configuration. A pointer to protected data still requires an owner that keeps the data alive.

How the RO-zone material fits

Start with read-only zone registration and geometry for the allocator's reserved IDs, RO submap and population policy. Then follow writing protected object fields for concrete process/task updates. Return to mutation checks and atomic updates and free for the general contracts.

Read-only describes the ordinary mapping and controlled update interface when enforcement is enabled; the fields can still change. The selected backends write through a physical-aperture virtual address for the same physical bytes. PPL and SPTM take different paths, and the SPTM write-preparation/completion hooks in this checkout have empty bodies. The update chapter separates what the source implements from external monitor behavior. Legacy ARM copy, SPTM copy, SPTM hooks.

For the surrounding storage lifecycle, use zone allocation and reuse and SMR publication and deferred callbacks. An SMR-protected lookup does not by itself mean the object was allocated with zalloc_smr; the process path uses an explicit deferred callback before releasing its allocation hold.

Keep storage, authority and lifetime separate

Each structure has several contracts. An allocator or protected mapping answers where bytes live; an accessor or capability conversion answers how code reaches an object; a reference, lock or read-side interval answers how long that access is valid. Follow all three before interpreting a field assignment.

The RO update API supplies a checked way to change protected bytes. It does not replace the owner's synchronization, convert an unretained pointer into a retained one, or make an object reached through a protected pointer immutable. Conversely, the writable IPC objects still have precise ownership and authority checks. Follow the chapter's accessor, mutation and teardown bodies together instead of inferring those contracts from const, a zone name or a structure member's spelling.

Worked reading routes

1. A newly created BSD thread: follow the task supplied to thread_create_internal(), the writable allocation and RO template, BSD initialization, credential holdings, task-list publication and IPC enablement in the thread chapter. Then follow final destruction backward: which references remain after the thread stops executing, and what prevents early reuse of the combined element?

2. A process changes identity: start with a concrete UID/GID operation in credential storage, follow template derivation, duplicate lookup, publication under the process credential lock, and release of the replaced owner. Then compare cached real and assumed credentials in the thread chapter. A published process credential and the identity already cached by another thread are separate observations.

3. A policy uses a label slot: follow allocation, slot access and owner verification in MAC label storage, then compare credential labels with a vnode's lazily installed label. Stop at the policy callback where its body is external; a framework-owned slot does not explain the provider's private representation or decision.

4. A task uses a Mach name: start with a numeric name in spaces and entries, resolve the index/generation and required right, then follow the locked port into kobject conversion. Finish with the returned object's reference release. Repeat the walk after receive-right destruction to see why a valid table lookup alone does not establish a live service.

5. An anonymous range becomes readable: start with the map entry, follow its object and offset, the resident descriptor and physical frame, then the translation tables. Use the existing fault walkthrough to connect these steps. Track metadata allocation separately from page acquisition, initialization and PTE installation.

6. A task exports and releases memory: follow a named entry from object construction through its copy wrapper and port, then map the handle in another task. Write down the additional backing reference, release the final send right, and identify why the established mapping remains valid. Compare consuming copyout with a preserving copyout and account for every entry reference.

7. An open file is duplicated and closed: follow slot reservation and publication in descriptor tables, then account for two fileprocs sharing one fileglob. Keep a read in flight while another thread closes one descriptor; record the slot flags, I/O count, shared count and offset lock separately. Repeat after the number is reused.

8. A signed file is mapped and reclaimed: acquire the vnode identity, follow its UBC/pager association into VM, and locate the signature wrapper and byte views. Explain which references survive descriptor close, what protects a page-validation traversal, and how reclaim detaches state before final storage release.

9. A message becomes a queued owner: choose one kmsg layout, follow user representation into kernel descriptors, and account for rights, voucher and out-of-line memory. Compare ordinary destruction with a reusable timer message: clearing message resources and releasing storage are separate events.

10. A socket receives and releases data: follow socket publication, PCB lookup and retention, then record insertion and buffer accounting. Clone an external mbuf view, free one descriptor, and explain why the bytes and conservative read-only flag survive. Finally compare descriptor close, protocol detach, timer draining and storage disposal.

For each route, keep a short ownership ledger beside the source: object or table pointer, how acquired, protecting lock or read-side interval, newly owned reference, transfer point, and matching cleanup. When a helper returns, record both the value and the lock/reference state promised by its caller contract.

Scope and remaining structures

The current route covers process/task/thread associations, credential and label storage, IPC namespace/port/message structures, VM maps/entries/objects/pages, ARM64 translation storage, named memory entries and VM copies, descriptor/open-file storage, vnodes, UBC/pagers, signature attachments, sockets, socket buffers, Internet PCBs and mbufs, with selected normal, failure and teardown paths. It does not enumerate every scheduling field, policy slot provider, kobject type, pager, memory policy, network protocol or configuration. Layout depends on the selected configuration, so arithmetic uses the source's alignment and offset expressions rather than a fixed structure size or an offset copied from another release.

IOKit client, memory-descriptor and memory-map objects remain candidates for the next structure companions; their driver operation chapters provide the current route. Mount, buffer-cache, knote/workloop and other supporting structures also have selected operation coverage without exhaustive structure companions. The new message/network chapters retain explicit limits around generated transport, driver providers, complete configuration matrices and concurrency interleavings.

The examples are source walkthroughs. They do not report a kernel build, device experiment or vulnerability investigation. External policy and monitor implementations remain explicit boundaries.