VM_MAP(9)

🌸 VM_MAP(9) 🌸

okay bestie, sit down, hydrate, and let's talk about the vm_map situation, because this is the virtual address space portion of the virtual memory subsystem and honestly? it's giving main character energy for the whole kernel. this is a Kernel Developer's Manual page, iykyk 💅

---

✨ SYNOPSIS ✨

like, first of all, you gotta include the girlies:

#include <sys/param.h>
#include <vm/vm.h>
#include <vm/vm_map.h>

---

💖 DESCRIPTION 💖

so the vm_map subsystem? it's literally what manages virtual address spaces. this section is about the main data structures used in the code, no skips, we're reading the whole thing, periodt.

The struct vm_map is a generic representation of an address space. this address space might belong to a user process, or it might belong to the kernel (she contains multitudes). fun fact: the kernel actually uses several maps, and those are maintained as subordinate maps, created using the vm_map_submap(9) function. iconic behaviour tbh.

struct vm_map {
        struct vm_map_entry header;
        struct sx lock;
        struct mtx system_mtx;
        int nentries;
        vm_size_t size;
        u_int timestamp;
        u_char needs_wakeup;
        u_char system_map;
        vm_flags_t flags;
        vm_map_entry_t root;
        pmap_t pmap;
        int busy;
};

The fields of struct vm_map are, one by one, no crumbs left behind:

• header — head node of a circular, doubly linked list of struct vm_map_entry objects. each one of those defines a particular region within this map's address space 🎀
• lock — used to serialize access to the structure. she's the bouncer.
• system_mtx — a mutex which is used if the map is a system map.
• nentries — a count of the members in use within the circular map entry list.
• size — specifies the size of the virtual address space.
• timestamp — used to determine if the map has changed since its last access.
• needs_wakeup — indicates if a thread is waiting for an allocation within the map. used only by system maps, bestie.
• system_map — set to TRUE to indicate that map is a system map; otherwise, it belongs to a user process.
• flags — map flags, described below 👇
• root — root node of a binary search tree used for fast lookup of map entries.
• pmap — pointer to the underlying physical map with which this virtual map is associated.
• busy — map busy counter, prevents forks.

🦋 Possible map flags 🦋

• MAP_WIREFUTURE — wire all future pages in this map.
• MAP_BUSY_WAKEUP — there are waiters for the map busy status.

🌈 The following flags can be passed to vm_map_find(9) and vm_map_insert(9) to specify the copy-on-write properties of regions within the map 🌈

• MAP_COPY_ON_WRITE — the mapping is copy-on-write.
• MAP_NOFAULT — the mapping should not generate page faults.
• MAP_PREFAULT — the mapping should be prefaulted into physical memory.
• MAP_PREFAULT_PARTIAL — the mapping should be partially prefaulted into physical memory.
• MAP_DISABLE_SYNCER — do not periodically flush dirty pages; only flush them when absolutely necessary.
• MAP_DISABLE_COREDUMP — do not include the mapping in a core dump.
• MAP_PREFAULT_MADVISE — specify that the request is from a user process calling madvise(2).
• MAP_ACC_CHARGED — region is already charged to the requestor by some means.
• MAP_ACC_NO_CHARGE — do not charge for allocated region.

---

🧚 the struct vm_map_entry 🧚

The struct vm_map_entry is a generic representation of a region. the region managed by each entry is associated with a union vm_map_object, described below.

struct vm_map_entry {
        struct vm_map_entry *prev;
        struct vm_map_entry *next;
        struct vm_map_entry *left;
        struct vm_map_entry *right;
        vm_offset_t start;
        vm_offset_t end;
        vm_offset_t avail_ssize;
        vm_size_t adj_free;
        vm_size_t max_free;
        union vm_map_object object;
        vm_ooffset_t offset;
        vm_eflags_t eflags;
        /* Only in task maps: */
        vm_prot_t protection;
        vm_prot_t max_protection;
        vm_inherit_t inheritance;
        int wired_count;
        vm_pindex_t lastr;
};

The fields of struct vm_map_entry are as follows:

