diff options
author | bms <bms@FreeBSD.org> | 2003-09-30 00:54:06 +0000 |
---|---|---|
committer | bms <bms@FreeBSD.org> | 2003-09-30 00:54:06 +0000 |
commit | 25f0aaccb1e4e4bbb54222f40c65082e7d9d2b8b (patch) | |
tree | 65fcaf0aeb41fc10a3d1f8f95ded635f8fa6c563 /share/man/man9/vm_map.9 | |
parent | 2e8e8cca73ba5c5237000da3729c627bda50a12c (diff) | |
download | FreeBSD-src-25f0aaccb1e4e4bbb54222f40c65082e7d9d2b8b.zip FreeBSD-src-25f0aaccb1e4e4bbb54222f40c65082e7d9d2b8b.tar.gz |
Add a (somewhat verbose) manual page for vm_map(9).
Reviewed by: juli
Approved by: jake (mentor)
Diffstat (limited to 'share/man/man9/vm_map.9')
-rw-r--r-- | share/man/man9/vm_map.9 | 320 |
1 files changed, 320 insertions, 0 deletions
diff --git a/share/man/man9/vm_map.9 b/share/man/man9/vm_map.9 new file mode 100644 index 0000000..9e12fbe --- /dev/null +++ b/share/man/man9/vm_map.9 @@ -0,0 +1,320 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 19, 2003 +.Dt vm_map 9 +.Sh NAME +.Nm vm_map +.Nd virtual address space portion of virtual memory subsystem +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Sh DESCRIPTION +The +.Nm +subsystem is used to manage virtual address spaces. +This section describes the main data structures used within the code. +.Pp +The +.Fa struct vm_map +is a generic representation of an address space. +This address space may belong to a user process or the kernel. +The kernel actually uses several maps, which are maintained as +subordinate maps, created using the +.Xr vm_map_submap 9 +function. +.Bd -literal -offset indent +struct vm_map { + struct vm_map_entry header; + struct lock lock; + struct mtx system_mtx; + int nentries; + vm_size_t size; + u_char needs_wakeup; + u_char system_map; + u_char infork; + vm_map_entry_t root; + unsigned int timestamp; + vm_map_entry_t first_free; + pmap_t pmap; +}; +.Ed +.Pp +The fields of +.Fa struct vm_map +are as follows: +.Bl -tag -width needs_wakeupXXX +.It header +Head node of a circular, doubly linked list of +.Fa struct vm_map_entry +objects. +Each object defines a particular region within this map's address space. +.It lock +Used to serialize access to the structure. +.It system_mtx +A mutex which is used if the map is a system map. +.It nentries +A count of the members in use within the circular map entry list. +.It size +Specifies the size of the virtual address space. +.It infork +Indicates if the map structure is currently undergoing fork processing. +.It needs_wakeup +Indicates if a thread is waiting for an allocation within the map. +Used only by system maps. +.It system_map +Set to TRUE to indicate that map is a system map; otherwise, it belongs +to a user process. +.It root +Root node of a binary search tree used for fast lookup of map entries. +.It timestamp +Used to determine if the map has changed since its last access. +.It first_free +Provides a hint to the first free space within the map. +.It pmap +Pointer to the underlying physical map with which this virtual map +is associated. +.El +.Pp +The following flags can be passed to +.Xr vm_map_find 9 +and +.Xr vm_map_insert 9 +to specify the copy-on-write properties of regions within the map: +.Bl -tag -width MAP_PREFAULT_MADVISEXXX +.It MAP_COPY_ON_WRITE +The mapping is copy-on-write. +.It MAP_NOFAULT +The mapping should not generate page faults. +.It MAP_PREFAULT +The mapping should be prefaulted into physical memory. +.It MAP_PREFAULT_PARTIAL +The mapping should be partially prefaulted into physical memory. +.It MAP_DISABLE_SYNCER +Do not periodically flush dirty pages; only flush them when absolutely +necessary. +.It MAP_DISABLE_COREDUMP +Do not include the mapping in a core dump. +.It MAP_PREFAULT_MADVISE +Specify that the request from a user process calling +.Xr madvise 2 . +.El +.Pp +The +.Fa struct vm_map_entry +is a generic representation of a region. +The region managed by each entry is associated with a +.Fa union vm_map_object , +described below. +.Bd -literal -offset indent +struct vm_map_entry { + struct vm_map_entry *prev; + struct vm_map_entry *next; + struct vm_map_entry *left; + struct vm_map_entry *right; + vm_offset_t start; + vm_offset_t end; + vm_offset_t avail_ssize; + union vm_map_object object; + vm_ooffset_t offset; + vm_eflags_t eflags; + /* Only in task maps: */ + vm_prot_t protection; + vm_prot_t max_protection; + vm_inherit_t inheritance; + int wired_count; + vm_pindex_t lastr; +}; +.Ed +.Pp +The fields of +.Fa struct vm_map_entry +are as follows: +.Bl -tag -width struct_vm_map_objectXXX +.It prev +Pointer to the previous node in a doubly-linked, circular list. +.It next +Pointer to the next node in a doubly-linked, circular list. +.It left +Pointer to the left node in a binary search tree. +.It right +Pointer to the right node in a binary search tree. +.It start +Lower address bound of this entry's region. +.It end +Upper address bound of this entry's region. +.It avail_ssize +If the entry is for a process stack, specifies how much the entry can grow. +.It object +Pointer to the +.Fa struct vm_map_object +with which this entry is associated. +.It offset +Offset within the +.Fa object +which is mapped from +.Fa start +onwards. +.It eflags +Flags applied to this entry, described below. +.El +.Pp +The following five members are only valid for entries forming part of +a user process's address space: +.Bl -tag -width struct_vm_map_objectXXX +.It protection +Memory protection bits applied to this region. +These are identical to those defined for +.Xr vm_page_protect 9 . +.It max_protection +Mask for the memory protection bits which may be actually be applied to +this region. +These are identical to those defined for +.Xr vm_page_protect 9 . +.It inheritance +Contains flags which specify how this entry should be treated +during fork processing. +.It wired_count +Count of how many times this entry has been wired into physical memory. +.It lastr +Contains the address of the last read which caused a page fault. +.El +.Pp +The following flags may be applied to each entry, by specifying them +as a mask within the +.Fa eflags +member: +.Bl -tag -width MAP_ENTRY_BEHAV_SEQUENTIALXXX +.It MAP_ENTRY_NOSYNC +The system should not flush the data associated with this map +periodically, but only when it needs to. +.It MAP_ENTRY_IS_SUB_MAP +If set, then the +.Fa object +member specifies a subordinate map. +.It MAP_ENTRY_COW +Indicate that this is a copy-on-write region. +.It MAP_ENTRY_NEEDS_COPY +Indicate that a copy-on-write region needs to be copied. +.It MAP_ENTRY_NOFAULT +Specifies that accesses within this region should never cause a page fault. +If a page fault occurs within this region, the system will panic. +.It MAP_ENTRY_USER_WIRED +Indicate that this region was wired on behalf of a user process. +.It MAP_ENTRY_BEHAV_NORMAL +The system should use the default paging behaviour for this region. +.It MAP_ENTRY_BEHAV_SEQUENTIAL +The system should depress the priority of pages immediately preceding +each page within this region when faulted in. +.It MAP_ENTRY_BEHAV_RANDOM +Is a hint that pages within this region will be accessed randomly, +and that prefetching is likely not advantageous. +.It MAP_ENTRY_IN_TRANSITION +Indicate that wiring or unwiring of an entry is in progress, and that +other kernel threads should not attempt to modify fields in the structure. +.It MAP_ENTRY_NEEDS_WAKEUP +Indicate that there are kernel threads waiting for this region to become +available. +.It MAP_ENTRY_NOCOREDUMP +The region should not be included in a core dump. +.El +.Pp +The +.Fa inheritance +member has type +.Fa vm_inherit_t . +This governs the inheritance behaviour for a map entry during fork processing. +The following values are defined for +.Fa vm_inherit_t : +.Bl -tag -width VM_INHERIT_DEFAULTXXX +.It VM_INHERIT_SHARE +The object associated with the entry should be cloned and shared +with the new map. +A new +.Fa struct vm_object +will be created if necessary. +.It VM_INHERIT_COPY +The object associated with the entry should be copied to the new map. +.It VM_INHERIT_NONE +The entry should not be copied to the new map. +.It VM_INHERIT_DEFAULT +Specifies the default behaviour, +.Fa VM_INHERIT_COPY . +.El +.Pp +The +.Fa union vm_map_object +is used to specify the structure which a +.Fa struct vm_map_entry +is associated with. +.Pp +The fields of +.Fa union vm_map_object +are as follows: +.Bd -literal -offset indent +union vm_map_object { + struct vm_object *vm_object; + struct vm_map *sub_map; +}; +.Pp +.Ed +Normally, the +.Fa sub_map +member is only used by system maps to indicate that a memory range +is managed by a subordinate system map. +Within a user process map, each +.Fa struct vm_map_entry +is backed by a +.Fa struct vm_object . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_map_check_protection 9 , +.Xr vm_map_clean 9 , +.Xr vm_map_create 9 , +.Xr vm_map_delete 9 , +.Xr vm_map_find 9 , +.Xr vm_map_findspace 9 , +.Xr vm_map_inherit 9 , +.Xr vm_map_init 9 , +.Xr vm_map_insert 9 , +.Xr vm_map_lock 9 , +.Xr vm_map_lookup 9 , +.Xr vm_map_madvise 9 , +.Xr vm_map_max 9 , +.Xr vm_map_min 9 , +.Xr vm_map_pmap 9 , +.Xr vm_map_protect 9 , +.Xr vm_map_remove 9 , +.Xr vm_map_simplify_entry 9 , +.Xr vm_map_stack 9 , +.Xr vm_map_submap 9 , +.Xr vm_map_wire 9 , +.Xr vm_page_protect 9 +.Sh AUTHORS +This man page was written by +.An Bruce M Simpson Aq bms@spc.org . |