feat: Added NetBSD man pages

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