Module Name: src
Committed By: rmind
Date: Wed Jun 1 02:22:20 UTC 2011
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile uvm.9
Added Files:
src/share/man/man9: uvm_km.9 uvm_map.9
Log Message:
Split parts of uvm(9) into uvm_km(9) and uvm_map(9) man pages.
OK mrg@
To generate a diff of this commit:
cvs rdiff -u -r1.1626 -r1.1627 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.346 -r1.347 src/share/man/man9/Makefile
cvs rdiff -u -r1.105 -r1.106 src/share/man/man9/uvm.9
cvs rdiff -u -r0 -r1.1 src/share/man/man9/uvm_km.9 \
src/share/man/man9/uvm_map.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1626 src/distrib/sets/lists/comp/mi:1.1627
--- src/distrib/sets/lists/comp/mi:1.1626 Mon May 30 02:10:25 2011
+++ src/distrib/sets/lists/comp/mi Wed Jun 1 02:22:19 2011
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1626 2011/05/30 02:10:25 christos Exp $
+# $NetBSD: mi,v 1.1627 2011/06/01 02:22:19 rmind Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -10169,6 +10169,7 @@
./usr/share/man/cat9/uvm_init_limits.0 comp-sys-catman .cat
./usr/share/man/cat9/uvm_io.0 comp-sys-catman .cat
./usr/share/man/cat9/uvm_kernacc.0 comp-sys-catman .cat
+./usr/share/man/cat9/uvm_km.0 comp-sys-catman .cat
./usr/share/man/cat9/uvm_km_alloc.0 comp-sys-catman .cat
./usr/share/man/cat9/uvm_km_alloc1.0 comp-obsolete obsolete
./usr/share/man/cat9/uvm_km_free.0 comp-sys-catman .cat
@@ -16106,6 +16107,7 @@
./usr/share/man/html9/uvm_init_limits.html comp-sys-htmlman html
./usr/share/man/html9/uvm_io.html comp-sys-htmlman html
./usr/share/man/html9/uvm_kernacc.html comp-sys-htmlman html
+./usr/share/man/html9/uvm_km.html comp-sys-htmlman html
./usr/share/man/html9/uvm_km_alloc.html comp-sys-htmlman html
./usr/share/man/html9/uvm_km_free.html comp-sys-htmlman html
./usr/share/man/html9/uvm_km_suballoc.html comp-sys-htmlman html
@@ -22259,6 +22261,7 @@
./usr/share/man/man9/uvm_init_limits.9 comp-sys-man .man
./usr/share/man/man9/uvm_io.9 comp-sys-man .man
./usr/share/man/man9/uvm_kernacc.9 comp-sys-man .man
+./usr/share/man/man9/uvm_km.9 comp-sys-man .man
./usr/share/man/man9/uvm_km_alloc.9 comp-sys-man .man
./usr/share/man/man9/uvm_km_alloc1.9 comp-obsolete obsolete
./usr/share/man/man9/uvm_km_free.9 comp-sys-man .man
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.346 src/share/man/man9/Makefile:1.347
--- src/share/man/man9/Makefile:1.346 Wed Apr 6 05:40:19 2011
+++ src/share/man/man9/Makefile Wed Jun 1 02:22:18 2011
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.346 2011/04/06 05:40:19 jruoho Exp $
+# $NetBSD: Makefile,v 1.347 2011/06/01 02:22:18 rmind Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -54,7 +54,7 @@
vattr.9 veriexec.9 vcons.9 vfs.9 vfs_hooks.9 vfsops.9 vfssubr.9 \
video.9 vme.9 \
vnfileops.9 vnode.9 vnodeops.9 vnsubr.9 \
- ubc.9 usbdi.9 uvm.9 vmem.9 \
+ ubc.9 usbdi.9 uvm.9 uvm_km.9 uvm_map.9 vmem.9 \
wdc.9 workqueue.9 \
wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9 \
xcall.9
@@ -734,18 +734,12 @@
tc.9 TC_PHYS_TO_UNCACHED.9
MLINKS+=todr.9 todr_gettime.9 todr.9 todr_settime.9 \
todr.9 clock_ymdhms_to_secs.9 todr.9 clock_secs_to_ymdhms.9
+
MLINKS+=ubc.9 ubc_alloc.9 ubc.9 ubc_release.9 ubc.9 ubc_uiomove.9
MLINKS+=uvm.9 uvm_init.9 uvm.9 uvm_init_limits.9 uvm.9 uvm_setpagesize.9 \
- uvm.9 uvm_swap_init.9 uvm.9 uvm_map.9 uvm.9 uvm_unmap.9 \
- uvm.9 uvm_map_pageable.9 \
- uvm.9 uvm_map_checkprot.9 uvm.9 uvm_map_protect.9 \
- uvm.9 uvm_deallocate.9 uvm.9 uvmspace_alloc.9 uvm.9 uvmspace_exec.9 \
- uvm.9 uvmspace_fork.9 uvm.9 uvmspace_free.9 uvm.9 uvmspace_share.9 \
- uvm.9 uvmspace_unshare.9 uvm.9 uvm_fault.9 \
+ uvm.9 uvm_swap_init.9 uvm.9 uvm_fault.9 \
uvm.9 uvm_vnp_setsize.9 \
- uvm.9 uvm_io.9 uvm.9 uvm_km_alloc.9 \
- uvm.9 uvm_km_suballoc.9 uvm.9 uvm_km_free.9 \
- uvm.9 uvm_pagealloc.9 \
+ uvm.9 uvm_io.9 uvm.9 uvm_pagealloc.9 \
uvm.9 uvm_pagerealloc.9 uvm.9 uvm_pagefree.9 uvm.9 uvm_pglistalloc.9 \
uvm.9 uvm_pglistfree.9 uvm.9 uvm_page_physload.9 uvm.9 uvm_pageout.9 \
uvm.9 uvm_scheduler.9 uvm.9 uvm_swapin.9 uvm.9 uao_create.9 \
@@ -755,6 +749,15 @@
uvm.9 uvm_fork.9 uvm.9 uvm_grow.9 \
uvm.9 uvn_findpages.9 \
uvm.9 uvm_loan.9 uvm.9 uvm_unloan.9
+MLINKS+=uvm_km.9 uvm_km_alloc.9 uvm_km.9 uvm_km_free.9 \
+ uvm_km.9 uvm_km_suballoc.9
+MLINKS+=uvm_map.9 uvm_unmap.9 uvm_map.9 uvm_map_pageable.9 \
+ uvm_map.9 uvm_map_checkprot.9 uvm_map.9 uvm_map_protect.9 \
+ uvm_map.9 uvm_deallocate.9 uvm_map.9 uvmspace_alloc.9 \
+ uvm_map.9 uvmspace_exec.9 uvm_map.9 uvmspace_fork.9 \
+ uvm_map.9 uvmspace_free.9 uvm_map.9 uvmspace_share.9 \
+ uvm_map.9 uvmspace_unshare.9
+
MLINKS+=vme.9 vme_probe.9 \
vme.9 vme_space_map.9 \
vme.9 vme_space_unmap.9 \
Index: src/share/man/man9/uvm.9
diff -u src/share/man/man9/uvm.9:1.105 src/share/man/man9/uvm.9:1.106
--- src/share/man/man9/uvm.9:1.105 Wed Apr 27 06:02:03 2011
+++ src/share/man/man9/uvm.9 Wed Jun 1 02:22:18 2011
@@ -1,4 +1,4 @@
-.\" $NetBSD: uvm.9,v 1.105 2011/04/27 06:02:03 wiz Exp $
+.\" $NetBSD: uvm.9,v 1.106 2011/06/01 02:22:18 rmind Exp $
.\"
.\" Copyright (c) 1998 Matthew R. Green
.\" All rights reserved.
@@ -24,7 +24,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
-.Dd April 27, 2011
+.Dd June 1, 2011
.Dt UVM 9
.Os
.Sh NAME
@@ -103,287 +103,8 @@
.Fn uvm_swap_init
initializes the swap sub-system.
.Sh VIRTUAL ADDRESS SPACE MANAGEMENT
-.Bl -ohang
-.It Ft int
-.Fn uvm_map "struct vm_map *map" "vaddr_t *startp" "vsize_t size" "struct uvm_object *uobj" "voff_t uoffset" "vsize_t align" "uvm_flag_t flags" ;
-.It Ft void
-.Fn uvm_unmap "struct vm_map *map" "vaddr_t start" "vaddr_t end" ;
-.It Ft int
-.Fn uvm_map_pageable "struct vm_map *map" "vaddr_t start" "vaddr_t end" "bool new_pageable" "int lockflags" ;
-.It Ft bool
-.Fn uvm_map_checkprot "struct vm_map *map" "vaddr_t start" "vaddr_t end" "vm_prot_t protection" ;
-.It Ft int
-.Fn uvm_map_protect "struct vm_map *map" "vaddr_t start" "vaddr_t end" "vm_prot_t new_prot" "bool set_max" ;
-.It Ft int
-.Fn uvm_deallocate "struct vm_map *map" "vaddr_t start" "vsize_t size" ;
-.It Ft struct vmspace *
-.Fn uvmspace_alloc "vaddr_t min" "vaddr_t max" "int pageable" ;
-.It Ft void
-.Fn uvmspace_exec "struct lwp *l" "vaddr_t start" "vaddr_t end" ;
-.It Ft struct vmspace *
-.Fn uvmspace_fork "struct vmspace *vm" ;
-.It Ft void
-.Fn uvmspace_free "struct vmspace *vm1" ;
-.It Ft void
-.Fn uvmspace_share "struct proc *p1" "struct proc *p2" ;
-.It Ft void
-.Fn uvmspace_unshare "struct lwp *l" ;
-.It Ft bool
-.Fn uvm_uarea_alloc "vaddr_t *uaddrp" ;
-.It Ft void
-.Fn uvm_uarea_free "vaddr_t uaddr" ;
-.El
-.Pp
-.Fn uvm_map
-establishes a valid mapping in map
-.Fa map ,
-which must be unlocked.
-The new mapping has size
-.Fa size ,
-which must be a multiple of
-.Dv PAGE_SIZE .
-The
-.Fa uobj
-and
-.Fa uoffset
-arguments can have four meanings.
-When
-.Fa uobj
-is
-.Dv NULL
-and
-.Fa uoffset
-is
-.Dv UVM_UNKNOWN_OFFSET ,
-.Fn uvm_map
-does not use the machine-dependent
-.Dv PMAP_PREFER
-function.
-If
-.Fa uoffset
-is any other value, it is used as the hint to
-.Dv PMAP_PREFER .
-When
-.Fa uobj
-is not
-.Dv NULL
-and
-.Fa uoffset
-is
-.Dv UVM_UNKNOWN_OFFSET ,
-.Fn uvm_map
-finds the offset based upon the virtual address, passed as
-.Fa startp .
-If
-.Fa uoffset
-is any other value, we are doing a normal mapping at this offset.
-The start address of the map will be returned in
-.Fa startp .
-.Pp
-.Fa align
-specifies alignment of mapping unless
-.Dv UVM_FLAG_FIXED
-is specified in
-.Fa flags .
-.Fa align
-must be a power of 2.
-.Pp
-.Fa flags
-passed to
-.Fn uvm_map
-are typically created using the
-.Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" "int advice" "int flags"
-macro, which uses the following values.
-The
-.Fa prot
-and
-.Fa maxprot
-can take are:
-.Bd -literal
-#define UVM_PROT_MASK 0x07 /* protection mask */
-#define UVM_PROT_NONE 0x00 /* protection none */
-#define UVM_PROT_ALL 0x07 /* everything */
-#define UVM_PROT_READ 0x01 /* read */
-#define UVM_PROT_WRITE 0x02 /* write */
-#define UVM_PROT_EXEC 0x04 /* exec */
-#define UVM_PROT_R 0x01 /* read */
-#define UVM_PROT_W 0x02 /* write */
-#define UVM_PROT_RW 0x03 /* read-write */
-#define UVM_PROT_X 0x04 /* exec */
-#define UVM_PROT_RX 0x05 /* read-exec */
-#define UVM_PROT_WX 0x06 /* write-exec */
-#define UVM_PROT_RWX 0x07 /* read-write-exec */
-.Ed
-.Pp
-The values that
-.Fa inh
-can take are:
-.Bd -literal
-#define UVM_INH_MASK 0x30 /* inherit mask */
-#define UVM_INH_SHARE 0x00 /* "share" */
-#define UVM_INH_COPY 0x10 /* "copy" */
-#define UVM_INH_NONE 0x20 /* "none" */
-#define UVM_INH_DONATE 0x30 /* "donate" \*[Lt]\*[Lt] not used */
-.Ed
-.Pp
-The values that
-.Fa advice
-can take are:
-.Bd -literal
-#define UVM_ADV_NORMAL 0x0 /* 'normal' */
-#define UVM_ADV_RANDOM 0x1 /* 'random' */
-#define UVM_ADV_SEQUENTIAL 0x2 /* 'sequential' */
-#define UVM_ADV_MASK 0x7 /* mask */
-.Ed
-.Pp
-The values that
-.Fa flags
-can take are:
-.Bd -literal
-#define UVM_FLAG_FIXED 0x010000 /* find space */
-#define UVM_FLAG_OVERLAY 0x020000 /* establish overlay */
-#define UVM_FLAG_NOMERGE 0x040000 /* don't merge map entries */
-#define UVM_FLAG_COPYONW 0x080000 /* set copy_on_write flag */
-#define UVM_FLAG_AMAPPAD 0x100000 /* for bss: pad amap to reduce malloc() */
-#define UVM_FLAG_TRYLOCK 0x200000 /* fail if we can not lock map */
-.Ed
-.Pp
-The
-.Dv UVM_MAPFLAG
-macro arguments can be combined with an or operator.
-There are several special purpose macros for checking protection
-combinations, e.g., the
-.Dv UVM_PROT_WX
-macro.
-There are also some additional macros to extract bits from the flags.
-The
-.Dv UVM_PROTECTION ,
-.Dv UVM_INHERIT ,
-.Dv UVM_MAXPROTECTION
-and
-.Dv UVM_ADVICE
-macros return the protection, inheritance, maximum protection and advice,
-respectively.
-.Fn uvm_map
-returns a standard UVM return value.
-.Pp
-.Fn uvm_unmap
-removes a valid mapping,
-from
-.Fa start
-to
-.Fa end ,
-in map
-.Fa map ,
-which must be unlocked.
-.Pp
-.Fn uvm_map_pageable
-changes the pageability of the pages in the range from
-.Fa start
-to
-.Fa end
-in map
-.Fa map
-to
-.Fa new_pageable .
-.Fn uvm_map_pageable
-returns a standard UVM return value.
-.Pp
-.Fn uvm_map_checkprot
-checks the protection of the range from
-.Fa start
-to
-.Fa end
-in map
-.Fa map
-against
-.Fa protection .
-This returns either
-.Dv true
-or
-.Dv false .
-.Pp
-.Fn uvm_map_protect
-changes the protection
-.Fa start
-to
-.Fa end
-in map
-.Fa map
-to
-.Fa new_prot ,
-also setting the maximum protection to the region to
-.Fa new_prot
-if
-.Fa set_max
-is true.
-This function returns a standard UVM return value.
-.Pp
-.Fn uvm_deallocate
-deallocates kernel memory in map
-.Fa map
-from address
-.Fa start
-to
-.Fa start + size .
-.Pp
-.Fn uvmspace_alloc
-allocates and returns a new address space, with ranges from
-.Fa min
-to
-.Fa max ,
-setting the pageability of the address space to
-.Fa pageable .
-.Pp
-.Fn uvmspace_exec
-either reuses the address space of lwp
-.Fa l
-if there are no other references to it, or creates
-a new one with
-.Fn uvmspace_alloc .
-The range of valid addresses in the address space is reset to
-.Fa start
-through
-.Fa end .
-.Pp
-.Fn uvmspace_fork
-creates and returns a new address space based upon the
-.Fa vm1
-address space, typically used when allocating an address space for a
-child process.
-.Pp
-.Fn uvmspace_free
-lowers the reference count on the address space
-.Fa vm ,
-freeing the data structures if there are no other references.
-.Pp
-.Fn uvmspace_share
-causes process
-.Pa p2
-to share the address space of
-.Fa p1 .
-.Pp
-.Fn uvmspace_unshare
-ensures that lwp
-.Fa l
-has its own, unshared address space, by creating a new one if
-necessary by calling
-.Fn uvmspace_fork .
-.Pp
-.Fn uvm_uarea_alloc
-allocates virtual space for a u-area (i.e., a kernel stack) and stores
-its virtual address in
-.Fa *uaddrp .
-The return value is
-.Dv true
-if the u-area is already backed by wired physical memory, otherwise
-.Dv false .
-.Pp
-.Fn uvm_uarea_free
-frees a u-area allocated with
-.Fn uvm_uarea_alloc ,
-freeing both the virtual space and any physical pages which may have been
-allocated to back that virtual space later.
+See
+.Xr uvm_map 9 .
.Sh PAGE FAULT HANDLING
.Bl -ohang
.It Ft int
@@ -401,6 +122,9 @@
describing the type of access requested.
.Fn uvm_fault
returns a standard UVM return value.
+.Sh MEMORY MAPPING FILES AND DEVICES
+See
+.Xr ubc 9 .
.Sh VIRTUAL MEMORY I/O
.Bl -ohang
.It Ft int
@@ -413,137 +137,8 @@
on the memory described in
.Fa map .
.Sh ALLOCATION OF KERNEL MEMORY
-.Bl -ohang
-.It Ft vaddr_t
-.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags" ;
-.It Ft void
-.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags" ;
-.It Ft struct vm_map *
-.Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max" \
-"vsize_t size" "int flags" "bool fixed" "struct vm_map *submap" ;
-.El
-.Pp
-.Fn uvm_km_alloc
-allocates
-.Fa size
-bytes of kernel memory in map
-.Fa map .
-The first address of the allocated memory range will be aligned according to the
-.Fa align
-argument
-.Pq specify 0 if no alignment is necessary .
-The alignment must be a multiple of page size.
-The
-.Fa flags
-is a bitwise inclusive OR of the allocation type and operation flags.
-.Pp
-The allocation type should be one of:
-.Bl -tag -width UVM_KMF_PAGEABLE
-.It UVM_KMF_WIRED
-Wired memory.
-.It UVM_KMF_PAGEABLE
-Demand-paged zero-filled memory.
-.It UVM_KMF_VAONLY
-Virtual address only.
-No physical pages are mapped in the allocated region.
-If necessary, it's the caller's responsibility to enter page mappings.
-It's also the caller's responsibility to clean up the mappings before freeing
-the address range.
-.El
-.Pp
-The following operation flags are available:
-.Bl -tag -width UVM_KMF_PAGEABLE
-.It UVM_KMF_CANFAIL
-Can fail even if
-.Dv UVM_KMF_NOWAIT
-is not specified and
-.Dv UVM_KMF_WAITVA
-is specified.
-.It UVM_KMF_ZERO
-Request zero-filled memory.
-Only supported for
-.Dv UVM_KMF_WIRED .
-Shouldn't be used with other types.
-.It UVM_KMF_TRYLOCK
-Fail if we can't lock the map.
-.It UVM_KMF_NOWAIT
-Fail immediately if no memory is available.
-.It UVM_KMF_WAITVA
-Sleep to wait for the virtual address resources if needed.
-.El
-.Pp
-(If neither
-.Dv UVM_KMF_NOWAIT
-nor
-.Dv UVM_KMF_CANFAIL
-are specified and
-.Dv UVM_KMF_WAITVA
-is specified,
-.Fn uvm_km_alloc
-will never fail, but rather sleep indefinitely until the allocation succeeds.)
-.Pp
-Pageability of the pages allocated with
-.Dv UVM_KMF_PAGEABLE
-can be changed by
-.Fn uvm_map_pageable .
-In that case, the entire range must be changed atomically.
-Changing a part of the range is not supported.
-.Pp
-.Fn uvm_km_free
-frees the memory range allocated by
-.Fn uvm_km_alloc .
-.Fa addr
-must be an address returned by
-.Fn uvm_km_alloc .
-.Fa map
-and
-.Fa size
-must be the same as the ones used for the corresponding
-.Fn uvm_km_alloc .
-.Fa flags
-must be the allocation type used for the corresponding
-.Fn uvm_km_alloc .
-.Pp
-.Fn uvm_km_free
-is the only way to free memory ranges allocated by
-.Fn uvm_km_alloc .
-.Fn uvm_unmap
-must not be used.
-.Pp
-.Fn uvm_km_suballoc
-allocates submap from
-.Fa map ,
-creating a new map if
-.Fa submap
-is
-.Dv NULL .
-The addresses of the submap can be specified exactly by setting the
-.Fa fixed
-argument to true, which causes the
-.Fa min
-argument to specify the beginning of the address in the submap.
-If
-.Fa fixed
-is false, any address of size
-.Fa size
-will be allocated from
-.Fa map
-and the start and end addresses returned in
-.Fa min
-and
-.Fa max .
-The
-.Fa flags
-are used to initialize the created submap.
-The following flags could be set:
-.Bl -tag -width VM_MAP_PAGEABLE
-.It VM_MAP_PAGEABLE
-Entries in the map may be paged out.
-.It VM_MAP_INTRSAFE
-Map should be interrupt-safe.
-.It VM_MAP_TOPDOWN
-A top-down mapping should be arranged.
-.El
+See
+.Xr uvm_km 9 .
.Sh ALLOCATION OF PHYSICAL MEMORY
.Bl -ohang
.It Ft struct vm_page *
@@ -1007,7 +602,9 @@
.Xr options 4 ,
.Xr memoryallocators 9 ,
.Xr pmap 9 ,
-.Xr ubc 9
+.Xr ubc 9 ,
+.Xr uvm_km 9 ,
+.Xr uvm_map 9
.Rs
.%A Charles D. Cranor
.%A Gurudatta M. Parulkar
Added files:
Index: src/share/man/man9/uvm_km.9
diff -u /dev/null src/share/man/man9/uvm_km.9:1.1
--- /dev/null Wed Jun 1 02:22:20 2011
+++ src/share/man/man9/uvm_km.9 Wed Jun 1 02:22:19 2011
@@ -0,0 +1,184 @@
+.\" $NetBSD: uvm_km.9,v 1.1 2011/06/01 02:22:19 rmind Exp $
+.\"
+.\" Copyright (c) 1998 Matthew R. Green
+.\" 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 ``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 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.
+.\"
+.Dd June 1, 2011
+.Dt UVM_KM 9
+.Os
+.Sh NAME
+.Nm uvm_km
+.Nd raw kernel memory or address space allocator
+.Sh SYNOPSIS
+.In sys/param.h
+.In uvm/uvm.h
+.Ft vaddr_t
+.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags"
+.Ft void
+.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags"
+.Ft struct vm_map *
+.Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max" \
+"vsize_t size" "int flags" "bool fixed" "struct vm_map *submap"
+.Sh DESCRIPTION
+The UVM facility for allocation of kernel memory or address space in pages.
+Both wired and pageable memory can be allocated by this facility, as well
+as kernel address space.
+Note that this is a raw allocator.
+For general purpose memory allocation,
+.Xr kmem 9
+interface should be used.
+.Sh FUNCTIONS
+.Fn uvm_km_alloc
+allocates
+.Fa size
+bytes of kernel memory in map
+.Fa map .
+The first address of the allocated memory range will be aligned according to the
+.Fa align
+argument
+.Pq specify 0 if no alignment is necessary .
+The alignment must be a multiple of page size.
+The
+.Fa flags
+is a bitwise inclusive OR of the allocation type and operation flags.
+.Pp
+The allocation type should be one of:
+.Bl -tag -width UVM_KMF_PAGEABLE
+.It UVM_KMF_WIRED
+Wired memory.
+.It UVM_KMF_PAGEABLE
+Demand-paged zero-filled memory.
+.It UVM_KMF_VAONLY
+Virtual address only.
+No physical pages are mapped in the allocated region.
+If necessary, it's the caller's responsibility to enter page mappings.
+It's also the caller's responsibility to clean up the mappings before freeing
+the address range.
+.El
+.Pp
+The following operation flags are available:
+.Bl -tag -width UVM_KMF_PAGEABLE
+.It UVM_KMF_CANFAIL
+Can fail even if
+.Dv UVM_KMF_NOWAIT
+is not specified and
+.Dv UVM_KMF_WAITVA
+is specified.
+.It UVM_KMF_ZERO
+Request zero-filled memory.
+Only supported for
+.Dv UVM_KMF_WIRED .
+Shouldn't be used with other types.
+.It UVM_KMF_TRYLOCK
+Fail if we can't lock the map.
+.It UVM_KMF_NOWAIT
+Fail immediately if no memory is available.
+.It UVM_KMF_WAITVA
+Sleep to wait for the virtual address resources if needed.
+.El
+.Pp
+(If neither
+.Dv UVM_KMF_NOWAIT
+nor
+.Dv UVM_KMF_CANFAIL
+are specified and
+.Dv UVM_KMF_WAITVA
+is specified,
+.Fn uvm_km_alloc
+will never fail, but rather sleep indefinitely until the allocation succeeds.)
+.Pp
+Pageability of the pages allocated with
+.Dv UVM_KMF_PAGEABLE
+can be changed by
+.Fn uvm_map_pageable .
+In that case, the entire range must be changed atomically.
+Changing a part of the range is not supported.
+.Pp
+.Fn uvm_km_free
+frees the memory range allocated by
+.Fn uvm_km_alloc .
+.Fa addr
+must be an address returned by
+.Fn uvm_km_alloc .
+.Fa map
+and
+.Fa size
+must be the same as the ones used for the corresponding
+.Fn uvm_km_alloc .
+.Fa flags
+must be the allocation type used for the corresponding
+.Fn uvm_km_alloc .
+.Pp
+.Fn uvm_km_free
+is the only way to free memory ranges allocated by
+.Fn uvm_km_alloc .
+.Fn uvm_unmap
+must not be used.
+.Pp
+.Fn uvm_km_suballoc
+allocates submap from
+.Fa map ,
+creating a new map if
+.Fa submap
+is
+.Dv NULL .
+The addresses of the submap can be specified exactly by setting the
+.Fa fixed
+argument to true, which causes the
+.Fa min
+argument to specify the beginning of the address in the submap.
+If
+.Fa fixed
+is false, any address of size
+.Fa size
+will be allocated from
+.Fa map
+and the start and end addresses returned in
+.Fa min
+and
+.Fa max .
+The
+.Fa flags
+are used to initialize the created submap.
+The following flags could be set:
+.Bl -tag -width VM_MAP_PAGEABLE
+.It VM_MAP_PAGEABLE
+Entries in the map may be paged out.
+.It VM_MAP_INTRSAFE
+Map should be interrupt-safe.
+.It VM_MAP_TOPDOWN
+A top-down mapping should be arranged.
+.El
+.Sh SEE ALSO
+.Xr kmem 9 ,
+.Xr pmap 9 ,
+.Xr pool_cache 9 ,
+.Xr uvm 9 ,
+.Xr uvm_map 9 ,
+.Xr vmem 9
+.Sh HISTORY
+UVM and
+.Nm
+first appeared in
+.Nx 1.4 .
Index: src/share/man/man9/uvm_map.9
diff -u /dev/null src/share/man/man9/uvm_map.9:1.1
--- /dev/null Wed Jun 1 02:22:20 2011
+++ src/share/man/man9/uvm_map.9 Wed Jun 1 02:22:19 2011
@@ -0,0 +1,331 @@
+.\" $NetBSD: uvm_map.9,v 1.1 2011/06/01 02:22:19 rmind Exp $
+.\"
+.\" Copyright (c) 1998 Matthew R. Green
+.\" 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 ``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 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.
+.\"
+.Dd June 1, 2011
+.Dt UVM_MAP 9
+.Os
+.Sh NAME
+.Nm uvm_map
+.Nd
+virtual address space management interface
+.Sh SYNOPSIS
+.In sys/param.h
+.In uvm/uvm.h
+.Ft int
+.Fn uvm_map "struct vm_map *map" "vaddr_t *startp" "vsize_t size" \
+"struct uvm_object *uobj" "voff_t uoffset" "vsize_t align" "uvm_flag_t flags"
+.Ft void
+.Fn uvm_unmap "struct vm_map *map" "vaddr_t start" "vaddr_t end"
+.Ft int
+.Fn uvm_map_pageable "struct vm_map *map" "vaddr_t start" "vaddr_t end" \
+"bool new_pageable" "int lockflags"
+.Ft bool
+.Fn uvm_map_checkprot "struct vm_map *map" "vaddr_t start" "vaddr_t end" \
+"vm_prot_t protection"
+.Ft int
+.Fn uvm_map_protect "struct vm_map *map" "vaddr_t start" "vaddr_t end" \
+"vm_prot_t new_prot" "bool set_max"
+.Ft int
+.Fn uvm_deallocate "struct vm_map *map" "vaddr_t start" "vsize_t size"
+.Ft struct vmspace *
+.Fn uvmspace_alloc "vaddr_t min" "vaddr_t max" "int pageable"
+.Ft void
+.Fn uvmspace_exec "struct lwp *l" "vaddr_t start" "vaddr_t end"
+.Ft struct vmspace *
+.Fn uvmspace_fork "struct vmspace *vm"
+.Ft void
+.Fn uvmspace_free "struct vmspace *vm1"
+.Ft void
+.Fn uvmspace_share "struct proc *p1" "struct proc *p2"
+.Ft void
+.Fn uvmspace_unshare "struct lwp *l"
+.Ft bool
+.Fn uvm_uarea_alloc "vaddr_t *uaddrp"
+.Ft void
+.Fn uvm_uarea_free "vaddr_t uaddr"
+.Sh DESCRIPTION
+The UVM facility for virtual address space management.
+.Sh FUNCTIONS
+.Fn uvm_map
+establishes a valid mapping in map
+.Fa map ,
+which must be unlocked.
+The new mapping has size
+.Fa size ,
+which must be a multiple of
+.Dv PAGE_SIZE .
+The
+.Fa uobj
+and
+.Fa uoffset
+arguments can have four meanings.
+When
+.Fa uobj
+is
+.Dv NULL
+and
+.Fa uoffset
+is
+.Dv UVM_UNKNOWN_OFFSET ,
+.Fn uvm_map
+does not use the machine-dependent
+.Dv PMAP_PREFER
+function.
+If
+.Fa uoffset
+is any other value, it is used as the hint to
+.Dv PMAP_PREFER .
+When
+.Fa uobj
+is not
+.Dv NULL
+and
+.Fa uoffset
+is
+.Dv UVM_UNKNOWN_OFFSET ,
+.Fn uvm_map
+finds the offset based upon the virtual address, passed as
+.Fa startp .
+If
+.Fa uoffset
+is any other value, we are doing a normal mapping at this offset.
+The start address of the map will be returned in
+.Fa startp .
+.Pp
+.Fa align
+specifies alignment of mapping unless
+.Dv UVM_FLAG_FIXED
+is specified in
+.Fa flags .
+.Fa align
+must be a power of 2.
+.Pp
+.Fa flags
+passed to
+.Fn uvm_map
+are typically created using the
+.Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" "int advice" "int flags"
+macro, which uses the following values.
+The
+.Fa prot
+and
+.Fa maxprot
+can take are:
+.Bd -literal
+#define UVM_PROT_MASK 0x07 /* protection mask */
+#define UVM_PROT_NONE 0x00 /* protection none */
+#define UVM_PROT_ALL 0x07 /* everything */
+#define UVM_PROT_READ 0x01 /* read */
+#define UVM_PROT_WRITE 0x02 /* write */
+#define UVM_PROT_EXEC 0x04 /* exec */
+#define UVM_PROT_R 0x01 /* read */
+#define UVM_PROT_W 0x02 /* write */
+#define UVM_PROT_RW 0x03 /* read-write */
+#define UVM_PROT_X 0x04 /* exec */
+#define UVM_PROT_RX 0x05 /* read-exec */
+#define UVM_PROT_WX 0x06 /* write-exec */
+#define UVM_PROT_RWX 0x07 /* read-write-exec */
+.Ed
+.Pp
+The values that
+.Fa inh
+can take are:
+.Bd -literal
+#define UVM_INH_MASK 0x30 /* inherit mask */
+#define UVM_INH_SHARE 0x00 /* "share" */
+#define UVM_INH_COPY 0x10 /* "copy" */
+#define UVM_INH_NONE 0x20 /* "none" */
+#define UVM_INH_DONATE 0x30 /* "donate" \*[Lt]\*[Lt] not used */
+.Ed
+.Pp
+The values that
+.Fa advice
+can take are:
+.Bd -literal
+#define UVM_ADV_NORMAL 0x0 /* 'normal' */
+#define UVM_ADV_RANDOM 0x1 /* 'random' */
+#define UVM_ADV_SEQUENTIAL 0x2 /* 'sequential' */
+#define UVM_ADV_MASK 0x7 /* mask */
+.Ed
+.Pp
+The values that
+.Fa flags
+can take are:
+.Bd -literal
+#define UVM_FLAG_FIXED 0x010000 /* find space */
+#define UVM_FLAG_OVERLAY 0x020000 /* establish overlay */
+#define UVM_FLAG_NOMERGE 0x040000 /* don't merge map entries */
+#define UVM_FLAG_COPYONW 0x080000 /* set copy_on_write flag */
+#define UVM_FLAG_AMAPPAD 0x100000 /* for bss: pad amap to reduce malloc() */
+#define UVM_FLAG_TRYLOCK 0x200000 /* fail if we can not lock map */
+.Ed
+.Pp
+The
+.Dv UVM_MAPFLAG
+macro arguments can be combined with an or operator.
+There are several special purpose macros for checking protection
+combinations, e.g., the
+.Dv UVM_PROT_WX
+macro.
+There are also some additional macros to extract bits from the flags.
+The
+.Dv UVM_PROTECTION ,
+.Dv UVM_INHERIT ,
+.Dv UVM_MAXPROTECTION
+and
+.Dv UVM_ADVICE
+macros return the protection, inheritance, maximum protection and advice,
+respectively.
+.Fn uvm_map
+returns a standard UVM return value.
+.Pp
+.Fn uvm_unmap
+removes a valid mapping,
+from
+.Fa start
+to
+.Fa end ,
+in map
+.Fa map ,
+which must be unlocked.
+.Pp
+.Fn uvm_map_pageable
+changes the pageability of the pages in the range from
+.Fa start
+to
+.Fa end
+in map
+.Fa map
+to
+.Fa new_pageable .
+.Fn uvm_map_pageable
+returns a standard UVM return value.
+.Pp
+.Fn uvm_map_checkprot
+checks the protection of the range from
+.Fa start
+to
+.Fa end
+in map
+.Fa map
+against
+.Fa protection .
+This returns either
+.Dv true
+or
+.Dv false .
+.Pp
+.Fn uvm_map_protect
+changes the protection
+.Fa start
+to
+.Fa end
+in map
+.Fa map
+to
+.Fa new_prot ,
+also setting the maximum protection to the region to
+.Fa new_prot
+if
+.Fa set_max
+is true.
+This function returns a standard UVM return value.
+.Pp
+.Fn uvm_deallocate
+deallocates kernel memory in map
+.Fa map
+from address
+.Fa start
+to
+.Fa start + size .
+.Pp
+.Fn uvmspace_alloc
+allocates and returns a new address space, with ranges from
+.Fa min
+to
+.Fa max ,
+setting the pageability of the address space to
+.Fa pageable .
+.Pp
+.Fn uvmspace_exec
+either reuses the address space of lwp
+.Fa l
+if there are no other references to it, or creates
+a new one with
+.Fn uvmspace_alloc .
+The range of valid addresses in the address space is reset to
+.Fa start
+through
+.Fa end .
+.Pp
+.Fn uvmspace_fork
+creates and returns a new address space based upon the
+.Fa vm1
+address space, typically used when allocating an address space for a
+child process.
+.Pp
+.Fn uvmspace_free
+lowers the reference count on the address space
+.Fa vm ,
+freeing the data structures if there are no other references.
+.Pp
+.Fn uvmspace_share
+causes process
+.Pa p2
+to share the address space of
+.Fa p1 .
+.Pp
+.Fn uvmspace_unshare
+ensures that lwp
+.Fa l
+has its own, unshared address space, by creating a new one if
+necessary by calling
+.Fn uvmspace_fork .
+.Pp
+.Fn uvm_uarea_alloc
+allocates virtual space for a u-area (i.e., a kernel stack) and stores
+its virtual address in
+.Fa *uaddrp .
+The return value is
+.Dv true
+if the u-area is already backed by wired physical memory, otherwise
+.Dv false .
+.Pp
+.Fn uvm_uarea_free
+frees a u-area allocated with
+.Fn uvm_uarea_alloc ,
+freeing both the virtual space and any physical pages which may have been
+allocated to back that virtual space later.
+.Sh SEE ALSO
+.Xr pmap 9 ,
+.Xr uvm 9 ,
+.Xr uvm_km 9 ,
+.Xr vmem 9
+.Sh HISTORY
+UVM and
+.Nm
+first appeared in
+.Nx 1.4 .
