NetBSD/share/man/man9/memoryallocators.9

134 lines
4.2 KiB
Groff

.\" $NetBSD: memoryallocators.9,v 1.3 2007/01/09 12:49:36 elad 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 January 7, 2007
.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.
.Ss The Malloc Allocator
The
.Xr malloc 9
allocator can be used for variable-sized allocations in the kernel address
space.
It is interrupt-safe, requires no setup (see below), and is considered to be
stable (given the number of years it has been in the kernel).
.Pp
This interface also allows associating a
.Dq type
with an allocation to indicate what subsystem is using the memory allocated,
thus providing statistics as to the memory usage of different kernel subsystems.
To define a type, one should use the
.Dv MALLOC_DEFINE
macro, otherwise, one of the built-in types, like
.Dv M_TEMP
can be used.
.Pp
See
.Xr malloc 9
for more details.
.Ss The Kmem Allocator
The kmem allocator is modelled after an interface of similar name implemented in
Solaris, and is under active development.
.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.
.Pp
Like
.Xr malloc 9 ,
it requires no setup, but can't be used yet from interrupt context.
.Pp
See
.Xr kmem_alloc 9 ,
.Xr kmem_zalloc 9 ,
and
.Xr kmem_free 9
for more details.
.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.
.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
.Xr pool 9
allocator, also allowing fixed-size allocation only, requires setup,
and is interrupt-safe.
.Pp
The pool cache allocator is expected to be faster than other allocators,
including the
.Dq normal
pool allocator.
.Pp
In the future this allocator is expected to have a per-CPU cache.
.Pp
See
.Xr pool_cache 9
for more details.
.Ss The UVM Kernel Memory Allocator
This is a low-level memory allocator interface.
It allows variable-sized allocations 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.
.Sh SEE ALSO
.Xr free 9 ,
.Xr intro 9 ,
.Xr kmem_alloc 9 ,
.Xr kmem_free 9 ,
.Xr kmem_zalloc 9 ,
.Xr malloc 9 ,
.Xr pool 9 ,
.Xr pool_cache 9 ,
.Xr uvm 9 ,
.Xr vmem 9
.Sh AUTHORS
.An Elad Efrat Aq elad@NetBSD.org
.An YAMAMOTO Takashi Aq yamt@NetBSD.org