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 April 26, 2017
  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_zdestroy ,
  38 .Nm uma_zone_set_max,
  39 .Nm uma_zone_get_max,
  40 .Nm uma_zone_get_cur,
  41 .Nm uma_zone_set_warning,
  42 .Nm uma_zone_set_maxaction
  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 void
  63 .Fn uma_zdestroy "uma_zone_t zone"
  64 .Ft int
  65 .Fn uma_zone_set_max "uma_zone_t zone" "int nitems"
  66 .Ft int
  67 .Fn uma_zone_get_max "uma_zone_t zone"
  68 .Ft int
  69 .Fn uma_zone_get_cur "uma_zone_t zone"
  70 .Ft void
  71 .Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning"
  72 .Ft void
  73 .Fn uma_zone_set_maxaction "uma_zone_t zone" "void (*maxaction)(uma_zone_t)"
  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_NODUMP
 156 Pages belonging to the zone will not be included into mini-dumps.
 157 .It Dv UMA_ZONE_PCPU
 158 An allocation from zone would have
 159 .Va mp_ncpu
 160 shadow copies, that are privately assigned to CPUs.
 161 A CPU can address its private copy using base allocation address plus
 162 multiple of current CPU id and
 163 .Fn sizeof "struct pcpu" :
 164 .Bd -literal -offset indent
 165 foo_zone = uma_zcreate(..., UMA_ZONE_PCPU);
 166  ...
 167 foo_base = uma_zalloc(foo_zone, ...);
 168  ...
 169 critical_enter();
 170 foo_pcpu = (foo_t *)zpcpu_get(foo_base);
 171 /* do something with foo_pcpu */
 172 critical_exit();
 173 .Ed
 174 .It Dv UMA_ZONE_OFFPAGE
 175 By default book-keeping of items within a slab is done in the slab page itself.
 176 This flag explicitly tells subsystem that book-keeping structure should be
 177 allocated separately from special internal zone.
 178 This flag requires either
 179 .Dv UMA_ZONE_VTOSLAB
 180 or
 181 .Dv UMA_ZONE_HASH ,
 182 since subsystem requires a mechanism to find a book-keeping structure
 183 to an item being freed.
 184 The subsystem may choose to prefer offpage book-keeping for certain zones
 185 implicitly.
 186 .It Dv UMA_ZONE_ZINIT
 187 The zone will have its
 188 .Ft uma_init
 189 method set to internal method that initializes a new allocated slab
 190 to all zeros.
 191 Do not mistake
 192 .Ft uma_init
 193 method with
 194 .Ft uma_ctor .
 195 A zone with
 196 .Dv UMA_ZONE_ZINIT
 197 flag would not return zeroed memory on every
 198 .Fn uma_zalloc .
 199 .It Dv UMA_ZONE_HASH
 200 The zone should use an internal hash table to find slab book-keeping
 201 structure where an allocation being freed belongs to.
 202 .It Dv UMA_ZONE_VTOSLAB
 203 The zone should use special field of
 204 .Vt vm_page_t
 205 to find slab book-keeping structure where an allocation being freed belongs to.
 206 .It Dv UMA_ZONE_MALLOC
 207 The zone is for the
 208 .Xr malloc 9
 209 subsystem.
 210 .It Dv UMA_ZONE_VM
 211 The zone is for the VM subsystem.
 212 .El
 213 .Pp
 214 To allocate an item from a zone, simply call
 215 .Fn uma_zalloc
 216 with a pointer to that zone
 217 and set the
 218 .Fa flags
 219 argument to selected flags as documented in
 220 .Xr malloc 9 .
 221 It will return a pointer to an item if successful,
 222 or
 223 .Dv NULL
 224 in the rare case where all items in the zone are in use and the
 225 allocator is unable to grow the zone
 226 and
 227 .Dv M_NOWAIT
 228 is specified.
 229 .Pp
 230 Items are released back to the zone from which they were allocated by
 231 calling
 232 .Fn uma_zfree
 233 with a pointer to the zone and a pointer to the item.
 234 If
 235 .Fa item
 236 is
 237 .Dv NULL ,
 238 then
 239 .Fn uma_zfree
 240 does nothing.
 241 .Pp
 242 The variations
 243 .Fn uma_zalloc_arg
 244 and
 245 .Fn uma_zfree_arg
 246 allow to
 247 specify an argument for the
 248 .Dv ctor
 249 and
 250 .Dv dtor
 251 functions, respectively.
 252 .Pp
 253 Created zones,
 254 which are empty,
 255 can be destroyed using
 256 .Fn uma_zdestroy ,
 257 freeing all memory that was allocated for the zone.
 258 All items allocated from the zone with
 259 .Fn uma_zalloc
 260 must have been freed with
 261 .Fn uma_zfree
 262 before.
 263 .Pp
 264 The
 265 .Fn uma_zone_set_max
 266 function limits the number of items
 267 .Pq and therefore memory
 268 that can be allocated to
 269 .Fa zone .
 270 The
 271 .Fa nitems
 272 argument specifies the requested upper limit number of items.
 273 The effective limit is returned to the caller, as it may end up being higher
 274 than requested due to the implementation rounding up to ensure all memory pages
 275 allocated to the zone are utilised to capacity.
 276 The limit applies to the total number of items in the zone, which includes
 277 allocated items, free items and free items in the per-cpu caches.
 278 On systems with more than one CPU it may not be possible to allocate
 279 the specified number of items even when there is no shortage of memory,
 280 because all of the remaining free items may be in the caches of the
 281 other CPUs when the limit is hit.
 282 .Pp
 283 The
 284 .Fn uma_zone_get_max
 285 function returns the effective upper limit number of items for a zone.
 286 .Pp
 287 The
 288 .Fn uma_zone_get_cur
 289 function returns the approximate current occupancy of the zone.
 290 The returned value is approximate because appropriate synchronisation to
 291 determine an exact value is not performed by the implementation.
 292 This ensures low overhead at the expense of potentially stale data being used
 293 in the calculation.
 294 .Pp
 295 The
 296 .Fn uma_zone_set_warning
 297 function sets a warning that will be printed on the system console when the
 298 given zone becomes full and fails to allocate an item.
 299 The warning will be printed no more often than every five minutes.
 300 Warnings can be turned off globally by setting the
 301 .Va vm.zone_warnings
 302 sysctl tunable to
 303 .Va 0 .
 304 .Pp
 305 The
 306 .Fn uma_zone_set_maxaction
 307 function sets a function that will be called when the given zone becomes full
 308 and fails to allocate an item.
 309 The function will be called with the zone locked.
 310 Also, the function
 311 that called the allocation function may have held additional locks.
 312 Therefore,
 313 this function should do very little work (similar to a signal handler).
 314 .Pp
 315 The
 316 .Fn SYSCTL_UMA_MAX parent nbr name access zone descr
 317 macro declares a static
 318 .Xr sysctl
 319 oid that exports the effective upper limit number of items for a zone.
 320 The
 321 .Fa zone
 322 argument should be a pointer to
 323 .Vt uma_zone_t .
 324 A read of the oid returns value obtained through
 325 .Fn uma_zone_get_max .
 326 A write to the oid sets new value via
 327 .Fn uma_zone_set_max .
 328 The
 329 .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr
 330 macro is provided to create this type of oid dynamically.
 331 .Pp
 332 The
 333 .Fn SYSCTL_UMA_CUR parent nbr name access zone descr
 334 macro declares a static read-only
 335 .Xr sysctl
 336 oid that exports the approximate current occupancy of the zone.
 337 The
 338 .Fa zone
 339 argument should be a pointer to
 340 .Vt uma_zone_t .
 341 A read of the oid returns value obtained through
 342 .Fn uma_zone_get_cur .
 343 The
 344 .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name zone descr
 345 macro is provided to create this type of oid dynamically.
 346 .Sh RETURN VALUES
 347 The
 348 .Fn uma_zalloc
 349 function returns a pointer to an item, or
 350 .Dv NULL
 351 if the zone ran out of unused items
 352 and
 353 .Dv M_NOWAIT
 354 was specified.
 355 .Sh SEE ALSO
 356 .Xr malloc 9
 357 .Sh HISTORY
 358 The zone allocator first appeared in
 359 .Fx 3.0 .
 360 It was radically changed in
 361 .Fx 5.0
 362 to function as a slab allocator.
 363 .Sh AUTHORS
 364 .An -nosplit
 365 The zone allocator was written by
 366 .An John S. Dyson .
 367 The zone allocator was rewritten in large parts by
 368 .An Jeff Roberson Aq Mt jeff@FreeBSD.org
 369 to function as a slab allocator.
 370 .Pp
 371 This manual page was written by
 372 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org .
 373 Changes for UMA by
 374 .An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org .