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