share/man/man9/vm_map.9

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