Address spaces, objects, and pages ================================== The layers of a mapping ----------------------- The central relationship is:: vmspace -> vm_map -> vm_map_entry -> vm_object -> vm_page | +-> pmap -> hardware translations A process's ``vmspace`` embeds its VM map. The map describes the ranges that exist in the address space, including ranges with no currently resident page. An entry records a half-open virtual address range, protection and inheritance attributes, and an object plus offset, or a submap. ``vm_map.h`` describes the threaded search tree used to organize entries and track available gaps. The ``pmap`` answers a different question: which physical translations have been installed for this address space? Creating a map entry need not install every translation or populate every page immediately. A subsequent access can require a fault even though the virtual range was already reserved. Objects describe backing data ----------------------------- A ``vm_object`` represents a backing store indexed by page number. Its type selects a pager, while its resident-page radix tree tracks pages currently associated with the object. The object can outlive an individual mapping, and several maps can refer to the same object. :c:func:`vm_object_allocate` creates an object. :c:func:`vm_object_reference` and :c:func:`vm_object_deallocate` participate in its reference-counted lifetime. These operations do not replace the locks or busy state needed to change an object's contents. An object offset and a virtual address are different units of identity. Map entries use byte offsets into backing objects; resident pages use ``vm_pindex_t`` indexes. Conversion helpers in ``vm_object.h`` make the page-size relationship explicit. Keeping those units separate matters when splitting mappings or following backing-object chains. Creating and changing a mapping ------------------------------- The mmap path in ``vm_mmap.c`` validates a request and arranges the mapping. At the map layer, :c:func:`vm_map_find` finds space and inserts the requested range, while :c:func:`vm_map_insert` is a lower-level insertion interface. The implementations differ in who acquires the map lock and in the ownership assumptions surrounding an object reference. Read their contracts before replacing one with the other. Changes to a subrange can require clipping an existing entry into pieces. Adjacent compatible entries can subsequently be merged. A caller should not assume that a ``vm_map_entry`` pointer remains valid after dropping a map lock or after another mapping operation. :c:func:`vm_map_remove` removes a virtual range. Unmapping changes the map and its translations; destruction of the backing object depends on the remaining references, including references from other mappings. Copy-on-write and backing objects --------------------------------- Copy-on-write allows mappings to share data until a write requires a private copy. The map-entry flags ``MAP_ENTRY_COW`` and ``MAP_ENTRY_NEEDS_COPY`` help describe that state. Object shadowing and ``backing_object`` relationships allow a fault to search for a page in another object. A write fault may therefore need to allocate or copy a page into the mapping's own object before installing a writable translation. Object collapse and related maintenance can change backing relationships as references disappear. Treat the chain as synchronized VM state rather than an immutable list. Physical pages and kernel allocations ------------------------------------- A ``vm_page`` describes a physical page and its VM bookkeeping. Being associated with an object, being mapped by a pmap, being busy, and being wired are separate properties. In particular, a resident page can exist without a translation in the current process. :c:func:`vm_page_alloc` allocates a page according to its request flags and object context. NUMA policy and physical-allocation constraints influence where the page comes from. Success does not by itself mean a user mapping has been created; the fault or mapping path still has work to do. Kernel allocation interfaces add other layers. ``vm_kern.c`` manages kernel virtual-memory operations, and UMA supplies reusable allocations organized into zones. Follow the allocation's actual owner and release interface instead of treating all kernel memory as interchangeable pages.