| @@ -1,41 +1,41 @@ | | | @@ -1,41 +1,41 @@ |
1 | .\" $NetBSD: vmem.9,v 1.15 2013/01/29 22:02:17 wiz Exp $ | | 1 | .\" $NetBSD: vmem.9,v 1.15.8.1 2017/12/03 10:25:02 snj Exp $ |
2 | .\" | | 2 | .\" |
3 | .\" Copyright (c)2006 YAMAMOTO Takashi, | | 3 | .\" Copyright (c)2006 YAMAMOTO Takashi, |
4 | .\" All rights reserved. | | 4 | .\" All rights reserved. |
5 | .\" | | 5 | .\" |
6 | .\" Redistribution and use in source and binary forms, with or without | | 6 | .\" Redistribution and use in source and binary forms, with or without |
7 | .\" modification, are permitted provided that the following conditions | | 7 | .\" modification, are permitted provided that the following conditions |
8 | .\" are met: | | 8 | .\" are met: |
9 | .\" 1. Redistributions of source code must retain the above copyright | | 9 | .\" 1. Redistributions of source code must retain the above copyright |
10 | .\" notice, this list of conditions and the following disclaimer. | | 10 | .\" notice, this list of conditions and the following disclaimer. |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | | 11 | .\" 2. Redistributions in binary form must reproduce the above copyright |
12 | .\" notice, this list of conditions and the following disclaimer in the | | 12 | .\" notice, this list of conditions and the following disclaimer in the |
13 | .\" documentation and/or other materials provided with the distribution. | | 13 | .\" documentation and/or other materials provided with the distribution. |
14 | .\" | | 14 | .\" |
15 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | | 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 | | 16 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
17 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | | 17 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
18 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | | 18 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE |
19 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | | 19 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
20 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | | 20 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
21 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | | 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 | | 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 | | 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 | | 24 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
25 | .\" SUCH DAMAGE. | | 25 | .\" SUCH DAMAGE. |
26 | .\" | | 26 | .\" |
27 | .\" ------------------------------------------------------------ | | 27 | .\" ------------------------------------------------------------ |
28 | .Dd January 29, 2013 | | 28 | .Dd February 28, 2016 |
29 | .Dt VMEM 9 | | 29 | .Dt VMEM 9 |
30 | .Os | | 30 | .Os |
31 | .\" ------------------------------------------------------------ | | 31 | .\" ------------------------------------------------------------ |
32 | .Sh NAME | | 32 | .Sh NAME |
33 | .Nm vmem | | 33 | .Nm vmem |
34 | .Nd virtual memory allocator | | 34 | .Nd virtual memory allocator |
35 | .\" ------------------------------------------------------------ | | 35 | .\" ------------------------------------------------------------ |
36 | .Sh SYNOPSIS | | 36 | .Sh SYNOPSIS |
37 | .In sys/vmem.h | | 37 | .In sys/vmem.h |
38 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 38 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
39 | .Ft vmem_t * | | 39 | .Ft vmem_t * |
40 | .Fn vmem_create \ | | 40 | .Fn vmem_create \ |
41 | "const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ | | 41 | "const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ |
| @@ -73,27 +73,27 @@ | | | @@ -73,27 +73,27 @@ |
73 | .Fn vmem_destroy "vmem_t *vm" | | 73 | .Fn vmem_destroy "vmem_t *vm" |
74 | .\" ------------------------------------------------------------ | | 74 | .\" ------------------------------------------------------------ |
75 | .Sh DESCRIPTION | | 75 | .Sh DESCRIPTION |
76 | The | | 76 | The |
77 | .Nm | | 77 | .Nm |
78 | is a general purpose resource allocator. | | 78 | is a general purpose resource allocator. |
79 | Despite its name, it can be used for arbitrary resources | | 79 | Despite its name, it can be used for arbitrary resources |
80 | other than virtual memory. | | 80 | other than virtual memory. |
81 | .Pp | | 81 | .Pp |
82 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 82 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
83 | .Fn vmem_create | | 83 | .Fn vmem_create |
84 | creates a new vmem arena. | | 84 | creates a new vmem arena. |
85 | .Pp | | 85 | .Pp |
86 | .Bl -tag -width qcache_max | | 86 | .Bl -tag -offset indent -width qcache_max |
87 | .It Fa name | | 87 | .It Fa name |
88 | The string to describe the vmem. | | 88 | The string to describe the vmem. |
89 | .It Fa base | | 89 | .It Fa base |
90 | The start address of the initial span. | | 90 | The start address of the initial span. |
91 | Pass | | 91 | Pass |
92 | .Dv 0 | | 92 | .Dv 0 |
93 | if no initial span is required. | | 93 | if no initial span is required. |
94 | .It Fa size | | 94 | .It Fa size |
95 | The size of the initial span. | | 95 | The size of the initial span. |
96 | Pass | | 96 | Pass |
97 | .Dv 0 | | 97 | .Dv 0 |
98 | if no initial span is required. | | 98 | if no initial span is required. |
99 | .It Fa quantum | | 99 | .It Fa quantum |
| @@ -108,27 +108,27 @@ to | | | @@ -108,27 +108,27 @@ to |
108 | .Dv NULL | | 108 | .Dv NULL |
109 | to disable automatic imports. | | 109 | to disable automatic imports. |
110 | .Nm | | 110 | .Nm |
111 | calls | | 111 | calls |
112 | .Fo "(*allocfn)" | | 112 | .Fo "(*allocfn)" |
113 | .Fa arg | | 113 | .Fa arg |
114 | .Fa size | | 114 | .Fa size |
115 | .Fa flags | | 115 | .Fa flags |
116 | .Fa "\*[Am]addrp" | | 116 | .Fa "\*[Am]addrp" |
117 | .Fc | | 117 | .Fc |
118 | to import a span of size at least | | 118 | to import a span of size at least |
119 | .Fa size . | | 119 | .Fa size . |
120 | .Fa allocfn | | 120 | .Fa allocfn |
121 | should accept the same | | 121 | must accept the same |
122 | .Fa flags | | 122 | .Fa flags |
123 | as | | 123 | as |
124 | .Fn vmem_alloc . | | 124 | .Fn vmem_alloc . |
125 | .Fa allocfn | | 125 | .Fa allocfn |
126 | must return | | 126 | must return |
127 | .Dv ENOMEM | | 127 | .Dv ENOMEM |
128 | to indicate failure, or 0 on success. | | 128 | to indicate failure, or 0 on success. |
129 | If | | 129 | If |
130 | .Fa allocfn | | 130 | .Fa allocfn |
131 | succeeds, it must write the starting address of the imported span to | | 131 | succeeds, it must write the starting address of the imported span to |
132 | .Fa addrp . | | 132 | .Fa addrp . |
133 | .It Fa freefn | | 133 | .It Fa freefn |
134 | The callback function used to free spans to the backend arena. | | 134 | The callback function used to free spans to the backend arena. |
| @@ -159,42 +159,43 @@ may be | | | @@ -159,42 +159,43 @@ may be |
159 | passes | | 159 | passes |
160 | .Fa arg | | 160 | .Fa arg |
161 | as the first argument of | | 161 | as the first argument of |
162 | .Fa allocfn | | 162 | .Fa allocfn |
163 | and | | 163 | and |
164 | .Fa freefn . | | 164 | .Fa freefn . |
165 | .It Fa qcache_max | | 165 | .It Fa qcache_max |
166 | The largest size of allocations which can be served by quantum cache. | | 166 | The largest size of allocations which can be served by quantum cache. |
167 | It is merely a hint and can be ignored. | | 167 | It is merely a hint and can be ignored. |
168 | .It Fa flags | | 168 | .It Fa flags |
169 | Either of: | | 169 | Either of: |
170 | .Bl -tag -width VM_NOSLEEP | | 170 | .Bl -tag -width VM_NOSLEEP |
171 | .It Dv VM_SLEEP | | 171 | .It Dv VM_SLEEP |
172 | Can sleep until enough resources are available. | | 172 | If the allocation cannot be satisfied immediately, sleep until enough |
| | | 173 | resources are available. |
173 | .It Dv VM_NOSLEEP | | 174 | .It Dv VM_NOSLEEP |
174 | Don't sleep. | | 175 | Don't sleep. |
175 | Immediately return | | 176 | Immediately return |
176 | .Dv NULL | | 177 | .Dv NULL |
177 | if there are not enough resources available. | | 178 | if there are not enough resources available. |
178 | .El | | 179 | .El |
179 | .It Fa ipl | | 180 | .It Fa ipl |
180 | Interrupt level to be blocked for allocating from vmem. | | 181 | Interrupt level to be blocked for allocating from vmem. |
181 | .El | | 182 | .El |
182 | .Pp | | 183 | .Pp |
183 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 184 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
184 | .Fn vmem_xcreate | | 185 | .Fn vmem_xcreate |
185 | creates a new vmem arena. | | 186 | creates a new vmem arena. |
186 | .Pp | | 187 | .Pp |
187 | .Bl -tag -width qcache_max | | 188 | .Bl -tag -offset indent -width qcache_max |
188 | .It Fa name | | 189 | .It Fa name |
189 | The string to describe the vmem. | | 190 | The string to describe the vmem. |
190 | .It Fa base | | 191 | .It Fa base |
191 | The start address of the initial span. | | 192 | The start address of the initial span. |
192 | Pass | | 193 | Pass |
193 | .Dv 0 | | 194 | .Dv 0 |
194 | if no initial span is required. | | 195 | if no initial span is required. |
195 | .It Fa size | | 196 | .It Fa size |
196 | The size of the initial span. | | 197 | The size of the initial span. |
197 | Pass | | 198 | Pass |
198 | .Dv 0 | | 199 | .Dv 0 |
199 | if no initial span is required. | | 200 | if no initial span is required. |
200 | .It Fa quantum | | 201 | .It Fa quantum |
| @@ -210,27 +211,27 @@ to | | | @@ -210,27 +211,27 @@ to |
210 | to disable automatic imports. | | 211 | to disable automatic imports. |
211 | .Nm | | 212 | .Nm |
212 | calls | | 213 | calls |
213 | .Fo "(*allocfn)" | | 214 | .Fo "(*allocfn)" |
214 | .Fa arg | | 215 | .Fa arg |
215 | .Fa size | | 216 | .Fa size |
216 | .Fa "\*[Am]actualsize" | | 217 | .Fa "\*[Am]actualsize" |
217 | .Fa flags | | 218 | .Fa flags |
218 | .Fa "\*[Am]addrp" | | 219 | .Fa "\*[Am]addrp" |
219 | .Fc | | 220 | .Fc |
220 | to import a span of size at least | | 221 | to import a span of size at least |
221 | .Fa size . | | 222 | .Fa size . |
222 | .Fa allocfn | | 223 | .Fa allocfn |
223 | should accept the same | | 224 | must accept the same |
224 | .Fa flags | | 225 | .Fa flags |
225 | as | | 226 | as |
226 | .Fn vmem_alloc . | | 227 | .Fn vmem_alloc . |
227 | .Fa allocfn | | 228 | .Fa allocfn |
228 | must return | | 229 | must return |
229 | .Dv ENOMEM | | 230 | .Dv ENOMEM |
230 | to indicate failure, or 0 on success. | | 231 | to indicate failure, or 0 on success. |
231 | If | | 232 | If |
232 | .Fa allocfn | | 233 | .Fa allocfn |
233 | succeeds, it must write the actual size of the allocation to | | 234 | succeeds, it must write the actual size of the allocation to |
234 | .Fa actualsize | | 235 | .Fa actualsize |
235 | and the starting address of the imported span to | | 236 | and the starting address of the imported span to |
236 | .Fa addrp . | | 237 | .Fa addrp . |
| @@ -264,227 +265,233 @@ may be | | | @@ -264,227 +265,233 @@ may be |
264 | passes | | 265 | passes |
265 | .Fa arg | | 266 | .Fa arg |
266 | as the first argument of | | 267 | as the first argument of |
267 | .Fa allocfn | | 268 | .Fa allocfn |
268 | and | | 269 | and |
269 | .Fa freefn . | | 270 | .Fa freefn . |
270 | .It Fa qcache_max | | 271 | .It Fa qcache_max |
271 | The largest size of allocations which can be served by quantum cache. | | 272 | The largest size of allocations which can be served by quantum cache. |
272 | It is merely a hint and can be ignored. | | 273 | It is merely a hint and can be ignored. |
273 | .It Fa flags | | 274 | .It Fa flags |
274 | Either of: | | 275 | Either of: |
275 | .Bl -tag -width VM_NOSLEEP | | 276 | .Bl -tag -width VM_NOSLEEP |
276 | .It Dv VM_SLEEP | | 277 | .It Dv VM_SLEEP |
277 | Can sleep until enough resources are available. | | 278 | If the allocation cannot be satisfied immediately, sleep until enough |
| | | 279 | resources are available. |
278 | .It Dv VM_NOSLEEP | | 280 | .It Dv VM_NOSLEEP |
279 | Don't sleep. | | 281 | Don't sleep. |
280 | Immediately return | | 282 | Immediately return |
281 | .Dv NULL | | 283 | .Dv NULL |
282 | if there are not enough resources available. | | 284 | if there are not enough resources available. |
283 | .El | | 285 | .El |
284 | .It Fa ipl | | 286 | .It Fa ipl |
285 | Interrupt level to be blocked for allocating from vmem. | | 287 | Interrupt level to be blocked for allocating from vmem. |
286 | .El | | 288 | .El |
287 | .Pp | | 289 | .Pp |
288 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 290 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
289 | .Fn vmem_add | | 291 | .Fn vmem_add |
290 | adds a span of size | | 292 | adds a span of size |
291 | .Fa size | | 293 | .Fa size |
292 | starting at | | 294 | starting at |
293 | .Fa addr | | 295 | .Fa addr |
294 | to the arena. | | 296 | to the arena. |
295 | Returns | | 297 | Returns |
296 | 0 | | 298 | 0 |
297 | on success, | | 299 | on success, |
298 | .Dv ENOMEM | | 300 | .Dv ENOMEM |
299 | on failure. | | 301 | on failure. |
300 | .Fa flags | | 302 | .Bl -tag -offset indent -width flags |
301 | should be one of: | | 303 | .It Fa flags |
| | | 304 | Either of: |
302 | .Bl -tag -width VM_NOSLEEP | | 305 | .Bl -tag -width VM_NOSLEEP |
303 | .It Dv VM_SLEEP | | 306 | .It Dv VM_SLEEP |
304 | Can sleep until enough resources are available. | | 307 | If the allocation cannot be satisfied immediately, sleep until enough |
| | | 308 | resources are available. |
305 | .It Dv VM_NOSLEEP | | 309 | .It Dv VM_NOSLEEP |
306 | Don't sleep. | | 310 | Don't sleep. |
307 | Immediately return | | 311 | Immediately return |
308 | .Dv ENOMEM | | 312 | .Dv ENOMEM |
309 | if there are not enough resources available. | | 313 | if there are not enough resources available. |
310 | .El | | 314 | .El |
| | | 315 | .El |
311 | .Pp | | 316 | .Pp |
312 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 317 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
313 | .Fn vmem_xalloc | | 318 | .Fn vmem_xalloc |
314 | allocates a resource from the arena. | | 319 | allocates a resource from the arena. |
315 | .Pp | | 320 | .Pp |
316 | .Bl -tag -width nocross | | 321 | .Bl -tag -offset indent -width nocross |
317 | .It Fa vm | | 322 | .It Fa vm |
318 | The arena which we allocate from. | | 323 | The arena which we allocate from. |
319 | .It Fa size | | 324 | .It Fa size |
320 | Specify the size of the allocation. | | 325 | Specify the size of the allocation. |
321 | .It Fa align | | 326 | .It Fa align |
322 | If zero, don't care about the alignment of the allocation. | | 327 | If zero, don't care about the alignment of the allocation. |
323 | Otherwise, request a resource segment starting at | | 328 | Otherwise, request a resource segment starting at |
324 | offset | | 329 | offset |
325 | .Fa phase | | 330 | .Fa phase |
326 | from an | | 331 | from an |
327 | .Fa align | | 332 | .Fa align |
328 | aligned boundary. | | 333 | aligned boundary. |
329 | .It Fa phase | | 334 | .It Fa phase |
330 | See the above description of | | 335 | See the above description of |
331 | .Fa align . | | 336 | .Fa align . |
332 | If | | 337 | If |
333 | .Fa align | | 338 | .Fa align |
334 | is zero, | | 339 | is zero, |
335 | .Fa phase | | 340 | .Fa phase |
336 | should be zero. | | 341 | must be zero. |
337 | Otherwise, | | 342 | Otherwise, |
338 | .Fa phase | | 343 | .Fa phase |
339 | should be smaller than | | 344 | must be smaller than |
340 | .Fa align . | | 345 | .Fa align . |
341 | .It Fa nocross | | 346 | .It Fa nocross |
342 | Request a resource which doesn't cross | | 347 | Request a resource which doesn't cross |
343 | .Fa nocross | | 348 | .Fa nocross |
344 | aligned boundary. | | 349 | aligned boundary. |
345 | .It Fa minaddr | | 350 | .It Fa minaddr |
346 | Specify the minimum address which can be allocated, or | | 351 | Specify the minimum address which can be allocated, or |
347 | .Dv VMEM_ADDR_MIN | | 352 | .Dv VMEM_ADDR_MIN |
348 | if the caller does not care. | | 353 | if the caller does not care. |
349 | .It Fa maxaddr | | 354 | .It Fa maxaddr |
350 | Specify the maximum address which can be allocated, or | | 355 | Specify the maximum address which can be allocated, or |
351 | .Dv VMEM_ADDR_MAX | | 356 | .Dv VMEM_ADDR_MAX |
352 | if the caller does not care. | | 357 | if the caller does not care. |
353 | .It Fa flags | | 358 | .It Fa flags |
354 | A bitwise OR of an allocation strategy and a sleep flag. | | 359 | A bitwise OR of an allocation strategy and a sleep flag. |
355 | .Pp | | 360 | .Pp |
356 | The allocation strategy is one of: | | 361 | The allocation strategy must be one of: |
357 | .Bl -tag -width VM_INSTANTFIT | | 362 | .Bl -tag -width VM_INSTANTFIT |
358 | .It Dv VM_BESTFIT | | 363 | .It Dv VM_BESTFIT |
359 | Prefer space efficiency. | | 364 | Prefer space efficiency. |
360 | .It Dv VM_INSTANTFIT | | 365 | .It Dv VM_INSTANTFIT |
361 | Prefer performance. | | 366 | Prefer performance. |
362 | .El | | 367 | .El |
363 | .Pp | | 368 | .Pp |
364 | The sleep flag should be one of: | | 369 | The sleep flag must be one of: |
365 | .Bl -tag -width VM_NOSLEEP | | 370 | .Bl -tag -width VM_NOSLEEP |
366 | .It Dv VM_SLEEP | | 371 | .It Dv VM_SLEEP |
367 | Can sleep until enough resources are available. | | 372 | If the allocation cannot be satisfied immediately, sleep until enough |
| | | 373 | resources are available. |
368 | .It Dv VM_NOSLEEP | | 374 | .It Dv VM_NOSLEEP |
369 | Don't sleep. | | 375 | Don't sleep. |
370 | Immediately return | | 376 | Immediately return |
371 | .Dv ENOMEM | | 377 | .Dv ENOMEM |
372 | if there are not enough resources available. | | 378 | if there are not enough resources available. |
373 | .El | | 379 | .El |
374 | .It Fa addrp | | 380 | .It Fa addrp |
375 | On success, if | | 381 | On success, if |
376 | .Fa addrp | | 382 | .Fa addrp |
377 | is not | | 383 | is not |
378 | .Dv NULL , | | 384 | .Dv NULL , |
379 | .Fn vmem_xalloc | | 385 | .Fn vmem_xalloc |
380 | overwrites it with the start address of the allocated span. | | 386 | overwrites it with the start address of the allocated span. |
381 | .El | | 387 | .El |
382 | .Pp | | 388 | .Pp |
383 | .\" ------------------------------------------------------------ | | 389 | .\" ------------------------------------------------------------ |
384 | .Fn vmem_xfree | | 390 | .Fn vmem_xfree |
385 | frees resource allocated by | | 391 | frees resource allocated by |
386 | .Fn vmem_xalloc | | 392 | .Fn vmem_xalloc |
387 | to the arena. | | 393 | to the arena. |
388 | .Pp | | 394 | .Pp |
389 | .Bl -tag -width addr | | 395 | .Bl -tag -offset indent -width addr |
390 | .It Fa vm | | 396 | .It Fa vm |
391 | The arena which we free to. | | 397 | The arena which we free to. |
392 | .It Fa addr | | 398 | .It Fa addr |
393 | The resource being freed. | | 399 | The resource being freed. |
394 | It must be the one returned by | | 400 | It must have been allocated via |
395 | .Fn vmem_xalloc . | | 401 | .Fn vmem_xalloc . |
396 | Notably, it must not be the one from | | 402 | Notably, it must not have been allocated via |
397 | .Fn vmem_alloc . | | 403 | .Fn vmem_alloc . |
398 | Otherwise, the behaviour is undefined. | | 404 | Otherwise, the behaviour is undefined. |
399 | .It Fa size | | 405 | .It Fa size |
400 | The size of the resource being freed. | | 406 | The size of the resource being freed. |
401 | It must be the same as the | | 407 | It must be the same as the |
402 | .Fa size | | 408 | .Fa size |
403 | argument used for | | 409 | argument used for |
404 | .Fn vmem_xalloc . | | 410 | .Fn vmem_xalloc . |
405 | .El | | 411 | .El |
406 | .Pp | | 412 | .Pp |
407 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 413 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
408 | .Fn vmem_alloc | | 414 | .Fn vmem_alloc |
409 | allocates a resource from the arena. | | 415 | allocates a resource from the arena. |
410 | .Pp | | 416 | .Pp |
411 | .Bl -tag -width flags | | 417 | .Bl -tag -offset indent -width flags |
412 | .It Fa vm | | 418 | .It Fa vm |
413 | The arena which we allocate from. | | 419 | The arena which we allocate from. |
414 | .It Fa size | | 420 | .It Fa size |
415 | Specify the size of the allocation. | | 421 | Specify the size of the allocation. |
416 | .It Fa flags | | 422 | .It Fa flags |
417 | A bitwise OR of an allocation strategy and a sleep flag. | | 423 | A bitwise OR of an allocation strategy and a sleep flag. |
418 | .Pp | | 424 | .Pp |
419 | The allocation strategy is one of: | | 425 | The allocation strategy must be one of: |
420 | .Bl -tag -width VM_INSTANTFIT | | 426 | .Bl -tag -width VM_INSTANTFIT |
421 | .It Dv VM_BESTFIT | | 427 | .It Dv VM_BESTFIT |
422 | Prefer space efficiency. | | 428 | Prefer space efficiency. |
423 | .It Dv VM_INSTANTFIT | | 429 | .It Dv VM_INSTANTFIT |
424 | Prefer performance. | | 430 | Prefer performance. |
425 | .El | | 431 | .El |
426 | .Pp | | 432 | .Pp |
427 | The sleep flag should be one of: | | 433 | The sleep flag must be one of: |
428 | .Bl -tag -width VM_NOSLEEP | | 434 | .Bl -tag -width VM_NOSLEEP |
429 | .It Dv VM_SLEEP | | 435 | .It Dv VM_SLEEP |
430 | Can sleep until enough resources are available. | | 436 | If the allocation cannot be satisfied immediately, sleep until enough |
| | | 437 | resources are available. |
431 | .It Dv VM_NOSLEEP | | 438 | .It Dv VM_NOSLEEP |
432 | Don't sleep. | | 439 | Don't sleep. |
433 | Immediately return | | 440 | Immediately return |
434 | .Dv ENOMEM | | 441 | .Dv ENOMEM |
435 | if there are not enough resources available. | | 442 | if there are not enough resources available. |
436 | .El | | 443 | .El |
437 | .It Fa addrp | | 444 | .It Fa addrp |
438 | On success, if | | 445 | On success, if |
439 | .Fa addrp | | 446 | .Fa addrp |
440 | is not | | 447 | is not |
441 | .Dv NULL , | | 448 | .Dv NULL , |
442 | .Fn vmem_alloc | | 449 | .Fn vmem_alloc |
443 | overwrites it with the start address of the allocated span. | | 450 | overwrites it with the start address of the allocated span. |
444 | .El | | 451 | .El |
445 | .Pp | | 452 | .Pp |
446 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - | | 453 | .\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - |
447 | .Fn vmem_free | | 454 | .Fn vmem_free |
448 | frees resource allocated by | | 455 | frees resource allocated by |
449 | .Fn vmem_alloc | | 456 | .Fn vmem_alloc |
450 | to the arena. | | 457 | to the arena. |
451 | .Pp | | 458 | .Pp |
452 | .Bl -tag -width addr | | 459 | .Bl -tag -offset indent -width addr |
453 | .It Fa vm | | 460 | .It Fa vm |
454 | The arena which we free to. | | 461 | The arena which we free to. |
455 | .It Fa addr | | 462 | .It Fa addr |
456 | The resource being freed. | | 463 | The resource being freed. |
457 | It must be the one returned by | | 464 | It must have been allocated via |
458 | .Fn vmem_alloc . | | 465 | .Fn vmem_alloc . |
459 | Notably, it must not be the one from | | 466 | Notably, it must not have been allocated via |
460 | .Fn vmem_xalloc . | | 467 | .Fn vmem_xalloc . |
461 | Otherwise, the behaviour is undefined. | | 468 | Otherwise, the behaviour is undefined. |
462 | .It Fa size | | 469 | .It Fa size |
463 | The size of the resource being freed. | | 470 | The size of the resource being freed. |
464 | It must be the same as the | | 471 | It must be the same as the |
465 | .Fa size | | 472 | .Fa size |
466 | argument used for | | 473 | argument used for |
467 | .Fn vmem_alloc . | | 474 | .Fn vmem_alloc . |
468 | .El | | 475 | .El |
469 | .Pp | | 476 | .Pp |
470 | .\" ------------------------------------------------------------ | | 477 | .\" ------------------------------------------------------------ |
471 | .Fn vmem_destroy | | 478 | .Fn vmem_destroy |
472 | destroys a vmem arena. | | 479 | destroys a vmem arena. |
473 | .Pp | | 480 | .Pp |
474 | .Bl -tag -width vm | | 481 | .Bl -tag -offset indent -width vm |
475 | .It Fa vm | | 482 | .It Fa vm |
476 | The vmem arena being destroyed. | | 483 | The vmem arena being destroyed. |
477 | The caller should ensure that no one will use it anymore. | | 484 | The caller must ensure that no one will use it anymore. |
478 | .El | | 485 | .El |
479 | .\" ------------------------------------------------------------ | | 486 | .\" ------------------------------------------------------------ |
480 | .Sh RETURN VALUES | | 487 | .Sh RETURN VALUES |
481 | .Fn vmem_create | | 488 | .Fn vmem_create |
482 | return a pointer to the newly allocated vmem_t. | | 489 | return a pointer to the newly allocated vmem_t. |
483 | Otherwise, it returns | | 490 | Otherwise, it returns |
484 | .Dv NULL . | | 491 | .Dv NULL . |
485 | .Pp | | 492 | .Pp |
486 | On success, | | 493 | On success, |
487 | .Fn vmem_xalloc | | 494 | .Fn vmem_xalloc |
488 | and | | 495 | and |
489 | .Fn vmem_alloc | | 496 | .Fn vmem_alloc |
490 | return 0. | | 497 | return 0. |