d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add manual pages for the vm_map(9) part of the VM.

Browse Source 
Reviewed by:    juli
Approved by:    jake (mentor)
This commit is contained in:
Bruce M Simpson 2003-09-30 00:51:31 +00:00
parent 9ffa96777e
commit 7d216f0fa9
20 changed files with 1587 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
share/man/man9/Makefile
View File

@ -81,6 +81,11 @@ MAN= BUF_LOCK.9 BUF_LOCKFREE.9 BUF_LOCKINIT.9 BUF_REFCNT.9 \
vfsconf.9 \
vget.9 vgone.9 vhold.9 vinvalbuf.9 \
vflush.9 \
vm_map_check_protection.9 vm_map_clean.9 vm_map_create.9 \
vm_map_delete.9 vm_map_find.9 vm_map_findspace.9 vm_map_inherit.9 \
vm_map_init.9 vm_map_insert.9 vm_map_lock.9 vm_map_lookup.9 \
vm_map_madvise.9 vm_map_max.9 vm_map_protect.9 vm_map_remove.9 \
vm_map_simplify_entry.9 vm_map_stack.9 vm_map_submap.9 vm_map_wire.9 \
vm_page_alloc.9 vm_page_bits.9 vm_page_cache.9 \
vm_page_copy.9 vm_page_deactivate.9 vm_page_dontneed.9 \
vm_page_flag.9 vm_page_free.9 vm_page_grab.9 vm_page_hold.9 \
@ -289,6 +294,18 @@ MLINKS+=vfsconf.9 vfs_register.9
MLINKS+=vfsconf.9 vfs_unregister.9
MLINKS+=vgone.9 vgonel.9
MLINKS+=vhold.9 vdrop.9
MLINKS+=vm_map_lock.9 vm_map_unlock.9
MLINKS+=vm_map_lock.9 vm_map_lock_read.9
MLINKS+=vm_map_lock.9 vm_map_unlock_read.9
MLINKS+=vm_map_lock.9 vm_map_trylock.9
MLINKS+=vm_map_lock.9 vm_map_trylock_read.9
MLINKS+=vm_map_lock.9 vm_map_lock_upgrade.9
MLINKS+=vm_map_lock.9 vm_map_lock_downgrade.9
MLINKS+=vm_map_lookup.9 vm_map_lookup_done.9
MLINKS+=vm_map_max.9 vm_map_min.9
MLINKS+=vm_map_max.9 vm_map_pmap.9
MLINKS+=vm_map_stack.9 vm_map_growstack.9
MLINKS+=vm_map_wire.9 vm_map_unwire.9
MLINKS+=vm_page_bits.9 vm_page_set_validclean.9
MLINKS+=vm_page_bits.9 vm_page_clear_dirty.9
MLINKS+=vm_page_bits.9 vm_page_set_invalid.9

67
share/man/man9/vm_map_check_protection.9 Normal file
View File

@ -0,0 +1,67 @@
.\"
.\" 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_check_protection 9
.Sh NAME
.Nm vm_map_check_protection
.Nd check memory protection for a vm_map
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft boolean_t
.Fn vm_map_check_protection "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_prot_t protection"
.Sh DESCRIPTION
The
.Fn vm_map_check_protection
function asserts that the target
.Fa map
allows the specified privilege
.Fa protection
over the entire address range from
.Fa start
to
.Fa end .
The region MUST be contiguous; no holes are allowed.
.Sh IMPLEMENTATION NOTES
This code does not and SHOULD not check whether the contents of
the region are accessible.
For example, a small file may be mapped into an address space which
is significantly larger in size.
.Sh RETURN VALUES
The
.Fn vm_map_check_protection
function returns TRUE if the privilege is allowed; if it is not allowed,
or if any other error occurred, the value FALSE is returned.
.Sh SEE ALSO
.Xr munmap 2 ,
.Xr vm_map 9 ,
.Xr vm_map_protect 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

84
share/man/man9/vm_map_clean.9 Normal file
View File

