--- name: "vm_map" section: "9" platform: "linux" package: "freebsd-manpages" version: "6.0-5" release: "Debian 4.0 (Etch)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/vm_map" --- # vm\_map(9) virtual address space portion of virtual memory subsystem ## NAME **vm\_map** – virtual address space portion of virtual memory subsystem ## SYNOPSIS **#include \** **#include \** **#include \** ## DESCRIPTION The **vm\_map** subsystem is used to manage virtual address spaces. This section describes the main data structures used within the code. The *struct vm\_map* is a generic representation of an address space. This address space may belong to a user process or the kernel. The kernel actually uses several maps, which are maintained as subordinate maps, created using the [vm\_map\_submap(9)](/vm_map_submap/9.md) function. ``` 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; #define min_offset header.start #define max_offset header.end }; ``` The fields of *struct* *vm\_map* are as follows: - *header* Head node of a circular, doubly linked list of *struct* *vm\_map\_entry* objects. Each object defines a particular region within this map's address space. - *lock* Used to serialize access to the structure. - *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. - *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. - *min\_offset* The minimum *vm\_offset\_t* in this map. Programs should never use *header.start* or *header.end* directly, use *min\_offset* and *max\_offset* instead. - *max\_offset* The maximum *vm\_offset\_t* in this map. There is one possible map flag: - MAP\_WIREFUTURE Wire all future pages in this map. The following flags can be passed to [vm\_map\_find(9)](/vm_map_find/9.md) and [vm\_map\_insert(9)](/vm_map_insert/9.md) 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 from a user process calling [madvise(2)](/madvise/2.md). 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. These are identical to those defined for [vm\_page\_protect(9)](/vm_page_protect/9.md). - *max\_protection* Mask for the memory protection bits which may be actually be applied to this region. These are identical to those defined for [vm\_page\_protect(9)](/vm_page_protect/9.md). - *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. - 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. 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* 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*. ## SEE ALSO [pmap(9)](/pmap/9.md), [vm\_map\_check\_protection(9)](/vm_map_check_protection/9.md), [vm\_map\_clean(9)](/vm_map_clean/9.md), [vm\_map\_create(9)](/vm_map_create/9.md), [vm\_map\_delete(9)](/vm_map_delete/9.md), [vm\_map\_entry\_resize\_free(9)](/vm_map_entry_resize_free/9.md), [vm\_map\_find(9)](/vm_map_find/9.md), [vm\_map\_findspace(9)](/vm_map_findspace/9.md), [vm\_map\_inherit(9)](/vm_map_inherit/9.md), [vm\_map\_init(9)](/vm_map_init/9.md), [vm\_map\_insert(9)](/vm_map_insert/9.md), [vm\_map\_lock(9)](/vm_map_lock/9.md), [vm\_map\_lookup(9)](/vm_map_lookup/9.md), [vm\_map\_madvise(9)](/vm_map_madvise/9.md), [vm\_map\_max(9)](/vm_map_max/9.md), [vm\_map\_min(9)](/vm_map_min/9.md), [vm\_map\_pmap(9)](/vm_map_pmap/9.md), [vm\_map\_protect(9)](/vm_map_protect/9.md), [vm\_map\_remove(9)](/vm_map_remove/9.md), [vm\_map\_simplify\_entry(9)](/vm_map_simplify_entry/9.md), [vm\_map\_stack(9)](/vm_map_stack/9.md), [vm\_map\_submap(9)](/vm_map_submap/9.md), [vm\_map\_wire(9)](/vm_map_wire/9.md), [vm\_page\_protect(9)](/vm_page_protect/9.md) ## AUTHORS This manual page was written by Bruce M Simpson ⟨bms@spc.org⟩.