• prev — pointer to the previous node in a doubly-linked, circular list.
• next — pointer to the next node in a doubly-linked, circular list.
• left — pointer to the left node in a binary search tree.
• right — pointer to the right node in a binary search tree.
• start — lower address bound of this entry's region.
• end — upper address bound of this entry's region.
• avail_ssize — if the entry is for a process stack, specifies how much the entry can grow.
• adj_free — the amount of free, unmapped address space adjacent to and immediately following this map entry.
• max_free — the maximum amount of contiguous free space in this map entry's subtree.
• object — pointer to the struct vm_map_object with which this entry is associated.
• offset — offset within the object which is mapped from start onwards.
• eflags — flags applied to this entry, described below.

💜 The following five members are only valid for entries forming part of a user process's address space 💜

• protection — memory protection bits applied to this region.
• max_protection — mask for the memory protection bits which may be actually be applied to this region.
• inheritance — contains flags which specify how this entry should be treated during fork processing.
• wired_count — count of how many times this entry has been wired into physical memory.
• lastr — contains the address of the last read which caused a page fault.

🌟 The following flags may be applied to each entry, by specifying them as a mask within the eflags member 🌟

• MAP_ENTRY_NOSYNC — the system should not flush the data associated with this map periodically, but only when it needs to.
• MAP_ENTRY_IS_SUB_MAP — if set, then the object member specifies a subordinate map.
• MAP_ENTRY_COW — indicate that this is a copy-on-write region.
• MAP_ENTRY_NEEDS_COPY — indicate that a copy-on-write region needs to be copied.
• MAP_ENTRY_NOFAULT — specifies that accesses within this region should never cause a page fault. ⚠️ if a page fault occurs within this region, the system will panic. not a drill, bestie.
• MAP_ENTRY_USER_WIRED — indicate that this region was wired on behalf of a user process.
• MAP_ENTRY_BEHAV_NORMAL — the system should use the default paging behaviour for this region.
• MAP_ENTRY_BEHAV_SEQUENTIAL — the system should depress the priority of pages immediately preceding each page within this region when faulted in.
• MAP_ENTRY_BEHAV_RANDOM — is a hint that pages within this region will be accessed randomly, and that prefetching is likely not advantageous.
• MAP_ENTRY_IN_TRANSITION — indicate that wiring or unwiring of an entry is in progress, and that other kernel threads should not attempt to modify fields in the structure.
• MAP_ENTRY_NEEDS_WAKEUP — indicate that there are kernel threads waiting for this region to become available.
• MAP_ENTRY_NOCOREDUMP — the region should not be included in a core dump.

---

🍓 inheritance, a whole personality 🍓

The inheritance member has type vm_inherit_t. this governs the inheritance behaviour for a map entry during fork processing. the following values are defined for vm_inherit_t:

• VM_INHERIT_SHARE — the object associated with the entry should be cloned and shared with the new map. a new struct vm_object will be created if necessary.
• VM_INHERIT_COPY — the object associated with the entry should be copied to the new map.
• VM_INHERIT_NONE — the entry should not be copied to the new map.
• VM_INHERIT_DEFAULT — specifies the default behaviour, VM_INHERIT_COPY.

---

🎀 the union vm_map_object 🎀

The union vm_map_object is used to specify the structure which a struct vm_map_entry is associated with.

The fields of union vm_map_object are as follows:

union vm_map_object {
        struct vm_object *vm_object;
        struct vm_map *sub_map;
};

Normally, the sub_map member is only used by system maps to indicate that a memory range is managed by a subordinate system map. within a user process map, each struct vm_map_entry is backed by a struct vm_object. yes queen, backing store 💅

---

🔥 SEE ALSO 🔥

pmap(9), vm_map_check_protection(9), vm_map_create(9), vm_map_delete(9), vm_map_entry_resize_free(9), vm_map_find(9), vm_map_findspace(9), vm_map_inherit(9), vm_map_init(9), vm_map_insert(9), vm_map_lock(9), vm_map_lookup(9), vm_map_madvise(9), vm_map_max(9), vm_map_min(9), vm_map_pmap(9), vm_map_protect(9), vm_map_remove(9), vm_map_simplify_entry(9), vm_map_stack(9), vm_map_submap(9), vm_map_sync(9), vm_map_wire(9)

---

👑 AUTHORS 👑

This manual page was written by Bruce M Simpson <bms@spc.org>. absolute legend, we love to see it 🫶

---

and that's the whole vibe check, bestie — this page came from Debian, dated July 3, 2018, on VM_MAP(9). go forth and map those virtual addresses, no cap 💖✨