@ -0,0 +1,84 @@
.\"
.\" 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_clean 9
.Sh NAME
.Nm vm_map_clean
.Nd push dirty pages to their pager
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_clean "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "boolean_t syncio" "boolean_t invalidate"
.Sh DESCRIPTION
The
.Fn vm_map_clean
function forces any dirty cached pages in the range
.Fa start
to
.Fa end
within the
.Fa map
to be pushed to their underlying pager.
.Pp
If
.Fa syncio
is TRUE, dirty pages are written synchronously.
.Pp
If
.Fa invalidate
is TRUE, any cached pages are also freed.
.Pp
The range provided must be contiguous, it MUST NOT contain holes.
The range provided MUST NOT contain any sub-map entries.
.Sh RETURN VALUES
The
.Fn vm_map_clean
function returns
.Dv KERN_SUCCESS
if successful.
otherwise
.Dv KERN_INVALID_ARGUMENT
will be returned.
.Pp
Otherwise,
.Dv KERN_INVALID_ADDRESS
will be returned if the function encountered a sub-map entry;
.Dv KERN_INVALID_ARGUMENT
will be returned if the function encountered a hole in the region provided,
or if an entry could not be found for the given start address.
.Sh IMPLEMENTATION NOTES
This routine holds the
.Dv Giant
lock to prevent multiple entry.
.Sh SEE ALSO
.Xr vm_map 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

65
share/man/man9/vm_map_create.9 Normal file
View File

@ -0,0 +1,65 @@
.\"
.\" 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_create 9
.Sh NAME
.Nm vm_map_create
.Nd create a new vm_map structure
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft vm_map_t
.Fn vm_map_create "pmap_t pmap" "vm_offset_t min" "vm_offset_t max"
.Sh DESCRIPTION
The
.Fn vm_map_create
function creates and returns a new, empty map structure, associated
with the physical map
.Fa pmap ,
and with the
upper and lower address bounds specified by
.Fa max
and
.Fa min
respectively.
.Sh IMPLEMENTATION NOTES
The kernel's zone allocator is used to allocate the map.
.Sh RETURN VALUES
The
.Fn vm_map_create
function returns a pointer to the newly allocated map if successful.
Otherwise, it returns
.Dv NULL .
.Sh SEE ALSO
.Xr pmap 9 ,
.Xr vm_map 9 ,
.Xr vm_map_init 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

67
share/man/man9/vm_map_delete.9 Normal file
View File

@ -0,0 +1,67 @@
.\"
.\" 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_delete 9
.Sh NAME
.Nm vm_map_delete
.Nd deallocate an address range from a map
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_delete "vm_map_t map" "vm_offset_t start" "vm_offset_t end"
.Sh DESCRIPTION
The
.Fn vm_map_delete
function deallocates the address range bounded by
.Fa start
and
.Fa end
from the
.Fa map .
.Sh IMPLEMENTATION NOTES
This function is for
.Fx
VM internal use only.
The
.Xr vm_map_remove 9
function should be called by
.Fx
VM consumers instead.
.Sh RETURN VALUES
The
.Fn vm_map_delete
function always returns
.Dv KERN_SUCCESS .
.Sh SEE ALSO
.Xr vm_map 9 ,
.Xr vm_map_remove 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

101
share/man/man9/vm_map_find.9 Normal file
View File

@ -0,0 +1,101 @@
.\"
.\" 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_find 9
.Sh NAME
.Nm vm_map_find
.Nd find a free region within a map, and optionally map a vm_object
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_find "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset" "vm_offset_t *addr" "vm_size_t length" "boolean_t find_space" "vm_prot_t prot" "vm_prot_t max" "int cow"
.Sh DESCRIPTION
The
.Fn vm_map_find
function attempts to find a free region in the target
.Fa map ,
with the given
.Fa length ,
and will also optionally create a mapping of
.Fa object .
.Pp
The arguments
.Fa offset ,
.Fa prot ,
.Fa max ,
and
.Fa cow
are passed unchanged to
.Xr vm_map_insert 9
when creating the mapping, if and only if a free region is found.
.Pp
If
.Fa object
is non-NULL, the reference count on the object must be incremented
by the caller before calling this function to account for the new entry.
.Pp
If
.Fa find_space
is
.Dv TRUE ,
the function will call
.Xr vm_map_findspace 9
to discover a free region.
.Sh IMPLEMENTATION NOTES
This function acquires a lock on
.Fa map
by calling
.Xr vm_map_lock 9 ,
and holds it until the function returns.
.Pp
The search for a free region is defined to be first-fit, from the address
.Fa addr
onwards.
.Sh RETURN VALUES
The
.Fn
function returns
.Dv KERN_SUCCESS
if space for the mapping could be found and
the mapping was successfully created.
If space could not be found in the map,
.Dv KERN_NO_SPACE
will be returned.
If the discovered range turned out to be bogus,
.Dv KERN_INVALID_ADDRESS
will be returned.
.Sh SEE ALSO
.Xr vm_map 9 ,
.Xr vm_map_findspace 9 ,
.Xr vm_map_insert 9 ,
.Xr vm_map_lock 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

