1.\" $NetBSD: vmem.9,v 1.13 2011/09/05 18:21:29 wiz 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 September 2, 2011 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"int (*allocfn)(void *, vmem_size_t, vmem_size_t *, vm_flag_t, vmem_addr_t *)" \ 43"void (*freefn)(void *, vmem_addr_t, vmem_size_t)" \ 44"void *arg" "vmem_size_t qcache_max" "vm_flag_t flags" "int ipl" 45.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 46.Ft int 47.Fn vmem_add \ 48"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "vm_flag_t flags" "vmem_addr_t *addrp" 49.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 50.Ft int 51.Fn vmem_xalloc \ 52"vmem_t *vm" "vmem_size_t size" "vmem_size_t align" \ 53"vmem_size_t phase" "vmem_size_t nocross" "vmem_addr_t minaddr" \ 54"vmem_addr_t maxaddr" "vm_flag_t flags" "vmem_addr_t *addrp" 55.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 56.Ft void 57.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" 58.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 59.Ft int 60.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "vm_flag_t flags" "vmem_addr_t *addrp" 61.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 62.Ft void 63.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" 64.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 65.Ft void 66.Fn vmem_destroy "vmem_t *vm" 67.\" ------------------------------------------------------------ 68.Sh DESCRIPTION 69The 70.Nm 71is a general purpose resource allocator. 72Despite its name, it can be used for arbitrary resources 73other than virtual memory. 74.Pp 75.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 76.Fn vmem_create 77creates a new vmem arena. 78.Pp 79.Bl -tag -width qcache_max 80.It Fa name 81The string to describe the vmem. 82.It Fa base 83The start address of the initial span. 84Pass 85.Dv 0 86if no initial span is required. 87.It Fa size 88The size of the initial span. 89Pass 90.Dv 0 91if no initial span is required. 92.It Fa quantum 93The smallest unit of allocation. 94.It Fa allocfn 95The callback function used to import spans from the backend arena. 96Set both 97.Fa allocfn 98and 99.Fa freefn 100to 101.Dv NULL 102to disable automatic imports. 103.Nm 104calls 105.Fo "(*allocfn)" 106.Fa arg 107.Fa size 108.Fa "\*[Am]actualsize" 109.Fa flags 110.Fa "\*[Am]addrp" 111.Fc 112to import a span of size at least 113.Fa size . 114.Fa allocfn 115should accept the same 116.Fa flags 117as 118.Fn vmem_alloc . 119.Fa allocfn 120must return 121.Dv ENOMEM 122to indicate failure, or 0 on success. 123If 124.Fa allocfn 125succeeds, it must write the actual size of the allocation to 126.Fa actualsize 127and the starting address of the imported span to 128.Fa addrp . 129The actual size will always be greater than or equal to the requested size. 130.It Fa freefn 131The callback function used to free spans to the backend arena. 132.Fa freefn 133may be 134.Dv NULL 135even if 136.Fa allocfn 137is not 138.Dv NULL . 139.Nm 140calls 141.Fn "(*freefn)" arg addr size 142to return to 143.Fa arg 144a span of size 145.Fa size , 146starting at 147.Fa addr , 148that was previously allocated by 149.Fa allocfn . 150.It Fa arg 151The backend arena. 152.Fa arg 153may be 154.Dv NULL . 155.Nm 156passes 157.Fa arg 158as the first argument of 159.Fa allocfn 160and 161.Fa freefn . 162.It Fa qcache_max 163The largest size of allocations which can be served by quantum cache. 164It is merely a hint and can be ignored. 165.It Fa flags 166Either of: 167.Bl -tag -width VM_NOSLEEP 168.It Dv VM_SLEEP 169Can sleep until enough resources are available. 170.It Dv VM_NOSLEEP 171Don't sleep. 172Immediately return 173.Dv NULL 174if there are not enough resources available. 175.El 176.It Fa ipl 177Interrupt level to be blocked for allocating from vmem. 178.El 179.Pp 180.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 181.Fn vmem_add 182adds a span of size 183.Fa size 184starting at 185.Fa addr 186to the arena. 187Returns 1880 189on success, 190.Dv ENOMEM 191on failure. 192.Fa flags 193should be one of: 194.Bl -tag -width VM_NOSLEEP 195.It Dv VM_SLEEP 196Can sleep until enough resources are available. 197.It Dv VM_NOSLEEP 198Don't sleep. 199Immediately return 200.Dv ENOMEM 201if there are not enough resources available. 202.El 203.Pp 204.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 205.Fn vmem_xalloc 206allocates a resource from the arena. 207.Pp 208.Bl -tag -width nocross 209.It Fa vm 210The arena which we allocate from. 211.It Fa size 212Specify the size of the allocation. 213.It Fa align 214If zero, don't care about the alignment of the allocation. 215Otherwise, request a resource segment starting at 216offset 217.Fa phase 218from an 219.Fa align 220aligned boundary. 221.It Fa phase 222See the above description of 223.Fa align . 224If 225.Fa align 226is zero, 227.Fa phase 228should be zero. 229Otherwise, 230.Fa phase 231should be smaller than 232.Fa align . 233.It Fa nocross 234Request a resource which doesn't cross 235.Fa nocross 236aligned boundary. 237.It Fa minaddr 238Specify the minimum address which can be allocated, or 239.Dv VMEM_ADDR_MIN 240if the caller does not care. 241.It Fa maxaddr 242Specify the maximum address which can be allocated, or 243.Dv VMEM_ADDR_MAX 244if the caller does not care. 245.It Fa flags 246A bitwise OR of an allocation strategy and a sleep flag. 247.Pp 248The allocation strategy is one of: 249.Bl -tag -width VM_INSTANTFIT 250.It Dv VM_BESTFIT 251Prefer space efficiency. 252.It Dv VM_INSTANTFIT 253Prefer performance. 254.El 255.Pp 256The sleep flag should be one of: 257.Bl -tag -width VM_NOSLEEP 258.It Dv VM_SLEEP 259Can sleep until enough resources are available. 260.It Dv VM_NOSLEEP 261Don't sleep. 262Immediately return 263.Dv ENOMEM 264if there are not enough resources available. 265.El 266.It Fa addrp 267On success, if 268.Fa addrp 269is not 270.Dv NULL , 271.Fn vmem_xalloc 272overwrites it with the start address of the allocated span. 273.El 274.Pp 275.\" ------------------------------------------------------------ 276.Fn vmem_xfree 277frees resource allocated by 278.Fn vmem_xalloc 279to the arena. 280.Pp 281.Bl -tag -width addr 282.It Fa vm 283The arena which we free to. 284.It Fa addr 285The resource being freed. 286It must be the one returned by 287.Fn vmem_xalloc . 288Notably, it must not be the one from 289.Fn vmem_alloc . 290Otherwise, the behaviour is undefined. 291.It Fa size 292The size of the resource being freed. 293It must be the same as the 294.Fa size 295argument used for 296.Fn vmem_xalloc . 297.El 298.Pp 299.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 300.Fn vmem_alloc 301allocates a resource from the arena. 302.Pp 303.Bl -tag -width flags 304.It Fa vm 305The arena which we allocate from. 306.It Fa size 307Specify the size of the allocation. 308.It Fa flags 309A bitwise OR of an allocation strategy and a sleep flag. 310.Pp 311The allocation strategy is one of: 312.Bl -tag -width VM_INSTANTFIT 313.It Dv VM_BESTFIT 314Prefer space efficiency. 315.It Dv VM_INSTANTFIT 316Prefer performance. 317.El 318.Pp 319The sleep flag should be one of: 320.Bl -tag -width VM_NOSLEEP 321.It Dv VM_SLEEP 322Can sleep until enough resources are available. 323.It Dv VM_NOSLEEP 324Don't sleep. 325Immediately return 326.Dv ENOMEM 327if there are not enough resources available. 328.El 329.It Fa addrp 330On success, if 331.Fa addrp 332is not 333.Dv NULL , 334.Fn vmem_alloc 335overwrites it with the start address of the allocated span. 336.El 337.Pp 338.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 339.Fn vmem_free 340frees resource allocated by 341.Fn vmem_alloc 342to the arena. 343.Pp 344.Bl -tag -width addr 345.It Fa vm 346The arena which we free to. 347.It Fa addr 348The resource being freed. 349It must be the one returned by 350.Fn vmem_alloc . 351Notably, it must not be the one from 352.Fn vmem_xalloc . 353Otherwise, the behaviour is undefined. 354.It Fa size 355The size of the resource being freed. 356It must be the same as the 357.Fa size 358argument used for 359.Fn vmem_alloc . 360.El 361.Pp 362.\" ------------------------------------------------------------ 363.Fn vmem_destroy 364destroys a vmem arena. 365.Pp 366.Bl -tag -width vm 367.It Fa vm 368The vmem arena being destroyed. 369The caller should ensure that no one will use it anymore. 370.El 371.\" ------------------------------------------------------------ 372.Sh RETURN VALUES 373.Fn vmem_create 374return a pointer to the newly allocated vmem_t. 375Otherwise, it returns 376.Dv NULL . 377.Pp 378On success, 379.Fn vmem_xalloc 380and 381.Fn vmem_alloc 382return 0. 383Otherwise, 384.Dv ENOMEM 385is returned. 386.\" ------------------------------------------------------------ 387.Sh CODE REFERENCES 388The 389.Nm 390subsystem is implemented within the file 391.Pa sys/kern/subr_vmem.c . 392.\" ------------------------------------------------------------ 393.Sh SEE ALSO 394.Xr intro 9 , 395.Xr kmem 9 , 396.Xr memoryallocators 9 , 397.Xr uvm 9 398.Rs 399.%A Jeff Bonwick 400.%A Jonathan Adams 401.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources" 402.%J "2001 USENIX Annual Technical Conference" 403.%D 2001 404.Re 405.\" ------------------------------------------------------------ 406.Sh AUTHORS 407This implementation of 408.Nm 409was written by 410.An YAMAMOTO Takashi . 411.Sh BUGS 412.Pp 413.Nm 414relies on 415.Xr malloc 9 , 416.Xr pool 9 , 417and 418.Xr RUN_ONCE 9 , 419so it cannot be used as early during system bootstrap as 420.Xr extent 9 . 421