1 files changed, 164 insertions, 0 deletions
diff --git a/static/netbsd/man9/memoryallocators.9 b/static/netbsd/man9/memoryallocators.9
new file mode 100644
index 00000000..4ab06679
--- /dev/null
+++ b/static/netbsd/man9/memoryallocators.9
@@ -0,0 +1,164 @@
+.\" $NetBSD: memoryallocators.9,v 1.8 2017/10/29 03:48:17 riastradh Exp $
+.\"
+.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org>
+.\" 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.
+.\" 3. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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 October 28, 2017
+.Dt MEMORYALLOCATORS 9
+.Os
+.Sh NAME
+.Nm memoryallocators
+.Nd introduction to kernel memory allocators
+.Sh DESCRIPTION
+The
+.Nx
+kernel provides several memory allocators, each with different characteristics
+and purpose.
+This document summarizes the main differences between them.
+.Pp
+You should use the
+.Xr kmem 9
+allocator for all allocations unless you have special needs that it
+does not provide, such as:
+.Bl -bullet -compact
+.It
+use from interrupt handlers
+.It
+a minimum reserved number of allocations
+.It
+a maximum usable number of allocations
+.It
+costly object initialization that can be reused
+.It
+allocating resources other than pageable RAM-backed kernel virtual
+address space
+.El
+.Ss The Kmem Allocator
+The
+.Xr kmem 9
+allocator is main general purpose allocator in the kernel.
+It was modelled after an interface of the same name implemented
+in Solaris.
+.Pp
+.Xr kmem 9
+is fast and requires no setup.
+It cannot be used from interrupt context.
+.Pp
+Internally,
+.Xr kmem 9
+is implemented using a collection of pool caches for common small
+allocation sizes, so there is no performance benefit to using a pool
+cache if you have no other needs.
+.Ss The Pool Allocator
+The
+.Xr pool 9
+allocator is a fixed-size memory allocator which requires setup to
+initialize a shared pool.
+.Pp
+A pool can be configured with a low-water mark to reserve a minimum
+number of objects available, a high-water mark to bound the maximum number of
+objects in reserve, and a hard limit to bound on the maximum number of
+objects in use.
+.Pp
+.Xr pool_get 9
+can be used to allocate memory in interrupt context for objects that
+have been reserved in advance, with the possibility of failure if there
+are none.
+.Pp
+By default,
+.Xr pool 9
+allocates pageable RAM-backed kernel virtual address space from the
+same backing store as
+.Xr kmem 9 ,
+but it can be configured to allocate any kind of resource with a custom
+allocator.
+.\".Pp
+.\" On some architectures (foo, bar) the
+.\" .Xr pool 9
+.\" allocator will use direct-mapped segments rather than normal page
+.\" mappings, which can reduce TLB contentions.
+.Ss The Pool Cache Allocator
+The pool cache allocator is a per-CPU cache on top of
+.Xr pool 9
+for fixed-size memory allocations that may occur in interrupt context
+requiring setup beforehand.
+.Pp
+The per-CPU cache makes allocation much cheaper \(em no interprocessor
+synchronization in the fast case \(em at the cost of potentially
+caching some extra resources on one CPU that cannot be used by another.
+.Pp
+In addition to all the features of a pool like a custom backing
+allocator, a pool cache also supports a constructor and destructor
+routine for when objects are drawn from the shared pool in case the
+per-CPU cache is empty, or returned to it when the cache is full.
+This can reduce the cost of reusable initialization and finalization,
+or associate objects with CPU-local resources.
+.Ss The UVM Kernel Memory Allocator
+The
+.Xr uvm_km 9
+API is a low-level memory allocator for page-aligned kernel virtual
+address space in multiples of
+.Dv PAGE_SIZE ,
+with wired RAM backing, pageable RAM backing, or backing to be supplied
+by the caller with
+.Xr pmap 9 .
+.Ss The VMEM Allocator API
+The
+.Xr vmem 9
+API is a general address space allocator.
+It is used internally by
+.Xr kmem 9 ,
+.Xr pool 9 ,
+.Xr uvm 9 ,
+and other kernel subsystems and device drivers to allocate regions of
+various kinds of address spaces.
+Internally, it allocates large chunks of the address space and uses a
+.Xr pool_cache 9
+to draw small allocations out of them.
+.Ss The Extent Manager
+The
+.Xr extent 9
+API manages and allocates constrained regions of an address space.
+The extent manager is optimized for simplicity, not speed, and is
+available early at boot.
+.Nx
+uses
+.Xr extent 9
+to reserve regions of I/O port and memory spaces to prevent drivers
+from using the same device registers or bus memory.
+.Sh SEE ALSO
+.Xr bus_space 9 ,
+.Xr extent 9 ,
+.Xr intro 9 ,
+.Xr kmem 9 ,
+.Xr pool 9 ,
+.Xr pool_cache 9 ,
+.Xr uvm 9 ,
+.Xr uvm_km 9 ,
+.Xr vmem 9
+.Sh AUTHORS
+.An Elad Efrat Aq Mt elad@NetBSD.org
+.An YAMAMOTO Takashi Aq Mt yamt@NetBSD.org
+.An Taylor R Campbell Aq Mt riastradh@NetBSD.org