[src/uebayasi-xip]: src/share/man/man9 Document uvm_page_physload_device(9).

[uebayasi <uebayasi%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a9a20ca0279f
branches:  uebayasi-xip
changeset: 751807:a9a20ca0279f
user:      uebayasi <uebayasi%NetBSD.org@localhost>
date:      Thu Oct 21 17:16:28 2010 +0000

description:
Document uvm_page_physload_device(9).

diffstat:

 share/man/man9/uvm.9 |  1150 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 1150 insertions(+), 0 deletions(-)

diffs (truncated from 1154 to 300 lines):

diff -r de0f9a12467d -r a9a20ca0279f share/man/man9/uvm.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/uvm.9      Thu Oct 21 17:16:28 2010 +0000
@@ -0,0 +1,1150 @@
+.\"    $NetBSD: uvm.9,v 1.102.2.2 2010/10/21 17:16:28 uebayasi 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 October 21, 2010
+.Dt UVM 9
+.Os
+.Sh NAME
+.Nm uvm
+.Nd virtual memory system external interface
+.Sh SYNOPSIS
+.In sys/param.h
+.In uvm/uvm.h
+.Sh DESCRIPTION
+The UVM virtual memory system manages access to the computer's memory
+resources.
+User processes and the kernel access these resources through
+UVM's external interface.
+UVM's external interface includes functions that:
+.Pp
+.Bl -hyphen -compact
+.It
+initialize UVM sub-systems
+.It
+manage virtual address spaces
+.It
+resolve page faults
+.It
+memory map files and devices
+.It
+perform uio-based I/O to virtual memory
+.It
+allocate and free kernel virtual memory
+.It
+allocate and free physical memory
+.El
+.Pp
+In addition to exporting these services, UVM has two kernel-level processes:
+pagedaemon and swapper.
+The pagedaemon process sleeps until physical memory becomes scarce.
+When that happens, pagedaemon is awoken.
+It scans physical memory, paging out and freeing memory that has not
+been recently used.
+The swapper process swaps in runnable processes that are currently swapped
+out, if there is room.
+.Pp
+There are also several miscellaneous functions.
+.Sh INITIALIZATION
+.Bl -ohang
+.It Ft void
+.Fn uvm_init "void" ;
+.It Ft void
+.Fn uvm_init_limits "struct lwp *l" ;
+.It Ft void
+.Fn uvm_setpagesize "void" ;
+.It Ft void
+.Fn uvm_swap_init "void" ;
+.El
+.Pp
+.Fn uvm_init
+sets up the UVM system at system boot time, after the
+console has been setup.
+It initializes global state, the page, map, kernel virtual memory state,
+machine-dependent physical map, kernel memory allocator,
+pager and anonymous memory sub-systems, and then enables
+paging of kernel objects.
+.Pp
+.Fn uvm_init_limits
+initializes process limits for the named process.
+This is for use by the system startup for process zero, before any
+other processes are created.
+.Pp
+.Fn uvm_setpagesize
+initializes the uvmexp members pagesize (if not already done by
+machine-dependent code), pageshift and pagemask.
+It should be called by machine-dependent code early in the
+.Fn pmap_init
+call (see
+.Xr pmap 9 ) .
+.Pp
+.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