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