[src/trunk]: src/share/man/man9 Rework memory allocators summary.

[riastradh <riastradh%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/739824a80d06
branches:  trunk
changeset: 827444:739824a80d06
user:      riastradh <riastradh%NetBSD.org@localhost>
date:      Sat Oct 28 17:40:45 2017 +0000

description:
Rework memory allocators summary.

Recommend kmem(9) for everything that doesn't have special needs.

Note vmem(9) and extent(9) too.

diffstat:

 share/man/man9/memoryallocators.9 |  138 +++++++++++++++++++++++++++----------
 1 files changed, 99 insertions(+), 39 deletions(-)

diffs (184 lines):

diff -r 395fb6716c3e -r 739824a80d06 share/man/man9/memoryallocators.9
--- a/share/man/man9/memoryallocators.9 Sat Oct 28 17:06:43 2017 +0000
+++ b/share/man/man9/memoryallocators.9 Sat Oct 28 17:40:45 2017 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: memoryallocators.9,v 1.6 2014/03/18 18:20:40 riastradh Exp $
+.\" $NetBSD: memoryallocators.9,v 1.7 2017/10/28 17:40:45 riastradh Exp $
 .\"
 .\" Copyright (c) 2006 Elad Efrat <elad%NetBSD.org@localhost>
 .\" All rights reserved.
@@ -25,7 +25,7 @@
 .\" (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 August 3, 2009
+.Dd October 28, 2017
 .Dt MEMORYALLOCATORS 9
 .Os
 .Sh NAME
@@ -37,68 +37,128 @@
 kernel provides several memory allocators, each with different characteristics
 and purpose.
 This document summarizes the main differences between them.
-.Ss The Kmem Allocator
-The kmem allocator is modelled after an interface of similar name implemented in
-Solaris.
-This is main general purpose allocator in the kernel.
 .Pp
-It is implemented on-top of the
-.Xr vmem 9
-resource allocator (beyond the scope of this document), meaning it will be using
-.Xr pool_cache 9
-internally to speed-up common (small) sized allocations.
+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-packed 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
-It requires no setup, but cannot be used from interrupt context.
+.Xr kmem 9
+is fast and requires no setup.
+It cannot be used from interrupt context.
 .Pp
-See
+Internally,
 .Xr kmem 9
-for more details.
+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.
-It requires setup (to initialize a memory pool) and is interrupt-safe.
+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.
-.\".Pp
-See
-.Xr pool 9
-for more details.
 .Ss The Pool Cache Allocator
-The pool cache allocator works on-top of the
+The pool cache allocator is a per-CPU cache on top of
 .Xr pool 9
-allocator, also allowing fixed-size allocation only, requires setup,
-and is interrupt-safe.
+for fixed-size memory allocations that may occur in interrupt context
+requiring setup beforehand.
 .Pp
-The pool cache allocator is expected to be faster than other allocators,
-including the
-.Dq normal
-pool allocator.
+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 the future this allocator is expected to have a per-CPU cache.
-.Pp
-See
-.Xr pool_cache 9
-for more details.
+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
-This is a low-level memory allocator interface.
-It allows variable-sized allocations in multiples of
+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 ,
-and can be used to allocate both wired and pageable kernel memory.
-.Pp
-See
-.Xr uvm 9
-for more details.
+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@localhost
 .An YAMAMOTO Takashi Aq Mt yamt%NetBSD.org@localhost
+.An Taylor R Campbell Aq Mt riastradh%NetBSD.org@localhost