1 .\" $NetBSD: vmem.9,v 1.15 2013/01/29 22:02:17 wiz Exp $
3 .\" Copyright (c)2006 YAMAMOTO Takashi,
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
29 .\" ------------------------------------------------------------
33 .\" ------------------------------------------------------------
36 .Nd general purpose resource allocator
37 .\" ------------------------------------------------------------
40 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
48 "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "int flags"
49 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
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" \
56 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
58 .Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
59 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
61 .Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "int flags" "vmem_addr_t *addrp"
62 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
64 .Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size"
65 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
67 .Fn vmem_destroy "vmem_t *vm"
68 .\" ------------------------------------------------------------
72 is a general purpose resource allocator.
73 Despite its name, it can be used for arbitrary resources
74 other than virtual memory.
76 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
78 creates a new vmem arena.
79 .Bl -tag -width qcache_max
81 The string to describe the vmem.
83 The start address of the initial span.
86 if no initial span is required.
88 The size of the initial span.
91 if no initial span is required.
93 The smallest unit of allocation.
95 The largest size of allocations which can be served by quantum cache.
96 It is merely a hint and can be ignored.
102 allocation strategy flag:
103 .Bl -tag -width M_FIRSTFIT
105 Prefer allocation performance.
107 Prefer space efficiency.
111 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
128 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
130 allocates a resource from the arena.
131 .Bl -tag -width nocross
133 The arena which we allocate from.
135 Specify the size of the allocation.
137 If zero, don't care about the alignment of the allocation.
138 Otherwise, request a resource segment starting at
145 See the above description of
154 should be smaller than
157 Request a resource which doesn't cross
161 Specify the minimum address which can be allocated, or
163 if the caller does not care.
165 Specify the maximum address which can be allocated, or
167 if the caller does not care.
169 A bitwise OR of an allocation strategy and a
172 The allocation strategy is one of
182 overwrites it with the start address of the allocated span.
185 .\" ------------------------------------------------------------
187 frees resource allocated by
192 The arena which we free to.
194 The resource being freed.
195 It must be the one returned by
197 Notably, it must not be the one from
199 Otherwise, the behaviour is undefined.
201 The size of the resource being freed.
202 It must be the same as the
208 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
210 allocates a resource from the arena.
211 .Bl -tag -width flags
213 The arena which we allocate from.
215 Specify the size of the allocation.
219 allocation strategy flag (see above) and a
228 overwrites it with the start address of the allocated span.
231 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
233 frees resource allocated by
238 The arena which we free to.
240 The resource being freed.
241 It must be the one returned by
243 Notably, it must not be the one from
245 Otherwise, the behaviour is undefined.
247 The size of the resource being freed.
248 It must be the same as the
254 .\" ------------------------------------------------------------
256 destroys a vmem arena.
259 The vmem arena being destroyed.
260 The caller should ensure that no one will use it anymore.
262 .\" ------------------------------------------------------------
265 returns a pointer to the newly allocated vmem_t.
266 Otherwise, it returns
277 .\" ------------------------------------------------------------
281 subsystem is implemented within the file
282 .Pa sys/kern/subr_vmem.c .
283 .\" ------------------------------------------------------------
289 .%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources"
290 .%J "2001 USENIX Annual Technical Conference"
293 .\" ------------------------------------------------------------
297 allocator was originally implemented in
303 Original implementation of
306 .An "YAMAMOTO Takashi" .
310 .An "Jeff Roberson" .
315 so it cannot be used as early during system bootstrap.