10aa028ffSDag-Erling Smørgrav.\"- 20aa028ffSDag-Erling Smørgrav.\" Copyright (c) 2001 Dag-Erling Co�dan Sm�rgrav 30aa028ffSDag-Erling Smørgrav.\" All rights reserved. 40aa028ffSDag-Erling Smørgrav.\" 50aa028ffSDag-Erling Smørgrav.\" Redistribution and use in source and binary forms, with or without 60aa028ffSDag-Erling Smørgrav.\" modification, are permitted provided that the following conditions 70aa028ffSDag-Erling Smørgrav.\" are met: 80aa028ffSDag-Erling Smørgrav.\" 1. Redistributions of source code must retain the above copyright 90aa028ffSDag-Erling Smørgrav.\" notice, this list of conditions and the following disclaimer. 100aa028ffSDag-Erling Smørgrav.\" 2. Redistributions in binary form must reproduce the above copyright 110aa028ffSDag-Erling Smørgrav.\" notice, this list of conditions and the following disclaimer in the 120aa028ffSDag-Erling Smørgrav.\" documentation and/or other materials provided with the distribution. 130aa028ffSDag-Erling Smørgrav.\" 140aa028ffSDag-Erling Smørgrav.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 150aa028ffSDag-Erling Smørgrav.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 160aa028ffSDag-Erling Smørgrav.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 170aa028ffSDag-Erling Smørgrav.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 180aa028ffSDag-Erling Smørgrav.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 190aa028ffSDag-Erling Smørgrav.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 200aa028ffSDag-Erling Smørgrav.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 210aa028ffSDag-Erling Smørgrav.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 220aa028ffSDag-Erling Smørgrav.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 230aa028ffSDag-Erling Smørgrav.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 240aa028ffSDag-Erling Smørgrav.\" SUCH DAMAGE. 250aa028ffSDag-Erling Smørgrav.\" 260aa028ffSDag-Erling Smørgrav.\" $FreeBSD$ 270aa028ffSDag-Erling Smørgrav.\" 28c4ae7908SLawrence Stewart.Dd October 9, 2010 290aa028ffSDag-Erling Smørgrav.Dt ZONE 9 300aa028ffSDag-Erling Smørgrav.Os 310aa028ffSDag-Erling Smørgrav.Sh NAME 32382682b2SJeroen Ruigrok van der Werven.Nm uma_zcreate , 337c32182eSJeroen Ruigrok van der Werven.Nm uma_zalloc , 346a4c41d1SRemko Lodder.Nm uma_zalloc_arg , 357c32182eSJeroen Ruigrok van der Werven.Nm uma_zfree , 366a4c41d1SRemko Lodder.Nm uma_zfree_arg , 37d7bbb21aSHartmut Brandt.Nm uma_zdestroy , 38c4ae7908SLawrence Stewart.Nm uma_zone_set_max, 39c4ae7908SLawrence Stewart.Nm uma_zone_get_max, 40c4ae7908SLawrence Stewart.Nm uma_zone_get_cur 41f5fccbbcSDag-Erling Smørgrav.Nd zone allocator 420aa028ffSDag-Erling Smørgrav.Sh SYNOPSIS 4332eef9aeSRuslan Ermilov.In sys/param.h 44f16b3c0dSChad David.In sys/queue.h 453a347a6eSJeroen Ruigrok van der Werven.In vm/uma.h 46382682b2SJeroen Ruigrok van der Werven.Ft uma_zone_t 479be1948fSRuslan Ermilov.Fo uma_zcreate 489be1948fSRuslan Ermilov.Fa "char *name" "int size" 499be1948fSRuslan Ermilov.Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini" 509be1948fSRuslan Ermilov.Fa "int align" "u_int16_t flags" 519be1948fSRuslan Ermilov.Fc 529be1948fSRuslan Ermilov.Ft "void *" 539be1948fSRuslan Ermilov.Fn uma_zalloc "uma_zone_t zone" "int flags" 546a4c41d1SRemko Lodder.Ft "void *" 556a4c41d1SRemko Lodder.Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags" 560aa028ffSDag-Erling Smørgrav.Ft void 57f1de92e6SJeroen Ruigrok van der Werven.Fn uma_zfree "uma_zone_t zone" "void *item" 585ca0c84eSThomas Moestl.Ft void 596a4c41d1SRemko Lodder.Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg" 606a4c41d1SRemko Lodder.Ft void 61f1de92e6SJeroen Ruigrok van der Werven.Fn uma_zdestroy "uma_zone_t zone" 621c6cae97SLawrence Stewart.Ft int 63d7bbb21aSHartmut Brandt.Fn uma_zone_set_max "uma_zone_t zone" "int nitems" 64c4ae7908SLawrence Stewart.Ft int 65c4ae7908SLawrence Stewart.Fn uma_zone_get_max "uma_zone_t zone" 66c4ae7908SLawrence Stewart.Ft int 67c4ae7908SLawrence Stewart.Fn uma_zone_get_cur "uma_zone_t zone" 680aa028ffSDag-Erling Smørgrav.Sh DESCRIPTION 690aa028ffSDag-Erling SmørgravThe zone allocator provides an efficient interface for managing 700aa028ffSDag-Erling Smørgravdynamically-sized collections of items of similar size. 710aa028ffSDag-Erling SmørgravThe zone allocator can work with preallocated zones as well as with 720aa028ffSDag-Erling Smørgravruntime-allocated ones, and is therefore available much earlier in the 730aa028ffSDag-Erling Smørgravboot process than other memory management routines. 740aa028ffSDag-Erling Smørgrav.Pp 750aa028ffSDag-Erling SmørgravA zone is an extensible collection of items of identical size. 760aa028ffSDag-Erling SmørgravThe zone allocator keeps track of which items are in use and which 77008080bdSJeroen Ruigrok van der Wervenare not, and provides functions for allocating items from the zone and 780aa028ffSDag-Erling Smørgravfor releasing them back (which makes them available for later use). 790aa028ffSDag-Erling Smørgrav.Pp 80ced699e3SRuslan ErmilovAfter the first allocation of an item, 8190d83886SJulian Elischerit will have been cleared to zeroes, however subsequent allocations 827251f557SKonstantin Belousovwill retain the contents as of the last free. 8390d83886SJulian Elischer.Pp 84382682b2SJeroen Ruigrok van der WervenThe 85382682b2SJeroen Ruigrok van der Werven.Fn uma_zcreate 86382682b2SJeroen Ruigrok van der Wervenfunction creates a new zone from which items may then be allocated from. 87382682b2SJeroen Ruigrok van der WervenThe 88382682b2SJeroen Ruigrok van der Werven.Fa name 89382682b2SJeroen Ruigrok van der Wervenargument is a text name of the zone for debugging and stats; this memory 90382682b2SJeroen Ruigrok van der Wervenshould not be freed until the zone has been deallocated. 91382682b2SJeroen Ruigrok van der Werven.Pp 924919e8cbSAlfred PerlsteinThe 934919e8cbSAlfred Perlstein.Fa ctor 944919e8cbSAlfred Perlsteinand 954919e8cbSAlfred Perlstein.Fa dtor 964919e8cbSAlfred Perlsteinarguments are callback functions that are called by 974919e8cbSAlfred Perlsteinthe uma subsystem at the time of the call to 984919e8cbSAlfred Perlstein.Fn uma_zalloc 994919e8cbSAlfred Perlsteinand 1004919e8cbSAlfred Perlstein.Fn uma_zfree 101d962d52aSRuslan Ermilovrespectively. 102d962d52aSRuslan ErmilovTheir purpose is to provide hooks for initializing or 1034919e8cbSAlfred Perlsteindestroying things that need to be done at the time of the allocation 104d962d52aSRuslan Ermilovor release of a resource. 105e07f1d5fSHiten PandyaA good usage for the 1064919e8cbSAlfred Perlstein.Fa ctor 1074919e8cbSAlfred Perlsteinand 1084919e8cbSAlfred Perlstein.Fa dtor 1094919e8cbSAlfred Perlsteincallbacks 1104919e8cbSAlfred Perlsteinmight be to adjust a global count of the number of objects allocated. 1114919e8cbSAlfred Perlstein.Pp 1124919e8cbSAlfred PerlsteinThe 1134919e8cbSAlfred Perlstein.Fa uminit 1144919e8cbSAlfred Perlsteinand 1154919e8cbSAlfred Perlstein.Fa fini 1164919e8cbSAlfred Perlsteinarguments are used to optimize the allocation of 117d962d52aSRuslan Ermilovobjects from the zone. 118d962d52aSRuslan ErmilovThey are called by the uma subsystem whenever 1194919e8cbSAlfred Perlsteinit needs to allocate or free several items to satisfy requests or memory 120d962d52aSRuslan Ermilovpressure. 121d962d52aSRuslan ErmilovA good use for the 122d962d52aSRuslan Ermilov.Fa uminit 123d962d52aSRuslan Ermilovand 124d962d52aSRuslan Ermilov.Fa fini 125d962d52aSRuslan Ermilovcallbacks might be to 126d962d52aSRuslan Ermilovinitialize and destroy mutexes contained within the object. 127d962d52aSRuslan ErmilovThis would 1284919e8cbSAlfred Perlsteinallow one to re-use already initialized mutexes when an object is returned 129d962d52aSRuslan Ermilovfrom the uma subsystem's object cache. 130d962d52aSRuslan ErmilovThey are not called on each call to 1314919e8cbSAlfred Perlstein.Fn uma_zalloc 1324919e8cbSAlfred Perlsteinand 1334919e8cbSAlfred Perlstein.Fn uma_zfree 1344919e8cbSAlfred Perlsteinbut rather in a batch mode on several objects. 1354919e8cbSAlfred Perlstein.Pp 1360aa028ffSDag-Erling SmørgravTo allocate an item from a zone, simply call 1377c32182eSJeroen Ruigrok van der Werven.Fn uma_zalloc 1381437c79aSJeroen Ruigrok van der Wervenwith a pointer to that zone 1391437c79aSJeroen Ruigrok van der Wervenand set the 140acff84fbSJeroen Ruigrok van der Werven.Fa flags 141acff84fbSJeroen Ruigrok van der Wervenargument to selected flags as documented in 142acff84fbSJeroen Ruigrok van der Werven.Xr malloc 9 . 1431437c79aSJeroen Ruigrok van der WervenIt will return a pointer to an item if successful, 1441437c79aSJeroen Ruigrok van der Wervenor 1450aa028ffSDag-Erling Smørgrav.Dv NULL 1460aa028ffSDag-Erling Smørgravin the rare case where all items in the zone are in use and the 1471437c79aSJeroen Ruigrok van der Wervenallocator is unable to grow the zone 1481437c79aSJeroen Ruigrok van der Wervenor when 1491437c79aSJeroen Ruigrok van der Werven.Dv M_NOWAIT 1501437c79aSJeroen Ruigrok van der Wervenis specified. 1510aa028ffSDag-Erling Smørgrav.Pp 1520aa028ffSDag-Erling SmørgravItems are released back to the zone from which they were allocated by 1530aa028ffSDag-Erling Smørgravcalling 1547c32182eSJeroen Ruigrok van der Werven.Fn uma_zfree 1550aa028ffSDag-Erling Smørgravwith a pointer to the zone and a pointer to the item. 156*20ed0cb0SMatthew D FlemingIf 157*20ed0cb0SMatthew D Fleming.Fa item 158*20ed0cb0SMatthew D Flemingis 159*20ed0cb0SMatthew D Fleming.Dv NULL , 160*20ed0cb0SMatthew D Flemingthen 161*20ed0cb0SMatthew D Fleming.Fn uma_zfree 162*20ed0cb0SMatthew D Flemingdoes nothing. 1635ca0c84eSThomas Moestl.Pp 1646a4c41d1SRemko LodderThe variations 1656a4c41d1SRemko Lodder.Fn uma_zalloc_arg 1666a4c41d1SRemko Lodderand 1676a4c41d1SRemko Lodder.Fn uma_zfree_arg 1686a4c41d1SRemko Lodderallow to 1696a4c41d1SRemko Lodderspecify an argument for the 1706a4c41d1SRemko Lodder.Dv ctor 1716a4c41d1SRemko Lodderand 1726a4c41d1SRemko Lodder.Dv dtor 1736a4c41d1SRemko Lodderfunctions, respectively. 1746a4c41d1SRemko Lodder.Pp 17555407559SJeroen Ruigrok van der WervenCreated zones, 17655407559SJeroen Ruigrok van der Wervenwhich are empty, 1775ca0c84eSThomas Moestlcan be destroyed using 1787c32182eSJeroen Ruigrok van der Werven.Fn uma_zdestroy , 1795ca0c84eSThomas Moestlfreeing all memory that was allocated for the zone. 1805ca0c84eSThomas MoestlAll items allocated from the zone with 1817c32182eSJeroen Ruigrok van der Werven.Fn uma_zalloc 1825ca0c84eSThomas Moestlmust have been freed with 1837c32182eSJeroen Ruigrok van der Werven.Fn uma_zfree 1845ca0c84eSThomas Moestlbefore. 185d7bbb21aSHartmut Brandt.Pp 186c4ae7908SLawrence StewartThe 187d7bbb21aSHartmut Brandt.Fn uma_zone_set_max 188c4ae7908SLawrence Stewartfunction limits the number of items 189c4ae7908SLawrence Stewart.Pq and therefore memory 190c4ae7908SLawrence Stewartthat can be allocated to 191c4ae7908SLawrence Stewart.Fa zone . 192d7bbb21aSHartmut BrandtThe 193d7bbb21aSHartmut Brandt.Fa nitems 194c4ae7908SLawrence Stewartargument specifies the requested upper limit number of items. 1951c6cae97SLawrence StewartThe effective limit is returned to the caller, as it may end up being higher 1961c6cae97SLawrence Stewartthan requested due to the implementation rounding up to ensure all memory pages 1971c6cae97SLawrence Stewartallocated to the zone are utilised to capacity. 198c4ae7908SLawrence StewartThe limit applies to the total number of items in the zone, which includes 199d7bbb21aSHartmut Brandtallocated items, free items and free items in the per-cpu caches. 200d7bbb21aSHartmut BrandtOn systems with more than one CPU it may not be possible to allocate 201d7bbb21aSHartmut Brandtthe specified number of items even when there is no shortage of memory, 202d7bbb21aSHartmut Brandtbecause all of the remaining free items may be in the caches of the 203d7bbb21aSHartmut Brandtother CPUs when the limit is hit. 204c4ae7908SLawrence Stewart.Pp 205c4ae7908SLawrence StewartThe 206c4ae7908SLawrence Stewart.Fn uma_zone_get_max 207c4ae7908SLawrence Stewartfunction returns the effective upper limit number of items for a zone. 208c4ae7908SLawrence Stewart.Pp 209c4ae7908SLawrence StewartThe 210c4ae7908SLawrence Stewart.Fn uma_zone_get_cur 211c4ae7908SLawrence Stewartfunction returns the approximate current occupancy of the zone. 212c4ae7908SLawrence StewartThe returned value is approximate because appropriate synchronisation to 213c4ae7908SLawrence Stewartdetermine an exact value is not performend by the implementation. 214c4ae7908SLawrence StewartThis ensures low overhead at the expense of potentially stale data being used 215c4ae7908SLawrence Stewartin the calculation. 2160aa028ffSDag-Erling Smørgrav.Sh RETURN VALUES 2170aa028ffSDag-Erling SmørgravThe 2187c32182eSJeroen Ruigrok van der Werven.Fn uma_zalloc 2190aa028ffSDag-Erling Smørgravfunction returns a pointer to an item, or 2200aa028ffSDag-Erling Smørgrav.Dv NULL 2210aa028ffSDag-Erling Smørgravif the zone ran out of unused items and the allocator was unable to 2220aa028ffSDag-Erling Smørgravenlarge it. 2230aa028ffSDag-Erling Smørgrav.Sh SEE ALSO 2240aa028ffSDag-Erling Smørgrav.Xr malloc 9 2250aa028ffSDag-Erling Smørgrav.Sh HISTORY 2260aa028ffSDag-Erling SmørgravThe zone allocator first appeared in 2270aa028ffSDag-Erling Smørgrav.Fx 3.0 . 2289a795583SJeroen Ruigrok van der WervenIt was radically changed in 2299a795583SJeroen Ruigrok van der Werven.Fx 5.0 2309a795583SJeroen Ruigrok van der Wervento function as a slab allocator. 2310aa028ffSDag-Erling Smørgrav.Sh AUTHORS 2320aa028ffSDag-Erling Smørgrav.An -nosplit 2330aa028ffSDag-Erling SmørgravThe zone allocator was written by 2340aa028ffSDag-Erling Smørgrav.An John S. Dyson . 2359a795583SJeroen Ruigrok van der WervenThe zone allocator was rewritten in large parts by 2369a795583SJeroen Ruigrok van der Werven.An Jeff Roberson Aq jeff@FreeBSD.org 2379a795583SJeroen Ruigrok van der Wervento function as a slab allocator. 2380aa028ffSDag-Erling Smørgrav.Pp 2390aa028ffSDag-Erling SmørgravThis manual page was written by 24009e06539SDag-Erling Smørgrav.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . 2419a795583SJeroen Ruigrok van der WervenChanges for UMA by 2429a795583SJeroen Ruigrok van der Werven.An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org . 243