xref: /freebsd/share/man/man9/zone.9 (revision 03836978bec158bdc0ecee7a4198962f91ce8298)
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 March 21, 2013
29.Dt ZONE 9
30.Os
31.Sh NAME
32.Nm uma_zcreate ,
33.Nm uma_zalloc ,
34.Nm uma_zalloc_arg ,
35.Nm uma_zfree ,
36.Nm uma_zfree_arg ,
37.Nm uma_find_refcnt ,
38.Nm uma_zdestroy ,
39.Nm uma_zone_set_max,
40.Nm uma_zone_get_max,
41.Nm uma_zone_get_cur,
42.Nm uma_zone_set_warning
43.Nd zone allocator
44.Sh SYNOPSIS
45.In sys/param.h
46.In sys/queue.h
47.In vm/uma.h
48.Ft uma_zone_t
49.Fo uma_zcreate
50.Fa "char *name" "int size"
51.Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini"
52.Fa "int align" "uint16_t flags"
53.Fc
54.Ft "void *"
55.Fn uma_zalloc "uma_zone_t zone" "int flags"
56.Ft "void *"
57.Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags"
58.Ft void
59.Fn uma_zfree "uma_zone_t zone" "void *item"
60.Ft void
61.Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg"
62.Ft "uint32_t *"
63.Fn uma_find_refcnt "uma_zone_t zone" "void *item"
64.Ft void
65.Fn uma_zdestroy "uma_zone_t zone"
66.Ft int
67.Fn uma_zone_set_max "uma_zone_t zone" "int nitems"
68.Ft int
69.Fn uma_zone_get_max "uma_zone_t zone"
70.Ft int
71.Fn uma_zone_get_cur "uma_zone_t zone"
72.Ft void
73.Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning"
74.Sh DESCRIPTION
75The zone allocator provides an efficient interface for managing
76dynamically-sized collections of items of similar size.
77The zone allocator can work with preallocated zones as well as with
78runtime-allocated ones, and is therefore available much earlier in the
79boot process than other memory management routines.
80.Pp
81A zone is an extensible collection of items of identical size.
82The zone allocator keeps track of which items are in use and which
83are not, and provides functions for allocating items from the zone and
84for releasing them back (which makes them available for later use).
85.Pp
86After the first allocation of an item,
87it will have been cleared to zeroes, however subsequent allocations
88will retain the contents as of the last free.
89.Pp
90The
91.Fn uma_zcreate
92function creates a new zone from which items may then be allocated from.
93The
94.Fa name
95argument is a text name of the zone for debugging and stats; this memory
96should not be freed until the zone has been deallocated.
97.Pp
98The
99.Fa ctor
100and
101.Fa dtor
102arguments are callback functions that are called by
103the uma subsystem at the time of the call to
104.Fn uma_zalloc
105and
106.Fn uma_zfree
107respectively.
108Their purpose is to provide hooks for initializing or
109destroying things that need to be done at the time of the allocation
110or release of a resource.
111A good usage for the
112.Fa ctor
113and
114.Fa dtor
115callbacks
116might be to adjust a global count of the number of objects allocated.
117.Pp
118The
119.Fa uminit
120and
121.Fa fini
122arguments are used to optimize the allocation of
123objects from the zone.
124They are called by the uma subsystem whenever
125it needs to allocate or free several items to satisfy requests or memory
126pressure.
127A good use for the
128.Fa uminit
129and
130.Fa fini
131callbacks might be to
132initialize and destroy mutexes contained within the object.
133This would
134allow one to re-use already initialized mutexes when an object is returned
135from the uma subsystem's object cache.
136They are not called on each call to
137.Fn uma_zalloc
138and
139.Fn uma_zfree
140but rather in a batch mode on several objects.
141.Pp
142The
143.Fa flags
144argument of the
145.Fn uma_zcreate
146is a subset of the following flags:
147.Bl -tag -width "foo"
148.It Dv UMA_ZONE_NOFREE
149Slabs of the zone are never returned back to VM.
150.It Dv UMA_ZONE_REFCNT
151Each item in the zone would have internal reference counter associated with it.
152See
153.Fn uma_find_refcnt .
154.It Dv UMA_ZONE_NODUMP
155Pages belonging to the zone will not be included into mini-dumps.
156.It Dv UMA_ZONE_PCPU
157An allocation from zone would have
158.Va mp_ncpu
159shadow copies, that are privately assigned to CPUs.
160A CPU can address its private copy using base allocation address plus
161multiple of current CPU id and
162.Fn sizeof "struct pcpu" :
163.Bd -literal -offset indent
164foo_zone = uma_zcreate(..., UMA_ZONE_PCPU);
165 ...
166foo_base = uma_zalloc(foo_zone, ...);
167 ...
168critical_enter();
169foo_pcpu = (foo_t *)zpcpu_get(foo_base);
170/* do something with foo_pcpu */
171critical_exit();
172.Ed
173.It Dv UMA_ZONE_OFFPAGE
174By default book-keeping of items within a slab is done in the slab page itself.
175This flag explicitly tells subsystem that book-keeping structure should be
176allocated separately from special internal zone.
177This flag requires either
178.Dv UMA_ZONE_VTOSLAB
179or
180.Dv UMA_ZONE_HASH ,
181since subsystem requires a mechanism to find a book-keeping structure
182to an item beeing freed.
183The subsystem may choose to prefer offpage book-keeping for certain zones
184implicitly.
185.It Dv UMA_ZONE_ZINIT
186The zone will have its
187.Ft uma_init
188method set to internal method that initializes a new allocated slab
189to all zeros.
190Do not mistake
191.Ft uma_init
192method with
193.Ft uma_ctor .
194A zone with
195.Dv UMA_ZONE_ZINIT
196flag would not return zeroed memory on every
197.Fn uma_zalloc .
198.It Dv UMA_ZONE_HASH
199The zone should use an internal hash table to find slab book-keeping
200structure where an allocation being freed belongs to.
201.It Dv UMA_ZONE_VTOSLAB
202The zone should use special field of
203.Vt vm_page_t
204to find slab book-keeping structure where an allocation being freed belongs to.
205.It Dv UMA_ZONE_MALLOC
206The zone is for the
207.Xr malloc 9
208subsystem.
209.It Dv UMA_ZONE_VM
210The zone is for the VM subsystem.
211.El
212.Pp
213To allocate an item from a zone, simply call
214.Fn uma_zalloc
215with a pointer to that zone
216and set the
217.Fa flags
218argument to selected flags as documented in
219.Xr malloc 9 .
220It will return a pointer to an item if successful,
221or
222.Dv NULL
223in the rare case where all items in the zone are in use and the
224allocator is unable to grow the zone
225and
226.Dv M_NOWAIT
227is specified.
228.Pp
229Items are released back to the zone from which they were allocated by
230calling
231.Fn uma_zfree
232with a pointer to the zone and a pointer to the item.
233If
234.Fa item
235is
236.Dv NULL ,
237then
238.Fn uma_zfree
239does nothing.
240.Pp
241The variations
242.Fn uma_zalloc_arg
243and
244.Fn uma_zfree_arg
245allow to
246specify an argument for the
247.Dv ctor
248and
249.Dv dtor
250functions, respectively.
251.Pp
252If zone was created with
253.Dv UMA_ZONE_REFCNT
254flag, then pointer to reference counter for an item can be retrieved with
255help of the
256.Fn uma_find_refcnt
257function.
258.Pp
259Created zones,
260which are empty,
261can be destroyed using
262.Fn uma_zdestroy ,
263freeing all memory that was allocated for the zone.
264All items allocated from the zone with
265.Fn uma_zalloc
266must have been freed with
267.Fn uma_zfree
268before.
269.Pp
270The
271.Fn uma_zone_set_max
272function limits the number of items
273.Pq and therefore memory
274that can be allocated to
275.Fa zone .
276The
277.Fa nitems
278argument specifies the requested upper limit number of items.
279The effective limit is returned to the caller, as it may end up being higher
280than requested due to the implementation rounding up to ensure all memory pages
281allocated to the zone are utilised to capacity.
282The limit applies to the total number of items in the zone, which includes
283allocated items, free items and free items in the per-cpu caches.
284On systems with more than one CPU it may not be possible to allocate
285the specified number of items even when there is no shortage of memory,
286because all of the remaining free items may be in the caches of the
287other CPUs when the limit is hit.
288.Pp
289The
290.Fn uma_zone_get_max
291function returns the effective upper limit number of items for a zone.
292.Pp
293The
294.Fn uma_zone_get_cur
295function returns the approximate current occupancy of the zone.
296The returned value is approximate because appropriate synchronisation to
297determine an exact value is not performed by the implementation.
298This ensures low overhead at the expense of potentially stale data being used
299in the calculation.
300.Pp
301The
302.Fn uma_zone_set_warning
303function sets a warning that will be printed on the system console when the
304given zone becomes full and fails to allocate an item.
305The warning will be printed not often than every five minutes.
306Warnings can be turned off globally by setting the
307.Va vm.zone_warnings
308sysctl tunable to
309.Va 0 .
310.Sh RETURN VALUES
311The
312.Fn uma_zalloc
313function returns a pointer to an item, or
314.Dv NULL
315if the zone ran out of unused items
316and
317.Dv M_NOWAIT
318was specified.
319.Sh SEE ALSO
320.Xr malloc 9
321.Sh HISTORY
322The zone allocator first appeared in
323.Fx 3.0 .
324It was radically changed in
325.Fx 5.0
326to function as a slab allocator.
327.Sh AUTHORS
328.An -nosplit
329The zone allocator was written by
330.An John S. Dyson .
331The zone allocator was rewritten in large parts by
332.An Jeff Roberson Aq jeff@FreeBSD.org
333to function as a slab allocator.
334.Pp
335This manual page was written by
336.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org .
337Changes for UMA by
338.An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org .
339