Page faults and memory pressure =============================== Resolving an access ------------------- Machine-dependent trap handlers enter :c:func:`vm_fault_trap`, which wraps :c:func:`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. :c:func:`vm_pager_get_pages` obtains backing data through that interface; :c:func:`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 :doc:`../vfs/lookup-and-io` 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 :c:func:`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 :doc:`locking` 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.