[src/trunk]: src/share/man/man9 document new stuff:

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

details:   https://anonhg.NetBSD.org/src/rev/fd309b0389df
branches:  trunk
changeset: 536801:fd309b0389df
user:      chs <chs%NetBSD.org@localhost>
date:      Sun Sep 22 07:22:27 2002 +0000

description:
document new stuff:
UVM_KMF_CANFAIL, uvm_uarea_alloc(), uvm_uarea_free(), pmap_remove_all().

diffstat:

 share/man/man9/pmap.9 |  37 ++++++++++++++++++++++++++++++++++++-
 share/man/man9/uvm.9  |  31 +++++++++++++++++++++++++++++--
 2 files changed, 65 insertions(+), 3 deletions(-)

diffs (130 lines):

diff -r eb1dcdfc3b39 -r fd309b0389df share/man/man9/pmap.9
--- a/share/man/man9/pmap.9     Sun Sep 22 07:21:29 2002 +0000
+++ b/share/man/man9/pmap.9     Sun Sep 22 07:22:27 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: pmap.9,v 1.16 2002/08/14 15:30:11 wiz Exp $
+.\"    $NetBSD: pmap.9,v 1.17 2002/09/22 07:22:28 chs Exp $
 .\"
 .\" Copyright (c) 2000, 2001, 2002 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -71,6 +71,8 @@
 .Ft void
 .Fn "pmap_remove" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva"
 .Ft void
+.Fn "pmap_remove_all" "pmap_t pmap"
+.Ft void
 .Fn "pmap_protect" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" "vm_prot_t prot"
 .Ft void
 .Fn "pmap_unwire" "pmap_t pmap" "vaddr_t va"
@@ -514,6 +516,39 @@
 to
 .Fa eva
 from the specified physical map.
+.It void Fn "pmap_remove_all" "pmap_t pmap"
+This function is a hint to the
+.Nm pmap
+implementation that all entries in
+.Fa pmap
+will be removed before any more entries are entered.
+Following this call, there will be
+.Fn pmap_remove
+calls resulting in every mapping being removed, followed by either
+.Fn pmap_destroy
+or
+.Fn pmap_update .
+No other
+.Nm pmap
+interfaces which take
+.Fa pmap
+as an argument will called during this process.  Other interfaces which
+might need to access
+.Fa pmap
+(such as
+.Fn pmap_page_protect )
+are permitted during this process.
+.Pp
+The
+.Nm pmap
+implementation is free to either remove all the
+.Nm pmap 's
+mappings immediately in
+.Fn pmap_remove_all ,
+or to use the knowledge of the upcoming
+.Fn pmap_remove
+calls to optimize the removals (or to just ignore this call).
+.Pp
 .It void Fn "pmap_protect" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" \
     "vm_prot_t prot"
 Set the protection of the mappings in the virtual address range
diff -r eb1dcdfc3b39 -r fd309b0389df share/man/man9/uvm.9
--- a/share/man/man9/uvm.9      Sun Sep 22 07:21:29 2002 +0000
+++ b/share/man/man9/uvm.9      Sun Sep 22 07:22:27 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: uvm.9,v 1.34 2002/06/02 14:59:11 drochner Exp $
+.\"    $NetBSD: uvm.9,v 1.35 2002/09/22 07:22:27 chs Exp $
 .\"
 .\" Copyright (c) 1998 Matthew R. Green
 .\" All rights reserved.
@@ -129,6 +129,10 @@
 .Fn uvmspace_share "struct proc *p1" "struct proc *p2"
 .Ft void
 .Fn uvmspace_unshare "struct proc *p"
+.Ft vaddr_t
+.Fn uvm_uarea_alloc "void"
+.Ft void
+.Fn uvm_uarea_free "vaddr_t va"
 .nr nS 0
 .Pp
 .Fn uvm_map
@@ -342,6 +346,16 @@
 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 (ie. a kernel stack) and returns
+its virtual address.
+.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 PAGE FAULT HANDLING
 .nr nS 1
 .Ft int
@@ -482,6 +496,7 @@
 .Bd -literal
 #define UVM_KMF_NOWAIT  0x1                     /* matches M_NOWAIT */
 #define UVM_KMF_VALLOC  0x2                     /* allocate VA only */
+#define UVM_KMF_CANFAIL 0x4                    /* caller handles failure */
 #define UVM_KMF_TRYLOCK UVM_FLAG_TRYLOCK        /* try locking only */
 .Ed
 .Pp
@@ -490,13 +505,25 @@
 .Fn uvm_km_kmemalloc
 to return immediately if no memory is available.
 .Dv UVM_KMF_VALLOC
-causes no pages to be allocated, only a virtual address.
+causes no physical pages to be allocated, only virtual space.
 .Dv UVM_KMF_TRYLOCK
 causes
 .Fn uvm_km_kmemalloc
 to use
 .Fn simple_lock_try
 when locking maps.
+.Dv UVM_KMF_CANFAIL
+indicates that
+.Fn uvm_km_kmemalloc
+can return 0 even if
+.Dv UVM_KMF_NOWAIT
+is not specified.  (If neither
+.Dv UVM_KMF_NOWAIT
+nor
+.Dv UVM_KMF_CANFAIL
+is specified,
+.Fn uvm_km_kmemalloc
+will never fail, but rather sleep indefinitely until the allocation succeeds.)
 .Pp
 .Fn uvm_km_valloc
 and