[src/trunk]: src/share/man/man9 merge yamt-km-doc branch.

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

details:   https://anonhg.NetBSD.org/src/rev/22276339f91d
branches:  trunk
changeset: 579931:22276339f91d
user:      yamt <yamt%NetBSD.org@localhost>
date:      Fri Apr 01 12:03:26 2005 +0000

description:
merge yamt-km-doc branch.

diffstat:

 share/man/man9/uvm.9 |  182 +++++++++++++++++++-------------------------------
 1 files changed, 71 insertions(+), 111 deletions(-)

diffs (222 lines):

diff -r 5a1876f658be -r 22276339f91d share/man/man9/uvm.9
--- a/share/man/man9/uvm.9      Fri Apr 01 12:01:32 2005 +0000
+++ b/share/man/man9/uvm.9      Fri Apr 01 12:03:26 2005 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: uvm.9,v 1.61 2005/03/11 19:40:47 rumble Exp $
+.\"    $NetBSD: uvm.9,v 1.62 2005/04/01 12:03:26 yamt Exp $
 .\"
 .\" Copyright (c) 1998 Matthew R. Green
 .\" All rights reserved.
@@ -516,142 +516,102 @@
 .Sh ALLOCATION OF KERNEL MEMORY
 .Ft vaddr_t
 .br
-.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" ;
-.Pp
-.Ft vaddr_t
-.br
-.Fn uvm_km_zalloc "struct vm_map *map" "vsize_t size" ;
+.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags";
 .Pp
-.Ft vaddr_t
-.br
-.Fn uvm_km_alloc1 "struct vm_map *map" "vsize_t size" "boolean_t zeroit" ;
-.Pp
-.Ft vaddr_t
+.Ft void
 .br
-.Fn uvm_km_kmemalloc1 "struct vm_map *map" "struct uvm_object *obj" "vsize_t size" "vsize_t align" "voff_t preferred offset" "int flags" ;
-.Pp
-.Ft vaddr_t
-.br
-.Fn uvm_km_kmemalloc "struct vm_map *map" "struct uvm_object *obj" "vsize_t size" "int flags" ;
-.Pp
-.Ft vaddr_t
-.br
-.Fn uvm_km_valloc "struct vm_map *map" "vsize_t size" ;
-.Pp
-.Ft vaddr_t
-.br
-.Fn uvm_km_valloc_wait "struct vm_map *map" "vsize_t size" ;
+.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags";
 .Pp
 .Ft struct vm_map *
 .br
 .Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max " "vsize_t size" "boolean_t pageable" "boolean_t fixed" "struct vm_map *submap" ;
 .Pp
-.Ft void
-.br
-.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" ;
-.Pp
-.Ft void
-.br
-.Fn uvm_km_free_wakeup "struct vm_map *map" "vaddr_t addr" "vsize_t size" ;
-.Pp
 .Fn uvm_km_alloc
-and
-.Fn uvm_km_zalloc
-allocate
+allocates
 .Fa size
-bytes of wired kernel memory in map
+bytes of kernel memory in map
 .Fa map .
-In addition to allocation,
-.Fn uvm_km_zalloc
-zeros the memory.
-Both of these functions are defined as macros in terms of
-.Fn uvm_km_alloc1 ,
-and should almost always be used in preference to
-.Fn uvm_km_alloc1 .
-.Pp
-.Fn uvm_km_alloc1
-allocates and returns
-.Fa size
-bytes of wired memory in the kernel map, zeroing the memory if the
-.Fa zeroit
-argument is non-zero.
-.Pp
-.Fn uvm_km_kmemalloc1
-allocates and returns
-.Fa size
-bytes of wired kernel memory into
-.Fa obj .
 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 flags can be any of:
-.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
+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
+Virtuall address only.
+No physical pages are mapped in the allocated region.
+If necessary, it's caller's responsibility to enter page mappings.
+It's also 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
-causes
-.Fn uvm_km_kmemalloc1
-to return immediately if no memory is available.
-.Dv UVM_KMF_VALLOC
-causes no physical pages to be allocated, only virtual space.
-.Dv UVM_KMF_TRYLOCK
-causes
-.Fn uvm_km_kmemalloc1
-to use
-.Fn simple_lock_try
-when locking maps.
-.Dv UVM_KMF_CANFAIL
-indicates that
-.Fn uvm_km_kmemalloc1
-can return 0 even if
-.Dv UVM_KMF_NOWAIT
-is not specified.
+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,
-.Fn uvm_km_kmemalloc1
+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
-.Fn uvm_km_kmemalloc
-allocates kernel memory like
-.Fn uvm_km_kmemalloc1
-but uses the default values
-.Dv 0
-for the
-.Fa align ,
-and
-.Dv UVM_UNKNOWN_OFFSET
-for the
-.Fa prefer
-arguments.
-.Pp
-.Fn uvm_km_valloc
-and
-.Fn uvm_km_valloc_wait
-return a newly allocated zero-filled address in the kernel map of size
-.Fa size .
-.Fn uvm_km_valloc_wait
-will also wait for kernel memory to become available, if there is a
-memory shortage.
+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
-.Fn uvm_km_free_wakeup
-free
 .Fa size
-bytes of memory in the kernel map, starting at address
-.Fa addr .
-.Fn uvm_km_free_wakeup
-calls
-.Fn wakeup
-on the map before unlocking the map.
+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