xref: /freebsd/share/man/man9/vm_map.9 (revision 39beb93c3f8bdbf72a61fda42300b5ebed7390c8)
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 September 26, 2004
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.El
150.Pp
151The
152.Vt struct vm_map_entry
153is a generic representation of a region.
154The region managed by each entry is associated with a
155.Vt union vm_map_object ,
156described below.
157.Bd -literal -offset indent
158struct vm_map_entry {
159        struct vm_map_entry *prev;
160        struct vm_map_entry *next;
161        struct vm_map_entry *left;
162        struct vm_map_entry *right;
163        vm_offset_t start;
164        vm_offset_t end;
165        vm_offset_t avail_ssize;
166        vm_size_t adj_free;
167        vm_size_t max_free;
168        union vm_map_object object;
169        vm_ooffset_t offset;
170        vm_eflags_t eflags;
171        /* Only in task maps: */
172        vm_prot_t protection;
173        vm_prot_t max_protection;
174        vm_inherit_t inheritance;
175        int wired_count;
176        vm_pindex_t lastr;
177};
178.Ed
179.Pp
180The fields of
181.Vt struct vm_map_entry
182are as follows:
183.Bl -tag -width ".Va avail_ssize"
184.It Va prev
185Pointer to the previous node in a doubly-linked, circular list.
186.It Va next
187Pointer to the next node in a doubly-linked, circular list.
188.It Va left
189Pointer to the left node in a binary search tree.
190.It Va right
191Pointer to the right node in a binary search tree.
192.It Va start
193Lower address bound of this entry's region.
194.It Va end
195Upper address bound of this entry's region.
196.It Va avail_ssize
197If the entry is for a process stack, specifies how much the entry can grow.
198.It Va adj_free
199The amount of free, unmapped address space adjacent to and immediately
200following this map entry.
201.It Va max_free
202The maximum amount of contiguous free space in this map entry's subtree.
203.It Va object
204Pointer to the
205.Vt struct vm_map_object
206with which this entry is associated.
207.It Va offset
208Offset within the
209.Va object
210which is mapped from
211.Va start
212onwards.
213.It Va eflags
214Flags applied to this entry, described below.
215.El
216.Pp
217The following five members are only valid for entries forming part of
218a user process's address space:
219.Bl -tag -width ".Va max_protection"
220.It Va protection
221Memory protection bits applied to this region.
222These are identical to those defined for
223.Xr vm_page_protect 9 .
224.It Va max_protection
225Mask for the memory protection bits which may be actually be applied to
226this region.
227These are identical to those defined for
228.Xr vm_page_protect 9 .
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_clean 9 ,
328.Xr vm_map_create 9 ,
329.Xr vm_map_delete 9 ,
330.Xr vm_map_entry_resize_free 9 ,
331.Xr vm_map_find 9 ,
332.Xr vm_map_findspace 9 ,
333.Xr vm_map_inherit 9 ,
334.Xr vm_map_init 9 ,
335.Xr vm_map_insert 9 ,
336.Xr vm_map_lock 9 ,
337.Xr vm_map_lookup 9 ,
338.Xr vm_map_madvise 9 ,
339.Xr vm_map_max 9 ,
340.Xr vm_map_min 9 ,
341.Xr vm_map_pmap 9 ,
342.Xr vm_map_protect 9 ,
343.Xr vm_map_remove 9 ,
344.Xr vm_map_simplify_entry 9 ,
345.Xr vm_map_stack 9 ,
346.Xr vm_map_submap 9 ,
347.Xr vm_map_wire 9 ,
348.Xr vm_page_protect 9
349.Sh AUTHORS
350This manual page was written by
351.An Bruce M Simpson Aq bms@spc.org .
352