[src/trunk]: src Sync (mostly, not fully) uvm_km(9) and uvm_map(9) man pages ...

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src Sync (mostly, not fully) uvm_km(9) and uvm_map(9) man pages ...
From: rmind <rmind%NetBSD.org@localhost>
Date: Mon, 06 Apr 2020 20:33:32 +0000
details:   https://anonhg.NetBSD.org/src/rev/f62aa025cb46
branches:  trunk
changeset: 765718:f62aa025cb46
user:      rmind <rmind%NetBSD.org@localhost>
date:      Fri Jun 03 18:43:38 2011 +0000

description:
Sync (mostly, not fully) uvm_km(9) and uvm_map(9) man pages with reality.

diffstat:

 distrib/sets/lists/comp/mi |    8 +-
 share/man/man9/Makefile    |    4 +-
 share/man/man9/uvm_km.9    |   24 +++---
 share/man/man9/uvm_map.9   |  176 ++++++++++++++++++++++++++------------------
 4 files changed, 121 insertions(+), 91 deletions(-)

diffs (truncated from 435 to 300 lines):

diff -r 88e6d095276b -r f62aa025cb46 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi        Fri Jun 03 18:40:41 2011 +0000
+++ b/distrib/sets/lists/comp/mi        Fri Jun 03 18:43:38 2011 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: mi,v 1.1627 2011/06/01 02:22:19 rmind Exp $
+#      $NetBSD: mi,v 1.1628 2011/06/03 18:43:38 rmind Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -10195,7 +10195,7 @@
 ./usr/share/man/cat9/uvm_scheduler.0           comp-sys-catman         .cat
 ./usr/share/man/cat9/uvm_setpagesize.0         comp-sys-catman         .cat
 ./usr/share/man/cat9/uvm_swap_init.0           comp-sys-catman         .cat
-./usr/share/man/cat9/uvm_swapin.0              comp-sys-catman         .cat
+./usr/share/man/cat9/uvm_swapin.0              comp-obsolete           obsolete
 ./usr/share/man/cat9/uvm_sysctl.0              comp-obsolete           obsolete
 ./usr/share/man/cat9/uvm_unloan.0              comp-sys-catman         .cat
 ./usr/share/man/cat9/uvm_unmap.0               comp-sys-catman         .cat
@@ -16127,7 +16127,7 @@
 ./usr/share/man/html9/uvm_scheduler.html       comp-sys-htmlman        html
 ./usr/share/man/html9/uvm_setpagesize.html     comp-sys-htmlman        html
 ./usr/share/man/html9/uvm_swap_init.html       comp-sys-htmlman        html
-./usr/share/man/html9/uvm_swapin.html          comp-sys-htmlman        html
+./usr/share/man/html9/uvm_swapin.html          comp-obsolete           obsolete
 ./usr/share/man/html9/uvm_unloan.html          comp-sys-htmlman        html
 ./usr/share/man/html9/uvm_unmap.html           comp-sys-htmlman        html
 ./usr/share/man/html9/uvm_vnp_setsize.html     comp-sys-htmlman        html
@@ -22287,7 +22287,7 @@
 ./usr/share/man/man9/uvm_scheduler.9           comp-sys-man            .man
 ./usr/share/man/man9/uvm_setpagesize.9         comp-sys-man            .man
 ./usr/share/man/man9/uvm_swap_init.9           comp-sys-man            .man
-./usr/share/man/man9/uvm_swapin.9              comp-sys-man            .man
+./usr/share/man/man9/uvm_swapin.9              comp-obsolete           obsolete
 ./usr/share/man/man9/uvm_sysctl.9              comp-obsolete           obsolete
 ./usr/share/man/man9/uvm_unloan.9              comp-sys-man            .man
 ./usr/share/man/man9/uvm_unmap.9               comp-sys-man            .man
diff -r 88e6d095276b -r f62aa025cb46 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Fri Jun 03 18:40:41 2011 +0000
+++ b/share/man/man9/Makefile   Fri Jun 03 18:43:38 2011 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.347 2011/06/01 02:22:18 rmind Exp $
+#       $NetBSD: Makefile,v 1.348 2011/06/03 18:43:38 rmind Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -742,7 +742,7 @@
        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 \
+       uvm.9 uvm_scheduler.9 uvm.9 uao_create.9 \
        uvm.9 uao_detach.9 uvm.9 uao_reference.9 uvm.9 uvm_chgkprot.9 \
        uvm.9 uvm_kernacc.9 uvm.9 uvm_vslock.9 \
        uvm.9 uvm_vsunlock.9 uvm.9 uvm_meter.9 \
diff -r 88e6d095276b -r f62aa025cb46 share/man/man9/uvm_km.9
--- a/share/man/man9/uvm_km.9   Fri Jun 03 18:40:41 2011 +0000
+++ b/share/man/man9/uvm_km.9   Fri Jun 03 18:43:38 2011 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: uvm_km.9,v 1.1 2011/06/01 02:22:19 rmind Exp $
+.\"    $NetBSD: uvm_km.9,v 1.2 2011/06/03 18:43:38 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 June 1, 2011
+.Dd June 3, 2011
 .Dt UVM_KM 9
 .Os
 .Sh NAME
@@ -39,7 +39,7 @@
 .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"
+"vsize_t size" "int flags" "bool fixed" "struct vm_map_kernel *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
@@ -72,8 +72,8 @@
 .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
