diff options
Diffstat (limited to 'static/netbsd/man9/vmem.9')
| -rw-r--r-- | static/netbsd/man9/vmem.9 | 642 |
1 files changed, 642 insertions, 0 deletions
diff --git a/static/netbsd/man9/vmem.9 b/static/netbsd/man9/vmem.9 new file mode 100644 index 00000000..b3f454dd --- /dev/null +++ b/static/netbsd/man9/vmem.9 @@ -0,0 +1,642 @@ +.\" $NetBSD: vmem.9,v 1.22 2023/12/02 21:02:12 thorpej Exp $ +.\" +.\" Copyright (c)2006 YAMAMOTO Takashi, +.\" 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 AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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 December 2, 2023 +.Dt VMEM 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.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" \ +"int (*allocfn)(void *, vmem_size_t, vm_flag_t, vmem_addr_t *)" \ +"void (*freefn)(void *, vmem_addr_t, vmem_size_t)" \ +"void *arg" "vmem_size_t qcache_max" "vm_flag_t flags" "int ipl" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft vmem_t * +.Fn vmem_xcreate \ +"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ +"int (*allocfn)(void *, vmem_size_t, vmem_size_t *, vm_flag_t, vmem_addr_t *)" \ +"void (*freefn)(void *, vmem_addr_t, vmem_size_t)" \ +"void *arg" "vmem_size_t qcache_max" "vm_flag_t flags" "int ipl" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_add \ +"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "vm_flag_t flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.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" "vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_xalloc_addr \ +"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "vm_flag_t flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_xfreeall "vmem_t *vm" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "vm_flag_t flags" "vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.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. +.Bl -tag -offset indent -width qcache_max +.It Fa name +The string to describe the vmem. +.It Fa base +The start address of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa size +The size of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa quantum +The smallest unit of allocation. +.It Fa allocfn +The callback function used to import spans from the backend arena. +Set both +.Fa allocfn +and +.Fa freefn +to +.Dv NULL +to disable automatic imports. +.Nm +calls +.Fo "(*allocfn)" +.Fa arg +.Fa size +.Fa flags +.Fa "&addrp" +.Fc +to import a span of size at least +.Fa size . +.Fa allocfn +must accept the same +.Fa flags +as +.Fn vmem_alloc . +.Fa allocfn +must return +.Dv ENOMEM +to indicate failure, or 0 on success. +If +.Fa allocfn +succeeds, it must write the starting address of the imported span to +.Fa addrp . +.It Fa freefn +The callback function used to free spans to the backend arena. +.Fa freefn +may be +.Dv NULL +even if +.Fa allocfn +is not +.Dv NULL . +.Nm +calls +.Fn "(*freefn)" arg addr size +to return to +.Fa arg +a span of size +.Fa size , +starting at +.Fa addr , +that was previously allocated by +.Fa allocfn . +.It Fa arg +The backend arena. +.Fa arg +may be +.Dv NULL . +.Nm +passes +.Fa arg +as the first argument of +.Fa allocfn +and +.Fa freefn . +.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 +If the allocation cannot be satisfied immediately, 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_xcreate +creates a new vmem arena. +.Bl -tag -offset indent -width qcache_max +.It Fa name +The string to describe the vmem. +.It Fa base +The start address of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa size +The size of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa quantum +The smallest unit of allocation. +.It Fa allocfn +The callback function used to import spans from the backend arena. +Set both +.Fa allocfn +and +.Fa freefn +to +.Dv NULL +to disable automatic imports. +.Nm +calls +.Fo "(*allocfn)" +.Fa arg +.Fa size +.Fa "&actualsize" +.Fa flags +.Fa "&addrp" +.Fc +to import a span of size at least +.Fa size . +.Fa allocfn +must accept the same +.Fa flags +as +.Fn vmem_alloc . +.Fa allocfn +must return +.Dv ENOMEM +to indicate failure, or 0 on success. +If +.Fa allocfn +succeeds, it must write the actual size of the allocation to +.Fa actualsize +and the starting address of the imported span to +.Fa addrp . +The actual size will always be greater than or equal to the requested size. +.It Fa freefn +The callback function used to free spans to the backend arena. +.Fa freefn +may be +.Dv NULL +even if +.Fa allocfn +is not +.Dv NULL . +.Nm +calls +.Fn "(*freefn)" arg addr size +to return to +.Fa arg +a span of size +.Fa size , +starting at +.Fa addr , +that was previously allocated by +.Fa allocfn . +.It Fa arg +The backend arena. +.Fa arg +may be +.Dv NULL . +.Nm +passes +.Fa arg +as the first argument of +.Fa allocfn +and +.Fa freefn . +.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 +If the allocation cannot be satisfied immediately, 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_add +adds a span of size +.Fa size +starting at +.Fa addr +to the arena. +Returns +0 +on success, +.Dv ENOMEM +on failure. +.Bl -tag -offset indent -width flags +.It Fa flags +Either of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until enough +resources are available. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv ENOMEM +if there are not enough resources available. +.El +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_xalloc +allocates a resource from the arena. +.Bl -tag -offset indent -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 +must be zero. +Otherwise, +.Fa phase +must be smaller than +.Fa align . +.It Fa nocross +Request a resource which doesn't cross +.Fa nocross +aligned boundary. +.It Fa minaddr +Specify the minimum address which can be allocated, or +.Dv VMEM_ADDR_MIN +if the caller does not care. +.It Fa maxaddr +Specify the maximum address which can be allocated, or +.Dv VMEM_ADDR_MAX +if the caller does not care. +.It Fa flags +A bitwise OR of an allocation strategy and a sleep flag. +.Pp +The allocation strategy must be 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 must be one of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until enough +resources are available. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv ENOMEM +if there are not enough resources available. +.El +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_xalloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_xalloc_addr +allocates a specific address from the arena. +The requested address must be aligned with the arena's quantum. +.Bl -tag -offset indent -width flags +.It Fa vm +The arena which we allocate from. +.It Fa addr +The address to allocate. +.It Fa size +Specify the size of the allocation. +.It Fa flags +A sleep flag. +Because a specific address is being allocated, any specified allocation +strategy is ignored. +.Pp +The sleep flag must be one of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until the +requested range can be allocated. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv ENOMEM +if the requested range is not available. +.El +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_xfree +frees resource allocated by +.Fn vmem_xalloc +or +.Fn vmem_xalloc_addr +to the arena. +.Bl -tag -offset indent -width addr +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must have been allocated via +.Fn vmem_xalloc +or +.Fn vmem_xalloc_addr . +Notably, it must not have been allocated via +.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 +or +.Fn vmem_xalloc_addr . +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_xfreeall +frees all resources that have been allocated by +.Fn vmem_xalloc +to the arena. +.Bl -tag -offset indent -width addr +.It Fa vm +The arena which we free to. +Note that this function is may not be used on arenas +where resources have been allocated using +.Fn vmem_alloc +or arenas that have a quantum cache +.Po +i.e. were created with a non-zero +.Fa qcache_max +.Pc . +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_alloc +allocates a resource from the arena. +.Bl -tag -offset indent -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 must be 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 must be one of: +.Bl -tag -width VM_NOSLEEP +.It Dv VM_SLEEP +If the allocation cannot be satisfied immediately, sleep until enough +resources are available. +.It Dv VM_NOSLEEP +Don't sleep. +Immediately return +.Dv ENOMEM +if there are not enough resources available. +.El +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_alloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_free +frees resource allocated by +.Fn vmem_alloc +to the arena. +.Bl -tag -offset indent -width addr +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must have been allocated via +.Fn vmem_alloc . +Notably, it must not have been allocated via +.Fn vmem_xalloc +or +.Fn vmem_xalloc addr , +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. +.Bl -tag -offset indent -width vm +.It Fa vm +The vmem arena being destroyed. +The caller must ensure that no one will use it anymore. +.El +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +.Fn vmem_create +and +.Fn vmem_xcreate +return a pointer to the newly allocated vmem_t on success, or +.Dv NULL +if +.Dv VM_NOSLEEP +was specified and memory could not be allocated immediately. +.Pp +.Fn vmem_add +returns 0 on success, or +.Er ENOMEM +if +.Dv VM_NOSLEEP +was specified and memory could not be allocated immediately to record +the region. +.Pp +.Fn vmem_alloc +and +.Fn vmem_xalloc +return 0 on success, or +.Er ENOMEM +if either: +.Bl -dash +.It +.Dv VM_NOSLEEP +was specified and a matching region could not be allocated immediately; +or +.It +non-default +.Fa align , +.Fa phase , +or +.Fa nocross +parameters were specified, and a matching region could not be allocated +without calling the backing +.Fa allocfn +passed to +.Fn vmem_create . +.El +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within the file +.Pa sys/kern/subr_vmem.c . +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr intro 9 , +.Xr kmem 9 , +.Xr memoryallocators 9 , +.Xr uvm 9 +.Rs +.%A Jeff Bonwick +.%A Jonathan Adams +.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources" +.%J "2001 USENIX Annual Technical Conference" +.%D 2001 +.Re +.\" ------------------------------------------------------------ +.Sh AUTHORS +This implementation of +.Nm +was written by +.An YAMAMOTO Takashi . +.Sh BUGS +.Nm +relies on +.Xr malloc 9 , +.Xr pool 9 , +and +.Xr RUN_ONCE 9 , +so it cannot be used as early during system bootstrap as +.Xr extent 9 . +.Pp +.Nm +has no way to pass +.Fa align , +.Fa phase , +.Fa nocross , +.Fa minaddr , +or +.Fa maxaddr +constraints into the backing allocator +.Fa allocfn , +so even if +.Dv VM_SLEEP +is specified, +.Fn vmem_alloc +and +.Fn vmem_xalloc +may spuriously fail immediately with +.Fa align , +.Fa phase , +or +.Fa nocross , +or sleep forever with +.Fa minaddr +or +.Fa maxaddr . |