Module Name: src
Committed By: rmind
Date: Mon Aug 3 23:15:29 UTC 2009
Modified Files:
src/share/man/man9: Makefile vmem.9
Removed Files:
src/share/man/man9: vmem_alloc.9 vmem_create.9 vmem_destroy.9
vmem_free.9 vmem_xalloc.9 vmem_xfree.9
Log Message:
Merge vmem_alloc(9) & friends (it's a whole company) into a single vmem(9).
To generate a diff of this commit:
cvs rdiff -u -r1.287 -r1.288 src/share/man/man9/Makefile
cvs rdiff -u -r1.5 -r1.6 src/share/man/man9/vmem.9
cvs rdiff -u -r1.3 -r0 src/share/man/man9/vmem_alloc.9 \
src/share/man/man9/vmem_destroy.9 src/share/man/man9/vmem_free.9
cvs rdiff -u -r1.4 -r0 src/share/man/man9/vmem_create.9
cvs rdiff -u -r1.2 -r0 src/share/man/man9/vmem_xalloc.9 \
src/share/man/man9/vmem_xfree.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.287 src/share/man/man9/Makefile:1.288
--- src/share/man/man9/Makefile:1.287 Mon Aug 3 23:03:05 2009
+++ src/share/man/man9/Makefile Mon Aug 3 23:15:29 2009
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.287 2009/08/03 23:03:05 rmind Exp $
+# $NetBSD: Makefile,v 1.288 2009/08/03 23:15:29 rmind Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -53,9 +53,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 vmem_alloc.9 vmem_create.9 vmem_destroy.9 vmem_free.9 \
- vmem_xalloc.9 vmem_xfree.9 \
+ ubc.9 usbdi.9 uvm.9 vmem.9 \
wdc.9 workqueue.9 \
wscons.9 wsdisplay.9 wsfont.9 wskbd.9 wsmouse.9
@@ -718,6 +716,12 @@
vfssubr.9 vfs_getopsbyname.9 \
vfssubr.9 vfs_resume.9 \
vfssubr.9 vfs_suspend.9
+MLINKS+=vmem.9 vmem_alloc.9 \
+ vmem.9 vmem_create.9 \
+ vmem.9 vmem_destroy.9 \
+ vmem.9 vmem_free.9 \
+ vmem.9 vmem_xalloc.9 \
+ vmem.9 vmem_xfree.9
MLINKS+=vnode.9 vcount.9 \
vnode.9 vref.9 \
vnode.9 VREF.9 \
Index: src/share/man/man9/vmem.9
diff -u src/share/man/man9/vmem.9:1.5 src/share/man/man9/vmem.9:1.6
--- src/share/man/man9/vmem.9:1.5 Fri Feb 16 23:13:05 2007
+++ src/share/man/man9/vmem.9 Mon Aug 3 23:15:29 2009
@@ -1,4 +1,4 @@
-.\" $NetBSD: vmem.9,v 1.5 2007/02/16 23:13:05 rmind Exp $
+.\" $NetBSD: vmem.9,v 1.6 2009/08/03 23:15:29 rmind Exp $
.\"
.\" Copyright (c)2006 YAMAMOTO Takashi,
.\" All rights reserved.
@@ -25,7 +25,7 @@
.\" SUCH DAMAGE.
.\"
.\" ------------------------------------------------------------
-.Dd October 22, 2006
+.Dd August 3, 2009
.Dt VMEM 9
.Os
.\" ------------------------------------------------------------
@@ -33,12 +33,245 @@
.Nm vmem
.Nd virtual memory allocator
.\" ------------------------------------------------------------
+.Sh SYNOPSIS
+.In sys/vmem.h
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft vmem_t *
+.Fn vmem_create \
+"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \
+"vmem_addr_t (*allocfn)(vmem_t *, vmem_size_t, vmem_size_t *, vm_flag_t)" \
+"void (*freefn)(vmem_t *, vmem_addr_t, vmem_size_t)" \
+"vmem_t *source" "vmem_size_t qcache_max" "vm_flag_t flags" "int ipl"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft vmem_addr_t
+.Fn vmem_xalloc \
+"vmem_t *vm" "vmem_size_t size" "vmem_size_t align" \
+"vmem_size_t phase" "vmem_size_t nocross" "vmem_addr_t minaddr" \
+"vmem_addr_t maxaddr" "vm_flag_t flags"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft vmem_addr_t
+.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "vm_flag_t flags"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Ft void
+.Fn vmem_destroy "vmem_t *vm"
+.\" ------------------------------------------------------------
.Sh DESCRIPTION
The
.Nm
is a general purpose resource allocator.
Despite its name, it can be used for arbitrary resources
other than virtual memory.
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_create
+creates a new vmem arena.
+.Pp
+.Bl -tag -width qcache_max
+.It Fa name
+The string to describe the vmem.
+.It Fa base
+The start address of the initial span.
+It can be
+.Dv VMEM_ADDR_NULL
+if no initial span is required.
+.It Fa size
+The size of the initial span.
+.It Fa quantum
+The smallest unit of allocation.
+.It Fa allocfn
+The callback function used to import spans from the backend arena.
+.It Fa freefn
+The callback function used to free spans to the backend arena.
+.It Fa source
+The backend arena.
+.It Fa qcache_max
+The largest size of allocations which can be served by quantum cache.
+It is merely a hint and can be ignored.
+.It Fa flags
+Either of:
+.Bl -tag -width VM_NOSLEEP
+.It Dv VM_SLEEP
+Can sleep until enough resources are available.
+.It Dv VM_NOSLEEP
+Don't sleep.
+Immediately return
+.Dv NULL
+if there are not enough resources available.
+.El
+.It Fa ipl
+Interrupt level to be blocked for allocating from vmem.
+.El
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_xalloc
+allocates a resource from the arena.
+.Pp
+.Bl -tag -width nocross
+.It Fa vm
+The arena which we allocate from.
+.It Fa size
+Specify the size of the allocation.
+.It Fa align
+If zero, don't care about the alignment of the allocation.
+Otherwise, request a resource segment starting at
+offset
+.Fa phase
+from an
+.Fa align
+aligned boundary.
+.It Fa phase
+See the above description of
+.Fa align .
+If
+.Fa align
+is zero,
+.Fa phase
+should be zero.
+Otherwise,
+.Fa phase
+should be smaller than
+.Fa align .
+.It Fa nocross
+Request a resource which doesn't cross
+.Fa nocross
+aligned boundary.
+.It Fa minaddr
+If non-zero, specify the minimum address which can be allocated.
+.It Fa maxaddr
+If non-zero, specify the maximum address + 1 which can be allocated.
+.It Fa flags
+A bitwise OR of an allocation strategy and a sleep flag.
+.Pp
+The allocation strategy is one of:
+.Bl -tag -width VM_INSTANTFIT
+.It Dv VM_BESTFIT
+Prefer space efficiency.
+.It Dv VM_INSTANTFIT
+Prefer performance.
+.El
+.Pp
+The sleep flag should be one of:
+.Bl -tag -width VM_NOSLEEP
+.It Dv VM_SLEEP
+Can sleep until enough resources are available.
+.It Dv VM_NOSLEEP
+Don't sleep.
+Immediately return
+.Dv VMEM_ADDR_NULL
+if there are not enough resources available.
+.El
+.El
+.Pp
+.\" ------------------------------------------------------------
+.Fn vmem_xfree
+frees resource allocated by
+.Fa vmem_xalloc
+to the arena.
+.Pp
+.Bl -tag -width addr
+.It Fa vm
+The arena which we free to.
+.It Fa addr
+The resource being freed.
+It must be the one returned by
+.Fn vmem_xalloc .
+Notably, it must not be the one from
+.Fn vmem_alloc .
+Otherwise, the behaviour is undefined.
+.It Fa size
+The size of the resource being freed.
+It must be the same as the
+.Fa size
+argument used for
+.Fn vmem_xalloc .
+.El
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_alloc
+allocates a resource from the arena.
+.Pp
+.Bl -tag -width flags
+.It Fa vm
+The arena which we allocate from.
+.It Fa size
+Specify the size of the allocation.
+.It Fa flags
+A bitwise OR of an allocation strategy and a sleep flag.
+.Pp
+The allocation strategy is one of:
+.Bl -tag -width VM_INSTANTFIT
+.It Dv VM_BESTFIT
+Prefer space efficiency.
+.It Dv VM_INSTANTFIT
+Prefer performance.
+.El
+.Pp
+The sleep flag should be one of:
+.Bl -tag -width VM_NOSLEEP
+.It Dv VM_SLEEP
+Can sleep until enough resources are available.
+.It Dv VM_NOSLEEP
+Don't sleep.
+Immediately return
+.Dv VMEM_ADDR_NULL
+if there are not enough resources available.
+.El
+.El
+.Pp
+.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+.Fn vmem_free
+frees resource allocated by
+.Fa vmem_alloc
+to the arena.
+.Pp
+.Bl -tag -width addr
+.It Fa vm
+The arena which we free to.
+.It Fa addr
+The resource being freed.
+It must be the one returned by
+.Fn vmem_alloc .
+Notably, it must not be the one from
+.Fn vmem_xalloc .
+Otherwise, the behaviour is undefined.
+.It Fa size
+The size of the resource being freed.
+It must be the same as the
+.Fa size
+argument used for
+.Fn vmem_alloc .
+.El
+.Pp
+.\" ------------------------------------------------------------
+.Fn vmem_destroy
+destroys a vmem arena.
+.Pp
+.Bl -tag -width vm
+.It Fa vm
+The vmem arena being destroyed.
+The caller should ensure that no one will use it anymore.
+.El
+.\" ------------------------------------------------------------
+.Sh RETURN VALUES
+.Fn vmem_create
+return a pointer to the newly allocated vmem_t.
+Otherwise, it returns
+.Dv NULL .
+.Pp
+On success,
+.Fn vmem_xalloc
+and
+.Fn vmem_alloc
+return an allocated vmem_addr_t.
+Otherwise,
+.Dv VMEM_ADDR_NULL
+is returned.
.\" ------------------------------------------------------------
.Sh CODE REFERENCES
This section describes places within the
@@ -56,13 +289,9 @@
.\" ------------------------------------------------------------
.Sh SEE ALSO
.Xr intro 9 ,
+.Xr kmem 9 ,
.Xr memoryallocators 9 ,
-.Xr vmem_alloc 9 ,
-.Xr vmem_create 9 ,
-.Xr vmem_destroy 9 ,
-.Xr vmem_free 9 ,
-.Xr vmem_xalloc 9 ,
-.Xr vmem_xfree 9
+.Xr uvm 9
.Rs
.%A Jeff Bonwick
.%A Jonathan Adams