74
share/man/man9/vm_map_findspace.9 Normal file
View File

@ -0,0 +1,74 @@
.\"
.\" 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_findspace 9
.Sh NAME
.Nm vm_map_findspace
.Nd find a free region within a map
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_findspace "vm_map_t map" "vm_offset_t start" "vm_size_t length" "vm_offset_t *addr"
.Sh DESCRIPTION
The
.Fn vm_map_findspace
function attempts to find a region with sufficient space in the
.Fa map
for an object of size
.Fa length
at the address
.Fa addr .
.Sh IMPLEMENTATION NOTES
It is the caller's responsibility to obtain a lock on the
.Fa map
using
.Xr vm_map_lock 9
before calling this function.
.Pp
This routine may call
.Xr pmap_growkernel 9
to grow the kernel's address space, if and only if the mapping is being
made within the kernel address space, and if insufficient space remains
in the
.Dv kernel_map .
.Sh RETURN VALUES
The
.Fn vm_map_findspace
function returns the value 0 if successful, and
.Fa *addr
will contain the first virtual address in the found region;
otherwise, the value 1 is returned.
.Sh SEE ALSO
.Xr pmap_growkernel 9 ,
.Xr vm_map 9 ,
.Xr vm_map_lock 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

81
share/man/man9/vm_map_inherit.9 Normal file
View File

@ -0,0 +1,81 @@
.\"
.\" 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_inherit 9
.Sh NAME
.Nm vm_map_inherit
.Nd set fork inheritance flags for a range within a map
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_inherit "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_inherit_t new_inheritance"
.Sh DESCRIPTION
The
.Fn vm_map_inherit
function sets the inheritance flags for the range
.Fa start
to
.Fa end
within the target
.Fa map
to the value
.Fa new_inheritance .
.Pp
The
.Fa new_inheritance
flag must have one of the values
.Dv VM_INHERIT_NONE ,
.Dv VM_INHERIT_COPY ,
or
.Dv VM_INHERIT_SHARE .
This affects how the map will be shared with child maps when the
associated process forks.
.Sh IMPLEMENTATION NOTES
The
.Fn
function obtains a lock on the
.Fa map
using
.Xr vm_map_lock 9
for the duration of the function.
.Sh RETURN VALUES
The
.Fn vm_map_inherit
function returns
.Dv KERN_SUCCESS
if the inheritance flags could be set.
Otherwise, if the provided flags were invalid,
.Dv KERN_INVALID_ARGUMENT
will be returned.
.Sh SEE ALSO
.Xr fork 2
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

58
share/man/man9/vm_map_init.9 Normal file
View File

@ -0,0 +1,58 @@
.\"
.\" 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_init 9
.Sh NAME
.Nm vm_map_init
.Nd initialize a vm_map structure for process zero
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft void
.Fn vm_map_init "vm_map_t map" "vm_offset_t min" "vm_offset_t max"
.Sh DESCRIPTION
The
.Fn vm_map_init
function initializes the system map
.Fa map
by setting its upper and lower address bounds to
.Fa max
and
.Fa min
respectively.
.Pp
It also initializes the system map mutex.
.Sh IMPLEMENTATION NOTES
This routine is for internal use only.
It is called during early system initialization.
.Sh SEE ALSO
.Xr vm_map 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

91
share/man/man9/vm_map_insert.9 Normal file
View File

