1.\" $NetBSD: pool_cache.9,v 1.18 2011/06/01 20:49:22 dyoung Exp $ 2.\" 3.\" Copyright (c)2003 YAMAMOTO Takashi, 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" Copyright (c) 1997, 1999, 2000, 2007, 2008 The NetBSD Foundation, Inc. 28.\" All rights reserved. 29.\" 30.\" This code is derived from software contributed to The NetBSD Foundation 31.\" by Paul Kranenburg; by Jason R. Thorpe of the Numerical Aerospace 32.\" Simulation Facility, NASA Ames Research Center, and by Andrew Doran. 33.\" 34.\" Redistribution and use in source and binary forms, with or without 35.\" modification, are permitted provided that the following conditions 36.\" are met: 37.\" 1. Redistributions of source code must retain the above copyright 38.\" notice, this list of conditions and the following disclaimer. 39.\" 2. Redistributions in binary form must reproduce the above copyright 40.\" notice, this list of conditions and the following disclaimer in the 41.\" documentation and/or other materials provided with the distribution. 42.\" 43.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 44.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 45.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 46.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 47.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 48.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 49.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 50.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 51.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 52.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 53.\" POSSIBILITY OF SUCH DAMAGE. 54.\" 55.\" ------------------------------------------------------------ 56.Dd June 1, 2011 57.Dt POOL_CACHE 9 58.Os 59.\" ------------------------------------------------------------ 60.Sh NAME 61.Nm pool_cache , 62.Nm pool_cache_init , 63.Nm pool_cache_destroy , 64.Nm pool_cache_get_paddr , 65.Nm pool_cache_get , 66.Nm pool_cache_put_paddr , 67.Nm pool_cache_put , 68.Nm pool_cache_destruct_object , 69.Nm pool_cache_invalidate , 70.Nm pool_cache_sethiwat , 71.Nm pool_cache_setlowat 72.Nd resource-pool cache manager 73.\" ------------------------------------------------------------ 74.Sh SYNOPSIS 75.In sys/pool.h 76.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 77.Ft pool_cache_t 78.Fn pool_cache_init \ 79"size_t size" "u_int align" "u_int align_offset" "int flags" \ 80"const char *name" "struct pool_allocator *palloc" "int ipl" \ 81"int (*ctor)(void *, void *, int)" "void (*dtor)(void *, void *)" "void *arg" 82.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 83.Ft void 84.Fn pool_cache_destroy \ 85"pool_cache_t pc" 86.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 87.Ft void * 88.Fn pool_cache_get_paddr \ 89"pool_cache_t pc" "int flags" "paddr_t *pap" 90.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 91.Ft void * 92.Fn pool_cache_get \ 93"pool_cache_t pc" "int flags" 94.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 95.Ft void 96.Fn pool_cache_put_paddr \ 97"pool_cache_t pc" "void *object" "paddr_t pa" 98.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 99.Ft void 100.Fn pool_cache_put \ 101"pool_cache_t pc" "void *object" 102.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 103.Ft void 104.Fn pool_cache_destruct_object \ 105"pool_cache_t pc" "void *object" 106.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 107.Ft void 108.Fn pool_cache_invalidate \ 109"pool_cache_t pc" 110.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 111.Ft void 112.Fn pool_cache_sethiwat \ 113"pool_cache_t pc" "int nitems" 114.Ft void 115.Fn pool_cache_setlowat \ 116"pool_cache_t pc" "int nitems" 117.\" ------------------------------------------------------------ 118.Sh DESCRIPTION 119These utility routines provide management of pools of fixed-sized 120areas of memory. 121Resource pools set aside an amount of memory for exclusive use by the resource 122pool owner. 123This can be used by applications to guarantee the availability of a minimum 124amount of memory needed to continue operation independent of the memory 125resources currently available from the system-wide memory allocator. 126.Pp 127Global and per-CPU caches of constructed objects are maintained. 128The two levels of cache work together to allow for low overhead 129allocation and release of objects, and improved L1/L2/L3 hardware 130cache locality in multiprocessor systems. 131.\" ------------------------------------------------------------ 132.Sh FUNCTIONS 133.Bl -tag -width compact 134.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 135.It Fn pool_cache_init "size" "align" "align_offset" "flags" \ 136"name" "palloc" "ipl" "ctor" "dtor" "arg" 137.Pp 138Allocate and initialize a pool cache. 139The arguments are: 140.Pp 141.Bl -tag -width four 142.It Fa size 143.Pp 144Specifies the size of the memory items managed by the pool. 145.It Fa align 146.Pp 147Specifies the memory address alignment of the items returned by 148.Fn pool_cache_get . 149This argument must be a power of two. 150If zero, 151the alignment defaults to an architecture-specific natural alignment. 152.It Fa align_offset 153.Pp 154The offset within an item to which the 155.Fa align 156parameter applies. 157.It Fa flags 158.Pp 159Should be set to zero or 160.Dv PR_NOTOUCH . 161If 162.Dv PR_NOTOUCH 163is given, free items are never used to keep internal state so that 164the pool can be used for non memory backed objects. 165.It Fa name 166.Pp 167The name used to identify the object in diagnostic output. 168.It Fa palloc 169.Pp 170Should be typically be set to NULL, instructing 171.Fn pool_cache_init 172to select an appropriate back-end allocator. 173Alternate allocators can be used to partition space from arbitrary sources. 174Use of alternate allocators is not documented here as it is not a stable, 175endorsed part of the API. 176.It Fa ipl 177.Pp 178Specifies an interrupt priority level that will block all interrupt 179handlers that could potentially access the pool. 180The 181.Nm 182facility provides its own synchronization. 183The users of any given 184.Nm 185need not provide additional synchronization for access to it. 186.It Fa ctor 187.Pp 188Specifies a constructor used to initialize newly allocated objects. 189If no constructor is required, specify 190.Dv NULL . 191The first argument to 192.Fa ctor 193is 194.Fa arg , 195the second is the new object, and the third is 196.Fa flags . 197.It Fa dtor 198.Pp 199Specifies a destructor used to destroy cached objects prior to 200their release to backing store. 201If no destructor is required, specify 202.Dv NULL . 203The first argument to 204.Fa dtor 205is 206.Fa arg , 207and the second is the object. 208.It Fa arg 209.Pp 210This value of this argument will be passed to both the constructor 211and destructor routines. 212.El 213.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 214.It Fn pool_cache_destroy "pc" 215.Pp 216Destroy a pool cache 217.Fa pc . 218All other access to the cache must be stopped before this call 219can be made. 220.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 221.It Fn pool_cache_get_paddr "pc" "flags" "pap" 222.Pp 223Get an object from a pool cache 224.Fa pc . 225If 226.Fa pap 227is not 228.Dv NULL , 229physical address of the object or 230.Dv POOL_PADDR_INVALID 231will be returned via it. 232.Fa flags 233will be passed to 234.Fn pool_get 235function of the backing 236.Xr pool 9 237and the object constructor specified when the pool cache is created by 238.Fn pool_cache_init . 239.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 240.It Fn pool_cache_get "pc" "flags" 241.Pp 242.Fn pool_cache_get 243is the same as 244.Fn pool_cache_get_paddr 245with 246.Dv NULL 247.Fa pap 248argument. 249It's implemented as a macro. 250.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 251.It Fn pool_cache_put_paddr "pc" "object" "pa" 252.Pp 253Put an object 254.Fa object 255back to the pool cache 256.Fa pc . 257.Fa pa 258should be physical address of the object 259.Fa object 260or 261.Dv POOL_PADDR_INVALID . 262.Fa pp . 263If the number of available items in the backing pool exceeds the maximum 264pool size set by 265.Fn pool_cache_sethiwat 266and there are no outstanding requests for pool items, 267the excess items will be returned to the system. 268.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 269.It Fn pool_cache_put "pc" "object" 270.Pp 271.Fn pool_cache_put 272is the same as 273.Fn pool_cache_put_paddr 274with 275.Dv POOL_PADDR_INVALID 276.Fa pa 277argument. 278It's implemented as a macro. 279.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 280.It Fn pool_cache_destruct_object "pc" "object" 281.Pp 282Force destruction of an object 283.Fa object 284and its release back into the pool. 285.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 286.It Fn pool_cache_invalidate "pc" 287.Pp 288Invalidate a pool cache 289.Fa pc . 290All objects in the cache will be destructed and freed back to the pool 291backing the cache. 292For pool caches that vend constructed objects, consumers of this API 293must take care to provide proper synchronization between the input to 294the constructor and cache invalidation. 295.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 296.It Fn pool_cache_sethiwat "pc" "nitems" 297.Pp 298A pool will attempt to increase its resource usage to keep up with the demand 299for its items. 300Conversely, 301it will return unused memory to the system should the number of accumulated 302unused items in the pool exceed a programmable limit. 303The limits for the minimum and maximum number of items which a pool should keep 304at hand are known as the high and low 305.Sy watermarks . 306.Pp 307The function 308.Fn pool_cache_sethiwat 309sets the backing pool's high water mark. 310As items are returned and the total number of pages in the pool is larger 311than the maximum set by this function, 312any completely unused pages are released immediately. 313If this function is not used to specify a maximum number of items, 314the pages will remain associated with the pool until the system runs low 315on memory, 316at which point the VM system will try to reclaim unused pages. 317.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 318.It Fn pool_cache_setlowat "pc" "nitems" 319.Pp 320Set the minimum number of items to keep in the pool. 321The number pages in the pool will not decrease below the required value to 322accommodate the minimum number of items specified by this function. 323.El 324.\" ------------------------------------------------------------ 325.Sh CODE REFERENCES 326The 327.Nm 328subsystem is implemented within the file 329.Pa sys/kern/subr_pool.c . 330.Sh SEE ALSO 331.Xr intro 9 , 332.Xr kmem 9 , 333.Xr memoryallocators 9 , 334.Xr percpu 9 , 335.Xr pool 9 336