1.\" $NetBSD: vmem.9,v 1.6 2009/08/03 23:15:29 rmind Exp $ 2.\" 3.\" Copyright (c)2006 YAMAMOTO Takashi, 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" ------------------------------------------------------------ 28.Dd August 3, 2009 29.Dt VMEM 9 30.Os 31.\" ------------------------------------------------------------ 32.Sh NAME 33.Nm vmem 34.Nd virtual memory allocator 35.\" ------------------------------------------------------------ 36.Sh SYNOPSIS 37.In sys/vmem.h 38.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 39.Ft vmem_t * 40.Fn vmem_create \ 41"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ 42"vmem_addr_t (*allocfn)(vmem_t *, vmem_size_t, vmem_size_t *, vm_flag_t)" \ 43"void (*freefn)(vmem_t *, vmem_addr_t, vmem_size_t)" \ 44"vmem_t *source" "vmem_size_t qcache_max" "vm_flag_t flags" "int ipl" 45.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 46.Ft vmem_addr_t 47.Fn vmem_xalloc \ 48"vmem_t *vm" "vmem_size_t size" "vmem_size_t align" \ 49"vmem_size_t phase" "vmem_size_t nocross" "vmem_addr_t minaddr" \ 50"vmem_addr_t maxaddr" "vm_flag_t flags" 51.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 52.Ft void 53.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" 54.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 55.Ft vmem_addr_t 56.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "vm_flag_t flags" 57.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 58.Ft void 59.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" 60.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 61.Ft void 62.Fn vmem_destroy "vmem_t *vm" 63.\" ------------------------------------------------------------ 64.Sh DESCRIPTION 65The 66.Nm 67is a general purpose resource allocator. 68Despite its name, it can be used for arbitrary resources 69other than virtual memory. 70.Pp 71.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 72.Fn vmem_create 73creates a new vmem arena. 74.Pp 75.Bl -tag -width qcache_max 76.It Fa name 77The string to describe the vmem. 78.It Fa base 79The start address of the initial span. 80It can be 81.Dv VMEM_ADDR_NULL 82if no initial span is required. 83.It Fa size 84The size of the initial span. 85.It Fa quantum 86The smallest unit of allocation. 87.It Fa allocfn 88The callback function used to import spans from the backend arena. 89.It Fa freefn 90The callback function used to free spans to the backend arena. 91.It Fa source 92The backend arena. 93.It Fa qcache_max 94The largest size of allocations which can be served by quantum cache. 95It is merely a hint and can be ignored. 96.It Fa flags 97Either of: 98.Bl -tag -width VM_NOSLEEP 99.It Dv VM_SLEEP 100Can sleep until enough resources are available. 101.It Dv VM_NOSLEEP 102Don't sleep. 103Immediately return 104.Dv NULL 105if there are not enough resources available. 106.El 107.It Fa ipl 108Interrupt level to be blocked for allocating from vmem. 109.El 110.Pp 111.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 112.Fn vmem_xalloc 113allocates a resource from the arena. 114.Pp 115.Bl -tag -width nocross 116.It Fa vm 117The arena which we allocate from. 118.It Fa size 119Specify the size of the allocation. 120.It Fa align 121If zero, don't care about the alignment of the allocation. 122Otherwise, request a resource segment starting at 123offset 124.Fa phase 125from an 126.Fa align 127aligned boundary. 128.It Fa phase 129See the above description of 130.Fa align . 131If 132.Fa align 133is zero, 134.Fa phase 135should be zero. 136Otherwise, 137.Fa phase 138should be smaller than 139.Fa align . 140.It Fa nocross 141Request a resource which doesn't cross 142.Fa nocross 143aligned boundary. 144.It Fa minaddr 145If non-zero, specify the minimum address which can be allocated. 146.It Fa maxaddr 147If non-zero, specify the maximum address + 1 which can be allocated. 148.It Fa flags 149A bitwise OR of an allocation strategy and a sleep flag. 150.Pp 151The allocation strategy is one of: 152.Bl -tag -width VM_INSTANTFIT 153.It Dv VM_BESTFIT 154Prefer space efficiency. 155.It Dv VM_INSTANTFIT 156Prefer performance. 157.El 158.Pp 159The sleep flag should be one of: 160.Bl -tag -width VM_NOSLEEP 161.It Dv VM_SLEEP 162Can sleep until enough resources are available. 163.It Dv VM_NOSLEEP 164Don't sleep. 165Immediately return 166.Dv VMEM_ADDR_NULL 167if there are not enough resources available. 168.El 169.El 170.Pp 171.\" ------------------------------------------------------------ 172.Fn vmem_xfree 173frees resource allocated by 174.Fa vmem_xalloc 175to the arena. 176.Pp 177.Bl -tag -width addr 178.It Fa vm 179The arena which we free to. 180.It Fa addr 181The resource being freed. 182It must be the one returned by 183.Fn vmem_xalloc . 184Notably, it must not be the one from 185.Fn vmem_alloc . 186Otherwise, the behaviour is undefined. 187.It Fa size 188The size of the resource being freed. 189It must be the same as the 190.Fa size 191argument used for 192.Fn vmem_xalloc . 193.El 194.Pp 195.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 196.Fn vmem_alloc 197allocates a resource from the arena. 198.Pp 199.Bl -tag -width flags 200.It Fa vm 201The arena which we allocate from. 202.It Fa size 203Specify the size of the allocation. 204.It Fa flags 205A bitwise OR of an allocation strategy and a sleep flag. 206.Pp 207The allocation strategy is one of: 208.Bl -tag -width VM_INSTANTFIT 209.It Dv VM_BESTFIT 210Prefer space efficiency. 211.It Dv VM_INSTANTFIT 212Prefer performance. 213.El 214.Pp 215The sleep flag should be one of: 216.Bl -tag -width VM_NOSLEEP 217.It Dv VM_SLEEP 218Can sleep until enough resources are available. 219.It Dv VM_NOSLEEP 220Don't sleep. 221Immediately return 222.Dv VMEM_ADDR_NULL 223if there are not enough resources available. 224.El 225.El 226.Pp 227.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 228.Fn vmem_free 229frees resource allocated by 230.Fa vmem_alloc 231to the arena. 232.Pp 233.Bl -tag -width addr 234.It Fa vm 235The arena which we free to. 236.It Fa addr 237The resource being freed. 238It must be the one returned by 239.Fn vmem_alloc . 240Notably, it must not be the one from 241.Fn vmem_xalloc . 242Otherwise, the behaviour is undefined. 243.It Fa size 244The size of the resource being freed. 245It must be the same as the 246.Fa size 247argument used for 248.Fn vmem_alloc . 249.El 250.Pp 251.\" ------------------------------------------------------------ 252.Fn vmem_destroy 253destroys a vmem arena. 254.Pp 255.Bl -tag -width vm 256.It Fa vm 257The vmem arena being destroyed. 258The caller should ensure that no one will use it anymore. 259.El 260.\" ------------------------------------------------------------ 261.Sh RETURN VALUES 262.Fn vmem_create 263return a pointer to the newly allocated vmem_t. 264Otherwise, it returns 265.Dv NULL . 266.Pp 267On success, 268.Fn vmem_xalloc 269and 270.Fn vmem_alloc 271return an allocated vmem_addr_t. 272Otherwise, 273.Dv VMEM_ADDR_NULL 274is returned. 275.\" ------------------------------------------------------------ 276.Sh CODE REFERENCES 277This section describes places within the 278.Nx 279source tree where actual code implementing the 280.Nm 281subsystem can be found. 282All pathnames are relative to 283.Pa /usr/src . 284.Pp 285The 286.Nm 287subsystem is implemented within the file 288.Pa sys/kern/subr_vmem.c . 289.\" ------------------------------------------------------------ 290.Sh SEE ALSO 291.Xr intro 9 , 292.Xr kmem 9 , 293.Xr memoryallocators 9 , 294.Xr uvm 9 295.Rs 296.%A Jeff Bonwick 297.%A Jonathan Adams 298.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources" 299.%J "2001 USENIX Annual Technical Conference" 300.%D 2001 301.Re 302.\" ------------------------------------------------------------ 303.Sh AUTHORS 304This implementation of 305.Nm 306was written by 307.An YAMAMOTO Takashi . 308