@ -0,0 +1,91 @@
.\"
.\" 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_insert 9
.Sh NAME
.Nm vm_map_insert
.Nd insert an object into a map
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_insert "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset" "vm_offset_t start" "vm_offset_t end" "vm_prot_t prot" "vm_prot_t max" "int cow"
.Sh DESCRIPTION
The
.Fn vm_map_insert
function inserts a mapping for the entire vm_object
.Fa object
into the target map
.Fa map .
.Pp
The
.Fa offset
argument specifies the offset into the
.Fa object
at which to begin mapping.
The object's size should match that of the specified address range.
.Pp
The
.Fa start
and
.Fa end
arguments specify the bounds of the mapped object's window in the
address space of
.Fa map .
.Pp
The
.Fa cow
argment specifies the flags which should be propagated to the new entry,
for example, to indicate that this is a copy-on-write mapping.
.Sh IMPLEMENTATION NOTES
This function implicity creates a new
.Dv vm_map_entry
by calling the internal function
.Fn vm_map_entry_create .
This function may use the
.Dv Giant
lock to ensure that only a single thread is present in the function.
.Sh RETURN VALUES
The
.Fn vm_map_insert
function returns
.Dv KERN_SUCCESS
if the mapping could be made successfully.
.Pp
Otherwise,
.Dv KERN_INVALID_ADDRESS
will be returned if the start of the range could not be found, or
.Dv KERN_NO_SPACE
if the range was found to be part of an existing entry or if it
overlaps the end of the map.
.Sh SEE ALSO
.Xr vm_map 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

118
share/man/man9/vm_map_lock.9 Normal file
View File

@ -0,0 +1,118 @@
.\"
.\" 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_lock 9
.Sh NAME
.Nm vm_map_lock ,
.Nm vm_map_unlock ,
.Nm vm_map_lock_read ,
.Nm vm_map_unlock_read ,
.Nm vm_map_trylock ,
.Nm vm_map_trylock_read ,
.Nm vm_map_lock_upgrade ,
.Nm vm_map_lock_downgrade
.Nd vm_map locking macros
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft void
.Fn vm_map_lock "vm_map_t map"
.Ft void
.Fn vm_map_unlock "vm_map_t map"
.Ft void
.Fn vm_map_lock_read "vm_map_t map"
.Ft void
.Fn vm_map_unlock_read "vm_map_t map"
.Ft int
.Fn vm_map_trylock "vm_map_t map"
.Ft int
.Fn vm_map_trylock_read "vm_map_t map"
.Ft int
.Fn vm_map_lock_upgrade "vm_map_t map"
.Ft int
.Fn vm_map_lock_downgrade "vm_map_t map"
.Sh DESCRIPTION
The
.Fn vm_map_lock
macro obtains an exclusive lock on
.Fa map .
.Pp
The
.Fn vm_map_unlock
macro releases an exclusive lock on
.Fa map .
.Pp
The
.Fn vm_map_lock_read
macro obtains a read-lock on
.Fa map .
Currently this is implemented as an exclusive lock.
.Pp
The
.Fn vm_map_unlock_read
macro releases a read-lock on
.Fa map .
.Pp
The
.Fn vm_map_trylock
macro attempts to obtain an exclusive lock on
.Fa map .
It returns FALSE if the lock cannot be immediately acquired;
otherwise return TRUE with the lock acquired.
.Pp
The
.Fn vm_map_trylock_read
macro attempts to obtain a read-lock on
.Fa map .
It returns FALSE if the lock cannot be immediately acquired;
otherwise return TRUE with the lock acquired.
Currently this is implemented as an exclusive lock.
.Pp
The
.Fn vm_map_lock_upgrade
macro attempts to atomically upgrade a read-lock on
.Fa map
to an exclusive lock.
As read-locks are currently implemented as exclusive locks,
this macro is a no-op.
.Pp
The
.Fn vm_map_lock_downgrade
macro attempts to downgrade an exclusive lock on
.Fa map
to a read-lock.
As read-locks are currently implemented as exclusive locks,
this macro is a no-op.
.Sh IMPLEMENTATION NOTES
Currently, all of the locking macros implement their locks as sleep locks.
.Sh SEE ALSO
.Xr vm_map 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

82
share/man/man9/vm_map_lookup.9 Normal file
View File

