1.\" 2.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd July 3, 2018 27.Dt VM_MAP 9 28.Os 29.Sh NAME 30.Nm vm_map 31.Nd virtual address space portion of virtual memory subsystem 32.Sh SYNOPSIS 33.In sys/param.h 34.In vm/vm.h 35.In vm/vm_map.h 36.Sh DESCRIPTION 37The 38.Nm 39subsystem is used to manage virtual address spaces. 40This section describes the main data structures used within the code. 41.Pp 42The 43.Vt "struct vm_map" 44is a generic representation of an address space. 45This address space may belong to a user process or the kernel. 46The kernel actually uses several maps, which are maintained as 47subordinate maps, created using the 48.Xr vm_map_submap 9 49function. 50.Bd -literal -offset indent 51struct vm_map { 52 struct vm_map_entry header; 53 struct sx lock; 54 struct mtx system_mtx; 55 int nentries; 56 vm_size_t size; 57 u_int timestamp; 58 u_char needs_wakeup; 59 u_char system_map; 60 vm_flags_t flags; 61 vm_map_entry_t root; 62 pmap_t pmap; 63 int busy; 64}; 65.Ed 66.Pp 67The fields of 68.Vt struct vm_map 69are as follows: 70.Bl -tag -width ".Va needs_wakeup" 71.It Va header 72Head node of a circular, doubly linked list of 73.Vt struct vm_map_entry 74objects. 75Each object defines a particular region within this map's address space. 76.It Va lock 77Used to serialize access to the structure. 78.It Va system_mtx 79A mutex which is used if the map is a system map. 80.It Va nentries 81A count of the members in use within the circular map entry list. 82.It Va size 83Specifies the size of the virtual address space. 84.It Va timestamp 85Used to determine if the map has changed since its last access. 86.It Va needs_wakeup 87Indicates if a thread is waiting for an allocation within the map. 88Used only by system maps. 89.It Va system_map 90Set to TRUE to indicate that map is a system map; otherwise, it belongs 91to a user process. 92.It Va flags 93Map flags, described below. 94.It Va root 95Root node of a binary search tree used for fast lookup of map entries. 96.It Va pmap 97Pointer to the underlying physical map with which this virtual map 98is associated. 99.It Va busy 100Map busy counter, prevents forks. 101.El 102.Pp 103Possible map flags: 104.Bl -tag -width ".Dv MAP_PREFAULT_MADVISE" 105.It Dv MAP_WIREFUTURE 106Wire all future pages in this map. 107.It Dv MAP_BUSY_WAKEUP 108There are waiters for the map busy status. 109.El 110.Pp 111The following flags can be passed to 112.Xr vm_map_find 9 113and 114.Xr vm_map_insert 9 115to specify the copy-on-write properties of regions within the map: 116.Bl -tag -width ".Dv MAP_PREFAULT_MADVISE" 117.It Dv MAP_COPY_ON_WRITE 118The mapping is copy-on-write. 119.It Dv MAP_NOFAULT 120The mapping should not generate page faults. 121.It Dv MAP_PREFAULT 122The mapping should be prefaulted into physical memory. 123.It Dv MAP_PREFAULT_PARTIAL 124The mapping should be partially prefaulted into physical memory. 125.It Dv MAP_DISABLE_SYNCER 126Do not periodically flush dirty pages; only flush them when absolutely 127necessary. 128.It Dv MAP_DISABLE_COREDUMP 129Do not include the mapping in a core dump. 130.It Dv MAP_PREFAULT_MADVISE 131Specify that the request is from a user process calling 132.Xr madvise 2 . 133.It Dv MAP_ACC_CHARGED 134Region is already charged to the requestor by some means. 135.It Dv MAP_ACC_NO_CHARGE 136Do not charge for allocated region. 137.El 138.Pp 139The 140.Vt struct vm_map_entry 141is a generic representation of a region. 142The region managed by each entry is associated with a 143.Vt union vm_map_object , 144described below. 145.Bd -literal -offset indent 146struct vm_map_entry { 147 struct vm_map_entry *prev; 148 struct vm_map_entry *next; 149 struct vm_map_entry *left; 150 struct vm_map_entry *right; 151 vm_offset_t start; 152 vm_offset_t end; 153 vm_offset_t avail_ssize; 154 vm_size_t adj_free; 155 vm_size_t max_free; 156 union vm_map_object object; 157 vm_ooffset_t offset; 158 vm_eflags_t eflags; 159 /* Only in task maps: */ 160 vm_prot_t protection; 161 vm_prot_t max_protection; 162 vm_inherit_t inheritance; 163 int wired_count; 164 vm_pindex_t lastr; 165}; 166.Ed 167.Pp 168The fields of 169.Vt struct vm_map_entry 170are as follows: 171.Bl -tag -width ".Va avail_ssize" 172.It Va prev 173Pointer to the previous node in a doubly-linked, circular list. 174.It Va next 175Pointer to the next node in a doubly-linked, circular list. 176.It Va left 177Pointer to the left node in a binary search tree. 178.It Va right 179Pointer to the right node in a binary search tree. 180.It Va start 181Lower address bound of this entry's region. 182.It Va end 183Upper address bound of this entry's region. 184.It Va avail_ssize 185If the entry is for a process stack, specifies how much the entry can grow. 186.It Va adj_free 187The amount of free, unmapped address space adjacent to and immediately 188following this map entry. 189.It Va max_free 190The maximum amount of contiguous free space in this map entry's subtree. 191.It Va object 192Pointer to the 193.Vt struct vm_map_object 194with which this entry is associated. 195.It Va offset 196Offset within the 197.Va object 198which is mapped from 199.Va start 200onwards. 201.It Va eflags 202Flags applied to this entry, described below. 203.El 204.Pp 205The following five members are only valid for entries forming part of 206a user process's address space: 207.Bl -tag -width ".Va max_protection" 208.It Va protection 209Memory protection bits applied to this region. 210.It Va max_protection 211Mask for the memory protection bits which may be actually be applied to 212this region. 213.It Va inheritance 214Contains flags which specify how this entry should be treated 215during fork processing. 216.It Va wired_count 217Count of how many times this entry has been wired into physical memory. 218.It Va lastr 219Contains the address of the last read which caused a page fault. 220.El 221.Pp 222The following flags may be applied to each entry, by specifying them 223as a mask within the 224.Va eflags 225member: 226.Bl -tag -width ".Dv MAP_ENTRY_BEHAV_SEQUENTIAL" 227.It Dv MAP_ENTRY_NOSYNC 228The system should not flush the data associated with this map 229periodically, but only when it needs to. 230.It Dv MAP_ENTRY_IS_SUB_MAP 231If set, then the 232.Va object 233member specifies a subordinate map. 234.It Dv MAP_ENTRY_COW 235Indicate that this is a copy-on-write region. 236.It Dv MAP_ENTRY_NEEDS_COPY 237Indicate that a copy-on-write region needs to be copied. 238.It Dv MAP_ENTRY_NOFAULT 239Specifies that accesses within this region should never cause a page fault. 240If a page fault occurs within this region, the system will panic. 241.It Dv MAP_ENTRY_USER_WIRED 242Indicate that this region was wired on behalf of a user process. 243.It Dv MAP_ENTRY_BEHAV_NORMAL 244The system should use the default paging behaviour for this region. 245.It Dv MAP_ENTRY_BEHAV_SEQUENTIAL 246The system should depress the priority of pages immediately preceding 247each page within this region when faulted in. 248.It Dv MAP_ENTRY_BEHAV_RANDOM 249Is a hint that pages within this region will be accessed randomly, 250and that prefetching is likely not advantageous. 251.It Dv MAP_ENTRY_IN_TRANSITION 252Indicate that wiring or unwiring of an entry is in progress, and that 253other kernel threads should not attempt to modify fields in the structure. 254.It Dv MAP_ENTRY_NEEDS_WAKEUP 255Indicate that there are kernel threads waiting for this region to become 256available. 257.It Dv MAP_ENTRY_NOCOREDUMP 258The region should not be included in a core dump. 259.El 260.Pp 261The 262.Va inheritance 263member has type 264.Vt vm_inherit_t . 265This governs the inheritance behaviour for a map entry during fork processing. 266The following values are defined for 267.Vt vm_inherit_t : 268.Bl -tag -width ".Dv VM_INHERIT_DEFAULT" 269.It Dv VM_INHERIT_SHARE 270The object associated with the entry should be cloned and shared 271with the new map. 272A new 273.Vt struct vm_object 274will be created if necessary. 275.It Dv VM_INHERIT_COPY 276The object associated with the entry should be copied to the new map. 277.It Dv VM_INHERIT_NONE 278The entry should not be copied to the new map. 279.It Dv VM_INHERIT_DEFAULT 280Specifies the default behaviour, 281.Dv VM_INHERIT_COPY . 282.El 283.Pp 284The 285.Vt union vm_map_object 286is used to specify the structure which a 287.Vt struct vm_map_entry 288is associated with. 289.Pp 290The fields of 291.Vt union vm_map_object 292are as follows: 293.Bd -literal -offset indent 294union vm_map_object { 295 struct vm_object *vm_object; 296 struct vm_map *sub_map; 297}; 298.Ed 299.Pp 300Normally, the 301.Va sub_map 302member is only used by system maps to indicate that a memory range 303is managed by a subordinate system map. 304Within a user process map, each 305.Vt struct vm_map_entry 306is backed by a 307.Vt struct vm_object . 308.Sh SEE ALSO 309.Xr pmap 9 , 310.Xr vm_map_check_protection 9 , 311.Xr vm_map_delete 9 , 312.Xr vm_map_entry_resize_free 9 , 313.Xr vm_map_find 9 , 314.Xr vm_map_findspace 9 , 315.Xr vm_map_inherit 9 , 316.Xr vm_map_init 9 , 317.Xr vm_map_insert 9 , 318.Xr vm_map_lock 9 , 319.Xr vm_map_lookup 9 , 320.Xr vm_map_madvise 9 , 321.Xr vm_map_max 9 , 322.Xr vm_map_min 9 , 323.Xr vm_map_pmap 9 , 324.Xr vm_map_protect 9 , 325.Xr vm_map_remove 9 , 326.Xr vm_map_simplify_entry 9 , 327.Xr vm_map_stack 9 , 328.Xr vm_map_submap 9 , 329.Xr vm_map_sync 9 , 330.Xr vm_map_wire 9 331.Sh AUTHORS 332This manual page was written by 333.An Bruce M Simpson Aq Mt bms@spc.org . 334