2 .\" Copyright (c) 2001 Dag-Erling Coïdan Smørgrav
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .Nd general-purpose kernel object allocator
38 .Cd "options UMA_FIRSTTOUCH"
39 .Cd "options UMA_XDOMAIN"
41 typedef int (*uma_ctor)(void *mem, int size, void *arg, int flags);
42 typedef void (*uma_dtor)(void *mem, int size, void *arg);
43 typedef int (*uma_init)(void *mem, int size, int flags);
44 typedef void (*uma_fini)(void *mem, int size);
45 typedef int (*uma_import)(void *arg, void **store, int count, int domain,
47 typedef void (*uma_release)(void *arg, void **store, int count);
48 typedef void *(*uma_alloc)(uma_zone_t zone, vm_size_t size, int domain,
49 uint8_t *pflag, int wait);
50 typedef void (*uma_free)(void *item, vm_size_t size, uint8_t pflag);
55 .Fa "char *name" "int size"
56 .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini"
57 .Fa "int align" "uint16_t flags"
61 .Fa "char *name" "int size"
62 .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini"
63 .Fa "uma_import zimport" "uma_release zrelease"
64 .Fa "void *arg" "int flags"
67 .Fo uma_zsecond_create
69 .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini"
70 .Fa "uma_zone_t master"
73 .Fn uma_zdestroy "uma_zone_t zone"
75 .Fn uma_zalloc "uma_zone_t zone" "int flags"
77 .Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags"
79 .Fn uma_zalloc_domain "uma_zone_t zone" "void *arg" "int domain" "int flags"
81 .Fn uma_zalloc_pcpu "uma_zone_t zone" "int flags"
83 .Fn uma_zalloc_pcpu_arg "uma_zone_t zone" "void *arg" "int flags"
85 .Fn uma_zfree "uma_zone_t zone" "void *item"
87 .Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg"
89 .Fn uma_zfree_domain "uma_zone_t zone" "void *item" "void *arg"
91 .Fn uma_zfree_pcpu "uma_zone_t zone" "void *item"
93 .Fn uma_zfree_pcpu_arg "uma_zone_t zone" "void *item" "void *arg"
95 .Fn uma_prealloc "uma_zone_t zone" "int nitems"
97 .Fn uma_zone_reserve "uma_zone_t zone" "int nitems"
99 .Fn uma_zone_reserve_kva "uma_zone_t zone" "int nitems"
101 .Fn uma_reclaim "int req"
103 .Fn uma_zone_reclaim "uma_zone_t zone" "int req"
105 .Fn uma_zone_set_allocf "uma_zone_t zone" "uma_alloc allocf"
107 .Fn uma_zone_set_freef "uma_zone_t zone" "uma_free freef"
109 .Fn uma_zone_set_max "uma_zone_t zone" "int nitems"
111 .Fn uma_zone_set_maxcache "uma_zone_t zone" "int nitems"
113 .Fn uma_zone_get_max "uma_zone_t zone"
115 .Fn uma_zone_get_cur "uma_zone_t zone"
117 .Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning"
119 .Fn uma_zone_set_maxaction "uma_zone_t zone" "void (*maxaction)(uma_zone_t)"
123 .Fn SYSCTL_UMA_MAX parent nbr name access zone descr
124 .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr
125 .Fn SYSCTL_UMA_CUR parent nbr name access zone descr
126 .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name access zone descr
128 UMA (Universal Memory Allocator) provides an efficient interface for managing
129 dynamically-sized collections of items of identical size, referred to as zones.
130 Zones keep track of which items are in use and which
131 are not, and UMA provides functions for allocating items from a zone and
132 for releasing them back, making them available for subsequent allocation requests.
133 Zones maintain per-CPU caches with linear scalability on SMP
134 systems as well as round-robin and first-touch policies for NUMA
136 The number of items cached per CPU is bounded, and each zone additionally
137 maintains an unbounded cache of items that is used to quickly satisfy
138 per-CPU cache allocation misses.
140 Two types of zones exist: regular zones and cache zones.
141 In a regular zone, items are allocated from a slab, which is one or more
142 virtually contiguous memory pages that have been allocated from the kernel's
144 Internally, slabs are managed by a UMA keg, which is responsible for allocating
145 slabs and keeping track of their usage by one or more zones.
146 In typical usage, there is one keg per zone, so slabs are not shared among
149 Normal zones import items from a keg, and release items back to that keg if
151 Cache zones do not have a keg, and instead use custom import and release
153 For example, some collections of kernel objects are statically allocated
154 at boot-time, and the size of the collection does not change.
155 A cache zone can be used to implement an efficient allocator for the objects in
161 .Fn uma_zcache_create
162 functions create a new regular zone and cache zone, respectively.
164 .Fn uma_zsecond_create
165 function creates a regular zone which shares the keg of the zone
171 argument is a text name of the zone for debugging and stats; this memory
172 should not be freed until the zone has been deallocated.
178 arguments are callback functions that are called by
179 the UMA subsystem at the time of the call to
184 Their purpose is to provide hooks for initializing or
185 destroying things that need to be done at the time of the allocation
186 or release of a resource.
191 callbacks might be to initialize a data structure embedded in the item,
200 arguments are used to optimize the allocation of items from the zone.
201 They are called by the UMA subsystem whenever
202 it needs to allocate or free items to satisfy requests or memory pressure.
207 callbacks might be to
208 initialize and destroy a mutex contained within an item.
209 This would allow one to avoid destroying and re-initializing the mutex
210 each time the item is freed and re-allocated.
211 They are not called on each call to
215 but rather when an item is imported into a zone's cache, and when a zone
216 releases an item to the slab allocator, typically as a response to memory
220 .Fn uma_zcache_create ,
225 functions are called to import items into the zone and to release items
226 from the zone, respectively.
229 function should store pointers to items in the
231 array, which contains a maximum of
234 The function must return the number of imported items, which may be less than
240 function contains an array of
246 .Fn uma_zcache_create
247 is provided to the import and release functions.
252 specifies the requested
254 domain for the allocation.
255 It is either a NUMA domain number or the special value
263 .Fn uma_zcache_create
264 is a subset of the following flags:
265 .Bl -tag -width "foo"
266 .It Dv UMA_ZONE_NOFREE
267 Slabs allocated to the zone's keg are never freed.
268 .It Dv UMA_ZONE_NODUMP
269 Pages belonging to the zone will not be included in minidumps.
271 An allocation from zone would have
273 shadow copies, that are privately assigned to CPUs.
274 A CPU can address its private copy using base the allocation address plus
275 a multiple of the current CPU ID and
276 .Fn sizeof "struct pcpu" :
277 .Bd -literal -offset indent
278 foo_zone = uma_zcreate(..., UMA_ZONE_PCPU);
280 foo_base = uma_zalloc(foo_zone, ...);
283 foo_pcpu = (foo_t *)zpcpu_get(foo_base);
284 /* do something with foo_pcpu */
290 cannot be used when allocating items from a PCPU zone.
291 To obtain zeroed memory from a PCPU zone, use the
293 function and its variants instead, and pass
295 .It Dv UMA_ZONE_OFFPAGE
296 By default book-keeping of items within a slab is done in the slab page itself.
297 This flag explicitly tells subsystem that book-keeping structure should be
298 allocated separately from special internal zone.
299 This flag requires either
303 since subsystem requires a mechanism to find a book-keeping structure
304 to an item being freed.
305 The subsystem may choose to prefer offpage book-keeping for certain zones
307 .It Dv UMA_ZONE_ZINIT
308 The zone will have its
310 method set to internal method that initializes a new allocated slab
318 flag would not return zeroed memory on every
321 The zone should use an internal hash table to find slab book-keeping
322 structure where an allocation being freed belongs to.
323 .It Dv UMA_ZONE_VTOSLAB
324 The zone should use special field of
326 to find slab book-keeping structure where an allocation being freed belongs to.
327 .It Dv UMA_ZONE_MALLOC
332 The zone is for the VM subsystem.
334 The zone should use a first-touch NUMA policy rather than the round-robin
338 kernel option is configured, all zones implicitly use a first-touch policy,
344 kernel option, when configured, causes UMA to do the extra tracking to ensure
345 that allocations from first-touch zones are always local.
346 Otherwise, consumers that do not free memory on the same domain from which it
347 was allocated will cause mixing in per-CPU caches.
353 Zones can be destroyed using
355 freeing all memory that is cached in the zone.
356 All items allocated from the zone must be freed to the zone before the zone
357 may be safely destroyed.
359 To allocate an item from a zone, simply call
361 with a pointer to that zone and set the
363 argument to selected flags as documented in
365 It will return a pointer to an item if successful, or
367 in the rare case where all items in the zone are in use and the
368 allocator is unable to grow the zone and
372 Items are released back to the zone from which they were allocated by
375 with a pointer to the zone and a pointer to the item.
389 specify an argument for the
393 functions of the zone, respectively.
395 .Fn uma_zalloc_domain
396 function allows callers to specify a fixed
398 domain to allocate from.
399 This uses a guaranteed but slow path in the allocator which reduces
403 function should be used to return memory allocated in this fashion.
404 This function infers the domain from the pointer and does not require it as an
408 .Fn uma_zone_prealloc
409 function allocates slabs for the requested number of items, typically following
410 the initial creation of a zone.
411 Subsequent allocations from the zone will be satisfied using the pre-allocated
413 Note that slab allocation is performed with the
416 .Fn uma_zone_prealloc
421 function sets the number of reserved items for the zone.
423 and variants will ensure that the zone contains at least the reserved number
425 Reserved items may be allocated by specifying
427 in the allocation request flags.
429 does not perform any pre-allocation by itself.
432 .Fn uma_zone_reserve_kva
433 function pre-allocates kernel virtual address space for the requested
435 Subsequent allocations from the zone will be satisfied using the pre-allocated
438 .Fn uma_zone_reserve ,
439 .Fn uma_zone_reserve_kva
440 does not restrict the use of the pre-allocation to
448 functions reclaim cached items from UMA zones, releasing unused memory.
451 function reclaims items from all regular zones, while
453 reclaims items only from the specified zone.
456 parameter must be one of three values which specify how aggressively
457 items are to be reclaimed:
458 .Bl -tag -width indent
459 .It Dv UMA_RECLAIM_TRIM
460 Reclaim items only in excess of the zone's estimated working set size.
461 The working set size is periodically updated and tracks the recent history
463 .It Dv UMA_RECLAIM_DRAIN
464 Reclaim all items from the unbounded cache.
465 Free items in the per-CPU caches are left alone.
466 .It Dv UMA_RECLAIM_DRAIN_CPU
467 Reclaim all cached items.
471 .Fn uma_zone_set_allocf
473 .Fn uma_zone_set_freef
474 functions allow a zone's default slab allocation and free functions to be
476 This is useful if the zone's items have special memory allocation constraints.
477 For example, if multi-page objects are required to be physically contiguous,
480 function which requests contiguous memory from the kernel's page allocator
485 function limits the number of items
486 .Pq and therefore memory
487 that can be allocated to
491 argument specifies the requested upper limit number of items.
492 The effective limit is returned to the caller, as it may end up being higher
493 than requested due to the implementation rounding up to ensure all memory pages
494 allocated to the zone are utilised to capacity.
495 The limit applies to the total number of items in the zone, which includes
496 allocated items, free items and free items in the per-cpu caches.
497 On systems with more than one CPU it may not be possible to allocate
498 the specified number of items even when there is no shortage of memory,
499 because all of the remaining free items may be in the caches of the
500 other CPUs when the limit is hit.
503 .Fn uma_zone_set_maxcache
504 function limits the number of free items which may be cached in the zone,
505 excluding the per-CPU caches, which are bounded in size.
506 For example, to implement a
508 per-CPU cache, a cache zone may be configured with a maximum cache size of 0.
512 function returns the effective upper limit number of items for a zone.
516 function returns an approximation of the number of items currently allocated
518 The returned value is approximate because appropriate synchronisation to
519 determine an exact value is not performed by the implementation.
520 This ensures low overhead at the expense of potentially stale data being used
524 .Fn uma_zone_set_warning
525 function sets a warning that will be printed on the system console when the
526 given zone becomes full and fails to allocate an item.
527 The warning will be printed no more often than every five minutes.
528 Warnings can be turned off globally by setting the
534 .Fn uma_zone_set_maxaction
535 function sets a function that will be called when the given zone becomes full
536 and fails to allocate an item.
537 The function will be called with the zone locked.
539 that called the allocation function may have held additional locks.
541 this function should do very little work (similar to a signal handler).
544 .Fn SYSCTL_UMA_MAX parent nbr name access zone descr
545 macro declares a static
547 oid that exports the effective upper limit number of items for a zone.
550 argument should be a pointer to
552 A read of the oid returns value obtained through
553 .Fn uma_zone_get_max .
554 A write to the oid sets new value via
555 .Fn uma_zone_set_max .
557 .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr
558 macro is provided to create this type of oid dynamically.
561 .Fn SYSCTL_UMA_CUR parent nbr name access zone descr
562 macro declares a static read-only
564 oid that exports the approximate current occupancy of the zone.
567 argument should be a pointer to
569 A read of the oid returns value obtained through
570 .Fn uma_zone_get_cur .
572 .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name zone descr
573 macro is provided to create this type of oid dynamically.
574 .Sh IMPLEMENTATION NOTES
575 The memory that these allocation calls return is not executable.
578 function does not support the
580 flag to allocate executable memory.
581 Not all platforms enforce a distinction between executable and
582 non-executable memory.
589 .%T "The Slab Allocator: An Object-Caching Kernel Memory Allocator"
593 The zone allocator first appeared in
595 It was radically changed in
597 to function as a slab allocator.
600 The zone allocator was written by
602 The zone allocator was rewritten in large parts by
603 .An Jeff Roberson Aq Mt jeff@FreeBSD.org
604 to function as a slab allocator.
606 This manual page was written by
607 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
609 .An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org .