@ -0,0 +1,82 @@
.\"
.\" 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_lookup 9
.Sh NAME
.Nm vm_map_lookup ,
.Nm vm_map_lookup_done
.Nd lookup the vm_object backing a given virtual region
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_lookup "vm_map_t *var_map" "vm_offset_t vaddr" "vm_prot_t fault_type" "vm_map_entry_t *out_entry" "vm_object_t *object" "vm_pindex_t *pindex" "vm_prot_t *out_prot" "boolean_t *wired"
.Ft void
.Fn vm_map_lookup_done "vm_map_t map" "vm_map_entry_t entry"
.Sh DESCRIPTION
The
.Fn vm_map_lookup
function attempts to find the
vm_object, page index and protection, for the given virtual address
.Fa vaddr ,
in the map
.Fa var_map ,
assuming a page fault of the type
.Fa fault_type
had occurred.
.Pp
Return values are guaranteed until
.Fn vm_map_lookup_done
is called to release the lock.
.Sh IMPLEMENTATION NOTES
The function
.Fn vm_map_lookup
acquires a read-lock on the map
.Fa *var_map ,
but does not release it.
The caller should invoke
.Fn vm_map_lookup_done
in order to release this lock.
.Sh RETURN VALUES
The
.Fn vm_map_lookup
function returns
.Dv KERN_SUCCESS ,
and sets the
.Fa *object ,
.Fa *pindex ,
.Fa *out_prot ,
and
.Fa *out_entry
arguments appropriately for the hypothetical page fault.
.Sh SEE ALSO
.Xr vm_map 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

74
share/man/man9/vm_map_madvise.9 Normal file
View File

@ -0,0 +1,74 @@
.\"
.\" 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_madvise 9
.Sh NAME
.Nm vm_map_madvise
.Nd apply advice about use of memory to map entries
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_madvise "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "int behav"
.Sh DESCRIPTION
The
.Fn vm_map_madvise
function applies the flags
.Fa behav
to the entries within
.Fa map
between
.Fa start
and
.Fa end .
.Pp
Advisories are classified as either those affecting the
.Dv vm_map_entry
structure, or those affecting the underlying objects.
.Pp
The
.Fn vm_map_madvise
function is used by the
.Fn madvise
system call.
.Sh RETURN VALUES
The
.Fn vm_map_madvise
function returns 0 if successful.
If the
.Fa behav
argument was not recognised,
.Dv KERN_INVALID_ARGUMENT
is returned.
.Sh SEE ALSO
.Xr madvise 2 ,
.Xr vm_map 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

65
share/man/man9/vm_map_max.9 Normal file
View File

@ -0,0 +1,65 @@
.\"
.\" 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_max 9
.Sh NAME
.Nm vm_map_max ,
.Nm vm_map_min ,
.Nm vm_map_pmap
.Nd return map properties
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft vm_offset_t
.Fn vm_map_max "vm_map_t map"
.Ft vm_offset_t
.Fn vm_map_min "vm_map_t map"
.Ft pmap_t
.Fn vm_map_pmap "vm_map_t map"
.Sh DESCRIPTION
The function
.Fn vm_map_max
returns the upper address bound of the map
.Fa map .
.Pp
The function
.Fn vm_map_min
returns the lower address bound of the map
.Fa map .
.Pp
The function
.Fn vm_map_pmap
returns a pointer to the physical map associated with the virtual map
.Fa map .
.Sh SEE ALSO
.Xr pmap 9 ,
.Xr vm_map 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

89
share/man/man9/vm_map_protect.9 Normal file
View File

@ -0,0 +1,89 @@
.\"
.\" 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_protect 9
.Sh NAME
.Nm vm_map_protect
.Nd apply protection bits to a virtual memory region
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_protect "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_prot_t new_prot" "boolean_t set_max"
.Sh DESCRIPTION
The
.Fn vm_map_protect
function sets the protection bits of the address region bounded by
.Fa start
and
.Fa end
within the map
.Fa map
to
.Fa new_prot .
.Pp
If
.Fa set_max
is TRUE,
.Fa new_prot
is treated as the new
.Dv max_protection
setting for each underlying entry.
Otherwise, only the
.Dv protection
field is affected.
.Pp
The range MUST be contiguous, and MUST NOT contain sub-maps.
.Sh IMPLEMENTATION NOTES
The function acquires a lock on the
.Fa map
for the duration, by calling
.Xr vm_map_lock .
.Sh RETURN VALUES
The
.Fn vm_map_protect
function returns
.Dv KERN_SUCCESS
if the protection bits could be set successfully.
.Pp
If a sub-map entry was encountered in the range,
.Dv KERN_INVALID_ARGUMENT
is returned.
If the value of
.Fa new_prot
would exceed
.Dv max_protection
for an entry within the range,
.Dv KERN_PROTECTION_FAILURE
is returned.
.Sh SEE ALSO
.Xr vm_map 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