+If necessary, it is the caller's responsibility to enter page mappings.
+It is also the caller's responsibility to clean up the mappings before freeing
 the address range.
 .El
 .Pp
@@ -89,16 +89,16 @@
 Request zero-filled memory.
 Only supported for
 .Dv UVM_KMF_WIRED .
-Shouldn't be used with other types.
+Should not be used with other types.
 .It UVM_KMF_TRYLOCK
-Fail if we can't lock the map.
+Fail if cannot lock the map without sleeping.
 .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
+If neither
 .Dv UVM_KMF_NOWAIT
 nor
 .Dv UVM_KMF_CANFAIL
@@ -106,7 +106,7 @@
 .Dv UVM_KMF_WAITVA
 is specified,
 .Fn uvm_km_alloc
-will never fail, but rather sleep indefinitely until the allocation succeeds.)
+will never fail, but rather sleep indefinitely until the allocation succeeds.
 .Pp
 Pageability of the pages allocated with
 .Dv UVM_KMF_PAGEABLE
@@ -129,7 +129,7 @@
 .Fa flags
 must be the allocation type used for the corresponding
 .Fn uvm_km_alloc .
-.Pp
+Note that
 .Fn uvm_km_free
 is the only way to free memory ranges allocated by
 .Fn uvm_km_alloc .
@@ -143,7 +143,7 @@
 .Fa submap
 is
 .Dv NULL .
-The addresses of the submap can be specified exactly by setting the
+The addresses of the submap can be specified explicitly by setting the
 .Fa fixed
 argument to true, which causes the
 .Fa min
@@ -161,7 +161,7 @@
 The
 .Fa flags
 are used to initialize the created submap.
-The following flags could be set:
+The following flags can be set:
 .Bl -tag -width VM_MAP_PAGEABLE
 .It VM_MAP_PAGEABLE
 Entries in the map may be paged out.
diff -r 88e6d095276b -r f62aa025cb46 share/man/man9/uvm_map.9
--- a/share/man/man9/uvm_map.9  Fri Jun 03 18:40:41 2011 +0000
+++ b/share/man/man9/uvm_map.9  Fri Jun 03 18:43:38 2011 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: uvm_map.9,v 1.1 2011/06/01 02:22:19 rmind Exp $
+.\"    $NetBSD: uvm_map.9,v 1.2 2011/06/03 18:43:38 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 June 1, 2011
+.Dd June 3, 2011
 .Dt UVM_MAP 9
 .Os
 .Sh NAME
@@ -51,21 +51,25 @@
 .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"
+.Fn uvmspace_alloc "vaddr_t min" "vaddr_t max"
 .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"
+.Fn uvmspace_free "struct vmspace *vm"
 .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 uvmspace_unshare "struct lwp *l"
+.Ft vaddr_t
+.Fn uvm_uarea_alloc "void"
 .Ft void
 .Fn uvm_uarea_free "vaddr_t uaddr"
+.Ft vaddr_t
+.Fn uvm_uarea_system_alloc "void"
+.Ft void
+.Fn uvm_uarea_system_free "vaddr_t uaddr"
 .Sh DESCRIPTION
 The UVM facility for virtual address space management.
 .Sh FUNCTIONS
@@ -111,7 +115,7 @@
 .Fa startp .
 If
 .Fa uoffset
-is any other value, we are doing a normal mapping at this offset.
+is any other value, then a regular mapping is performed at this offset.
 The start address of the map will be returned in
 .Fa startp .
 .Pp
@@ -127,69 +131,99 @@
 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"
+.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
+.Bl -tag -width UVM_ADV_SEQUENTIAL
+.It UVM_PROT_NONE
+No protection bits.
+.It UVM_PROT_R
+Read.
+.It UVM_PROT_W
+Write.
+.It UVM_PROT_X
+Exec.
+.It UVM_PROT_MASK
+Mask to extraction the protection bits.
+.El
+.Pp
+Additionally, the following constants for ORed values are available:
+.Dv UVM_PROT_RW ,
+.Dv UVM_PROT_RX ,
+.Dv UVM_PROT_WX
+and
+.Dv UVM_PROT_RWX .
 .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
+.Bl -tag -width UVM_ADV_SEQUENTIAL
+.It UVM_INH_SHARE
+Share the map.
+.It UVM_INH_COPY
+Copy the map.
+.It UVM_INH_NONE
+No inheritance.
+.It UVM_INH_MASK
+Mark to extract inherit flags.
+.El
 .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
+.Bl -tag -width UVM_ADV_SEQUENTIAL
+.It UVM_ADV_NORMAL
+"Normal" use.
+.It UVM_ADV_RANDOM
+"Random" access likelyhood.
+.It UVM_ADV_SEQUENTIAL
+"Sequential" access likelyhood.
+.It UVM_ADV_MASK
+Mask to extract the advice flags.
+.El
 .Pp
 The values that
 .Fa flags
 can take are:
-.Bd -literal
Prev by Date: [src/trunk]: src/sys Revert maxdmap/maxsmap constification, as it causes prob...
Next by Date: [src/trunk]: src/sys/dev/acpi Add locking to account improbable but possible ...
Previous by Thread: [src/trunk]: src/sys Revert maxdmap/maxsmap constification, as it causes prob...
Next by Thread: [src/trunk]: src/sys/dev/acpi Add locking to account improbable but possible ...
Indexes:
Home | Main Index | Thread Index | Old Index