Module Name: src Committed By: riastradh Date: Sat Oct 28 17:40:45 UTC 2017
Modified Files: src/share/man/man9: memoryallocators.9 Log Message: Rework memory allocators summary. Recommend kmem(9) for everything that doesn't have special needs. Note vmem(9) and extent(9) too. To generate a diff of this commit: cvs rdiff -u -r1.6 -r1.7 src/share/man/man9/memoryallocators.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/share/man/man9/memoryallocators.9 diff -u src/share/man/man9/memoryallocators.9:1.6 src/share/man/man9/memoryallocators.9:1.7 --- src/share/man/man9/memoryallocators.9:1.6 Tue Mar 18 18:20:40 2014 +++ src/share/man/man9/memoryallocators.9 Sat Oct 28 17:40:45 2017 @@ -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 <e...@netbsd.org> .\" 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 @@ The 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. -.Pp -In the future this allocator is expected to have a per-CPU cache. -.Pp -See -.Xr pool_cache 9 -for more details. +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 -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 e...@netbsd.org .An YAMAMOTO Takashi Aq Mt y...@netbsd.org +.An Taylor R Campbell Aq Mt riastr...@netbsd.org