Page faults and memory pressure

Resolving an access

Machine-dependent trap handlers enter vm_fault_trap(), which wraps vm_fault() and translates failure results into information needed by the trap path. The core fault routine works with a page-aligned virtual address and the permissions required by the access.

The broad flow through vm_fault.c is:

validate map entry and permissions
  -> locate the object and page index
  -> find a resident page, traverse backing objects, or obtain data
  -> resolve zero-fill or copy-on-write as needed
  -> install an appropriate pmap translation
  -> release transient state or retry after a race

This is a reading guide, not an assertion that every fault visits each stage. The implementation has fast paths for already resident data, including cases that can use a shared object lock. Other faults require allocation, a pager, or filesystem interaction.

Pager dispatch

The object’s type selects a pagerops implementation. vm_pager_get_pages() obtains backing data through that interface; vm_pager_put_pages() dispatches page writeback. The pager result and the page’s valid/dirty state determine what the fault or writeback path can do next.

vnode_pager.c connects file-backed objects to filesystem operations. swap_pager.c tracks swap backing and transfers anonymous data. device_pager.c, phys_pager.c, and sg_pager.c supply other backing models. A request for a page does not always imply disk I/O.

The vnode pager is also where filesystem size, invalidation, and mapping changes meet the VM object’s view of the file. See Pathname lookup and filesystem I/O for the filesystem side of that relationship.

Retries and blocking

Obtaining a page may involve waiting for another thread, allocating memory, or completing I/O. The fault code can release locks, retain the lifetime protection it needs, and restart or revalidate its lookup afterward. An address-space change while a fault sleeps can invalidate the entry that originally motivated the operation.

The comment on vm_fault() states that ordinary callers may hold no locks. Its TDP_NOFAULTING handling is a separate failure path, not a way to make an arbitrary potentially blocking operation safe while locked. Consult VM locking and lifetime rules before adding a call from another subsystem.

Reclamation and laundry

vm_pageout.c implements reclamation and laundry workers associated with memory domains. Queue state, object state, and page references jointly determine whether a page can be reclaimed.

  • Active and inactive processing ages pages and searches for reclaimable memory. Referenced pages may be retained or reactivated.

  • Clean pages with suitable state can be reclaimed without first writing their contents to backing storage.

  • Dirty data can require laundering through the pager before its physical storage is reusable. The laundry worker is distinct from the ordinary page-scanning path.

  • Busy, referenced, or wired pages impose additional restrictions. A page being on a queue does not alone establish that it can be freed.

The pageout code rechecks state while coordinating object and queue locks; it also uses batching to reduce queue-lock traffic. Under pressure, allocation and fault paths can wait for progress. A stalled fault can therefore reflect contention, backing-store latency, or a lack of reclaimable pages rather than simply an empty free list.

Tracing a problem in the source

For a fault, establish the map, virtual address, requested access, object type, and page index. Then identify whether the path found resident data, waited for busy state, copied a page, or called a pager. For reclamation, identify the memory domain and distinguish scanning from dirty-page writeback.

The vm sysctl tree, VM counters, and DDB facilities help describe the running system, while vm_fault.c and vm_pageout.c expose the relevant state transitions. Match observations to this checkout’s definitions before interpreting a counter as a specific bottleneck.