Add a (somewhat verbose) manual page for vm_map(9).

Reviewed by:	juli
Approved by:	jake (mentor)

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 .