diff options
Diffstat (limited to 'static/netbsd/man9/pool_cache.9')
| -rw-r--r-- | static/netbsd/man9/pool_cache.9 | 383 |
1 files changed, 383 insertions, 0 deletions
diff --git a/static/netbsd/man9/pool_cache.9 b/static/netbsd/man9/pool_cache.9 new file mode 100644 index 00000000..82115c3a --- /dev/null +++ b/static/netbsd/man9/pool_cache.9 @@ -0,0 +1,383 @@ +.\" $NetBSD: pool_cache.9,v 1.24 2021/12/22 17:28:17 thorpej Exp $ +.\" +.\" Copyright (c)2003 YAMAMOTO Takashi, +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Copyright (c) 1997, 1999, 2000, 2007, 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg; by Jason R. Thorpe of the Numerical Aerospace +.\" Simulation Facility, NASA Ames Research Center, and by Andrew Doran. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" ------------------------------------------------------------ +.Dd December 21, 2021 +.Dt POOL_CACHE 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm pool_cache , +.Nm pool_cache_init , +.Nm pool_cache_destroy , +.Nm pool_cache_get_paddr , +.Nm pool_cache_get , +.Nm pool_cache_put_paddr , +.Nm pool_cache_put , +.Nm pool_cache_destruct_object , +.Nm pool_cache_invalidate , +.Nm pool_cache_sethiwat , +.Nm pool_cache_setlowat , +.Nm pool_cache_sethardlimit +.Nd resource-pool cache manager +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/pool.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft pool_cache_t +.Fn pool_cache_init \ +"size_t size" "u_int align" "u_int align_offset" "int flags" \ +"const char *name" "struct pool_allocator *palloc" "int ipl" \ +"int (*ctor)(void *, void *, int)" "void (*dtor)(void *, void *)" "void *arg" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_destroy \ +"pool_cache_t pc" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void * +.Fn pool_cache_get_paddr \ +"pool_cache_t pc" "int flags" "paddr_t *pap" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void * +.Fn pool_cache_get \ +"pool_cache_t pc" "int flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_put_paddr \ +"pool_cache_t pc" "void *object" "paddr_t pa" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_put \ +"pool_cache_t pc" "void *object" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_destruct_object \ +"pool_cache_t pc" "void *object" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_invalidate \ +"pool_cache_t pc" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn pool_cache_sethiwat \ +"pool_cache_t pc" "int n" +.Ft void +.Fn pool_cache_setlowat \ +"pool_cache_t pc" "int n" +.Ft void +.Fn pool_cache_sethardlimit \ +"pool_cache_t pc" "int n" "const char *warnmess" "int ratecap" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +These utility routines provide management of pools of fixed-sized +areas of memory. +Resource pools set aside an amount of memory for exclusive use by the resource +pool owner. +This can be used by applications to guarantee the availability of a minimum +amount of memory needed to continue operation independent of the memory +resources currently available from the system-wide memory allocator. +.Pp +.Nm +follows the +.Xr pool 9 +API closely and offers routines that are functionally equivalent to +their +.Xr pool 9 +counterparts. +In addition, +.Nm +provides object management functions used to manipulate +objects allocated from the pool. +It also maintains global and per-CPU caches, both levels +of cache work together to allow for low overhead +allocation and release of objects, and improved L1/L2/L3 hardware +cache locality in multiprocessor systems. +.\" ------------------------------------------------------------ +.Sh FUNCTIONS +.Bl -tag -width compact +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_init "size" "align" "align_offset" "flags" \ +"name" "palloc" "ipl" "ctor" "dtor" "arg" +.Pp +Allocate and initialize a pool cache. +The arguments are: +.Bl -tag -width four +.It Fa size +.Pp +Specifies the size of the memory items managed by the pool. +.It Fa align +.Pp +Specifies the memory address alignment of the items returned by +.Fn pool_cache_get . +This argument must be a power of two. +If zero, +the alignment defaults to an architecture-specific natural alignment. +.It Fa align_offset +.Pp +The offset within an item to which the +.Fa align +parameter applies. +.It Fa flags +.Pp +Should be set to zero, +.Dv PR_NOTOUCH , +or +.Dv PR_PSERIALIZE . +If +.Dv PR_NOTOUCH +is given, free items are never used to keep internal state so that +the pool can be used for non memory backed objects. +If +.Dv PR_PSERIALIZE +is given, then the allocator guarantees that a passive serialization barrier +equivalent to +.Dq xc_barrier(0) +will be performed before either the object's destructor is called or +before object's backing store is returned to the system. +.Dv PR_PSERIALIZE +implies +.Dv PR_NOTOUCH . +Because of the guarantees provided by +.Dv PR_PSERIALIZE , +objects must never be freed to a pool cache using this option +from either hard or soft interrupt context, as doing so may block. +.It Fa name +.Pp +The name used to identify the object in diagnostic output. +.It Fa palloc +.Pp +Should be typically be set to NULL, instructing +.Fn pool_cache_init +to select an appropriate back-end allocator. +Alternate allocators can be used to partition space from arbitrary sources. +Use of alternate allocators is not documented here as it is not a stable, +endorsed part of the API. +.It Fa ipl +.Pp +Specifies an interrupt priority level that will block all interrupt +handlers that could potentially access the pool. +The +.Nm +facility provides its own synchronization. +The users of any given +.Nm +need not provide additional synchronization for access to it. +.It Fa ctor +.Pp +Specifies a constructor used to initialize newly allocated objects. +If no constructor is required, specify +.Dv NULL . +The first argument to +.Fa ctor +is +.Fa arg , +the second is the new object, and the third is +.Fa flags . +.It Fa dtor +.Pp +Specifies a destructor used to destroy cached objects prior to +their release to backing store. +If no destructor is required, specify +.Dv NULL . +The first argument to +.Fa dtor +is +.Fa arg , +and the second is the object. +.It Fa arg +.Pp +This value of this argument will be passed to both the constructor +and destructor routines. +.El +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_destroy "pc" +.Pp +Destroy a pool cache +.Fa pc . +All other access to the cache must be stopped before this call +can be made. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_get_paddr "pc" "flags" "pap" +.Pp +Get an object from a pool cache +.Fa pc . +If +.Fa pap +is not +.Dv NULL , +physical address of the object or +.Dv POOL_PADDR_INVALID +will be returned via it. +.Fa flags +will be passed to +.Fn pool_get +function of the backing +.Xr pool 9 +and the object constructor specified when the pool cache is created by +.Fn pool_cache_init . +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_get "pc" "flags" +.Pp +.Fn pool_cache_get +is the same as +.Fn pool_cache_get_paddr +with +.Dv NULL +.Fa pap +argument. +It's implemented as a macro. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_put_paddr "pc" "object" "pa" +.Pp +Put an object +.Fa object +back to the pool cache +.Fa pc . +.Fa pa +should be physical address of the object +.Fa object +or +.Dv POOL_PADDR_INVALID . +If the number of available items in the backing pool exceeds the maximum +pool size set by +.Fn pool_cache_sethiwat +and there are no outstanding requests for pool items, +the excess items will be returned to the system. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_put "pc" "object" +.Pp +.Fn pool_cache_put +is the same as +.Fn pool_cache_put_paddr +with +.Dv POOL_PADDR_INVALID +.Fa pa +argument. +It's implemented as a macro. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_destruct_object "pc" "object" +.Pp +Force destruction of an object +.Fa object +and release it back into the pool. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_invalidate "pc" +.Pp +Invalidate a pool cache +.Fa pc . +All objects in the cache will be destructed and freed back to the pool +backing the cache. +For pool caches that vend constructed objects, consumers of this API +must take care to provide proper synchronization between the input to +the constructor and cache invalidation. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_sethiwat "pc" "n" +.Pp +A pool will attempt to increase its resource usage to keep up with the demand +for its items. +Conversely, +it will return unused memory to the system should the number of accumulated +free items in the pool exceed a programmable limit. +The limits for the minimum and maximum number of free items which a pool should +try to keep available are known as the high and low +.Sy watermarks . +.Pp +The function +.Fn pool_cache_sethiwat +sets the backing pool's high water mark. +As items are freed and the number of free items in the pool is larger +than the maximum set by this function, +any completely unused pages are released immediately. +If this function is not used to specify a maximum number of items, +the pages will remain associated with the pool until the system runs low +on memory, +at which point the VM system will try to reclaim unused pages. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_setlowat "pc" "n" +.Pp +Set the minimum number of free items to try to keep in the pool. +When the number of free items in the pool drops below this threshold, +a non-blocking attempt is made to allocate memory for more items. +The number of free items is not guaranteed to remain above this threshold. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_sethardlimit "pc" "n" "warnmess" "ratecap" +Set the maximum number of total items (both free and allocated) for the backing +.Xr pool 9 +to +.Fa n . +When the hard limit is reached, the warning message +.Fa warnmess +will be logged. +.Fa ratecap +represents the minimal interval (in seconds) after which another warning +message is issued when the pool hits its hard limit again. +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.It Fn pool_cache_prime "pc" "n" +Set the minimum number of total items (both free and allocated) for the backing +.Xr pool 9 +to +.Fa n . +.El +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within the file +.Pa sys/kern/subr_pool.c . +.Sh SEE ALSO +.Xr intro 9 , +.Xr kmem 9 , +.Xr memoryallocators 9 , +.Xr percpu 9 , +.Xr pool 9 |