1.\" $NetBSD: vmem.9,v 1.15 2013/01/29 22:02:17 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.\" $FreeBSD$ 28.\" 29.\" ------------------------------------------------------------ 30.Dd May 17, 2019 31.Dt VMEM 9 32.Os 33.\" ------------------------------------------------------------ 34.Sh NAME 35.Nm vmem 36.Nd general purpose resource allocator 37.\" ------------------------------------------------------------ 38.Sh SYNOPSIS 39.In sys/vmem.h 40.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 41.Ft vmem_t * 42.Fn vmem_create \ 43"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ 44"vmem_size_t qcache_max" "int flags" 45.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 46.Ft int 47.Fn vmem_add \ 48"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "int flags" 49.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 50.Ft int 51.Fn vmem_xalloc \ 52"vmem_t *vm" "const vmem_size_t size" "vmem_size_t align" \ 53"const vmem_size_t phase" "const vmem_size_t nocross" \ 54"const vmem_addr_t minaddr" "const vmem_addr_t maxaddr" "int flags" \ 55"vmem_addr_t *addrp" 56.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 57.Ft void 58.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" 59.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 60.Ft int 61.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "int flags" "vmem_addr_t *addrp" 62.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 63.Ft void 64.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" 65.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 66.Ft void 67.Fn vmem_destroy "vmem_t *vm" 68.\" ------------------------------------------------------------ 69.Sh DESCRIPTION 70The 71.Nm 72is a general purpose resource allocator. 73Despite its name, it can be used for arbitrary resources 74other than virtual memory. 75.Pp 76.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 77.Fn vmem_create 78creates a new vmem arena. 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 qcache_max 95The largest size of allocations which can be served by quantum cache. 96It is merely a hint and can be ignored. 97.It Fa flags 98.Xr malloc 9 99wait flag. 100.El 101.Pp 102.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 103.Fn vmem_add 104adds a span of size 105.Fa size 106starting at 107.Fa addr 108to the arena. 109Returns 1100 111on success, 112.Dv ENOMEM 113on failure. 114.Fa flags 115is 116.Xr malloc 9 117wait flag. 118.Pp 119.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 120.Fn vmem_xalloc 121allocates a resource from the arena. 122.Bl -tag -width nocross 123.It Fa vm 124The arena which we allocate from. 125.It Fa size 126Specify the size of the allocation. 127.It Fa align 128If zero, don't care about the alignment of the allocation. 129Otherwise, request a resource segment starting at 130offset 131.Fa phase 132from an 133.Fa align 134aligned boundary. 135.It Fa phase 136See the above description of 137.Fa align . 138If 139.Fa align 140is zero, 141.Fa phase 142should be zero. 143Otherwise, 144.Fa phase 145should be smaller than 146.Fa align . 147.It Fa nocross 148Request a resource which doesn't cross 149.Fa nocross 150aligned boundary. 151.It Fa minaddr 152Specify the minimum address which can be allocated, or 153.Dv VMEM_ADDR_MIN 154if the caller does not care. 155.It Fa maxaddr 156Specify the maximum address which can be allocated, or 157.Dv VMEM_ADDR_MAX 158if the caller does not care. 159.It Fa flags 160A bitwise OR of an allocation strategy and a 161.Xr malloc 9 162wait flag. 163The allocation strategy is one of: 164.Bl -tag width indent 165.It Dv M_FIRSTFIT 166Prefer allocation performance. 167.It Dv M_BESTFIT 168Prefer space efficiency. 169.It Dv M_NEXTFIT 170Perform an address-ordered search for free addresses, beginning where 171the previous search ended. 172.El 173.It Fa addrp 174On success, if 175.Fa addrp 176is not 177.Dv NULL , 178.Fn vmem_xalloc 179overwrites it with the start address of the allocated span. 180.El 181.Pp 182.\" ------------------------------------------------------------ 183.Fn vmem_xfree 184frees resource allocated by 185.Fn vmem_xalloc 186to the arena. 187.Bl -tag -width addr 188.It Fa vm 189The arena which we free to. 190.It Fa addr 191The resource being freed. 192It must be the one returned by 193.Fn vmem_xalloc . 194Notably, it must not be the one from 195.Fn vmem_alloc . 196Otherwise, the behaviour is undefined. 197.It Fa size 198The size of the resource being freed. 199It must be the same as the 200.Fa size 201argument used for 202.Fn vmem_xalloc . 203.El 204.Pp 205.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 206.Fn vmem_alloc 207allocates a resource from the arena. 208.Bl -tag -width flags 209.It Fa vm 210The arena which we allocate from. 211.It Fa size 212Specify the size of the allocation. 213.It Fa flags 214A bitwise OR of an 215.Nm 216allocation strategy flag (see above) and a 217.Xr malloc 9 218sleep flag. 219.It Fa addrp 220On success, if 221.Fa addrp 222is not 223.Dv NULL , 224.Fn vmem_alloc 225overwrites it with the start address of the allocated span. 226.El 227.Pp 228.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 229.Fn vmem_free 230frees resource allocated by 231.Fn vmem_alloc 232to the arena. 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.Bl -tag -width vm 255.It Fa vm 256The vmem arena being destroyed. 257The caller should ensure that no one will use it anymore. 258.El 259.\" ------------------------------------------------------------ 260.Sh RETURN VALUES 261.Fn vmem_create 262returns a pointer to the newly allocated vmem_t. 263Otherwise, it returns 264.Dv NULL . 265.Pp 266On success, 267.Fn vmem_xalloc 268and 269.Fn vmem_alloc 270return 0. 271Otherwise, 272.Dv ENOMEM 273is returned. 274.\" ------------------------------------------------------------ 275.Sh CODE REFERENCES 276The 277.Nm 278subsystem is implemented within the file 279.Pa sys/kern/subr_vmem.c . 280.\" ------------------------------------------------------------ 281.Sh SEE ALSO 282.Xr malloc 9 283.Rs 284.%A Jeff Bonwick 285.%A Jonathan Adams 286.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources" 287.%J "2001 USENIX Annual Technical Conference" 288.%D 2001 289.Re 290.\" ------------------------------------------------------------ 291.Sh HISTORY 292The 293.Nm 294allocator was originally implemented in 295.Nx . 296It was introduced in 297.Fx 10.0 . 298.Sh AUTHORS 299.An -nosplit 300Original implementation of 301.Nm 302was written by 303.An "YAMAMOTO Takashi" . 304The 305.Fx 306port was made by 307.An "Jeff Roberson" . 308.Sh BUGS 309.Nm 310relies on 311.Xr malloc 9 , 312so it cannot be used as early during system bootstrap. 313