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