1.\" $NetBSD: memoryallocators.9,v 1.8 2017/10/29 03:48:17 riastradh Exp $ 2.\" 3.\" Copyright (c) 2006 Elad Efrat <elad@NetBSD.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote products 15.\" derived from this software without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 18.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 19.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 20.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 21.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 22.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 23.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 24.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 26.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.Dd October 28, 2017 29.Dt MEMORYALLOCATORS 9 30.Os 31.Sh NAME 32.Nm memoryallocators 33.Nd introduction to kernel memory allocators 34.Sh DESCRIPTION 35The 36.Nx 37kernel provides several memory allocators, each with different characteristics 38and purpose. 39This document summarizes the main differences between them. 40.Pp 41You should use the 42.Xr kmem 9 43allocator for all allocations unless you have special needs that it 44does not provide, such as: 45.Bl -bullet -compact 46.It 47use from interrupt handlers 48.It 49a minimum reserved number of allocations 50.It 51a maximum usable number of allocations 52.It 53costly object initialization that can be reused 54.It 55allocating resources other than pageable RAM-backed kernel virtual 56address space 57.El 58.Ss The Kmem Allocator 59The 60.Xr kmem 9 61allocator is main general purpose allocator in the kernel. 62It was modelled after an interface of the same name implemented 63in Solaris. 64.Pp 65.Xr kmem 9 66is fast and requires no setup. 67It cannot be used from interrupt context. 68.Pp 69Internally, 70.Xr kmem 9 71is implemented using a collection of pool caches for common small 72allocation sizes, so there is no performance benefit to using a pool 73cache if you have no other needs. 74.Ss The Pool Allocator 75The 76.Xr pool 9 77allocator is a fixed-size memory allocator which requires setup to 78initialize a shared pool. 79.Pp 80A pool can be configured with a low-water mark to reserve a minimum 81number of objects available, a high-water mark to bound the maximum number of 82objects in reserve, and a hard limit to bound on the maximum number of 83objects in use. 84.Pp 85.Xr pool_get 9 86can be used to allocate memory in interrupt context for objects that 87have been reserved in advance, with the possibility of failure if there 88are none. 89.Pp 90By default, 91.Xr pool 9 92allocates pageable RAM-backed kernel virtual address space from the 93same backing store as 94.Xr kmem 9 , 95but it can be configured to allocate any kind of resource with a custom 96allocator. 97.\".Pp 98.\" On some architectures (foo, bar) the 99.\" .Xr pool 9 100.\" allocator will use direct-mapped segments rather than normal page 101.\" mappings, which can reduce TLB contentions. 102.Ss The Pool Cache Allocator 103The pool cache allocator is a per-CPU cache on top of 104.Xr pool 9 105for fixed-size memory allocations that may occur in interrupt context 106requiring setup beforehand. 107.Pp 108The per-CPU cache makes allocation much cheaper \(em no interprocessor 109synchronization in the fast case \(em at the cost of potentially 110caching some extra resources on one CPU that cannot be used by another. 111.Pp 112In addition to all the features of a pool like a custom backing 113allocator, a pool cache also supports a constructor and destructor 114routine for when objects are drawn from the shared pool in case the 115per-CPU cache is empty, or returned to it when the cache is full. 116This can reduce the cost of reusable initialization and finalization, 117or associate objects with CPU-local resources. 118.Ss The UVM Kernel Memory Allocator 119The 120.Xr uvm_km 9 121API is a low-level memory allocator for page-aligned kernel virtual 122address space in multiples of 123.Dv PAGE_SIZE , 124with wired RAM backing, pageable RAM backing, or backing to be supplied 125by the caller with 126.Xr pmap 9 . 127.Ss The VMEM Allocator API 128The 129.Xr vmem 9 130API is a general address space allocator. 131It is used internally by 132.Xr kmem 9 , 133.Xr pool 9 , 134.Xr uvm 9 , 135and other kernel subsystems and device drivers to allocate regions of 136various kinds of address spaces. 137Internally, it allocates large chunks of the address space and uses a 138.Xr pool_cache 9 139to draw small allocations out of them. 140.Ss The Extent Manager 141The 142.Xr extent 9 143API manages and allocates constrained regions of an address space. 144The extent manager is optimized for simplicity, not speed, and is 145available early at boot. 146.Nx 147uses 148.Xr extent 9 149to reserve regions of I/O port and memory spaces to prevent drivers 150from using the same device registers or bus memory. 151.Sh SEE ALSO 152.Xr bus_space 9 , 153.Xr extent 9 , 154.Xr intro 9 , 155.Xr kmem 9 , 156.Xr pool 9 , 157.Xr pool_cache 9 , 158.Xr uvm 9 , 159.Xr uvm_km 9 , 160.Xr vmem 9 161.Sh AUTHORS 162.An Elad Efrat Aq Mt elad@NetBSD.org 163.An YAMAMOTO Takashi Aq Mt yamt@NetBSD.org 164.An Taylor R Campbell Aq Mt riastradh@NetBSD.org 165