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