68
share/man/man9/vm_map_remove.9 Normal file
View File

@ -0,0 +1,68 @@
.\"
.\" 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_remove 9
.Sh NAME
.Nm vm_map_remove
.Nd remove a virtual address range from a map
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_remove "vm_map_t map" "vm_offset_t start" "vm_offset_t end"
.Sh DESCRIPTION
The
.Fn vm_map_remove
function removes the given address range bounded by
.Fa start
and
.Fa end
from the target
.Fa map .
.Sh IMPLEMENTATION NOTES
This is the exported form of
.Xr vm_map_remove 9
which may be called by consumers of the VM subsystem.
.Pp
The function calls
.Xr vm_map_lock 9
to hold a lock on
.Fa map
for the duration of the function call.
.Sh RETURN VALUES
The
.Fn vm_map_remove
always returns
.Dv KERN_SUCCESS .
.Sh SEE ALSO
.Xr vm_map 9 ,
.Xr vm_map_delete 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

59
share/man/man9/vm_map_simplify_entry.9 Normal file
View File

@ -0,0 +1,59 @@
.\"
.\" 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_simplify_entry 9
.Sh NAME
.Nm vm_map_simplify_entry
.Nd simplify a vm_map_entry
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft void
.Fn vm_map_simplify_entry "vm_map_t map" "vm_map_entry_t entry"
.Sh DESCRIPTION
The
.Fn vm_map_simplify_entry
function simplifies the given
.Fa entry
by merging with either neighbour.
The
.Fa map
must be locked upon entry.
.Pp
This function also has the ability to merge with both neighbours.
.Pp
This function guarantees that the passed entry remains valid, although
possibly extended.
.Sh SEE ALSO
.Xr vm_map 9 ,
.Xr vm_map_insert 9 ,
.Xr vm_map_remove 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

128
share/man/man9/vm_map_stack.9 Normal file
View File

@ -0,0 +1,128 @@
.\"
.\" 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_stack 9
.Sh NAME
.Nm vm_map_stack ,
.Nm vm_map_growstack
.Nd manage process stacks
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_stack "vm_map_t map" "vm_offset_t addrbos" "vm_size_t max_ssize" "vm_prot_t prot" "vm_prot_t max" "int cow"
.Ft int
.Fn vm_map_growstack "struct proc *p" "vm_offset_t addr"
.Sh DESCRIPTION
The
.Fn
function maps a process stack for a new process image.
The stack is mapped
.Fa addrbos
in
.Fa map ,
with a maximum size of
.Fa max_ssize .
Copy-on-write flags passed in
.Fa cow
are also applied to the new mapping.
Protection bits are supplied by
.Fa prot
and
.Fa max .
.Pp
It is typically called by
.Xr exec 2 .
.Pp
The
.Fn vm_map_growstack
function is responsible for growing a stack for the process
.Fa p
to the desired address
.Fa addr ,
similar to the legacy
.Xr sbrk 2
call.
.Sh IMPLEMENTATION NOTES
The
.Fn vm_map_stack
function calls
.Xr vm_map_insert 9
to create its mappings.
.Pp
The
.Fn vm_map_growstack
function acquires the
.Dv Giant
lock, and the process lock on
.Fa p ,
for the duration of the call.
.Sh RETURN VALUES
The
.Fn vm_map_stack
function returns
.Dv KERN_SUCCESS
if the mapping was allocated successfully.
.Pp
Otherwise,
if mapping the stack would exceed the process's VMEM resource limit,
or if the specified bottom-of-stack address is out of range for the map,
or if there is already a mapping at the address which would result,
or if
.Fa max_ssize
could not be accomodated within the current mapping,
.Dv KERN_NO_SPACE
is returned.
.Pp
Other possible return values for this function are documented in
.Xr vm_map_insert 9 .
.Pp
The
.Fn vm_map_growstack
function returns
.Dv KERN_SUCCESS
if
.Fa addr
is already mapped, or if the stack was grown successfully.
.Pp
It also returns
.Dv KERN_SUCCESS
if
.Fa addr
is outside the stack range; this is done in order to preserve
compatibility with the deprecated
.Fn grow
function previously located in the file
.Li vm_machdep.c .
.Sh SEE ALSO
.Xr vm_map 9 ,
.Xr vm_map_insert 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

