Virtual memory and kernel allocation

Guide index · Architecture

XNU's VM subsystem manages address spaces, the objects supplying their contents, resident physical pages, and the work needed to make pages available under pressure. Its core is in osfmk/vm; process-level memory policy lives in BSD, hardware translation in architecture-specific pmap implementations, and small kernel allocations in osfmk/kern.

Start with maps, objects, pages, and faults, then follow one mapping from API request to CPU access. The detailed chapters below separate address-space policy, content ownership, and hardware translation while tracing their interfaces.

For worked operations spanning other subsystems, use a mapped file through an ARM64 fault and a user buffer through DMA completion. They carry concrete object offsets, virtual/physical/device addresses and resource ownership through the same VM mechanisms.

Detailed reading route

For allocation, field access and final storage release, use the VM structure route: maps and entries → objects → page descriptors → pmap and table storage → named entries and copies. These companions supply field and ownership maps for the operation chapters below.

For concrete clients of the allocator, the key-structures section follows proc and task from their combined allocation into a separate protected record. Writing protected object fields connects their update helpers to the RO-zone validation and ARM64 alias-write paths described below.

The examples use page-size symbols where possible. Before following an address into pmap, identify the map's page size, system VM page size, and hardware translation granule; these are separate inputs in supported configurations.

The central distinction

A mapping describes what an address means. A resident page holds its current contents. A hardware translation allows a CPU to access those contents. These can exist independently: an untouched anonymous mapping can have neither a resident page nor a page-table entry; a file's cached pages can outlive a particular process mapping. The public vm_map_create documentation explicitly identifies the VM map as the source of truth for region configuration and the pmap as its machine-dependent cache.

Mermaid source

flowchart TD
    BSD[BSD mmap, fork, exec] --> MAP[vm_map and vm_map_entry]
    MACH[Mach VM APIs and memory entries] --> MAP
    MAP --> OBJ[vm_object plus object offset]
    MAP --> PMAP[pmap: CPU translations]
    OBJ --> PAGE[vm_page: resident contents]
    PAGE --> PMAP
    OBJ --> PAGER[memory_object pager]
    PAGER --> VNODE[Vnode pager / UBC / filesystem]
    PAGER --> COMP[Compressor pager / segments / optional swap]
    PAGER --> DEVICE[Device pager / IOKit]
    SCAN[Pageout scanner] --> PAGE
    SCAN --> COMP
    PRESSURE[BSD memorystatus and freezer] --> SCAN
    ALLOC[zones / kalloc / kmem] --> PAGE
    ALLOC --> MAP

The arrows summarize dependency and data flow, not a universal synchronous call chain. Pager dispatch is directly through operation tables in this checkout; do not assume every memory_object_* call sends an IPC message. See memory_object_data_request.

Follow one address in both directions

Mermaid source

flowchart LR
    VA[Task virtual address] --> E[Map entry and allowed protection]
    E --> O[Object and offset]
    O --> R[Resident vm_page or backing pager]
    R --> F[Physical frame selected by fault]
    VA --> PT[Pmap root and page-table walk]
    PT --> PTE[Leaf translation and permissions]
    PTE --> F
    F --> PV[Reverse mappings]
    PV --> PTE
    PTE --> TLB[CPU cached translation]

The upper route decides what contents an access is allowed to obtain. The lower route supplies the hardware translation once contents are ready. Reverse mappings let VM begin with a physical page and find affected translations during reclaim or protection changes. A PTE can temporarily grant less access than the map permits, for example to enforce COW or track writes. Replacing or removing a PTE must also honor invalidation completion before the old mapping's resources can be reused. Faults, mapping lifecycle, TLB completion.

Ownership and interfaces

The most useful cross-subsystem routes are BSD mmap to a vnode's UBC object, VM faults to filesystem page-in, pageout to filesystem writeback, and IOKit memory descriptors to wired pages/device mappings. Continue into the VFS documentation for filesystem operation dispatch. Process creation and termination determine map lifetime; scheduler waits and wakeups make faulting, pageout, and freezer work executable.

Read the selected pmap backend

arm/pmap.h selects the SPTM or legacy ARM representation. files.arm64 selects matching sources; files.x86_64 selects the x86 files. The same common API name is not evidence that all backends share one algorithm.

Definitions: legacy pmap, SPTM pmap, x86 pmap. SPTM's implementation cannot be explained by replacing a legacy PPL function call with a different entry instruction; its local concurrency and table-lifetime machinery also differ.

Read these as interface families; argument types, helper names, fast paths, and completion contracts differ. common pmap interface, ARM lifecycle, x86 implementation.

Details specific to this checkout

• Map lookup storage is a B+tree, including summaries of holes for allocation. Older descriptions of XNU's red-black VM map tree do not describe vm_map_store_node.
• The map has an interlock and individual entries have locks. Range-lock contexts prepare and stabilize entries, including submap descent and COW resolution. A model with one map-wide lock is insufficient; see vm_map_lock_internal.h.
• Page size belongs to multiple layers. A map has hdr.page_shift, while VM objects and physical pages use system-page conventions. Code explicitly handles different sizes; never replace VM_MAP_PAGE_SIZE(map) with a hard-coded 4096 in your mental model. See vm_object_shadow.
• Compressor, general swap, and freezer swap have separate runtime configuration predicates. The presence of their source does not establish that a particular product uses every facility. See vm_config predicates.
• VM submaps have a constrained hierarchy in the current range-lock implementation; this is separate from sharing a hardware hierarchy through pmap nesting. See submap rules.
• A named memory entry carries a capability to backing described by a submap or vm_map_copy. The current copy representation has entry-list and kernel-buffer variants. See memory entries and copies.
• An invalid compressed PTE marker preserves mapping accounting; compressed contents and slot locators live in the object's compressor pager. See compression.

Sources inspected and limits

“Deep” means the named data definitions and relevant multi-stage implementation paths were read, not that every line or configuration branch in a large file was audited.

Useful original documentation includes pageout scan, memorystatus, freezer, shared region, VM sanitization, and allocator API guidance. Prefer implementation when an older narrative uses a superseded function or structure name.

Backing-store and reclaim companions

• Shared regions and transforming pagers: exec placeholders, shared-cache installation, submap/pmap nesting, page transformation and pager lifetime.
• Compressor segments and swapfiles: filling allocation, locator repair during compaction, swap workers, file creation, trim and reclamation.
• Deferred reclamation: userspace publication/cancellation, kernel gate ownership, partial progress, sampling, fork and teardown.
• Purgeable memory: volatile/empty transitions, aging tokens, selection locks and resident/compressed owner accounting.
• Phantom cache and refaults: bounded eviction history and conditional pressure decisions, including the macOS ARM64 exclusion.