diff options
Diffstat (limited to 'static/freebsd/man9/zone.9 3.html')
| -rw-r--r-- | static/freebsd/man9/zone.9 3.html | 596 |
1 files changed, 0 insertions, 596 deletions
diff --git a/static/freebsd/man9/zone.9 3.html b/static/freebsd/man9/zone.9 3.html deleted file mode 100644 index e45ef578..00000000 --- a/static/freebsd/man9/zone.9 3.html +++ /dev/null @@ -1,596 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">UMA(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">UMA(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">UMA</code> — - <span class="Nd">general-purpose kernel object allocator</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/queue.h</a>></code> - <br/> - <code class="In">#include <<a class="In">vm/uma.h</a>></code></p> -<div class="Bd Pp Li"> -<pre>typedef int (*uma_ctor)(void *mem, int size, void *arg, int flags); -typedef void (*uma_dtor)(void *mem, int size, void *arg); -typedef int (*uma_init)(void *mem, int size, int flags); -typedef void (*uma_fini)(void *mem, int size); -typedef int (*uma_import)(void *arg, void **store, int count, int domain, - int flags); -typedef void (*uma_release)(void *arg, void **store, int count); -typedef void *(*uma_alloc)(uma_zone_t zone, vm_size_t size, int domain, - uint8_t *pflag, int wait); -typedef void (*uma_free)(void *item, vm_size_t size, uint8_t pflag); - -</pre> -</div> -<br/> -<var class="Ft">uma_zone_t</var> -<br/> -<code class="Fn">uma_zcreate</code>(<var class="Fa">char *name</var>, - <var class="Fa">size_t size</var>, <var class="Fa">uma_ctor ctor</var>, - <var class="Fa">uma_dtor dtor</var>, <var class="Fa">uma_init zinit</var>, - <var class="Fa">uma_fini zfini</var>, <var class="Fa">int align</var>, - <var class="Fa">uint16_t flags</var>); -<p class="Pp"><var class="Ft">uma_zone_t</var> - <br/> - <code class="Fn">uma_zcache_create</code>(<var class="Fa">char *name</var>, - <var class="Fa">int size</var>, <var class="Fa">uma_ctor ctor</var>, - <var class="Fa">uma_dtor dtor</var>, <var class="Fa">uma_init zinit</var>, - <var class="Fa">uma_fini zfini</var>, <var class="Fa">uma_import - zimport</var>, <var class="Fa">uma_release zrelease</var>, - <var class="Fa">void *arg</var>, <var class="Fa">int flags</var>);</p> -<p class="Pp"><var class="Ft">uma_zone_t</var> - <br/> - <code class="Fn">uma_zsecond_create</code>(<var class="Fa">char *name</var>, - <var class="Fa">uma_ctor ctor</var>, <var class="Fa">uma_dtor dtor</var>, - <var class="Fa">uma_init zinit</var>, <var class="Fa">uma_fini zfini</var>, - <var class="Fa">uma_zone_t master</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zdestroy</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">uma_zalloc</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">uma_zalloc_arg</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">void *arg</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">uma_zalloc_domain</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">void *arg</var>, - <var class="Fa" style="white-space: nowrap;">int domain</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">uma_zalloc_pcpu</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">uma_zalloc_pcpu_arg</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">void *arg</var>, - <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> -<p class="Pp"><var class="Ft">void *</var> - <br/> - <code class="Fn">uma_zalloc_smr</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zfree</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">void - *item</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zfree_arg</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">void *item</var>, - <var class="Fa" style="white-space: nowrap;">void *arg</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zfree_pcpu</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">void - *item</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zfree_pcpu_arg</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">void *item</var>, - <var class="Fa" style="white-space: nowrap;">void *arg</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zfree_smr</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">void - *item</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_prealloc</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int - nitems</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_reserve</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int - nitems</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_reserve_kva</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int - nitems</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_reclaim</code>(<var class="Fa" style="white-space: nowrap;">int - req</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_reclaim_domain</code>(<var class="Fa" style="white-space: nowrap;">int - req</var>, <var class="Fa" style="white-space: nowrap;">int - domain</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_reclaim</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int req</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_reclaim_domain</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int req</var>, - <var class="Fa" style="white-space: nowrap;">int domain</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_set_allocf</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">uma_alloc - allocf</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_set_freef</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">uma_free - freef</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">uma_zone_set_max</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int - nitems</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_set_maxcache</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">int - nitems</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">uma_zone_get_max</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">uma_zone_get_cur</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_set_warning</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">const char - *warning</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_set_maxaction</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">void - (*maxaction)(uma_zone_t)</var>);</p> -<p class="Pp"><var class="Ft">smr_t</var> - <br/> - <code class="Fn">uma_zone_get_smr</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">uma_zone_set_smr</code>(<var class="Fa" style="white-space: nowrap;">uma_zone_t - zone</var>, <var class="Fa" style="white-space: nowrap;">smr_t - smr</var>);</p> -<p class="Pp"><code class="In">#include - <<a class="In">sys/sysctl.h</a>></code></p> -<p class="Pp"><code class="Fn">SYSCTL_UMA_MAX</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">nbr</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">access</var>, - <var class="Fa" style="white-space: nowrap;">zone</var>, - <var class="Fa" style="white-space: nowrap;">descr</var>);</p> -<p class="Pp"><code class="Fn">SYSCTL_ADD_UMA_MAX</code>(<var class="Fa" style="white-space: nowrap;">ctx</var>, - <var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">nbr</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">access</var>, - <var class="Fa" style="white-space: nowrap;">zone</var>, - <var class="Fa" style="white-space: nowrap;">descr</var>);</p> -<p class="Pp"><code class="Fn">SYSCTL_UMA_CUR</code>(<var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">nbr</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">access</var>, - <var class="Fa" style="white-space: nowrap;">zone</var>, - <var class="Fa" style="white-space: nowrap;">descr</var>);</p> -<p class="Pp"><code class="Fn">SYSCTL_ADD_UMA_CUR</code>(<var class="Fa" style="white-space: nowrap;">ctx</var>, - <var class="Fa" style="white-space: nowrap;">parent</var>, - <var class="Fa" style="white-space: nowrap;">nbr</var>, - <var class="Fa" style="white-space: nowrap;">name</var>, - <var class="Fa" style="white-space: nowrap;">access</var>, - <var class="Fa" style="white-space: nowrap;">zone</var>, - <var class="Fa" style="white-space: nowrap;">descr</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">UMA (Universal Memory Allocator) provides an efficient interface - for managing dynamically-sized collections of items of identical size, - referred to as zones. Zones keep track of which items are in use and which - are not, and UMA provides functions for allocating items from a zone and for - releasing them back, making them available for subsequent allocation - requests. Zones maintain per-CPU caches with linear scalability on SMP - systems as well as round-robin and first-touch policies for NUMA systems. - The number of items cached per CPU is bounded, and each zone additionally - maintains an unbounded cache of items that is used to quickly satisfy - per-CPU cache allocation misses.</p> -<p class="Pp">Two types of zones exist: regular zones and cache zones. In a - regular zone, items are allocated from a slab, which is one or more - virtually contiguous memory pages that have been allocated from the kernel's - page allocator. Internally, slabs are managed by a UMA keg, which is - responsible for allocating slabs and keeping track of their usage by one or - more zones. In typical usage, there is one keg per zone, so slabs are not - shared among multiple zones.</p> -<p class="Pp">Normal zones import items from a keg, and release items back to - that keg if requested. Cache zones do not have a keg, and instead use custom - import and release methods. For example, some collections of kernel objects - are statically allocated at boot-time, and the size of the collection does - not change. A cache zone can be used to implement an efficient allocator for - the objects in such a collection.</p> -<p class="Pp" id="uma_zcreate">The - <a class="permalink" href="#uma_zcreate"><code class="Fn">uma_zcreate</code></a>() - and <code class="Fn">uma_zcache_create</code>() functions create a new - regular zone and cache zone, respectively. The - <a class="permalink" href="#uma_zsecond_create"><code class="Fn" id="uma_zsecond_create">uma_zsecond_create</code></a>() - function creates a regular zone which shares the keg of the zone specified - by the <var class="Fa">master</var> argument. The <var class="Fa">name</var> - argument is a text name of the zone for debugging and stats; this memory - should not be freed until the zone has been deallocated.</p> -<p class="Pp" id="uma_zalloc">The <var class="Fa">ctor</var> and - <var class="Fa">dtor</var> arguments are callback functions that are called - by the UMA subsystem at the time of the call to - <a class="permalink" href="#uma_zalloc"><code class="Fn">uma_zalloc</code></a>() - and <code class="Fn">uma_zfree</code>() respectively. Their purpose is to - provide hooks for initializing or destroying things that need to be done at - the time of the allocation or release of a resource. A good usage for the - <var class="Fa">ctor</var> and <var class="Fa">dtor</var> callbacks might be - to initialize a data structure embedded in the item, such as a - <a class="Xr">queue(3)</a> head.</p> -<p class="Pp" id="uma_zalloc~2">The <var class="Fa">zinit</var> and - <var class="Fa">zfini</var> arguments are used to optimize the allocation of - items from the zone. They are called by the UMA subsystem whenever it needs - to allocate or free items to satisfy requests or memory pressure. A good use - for the <var class="Fa">zinit</var> and <var class="Fa">zfini</var> - callbacks might be to initialize and destroy a mutex contained within an - item. This would allow one to avoid destroying and re-initializing the mutex - each time the item is freed and re-allocated. They are not called on each - call to - <a class="permalink" href="#uma_zalloc~2"><code class="Fn">uma_zalloc</code></a>() - and <code class="Fn">uma_zfree</code>() but rather when an item is imported - into a zone's cache, and when a zone releases an item to the slab allocator, - typically as a response to memory pressure.</p> -<p class="Pp" id="uma_zcache_create">For - <a class="permalink" href="#uma_zcache_create"><code class="Fn">uma_zcache_create</code></a>(), - the <var class="Fa">zimport</var> and <var class="Fa">zrelease</var> - functions are called to import items into the zone and to release items from - the zone, respectively. The <var class="Fa">zimport</var> function should - store pointers to items in the <var class="Fa">store</var> array, which - contains a maximum of <var class="Fa">count</var> entries. The function must - return the number of imported items, which may be less than the maximum. - Similarly, the <var class="Fa">store</var> parameter to the - <var class="Fa">zrelease</var> function contains an array of - <var class="Fa">count</var> pointers to items. The <var class="Fa">arg</var> - parameter passed to <code class="Fn">uma_zcache_create</code>() is provided - to the import and release functions. The <var class="Fa">domain</var> - parameter to <var class="Fa">zimport</var> specifies the requested - <a class="Xr">numa(4)</a> domain for the allocation. It is either a NUMA - domain number or the special value - <code class="Dv">UMA_ANYDOMAIN</code>.</p> -<p class="Pp" id="uma_zcreate~2">The <var class="Fa">flags</var> argument of - <a class="permalink" href="#uma_zcreate~2"><code class="Fn">uma_zcreate</code></a>() - and <code class="Fn">uma_zcache_create</code>() is a subset of the following - flags:</p> -<dl class="Bl-tag"> - <dt id="UMA_ZONE_NOFREE"><a class="permalink" href="#UMA_ZONE_NOFREE"><code class="Dv">UMA_ZONE_NOFREE</code></a></dt> - <dd>Slabs allocated to the zone's keg are never freed.</dd> - <dt id="UMA_ZONE_NODUMP"><a class="permalink" href="#UMA_ZONE_NODUMP"><code class="Dv">UMA_ZONE_NODUMP</code></a></dt> - <dd>Pages belonging to the zone will not be included in minidumps.</dd> - <dt id="UMA_ZONE_PCPU"><a class="permalink" href="#UMA_ZONE_PCPU"><code class="Dv">UMA_ZONE_PCPU</code></a></dt> - <dd>An allocation from zone would have <var class="Va">mp_ncpu</var> shadow - copies, that are privately assigned to CPUs. A CPU can address its private - copy using base the allocation address plus a multiple of the current CPU - ID and - <a class="permalink" href="#sizeof"><code class="Fn" id="sizeof">sizeof</code></a>(<var class="Fa">struct - pcpu</var>): - <div class="Bd Pp Bd-indent Li"> - <pre>foo_zone = uma_zcreate(..., UMA_ZONE_PCPU); - ... -foo_base = uma_zalloc(foo_zone, ...); - ... -critical_enter(); -foo_pcpu = (foo_t *)zpcpu_get(foo_base); -/* do something with foo_pcpu */ -critical_exit(); - - </pre> - </div> - Note that <code class="Dv">M_ZERO</code> cannot be used when allocating - items from a PCPU zone. To obtain zeroed memory from a PCPU zone, use the - <code class="Fn">uma_zalloc_pcpu</code>() function and its variants - instead, and pass <code class="Dv">M_ZERO</code>.</dd> - <dt id="UMA_ZONE_NOTOUCH"><a class="permalink" href="#UMA_ZONE_NOTOUCH"><code class="Dv">UMA_ZONE_NOTOUCH</code></a></dt> - <dd>The UMA subsystem may not directly touch (i.e. read or write) the slab - memory. Otherwise, by default, book-keeping of items within a slab may be - done in the slab page itself, and <code class="Dv">INVARIANTS</code> - kernels may also do use-after-free checking by accessing the slab - memory.</dd> - <dt id="UMA_ZONE_ZINIT"><a class="permalink" href="#UMA_ZONE_ZINIT"><code class="Dv">UMA_ZONE_ZINIT</code></a></dt> - <dd>The zone will have its <var class="Ft">uma_init</var> method set to - internal method that initializes a new allocated slab to all zeros. Do not - mistake <var class="Ft">uma_init</var> method with - <var class="Ft">uma_ctor</var>. A zone with - <code class="Dv">UMA_ZONE_ZINIT</code> flag would not return zeroed memory - on every <code class="Fn">uma_zalloc</code>().</dd> - <dt id="UMA_ZONE_NOTPAGE"><a class="permalink" href="#UMA_ZONE_NOTPAGE"><code class="Dv">UMA_ZONE_NOTPAGE</code></a></dt> - <dd>An allocator function will be supplied with - <code class="Fn">uma_zone_set_allocf</code>() and the memory that it - returns may not be kernel virtual memory backed by VM pages in the page - array.</dd> - <dt id="UMA_ZONE_MALLOC"><a class="permalink" href="#UMA_ZONE_MALLOC"><code class="Dv">UMA_ZONE_MALLOC</code></a></dt> - <dd>The zone is for the <a class="Xr">malloc(9)</a> subsystem.</dd> - <dt id="UMA_ZONE_VM"><a class="permalink" href="#UMA_ZONE_VM"><code class="Dv">UMA_ZONE_VM</code></a></dt> - <dd>The zone is for the VM subsystem.</dd> - <dt id="UMA_ZONE_CONTIG"><a class="permalink" href="#UMA_ZONE_CONTIG"><code class="Dv">UMA_ZONE_CONTIG</code></a></dt> - <dd>Items in this zone must be contiguous in physical address space. Items - will follow normal alignment constraints and may span page boundaries - between pages with contiguous physical addresses.</dd> - <dt id="UMA_ZONE_UNMANAGED"><a class="permalink" href="#UMA_ZONE_UNMANAGED"><code class="Dv">UMA_ZONE_UNMANAGED</code></a></dt> - <dd>By default, UMA zone caches are shrunk to help resolve free page - shortages. Cached items that have not been used for a long period may also - be freed from zone. When this flag is set, the system will not reclaim - memory from the zone's caches.</dd> - <dt id="UMA_ZONE_SMR"><a class="permalink" href="#UMA_ZONE_SMR"><code class="Dv">UMA_ZONE_SMR</code></a></dt> - <dd>Create a zone whose items will be synchronized using the - <a class="Xr">smr(9)</a> mechanism. Upon creation the zone will have an - associated <var class="Ft">smr_t</var> structure which can be fetched - using - <a class="permalink" href="#uma_zone_get_smr"><code class="Fn" id="uma_zone_get_smr">uma_zone_get_smr</code></a>().</dd> -</dl> -<p class="Pp" id="uma_zdestroy">Zones can be destroyed using - <a class="permalink" href="#uma_zdestroy"><code class="Fn">uma_zdestroy</code></a>(), - freeing all memory that is cached in the zone. All items allocated from the - zone must be freed to the zone before the zone may be safely destroyed.</p> -<p class="Pp" id="uma_zalloc~3">To allocate an item from a zone, simply call - <a class="permalink" href="#uma_zalloc~3"><code class="Fn">uma_zalloc</code></a>() - with a pointer to that zone and set the <var class="Fa">flags</var> argument - to selected flags as documented in <a class="Xr">malloc(9)</a>. It will - return a pointer to an item if successful, or <code class="Dv">NULL</code> - in the rare case where all items in the zone are in use and the allocator is - unable to grow the zone and <code class="Dv">M_NOWAIT</code> is - specified.</p> -<p class="Pp" id="uma_zfree">Items are released back to the zone from which they - were allocated by calling - <a class="permalink" href="#uma_zfree"><code class="Fn">uma_zfree</code></a>() - with a pointer to the zone and a pointer to the item. If - <var class="Fa">item</var> is <code class="Dv">NULL</code>, then - <code class="Fn">uma_zfree</code>() does nothing.</p> -<p class="Pp" id="uma_zalloc_arg">The variants - <a class="permalink" href="#uma_zalloc_arg"><code class="Fn">uma_zalloc_arg</code></a>() - and - <a class="permalink" href="#uma_zfree_arg"><code class="Fn" id="uma_zfree_arg">uma_zfree_arg</code></a>() - allow callers to specify an argument for the <code class="Dv">ctor</code> - and <code class="Dv">dtor</code> functions of the zone, respectively. The - variants - <a class="permalink" href="#uma_zalloc_pcpu"><code class="Fn" id="uma_zalloc_pcpu">uma_zalloc_pcpu</code></a>() - and - <a class="permalink" href="#uma_zfree_pcpu"><code class="Fn" id="uma_zfree_pcpu">uma_zfree_pcpu</code></a>() - allocate and free <var class="Va">mp_ncpu</var> shadow copies as described - for <code class="Dv">UMA_ZONE_PCPU</code>. If <var class="Fa">item</var> is - <code class="Dv">NULL</code>, then <code class="Fn">uma_zfree_pcpu</code>() - does nothing.</p> -<p class="Pp" id="uma_zalloc_smr">The - <a class="permalink" href="#uma_zalloc_smr"><code class="Fn">uma_zalloc_smr</code></a>() - and - <a class="permalink" href="#uma_zfree_smr"><code class="Fn" id="uma_zfree_smr">uma_zfree_smr</code></a>() - functions allocate and free items from an SMR-enabled zone, that is, a zone - created with <code class="Dv">UMA_ZONE_SMR</code> or a zone that has had - <code class="Fn">uma_zone_set_smr</code>() called.</p> -<p class="Pp" id="uma_zalloc_domain">The - <a class="permalink" href="#uma_zalloc_domain"><code class="Fn">uma_zalloc_domain</code></a>() - function allows callers to specify a fixed <a class="Xr">numa(4)</a> domain - to allocate from. This uses a guaranteed but slow path in the allocator - which reduces concurrency.</p> -<p class="Pp" id="uma_prealloc">The - <a class="permalink" href="#uma_prealloc"><code class="Fn">uma_prealloc</code></a>() - function allocates slabs for the requested number of items, typically - following the initial creation of a zone. Subsequent allocations from the - zone will be satisfied using the pre-allocated slabs. Note that slab - allocation is performed with the <code class="Dv">M_WAITOK</code> flag, so - <code class="Fn">uma_prealloc</code>() may sleep.</p> -<p class="Pp" id="uma_zone_reserve">The - <a class="permalink" href="#uma_zone_reserve"><code class="Fn">uma_zone_reserve</code></a>() - function sets the number of reserved items for the zone. - <code class="Fn">uma_zalloc</code>() and variants will ensure that the zone - contains at least the reserved number of free items. Reserved items may be - allocated by specifying <code class="Dv">M_USE_RESERVE</code> in the - allocation request flags. <code class="Fn">uma_zone_reserve</code>() does - not perform any pre-allocation by itself.</p> -<p class="Pp" id="uma_zone_reserve_kva">The - <a class="permalink" href="#uma_zone_reserve_kva"><code class="Fn">uma_zone_reserve_kva</code></a>() - function pre-allocates kernel virtual address space for the requested number - of items. Subsequent allocations from the zone will be satisfied using the - pre-allocated address space. Note that unlike - <code class="Fn">uma_zone_reserve</code>(), - <code class="Fn">uma_zone_reserve_kva</code>() does not restrict the use of - the pre-allocation to <code class="Dv">M_USE_RESERVE</code> requests.</p> -<p class="Pp" id="uma_reclaim">The - <a class="permalink" href="#uma_reclaim"><code class="Fn">uma_reclaim</code></a>() - and - <a class="permalink" href="#uma_zone_reclaim"><code class="Fn" id="uma_zone_reclaim">uma_zone_reclaim</code></a>() - functions reclaim cached items from UMA zones, releasing unused memory. The - <code class="Fn">uma_reclaim</code>() function reclaims items from all - regular zones, while <code class="Fn">uma_zone_reclaim</code>() reclaims - items only from the specified zone. The <var class="Fa">req</var> parameter - must be one of three values which specify how aggressively items are to be - reclaimed:</p> -<dl class="Bl-tag"> - <dt id="UMA_RECLAIM_TRIM"><a class="permalink" href="#UMA_RECLAIM_TRIM"><code class="Dv">UMA_RECLAIM_TRIM</code></a></dt> - <dd>Reclaim items only in excess of the zone's estimated working set size. The - working set size is periodically updated and tracks the recent history of - the zone's usage.</dd> - <dt id="UMA_RECLAIM_DRAIN"><a class="permalink" href="#UMA_RECLAIM_DRAIN"><code class="Dv">UMA_RECLAIM_DRAIN</code></a></dt> - <dd>Reclaim all items from the unbounded cache. Free items in the per-CPU - caches are left alone.</dd> - <dt id="UMA_RECLAIM_DRAIN_CPU"><a class="permalink" href="#UMA_RECLAIM_DRAIN_CPU"><code class="Dv">UMA_RECLAIM_DRAIN_CPU</code></a></dt> - <dd>Reclaim all cached items.</dd> -</dl> -The - <a class="permalink" href="#uma_reclaim_domain"><code class="Fn" id="uma_reclaim_domain">uma_reclaim_domain</code></a>() - and - <a class="permalink" href="#uma_zone_reclaim_domain"><code class="Fn" id="uma_zone_reclaim_domain">uma_zone_reclaim_domain</code></a>() - functions apply only to items allocated from the specified domain. In the case - of domains using a round-robin NUMA policy, cached items from all domains are - freed to the keg, but only slabs from the specific domain will be freed. -<p class="Pp" id="uma_zone_set_allocf">The - <a class="permalink" href="#uma_zone_set_allocf"><code class="Fn">uma_zone_set_allocf</code></a>() - and - <a class="permalink" href="#uma_zone_set_freef"><code class="Fn" id="uma_zone_set_freef">uma_zone_set_freef</code></a>() - functions allow a zone's default slab allocation and free functions to be - overridden. This is useful if memory with special constraints such as - attributes, alignment, or address ranges must be used.</p> -<p class="Pp" id="uma_zone_set_max">The - <a class="permalink" href="#uma_zone_set_max"><code class="Fn">uma_zone_set_max</code></a>() - function limits the number of items (and therefore memory) that can be - allocated to <var class="Fa">zone</var>. The <var class="Fa">nitems</var> - argument specifies the requested upper limit number of items. The effective - limit is returned to the caller, as it may end up being higher than - requested due to the implementation rounding up to ensure all memory pages - allocated to the zone are utilised to capacity. The limit applies to the - total number of items in the zone, which includes allocated items, free - items and free items in the per-cpu caches. On systems with more than one - CPU it may not be possible to allocate the specified number of items even - when there is no shortage of memory, because all of the remaining free items - may be in the caches of the other CPUs when the limit is hit.</p> -<p class="Pp" id="uma_zone_set_maxcache">The - <a class="permalink" href="#uma_zone_set_maxcache"><code class="Fn">uma_zone_set_maxcache</code></a>() - function limits the number of free items which may be cached in the zone. - This limit applies to both the per-CPU caches and the cache of free - buckets.</p> -<p class="Pp" id="uma_zone_get_max">The - <a class="permalink" href="#uma_zone_get_max"><code class="Fn">uma_zone_get_max</code></a>() - function returns the effective upper limit number of items for a zone.</p> -<p class="Pp" id="uma_zone_get_cur">The - <a class="permalink" href="#uma_zone_get_cur"><code class="Fn">uma_zone_get_cur</code></a>() - function returns an approximation of the number of items currently allocated - from the zone. The returned value is approximate because appropriate - synchronisation to determine an exact value is not performed by the - implementation. This ensures low overhead at the expense of potentially - stale data being used in the calculation.</p> -<p class="Pp" id="uma_zone_set_warning">The - <a class="permalink" href="#uma_zone_set_warning"><code class="Fn">uma_zone_set_warning</code></a>() - function sets a warning that will be printed on the system console when the - given zone becomes full and fails to allocate an item. The warning will be - printed no more often than every five minutes. Warnings can be turned off - globally by setting the <var class="Va">vm.zone_warnings</var> sysctl - tunable to <var class="Va">0</var>.</p> -<p class="Pp" id="uma_zone_set_maxaction">The - <a class="permalink" href="#uma_zone_set_maxaction"><code class="Fn">uma_zone_set_maxaction</code></a>() - function sets a function that will be called when the given zone becomes - full and fails to allocate an item. The function will be called with the - zone locked. Also, the function that called the allocation function may have - held additional locks. Therefore, this function should do very little work - (similar to a signal handler).</p> -<p class="Pp" id="uma_zone_set_smr">The - <a class="permalink" href="#uma_zone_set_smr"><code class="Fn">uma_zone_set_smr</code></a>() - function associates an existing <a class="Xr">smr(9)</a> structure with a - UMA zone. The effect is similar to creating a zone with the - <code class="Dv">UMA_ZONE_SMR</code> flag, except that a new SMR structure - is not created. This function must be called before any allocations from the - zone are performed.</p> -<p class="Pp" id="SYSCTL_UMA_MAX">The - <a class="permalink" href="#SYSCTL_UMA_MAX"><code class="Fn">SYSCTL_UMA_MAX</code></a>(<var class="Fa">parent</var>, - <var class="Fa">nbr</var>, <var class="Fa">name</var>, - <var class="Fa">access</var>, <var class="Fa">zone</var>, - <var class="Fa">descr</var>) macro declares a static - <a class="Xr">sysctl(9)</a> oid that exports the effective upper limit - number of items for a zone. The <var class="Fa">zone</var> argument should - be a pointer to <var class="Vt">uma_zone_t</var>. A read of the oid returns - value obtained through <code class="Fn">uma_zone_get_max</code>(). A write - to the oid sets new value via <code class="Fn">uma_zone_set_max</code>(). - The - <a class="permalink" href="#SYSCTL_ADD_UMA_MAX"><code class="Fn" id="SYSCTL_ADD_UMA_MAX">SYSCTL_ADD_UMA_MAX</code></a>(<var class="Fa">ctx</var>, - <var class="Fa">parent</var>, <var class="Fa">nbr</var>, - <var class="Fa">name</var>, <var class="Fa">access</var>, - <var class="Fa">zone</var>, <var class="Fa">descr</var>) macro is provided - to create this type of oid dynamically.</p> -<p class="Pp" id="SYSCTL_UMA_CUR">The - <a class="permalink" href="#SYSCTL_UMA_CUR"><code class="Fn">SYSCTL_UMA_CUR</code></a>(<var class="Fa">parent</var>, - <var class="Fa">nbr</var>, <var class="Fa">name</var>, - <var class="Fa">access</var>, <var class="Fa">zone</var>, - <var class="Fa">descr</var>) macro declares a static read-only - <a class="Xr">sysctl(9)</a> oid that exports the approximate current - occupancy of the zone. The <var class="Fa">zone</var> argument should be a - pointer to <var class="Vt">uma_zone_t</var>. A read of the oid returns value - obtained through <code class="Fn">uma_zone_get_cur</code>(). The - <a class="permalink" href="#SYSCTL_ADD_UMA_CUR"><code class="Fn" id="SYSCTL_ADD_UMA_CUR">SYSCTL_ADD_UMA_CUR</code></a>(<var class="Fa">ctx</var>, - <var class="Fa">parent</var>, <var class="Fa">nbr</var>, - <var class="Fa">name</var>, <var class="Fa">zone</var>, - <var class="Fa">descr</var>) macro is provided to create this type of oid - dynamically.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION - NOTES</a></h1> -<p class="Pp">The memory that these allocation calls return is not executable. - The <code class="Fn">uma_zalloc</code>() function does not support the - <code class="Dv">M_EXEC</code> flag to allocate executable memory. Not all - platforms enforce a distinction between executable and non-executable - memory.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">numa(4)</a>, <a class="Xr">vmstat(8)</a>, - <a class="Xr">malloc(9)</a>, <a class="Xr">smr(9)</a></p> -<p class="Pp"><cite class="Rs"><span class="RsA">Jeff Bonwick</span>, - <span class="RsT">The Slab Allocator: An Object-Caching Kernel Memory - Allocator</span>, <span class="RsD">1994</span>.</cite></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The zone allocator first appeared in <span class="Ux">FreeBSD - 3.0</span>. It was radically changed in <span class="Ux">FreeBSD 5.0</span> - to function as a slab allocator.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The zone allocator was written by <span class="An">John S. - Dyson</span>. The zone allocator was rewritten in large parts by - <span class="An">Jeff Roberson</span> - <<a class="Mt" href="mailto:jeff@FreeBSD.org">jeff@FreeBSD.org</a>> to - function as a slab allocator.</p> -<p class="Pp">This manual page was written by <span class="An">Dag-Erling - Smørgrav</span> - <<a class="Mt" href="mailto:des@FreeBSD.org">des@FreeBSD.org</a>>. - Changes for UMA by <span class="An">Jeroen Ruigrok van der Werven</span> - <<a class="Mt" href="mailto:asmodai@FreeBSD.org">asmodai@FreeBSD.org</a>>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">January 16, 2023</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |