.\" $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