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