mirror of
https://github.com/opnsense/src.git
synced 2026-04-24 07:37:25 -04:00
Add a (somewhat verbose) manual page for vm_map(9).
Reviewed by: juli Approved by: jake (mentor)
This commit is contained in:
Bruce M Simpson
parent
7d216f0fa9
commit
274302ba7a
1 changed files with 320 additions and 0 deletions
320
share/man/man9/vm_map.9
Normal file
320
share/man/man9/vm_map.9
Normal file
|
|
@ -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 .
|
||||
Loading…
Reference in a new issue