]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man9/zone.9
MFV r362082:
[FreeBSD/FreeBSD.git] / share / man / man9 / zone.9
1 .\"-
2 .\" Copyright (c) 2001 Dag-Erling Coïdan Smørgrav
3 .\" All rights reserved.
4 .\"
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
7 .\" are met:
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.
13 .\"
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
24 .\" SUCH DAMAGE.
25 .\"
26 .\" $FreeBSD$
27 .\"
28 .Dd February 4, 2020
29 .Dt UMA 9
30 .Os
31 .Sh NAME
32 .Nm UMA
33 .Nd general-purpose kernel object allocator
34 .Sh SYNOPSIS
35 .In sys/param.h
36 .In sys/queue.h
37 .In vm/uma.h
38 .Cd "options UMA_FIRSTTOUCH"
39 .Cd "options UMA_XDOMAIN"
40 .Bd -literal
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,
46     int flags);
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);
51
52 .Ed
53 .Ft uma_zone_t
54 .Fo uma_zcreate
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"
58 .Fc
59 .Ft uma_zone_t
60 .Fo uma_zcache_create
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"
65 .Fc
66 .Ft uma_zone_t
67 .Fo uma_zsecond_create
68 .Fa "char *name"
69 .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini"
70 .Fa "uma_zone_t master"
71 .Fc
72 .Ft void
73 .Fn uma_zdestroy "uma_zone_t zone"
74 .Ft "void *"
75 .Fn uma_zalloc "uma_zone_t zone" "int flags"
76 .Ft "void *"
77 .Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags"
78 .Ft "void *"
79 .Fn uma_zalloc_domain "uma_zone_t zone" "void *arg" "int domain" "int flags"
80 .Ft "void *"
81 .Fn uma_zalloc_pcpu "uma_zone_t zone" "int flags"
82 .Ft "void *"
83 .Fn uma_zalloc_pcpu_arg "uma_zone_t zone" "void *arg" "int flags"
84 .Ft void
85 .Fn uma_zfree "uma_zone_t zone" "void *item"
86 .Ft void
87 .Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg"
88 .Ft void
89 .Fn uma_zfree_domain "uma_zone_t zone" "void *item" "void *arg"
90 .Ft void
91 .Fn uma_zfree_pcpu "uma_zone_t zone" "void *item"
92 .Ft void
93 .Fn uma_zfree_pcpu_arg "uma_zone_t zone" "void *item" "void *arg"
94 .Ft void
95 .Fn uma_prealloc "uma_zone_t zone" "int nitems"
96 .Ft void
97 .Fn uma_zone_reserve "uma_zone_t zone" "int nitems"
98 .Ft void
99 .Fn uma_zone_reserve_kva "uma_zone_t zone" "int nitems"
100 .Ft void
101 .Fn uma_reclaim "int req"
102 .Ft void
103 .Fn uma_zone_reclaim "uma_zone_t zone" "int req"
104 .Ft void
105 .Fn uma_zone_set_allocf "uma_zone_t zone" "uma_alloc allocf"
106 .Ft void
107 .Fn uma_zone_set_freef "uma_zone_t zone" "uma_free freef"
108 .Ft int
109 .Fn uma_zone_set_max "uma_zone_t zone" "int nitems"
110 .Ft void
111 .Fn uma_zone_set_maxcache "uma_zone_t zone" "int nitems"
112 .Ft int
113 .Fn uma_zone_get_max "uma_zone_t zone"
114 .Ft int
115 .Fn uma_zone_get_cur "uma_zone_t zone"
116 .Ft void
117 .Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning"
118 .Ft void
119 .Fn uma_zone_set_maxaction "uma_zone_t zone" "void (*maxaction)(uma_zone_t)"
120 .Ft void
121 .Fn uma_reclaim
122 .In sys/sysctl.h
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
127 .Sh DESCRIPTION
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
135 systems.
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.
139 .Pp
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
143 page allocator.
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
147 multiple zones.
148 .Pp
149 Normal zones import items from a keg, and release items back to that keg if
150 requested.
151 Cache zones do not have a keg, and instead use custom import and release
152 methods.
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
156 such a collection.
157 .Pp
158 The
159 .Fn uma_zcreate
160 and
161 .Fn uma_zcache_create
162 functions create a new regular zone and cache zone, respectively.
163 The
164 .Fn uma_zsecond_create
165 function creates a regular zone which shares the keg of the zone
166 specified by the
167 .Fa master
168 argument.
169 The
170 .Fa name
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.
173 .Pp
174 The
175 .Fa ctor
176 and
177 .Fa dtor
178 arguments are callback functions that are called by
179 the UMA subsystem at the time of the call to
180 .Fn uma_zalloc
181 and
182 .Fn uma_zfree
183 respectively.
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.
187 A good usage for the
188 .Fa ctor
189 and
190 .Fa dtor
191 callbacks might be to initialize a data structure embedded in the item,
192 such as a
193 .Xr queue 3
194 head.
195 .Pp
196 The
197 .Fa zinit
198 and
199 .Fa zfini
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.
203 A good use for the
204 .Fa zinit
205 and
206 .Fa zfini
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
212 .Fn uma_zalloc
213 and
214 .Fn uma_zfree
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
217 pressure.
218 .Pp
219 For
220 .Fn uma_zcache_create ,
221 the
222 .Fa zimport
223 and
224 .Fa zrelease
225 functions are called to import items into the zone and to release items
226 from the zone, respectively.
227 The
228 .Fa zimport
229 function should store pointers to items in the
230 .Fa store
231 array, which contains a maximum of
232 .Fa count
233 entries.
234 The function must return the number of imported items, which may be less than
235 the maximum.
236 Similarly, the
237 .Fa store
238 parameter to the
239 .Fa zrelease
240 function contains an array of
241 .Fa count
242 pointers to items.
243 The
244 .Fa arg
245 parameter passed to
246 .Fn uma_zcache_create
247 is provided to the import and release functions.
248 The
249 .Fa domain
250 parameter to
251 .Fa zimport
252 specifies the requested
253 .Xr numa 4
254 domain for the allocation.
255 It is either a NUMA domain number or the special value
256 .Dv UMA_ANYDOMAIN .
257 .Pp
258 The
259 .Fa flags
260 argument of
261 .Fn uma_zcreate
262 and
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.
270 .It Dv UMA_ZONE_PCPU
271 An allocation from zone would have
272 .Va mp_ncpu
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);
279  ...
280 foo_base = uma_zalloc(foo_zone, ...);
281  ...
282 critical_enter();
283 foo_pcpu = (foo_t *)zpcpu_get(foo_base);
284 /* do something with foo_pcpu */
285 critical_exit();
286
287 .Ed
288 Note that
289 .Dv M_ZERO
290 cannot be used when allocating items from a PCPU zone.
291 To obtain zeroed memory from a PCPU zone, use the
292 .Fn uma_zalloc_pcpu
293 function and its variants instead, and pass
294 .Dv M_ZERO .
295 .It Dv UMA_ZONE_NOTOUCH
296 The UMA subsystem may not directly touch (i.e. read or write) the slab memory.
297 Otherwise, by default, book-keeping of items within a slab may be done in the
298 slab page itself, and
299 .Dv INVARIANTS
300 kernels may also do use-after-free checking by accessing the slab memory.
301 .It Dv UMA_ZONE_ZINIT
302 The zone will have its
303 .Ft uma_init
304 method set to internal method that initializes a new allocated slab
305 to all zeros.
306 Do not mistake
307 .Ft uma_init
308 method with
309 .Ft uma_ctor .
310 A zone with
311 .Dv UMA_ZONE_ZINIT
312 flag would not return zeroed memory on every
313 .Fn uma_zalloc .
314 .It Dv UMA_ZONE_NOTPAGE
315 An allocator function will be supplied with
316 .Fn uma_zone_set_allocf
317 and the memory that it returns may not be kernel virtual memory backed by VM
318 pages in the page array.
319 .It Dv UMA_ZONE_MALLOC
320 The zone is for the
321 .Xr malloc 9
322 subsystem.
323 .It Dv UMA_ZONE_VM
324 The zone is for the VM subsystem.
325 .It Dv UMA_ZONE_NUMA
326 The zone should use a first-touch NUMA policy rather than the round-robin
327 default.
328 If the
329 .Dv UMA_FIRSTTOUCH
330 kernel option is configured, all zones implicitly use a first-touch policy,
331 and the
332 .Dv UMA_ZONE_NUMA
333 flag has no effect.
334 The
335 .Dv UMA_XDOMAIN
336 kernel option, when configured, causes UMA to do the extra tracking to ensure
337 that allocations from first-touch zones are always local.
338 Otherwise, consumers that do not free memory on the same domain from which it
339 was allocated will cause mixing in per-CPU caches.
340 See
341 .Xr numa 4
342 for more details.
343 .It Dv UMA_ZONE_CONTIG
344 Items in this zone must be contiguous in physical address space.
345 Items will follow normal alignment constraints and may span page boundaries
346 between pages with contiguous physical addresses.
347 .El
348 .Pp
349 Zones can be destroyed using
350 .Fn uma_zdestroy ,
351 freeing all memory that is cached in the zone.
352 All items allocated from the zone must be freed to the zone before the zone
353 may be safely destroyed.
354 .Pp
355 To allocate an item from a zone, simply call
356 .Fn uma_zalloc
357 with a pointer to that zone and set the
358 .Fa flags
359 argument to selected flags as documented in
360 .Xr malloc 9 .
361 It will return a pointer to an item if successful, or
362 .Dv NULL
363 in the rare case where all items in the zone are in use and the
364 allocator is unable to grow the zone and
365 .Dv M_NOWAIT
366 is specified.
367 .Pp
368 Items are released back to the zone from which they were allocated by
369 calling
370 .Fn uma_zfree
371 with a pointer to the zone and a pointer to the item.
372 If
373 .Fa item
374 is
375 .Dv NULL ,
376 then
377 .Fn uma_zfree
378 does nothing.
379 .Pp
380 The variants
381 .Fn uma_zalloc_arg
382 and
383 .Fn uma_zfree_arg
384 allow callers to
385 specify an argument for the
386 .Dv ctor
387 and
388 .Dv dtor
389 functions of the zone, respectively.
390 The
391 .Fn uma_zalloc_domain
392 function allows callers to specify a fixed
393 .Xr numa 4
394 domain to allocate from.
395 This uses a guaranteed but slow path in the allocator which reduces
396 concurrency.
397 The
398 .Fn uma_zfree_domain
399 function should be used to return memory allocated in this fashion.
400 This function infers the domain from the pointer and does not require it as an
401 argument.
402 .Pp
403 The
404 .Fn uma_zone_prealloc
405 function allocates slabs for the requested number of items, typically following
406 the initial creation of a zone.
407 Subsequent allocations from the zone will be satisfied using the pre-allocated
408 slabs.
409 Note that slab allocation is performed with the
410 .Dv M_WAITOK
411 flag, so
412 .Fn uma_zone_prealloc
413 may sleep.
414 .Pp
415 The
416 .Fn uma_zone_reserve
417 function sets the number of reserved items for the zone.
418 .Fn uma_zalloc
419 and variants will ensure that the zone contains at least the reserved number
420 of free items.
421 Reserved items may be allocated by specifying
422 .Dv M_USE_RESERVE
423 in the allocation request flags.
424 .Fn uma_zone_reserve
425 does not perform any pre-allocation by itself.
426 .Pp
427 The
428 .Fn uma_zone_reserve_kva
429 function pre-allocates kernel virtual address space for the requested
430 number of items.
431 Subsequent allocations from the zone will be satisfied using the pre-allocated
432 address space.
433 Note that unlike
434 .Fn uma_zone_reserve ,
435 .Fn uma_zone_reserve_kva
436 does not restrict the use of the pre-allocation to
437 .Dv M_USE_RESERVE
438 requests.
439 .Pp
440 The
441 .Fn uma_reclaim
442 and
443 .Fn uma_zone_reclaim
444 functions reclaim cached items from UMA zones, releasing unused memory.
445 The
446 .Fn uma_reclaim
447 function reclaims items from all regular zones, while
448 .Fn uma_zone_reclaim
449 reclaims items only from the specified zone.
450 The
451 .Fa req
452 parameter must be one of three values which specify how aggressively
453 items are to be reclaimed:
454 .Bl -tag -width indent
455 .It Dv UMA_RECLAIM_TRIM
456 Reclaim items only in excess of the zone's estimated working set size.
457 The working set size is periodically updated and tracks the recent history
458 of the zone's usage.
459 .It Dv UMA_RECLAIM_DRAIN
460 Reclaim all items from the unbounded cache.
461 Free items in the per-CPU caches are left alone.
462 .It Dv UMA_RECLAIM_DRAIN_CPU
463 Reclaim all cached items.
464 .El
465 .Pp
466 The
467 .Fn uma_zone_set_allocf
468 and
469 .Fn uma_zone_set_freef
470 functions allow a zone's default slab allocation and free functions to be
471 overridden.
472 This is useful if memory with special constraints such as attributes,
473 alignment, or address ranges must be used.
474 .Pp
475 The
476 .Fn uma_zone_set_max
477 function limits the number of items
478 .Pq and therefore memory
479 that can be allocated to
480 .Fa zone .
481 The
482 .Fa nitems
483 argument specifies the requested upper limit number of items.
484 The effective limit is returned to the caller, as it may end up being higher
485 than requested due to the implementation rounding up to ensure all memory pages
486 allocated to the zone are utilised to capacity.
487 The limit applies to the total number of items in the zone, which includes
488 allocated items, free items and free items in the per-cpu caches.
489 On systems with more than one CPU it may not be possible to allocate
490 the specified number of items even when there is no shortage of memory,
491 because all of the remaining free items may be in the caches of the
492 other CPUs when the limit is hit.
493 .Pp
494 The
495 .Fn uma_zone_set_maxcache
496 function limits the number of free items which may be cached in the zone.
497 This limit applies to both the per-CPU caches and the cache of free buckets.
498 .Pp
499 The
500 .Fn uma_zone_get_max
501 function returns the effective upper limit number of items for a zone.
502 .Pp
503 The
504 .Fn uma_zone_get_cur
505 function returns an approximation of the number of items currently allocated
506 from the zone.
507 The returned value is approximate because appropriate synchronisation to
508 determine an exact value is not performed by the implementation.
509 This ensures low overhead at the expense of potentially stale data being used
510 in the calculation.
511 .Pp
512 The
513 .Fn uma_zone_set_warning
514 function sets a warning that will be printed on the system console when the
515 given zone becomes full and fails to allocate an item.
516 The warning will be printed no more often than every five minutes.
517 Warnings can be turned off globally by setting the
518 .Va vm.zone_warnings
519 sysctl tunable to
520 .Va 0 .
521 .Pp
522 The
523 .Fn uma_zone_set_maxaction
524 function sets a function that will be called when the given zone becomes full
525 and fails to allocate an item.
526 The function will be called with the zone locked.
527 Also, the function
528 that called the allocation function may have held additional locks.
529 Therefore,
530 this function should do very little work (similar to a signal handler).
531 .Pp
532 The
533 .Fn SYSCTL_UMA_MAX parent nbr name access zone descr
534 macro declares a static
535 .Xr sysctl 9
536 oid that exports the effective upper limit number of items for a zone.
537 The
538 .Fa zone
539 argument should be a pointer to
540 .Vt uma_zone_t .
541 A read of the oid returns value obtained through
542 .Fn uma_zone_get_max .
543 A write to the oid sets new value via
544 .Fn uma_zone_set_max .
545 The
546 .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr
547 macro is provided to create this type of oid dynamically.
548 .Pp
549 The
550 .Fn SYSCTL_UMA_CUR parent nbr name access zone descr
551 macro declares a static read-only
552 .Xr sysctl 9
553 oid that exports the approximate current occupancy of the zone.
554 The
555 .Fa zone
556 argument should be a pointer to
557 .Vt uma_zone_t .
558 A read of the oid returns value obtained through
559 .Fn uma_zone_get_cur .
560 The
561 .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name zone descr
562 macro is provided to create this type of oid dynamically.
563 .Sh IMPLEMENTATION NOTES
564 The memory that these allocation calls return is not executable.
565 The
566 .Fn uma_zalloc
567 function does not support the
568 .Dv M_EXEC
569 flag to allocate executable memory.
570 Not all platforms enforce a distinction between executable and
571 non-executable memory.
572 .Sh SEE ALSO
573 .Xr numa 4 ,
574 .Xr vmstat 8 ,
575 .Xr malloc 9
576 .Rs
577 .%A Jeff Bonwick
578 .%T "The Slab Allocator: An Object-Caching Kernel Memory Allocator"
579 .%D 1994
580 .Re
581 .Sh HISTORY
582 The zone allocator first appeared in
583 .Fx 3.0 .
584 It was radically changed in
585 .Fx 5.0
586 to function as a slab allocator.
587 .Sh AUTHORS
588 .An -nosplit
589 The zone allocator was written by
590 .An John S. Dyson .
591 The zone allocator was rewritten in large parts by
592 .An Jeff Roberson Aq Mt jeff@FreeBSD.org
593 to function as a slab allocator.
594 .Pp
595 This manual page was written by
596 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
597 Changes for UMA by
598 .An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org .