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 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
119 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
121 allocates a resource from the arena.
122 .Bl -tag -width nocross
124 The arena which we allocate from.
126 Specify the size of the allocation.
128 If zero, don't care about the alignment of the allocation.
129 Otherwise, request a resource segment starting at
136 See the above description of
145 should be smaller than
148 Request a resource which doesn't cross
152 Specify the minimum address which can be allocated, or
154 if the caller does not care.
156 Specify the maximum address which can be allocated, or
158 if the caller does not care.
160 A bitwise OR of an allocation strategy and a
163 The allocation strategy is one of:
164 .Bl -tag width indent
166 Prefer allocation performance.
168 Prefer space efficiency.
170 Perform an address-ordered search for free addresses, beginning where
171 the previous search ended.
179 overwrites it with the start address of the allocated span.
182 .\" ------------------------------------------------------------
184 frees resource allocated by
189 The arena which we free to.
191 The resource being freed.
192 It must be the one returned by
194 Notably, it must not be the one from
196 Otherwise, the behaviour is undefined.
198 The size of the resource being freed.
199 It must be the same as the
205 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
207 allocates a resource from the arena.
208 .Bl -tag -width flags
210 The arena which we allocate from.
212 Specify the size of the allocation.
216 allocation strategy flag (see above) and a
225 overwrites it with the start address of the allocated span.
228 .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
230 frees resource allocated by
235 The arena which we free to.
237 The resource being freed.
238 It must be the one returned by
240 Notably, it must not be the one from
242 Otherwise, the behaviour is undefined.
244 The size of the resource being freed.
245 It must be the same as the
251 .\" ------------------------------------------------------------
253 destroys a vmem arena.
256 The vmem arena being destroyed.
257 The caller should ensure that no one will use it anymore.
259 .\" ------------------------------------------------------------
262 returns a pointer to the newly allocated vmem_t.
263 Otherwise, it returns
274 .\" ------------------------------------------------------------
278 subsystem is implemented within the file
279 .Pa sys/kern/subr_vmem.c .
280 .\" ------------------------------------------------------------
286 .%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources"
287 .%J "2001 USENIX Annual Technical Conference"
290 .\" ------------------------------------------------------------
294 allocator was originally implemented in
300 Original implementation of
303 .An "YAMAMOTO Takashi" .
307 .An "Jeff Roberson" .
312 so it cannot be used as early during system bootstrap.