90
share/man/man9/vm_map_submap.9 Normal file
View File

@ -0,0 +1,90 @@
.\"
.\" 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_submap 9
.Sh NAME
.Nm vm_map_submap
.Nd create a subordinate map
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_submap "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_map_t submap"
.Sh DESCRIPTION
The
.Fn vm_map_submap
function marks the range bounded by
.Fa start
and
.Fa end
within the map
.Fa map
as being handled by a subordinate map
.Fa sub_map .
.Pp
It is generally called by the kernel memory allocator.
.Sh IMPLEMENTATION NOTES
This function is for internal use only.
.Pp
Both maps must exist.
The range must have been created with
.Xr vm_map_find 9
previously.
.Pp
No other operations may have been performed on this range
before calling this function.
Only the
.Fn vm_fault
operation may be performed within this range after calling
this function.
.Pp
To remove a submapping, one must first remove the range from
the parent
.Fa map ,
and then destroy the
.Fa sub_map .
This procedure is not recommended.
.Sh RETURN VALUES
The
.Fn vm_map_submap
function returns
.Dv KERN_SUCCESS
if successful.
.Pp
Otherwise, it returns
.Dv KERN_INVALID_ARGUMENT
if the caller requested copy-on-write flags,
or if the range specified for the sub-map was out of range for the parent map,
or if a NULL backing object was specified.
.Sh SEE ALSO
.Xr vm_map 9 ,
.Xr vm_map_find 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .

109
share/man/man9/vm_map_wire.9 Normal file
View File

@ -0,0 +1,109 @@
.\"
.\" 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_wire 9
.Sh NAME
.Nm vm_map_wire ,
.Nm vm_map_unwire
.Nd manage page wiring within a virtual memory map
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_map.h
.Ft int
.Fn vm_map_wire "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "int flags"
.Ft int
.Fn vm_map_unwire "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "int flags"
.Sh DESCRIPTION
The
.Fn vm_map_wire
function is responsible for wiring pages in the range between
.Fa start
and
.Fa end
within the map
.Fa map .
Wired pages are locked into physical memory, and may not be paged out
as long as their wire count remains above zero.
.Pp
The
.Fn vm_map_unwire
function performs the corresponding unwire operation.
.Pp
The
.Fa flags
argument is a bit mask, consisting of the following flags:
.Pp
If the
.Dv VM_MAP_WIRE_USER
flag is set, the function operates within user address space.
.Pp
If the
.Dv VM_MAP_WIRE_HOLESOK
flag is set, it may operate upon an arbitrary range within the
address space of
.Fa map .
.Pp
If a contiguous range is desired, callers should explicitly express
their intent by specifying the
.Dv VM_MAP_WIRE_NOHOLES
flag.
.Sh IMPLEMENTATION NOTES
Both functions will attempt to acquire a lock on the map using
.Xr vm_map_lock 9
and hold it for the duration of the call.
If they detect
.Dv MAP_ENTRY_IN_TRANSITION ,
they will call
.Xr vm_map_unlock_and_wait 9
until the map becomes available again.
.Pp
The map could have changed during this window as it was held by another
consumer, therefore consumers of this interface should check for this
condition using the return values below.
.Sh RETURN VALUES
The
.Fn vm_map_wire
and
.Fn vm_map_unwire
functions have identical return values.
The functions return
.Dv KERN_SUCCESS
if all pages within the range were [un]wired successfully.
.Pp
Otherwise, if the specified range was not valid,
or if the map changed while the MAP_ENTRY_IN_TRANSITION flag was set,
.Dv KERN_INVALID_ADDRESS
is returned.
.Sh SEE ALSO
.Xr mlockall 2 ,
.Xr munlockall 2 ,
.Xr vm_map 9
.Sh AUTHORS
This man page was written by
.An Bruce M Simpson Aq bms@spc.org .