1.\" $NetBSD: kmem.9,v 1.12 2011/01/08 18:07:14 jym Exp $ 2.\" 3.\" Copyright (c)2006 YAMAMOTO Takashi, 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.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" ------------------------------------------------------------ 28.Dd May 16, 2010 29.Dt KMEM 9 30.Os 31.\" ------------------------------------------------------------ 32.Sh NAME 33.Nm kmem 34.Nd kernel wired memory allocator 35.\" ------------------------------------------------------------ 36.Sh SYNOPSIS 37.In sys/kmem.h 38.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 39.Ft void * 40.Fn kmem_alloc \ 41"size_t size" "km_flag_t kmflags" 42.Ft void * 43.Fn kmem_zalloc \ 44"size_t size" "km_flag_t kmflags" 45.Ft void 46.Fn kmem_free \ 47"void *p" "size_t size" 48.Ft char * 49.Fn kmem_asprintf \ 50"const char *fmt" "..." 51.\" ------------------------------------------------------------ 52.Pp 53.Cd "options DEBUG" 54.Sh DESCRIPTION 55.Fn kmem_alloc 56allocates kernel wired memory. 57It takes the following arguments. 58.Bl -tag -width kmflags 59.It Fa size 60Specify the size of allocation in bytes. 61.It Fa kmflags 62Either of the following: 63.Bl -tag -width KM_NOSLEEP 64.It KM_SLEEP 65If the allocation cannot be satisfied immediately, sleep until enough 66memory is available. 67.It KM_NOSLEEP 68Don't sleep. 69Immediately return 70.Dv NULL 71if there is not enough memory available. 72It should only be used when failure to allocate will not have harmful, 73user-visible effects. 74.Pp 75.Bf -symbolic 76Use of 77.Dv KM_NOSLEEP 78is strongly discouraged as it can create transient, hard to debug failures 79that occur when the system is under memory pressure. 80.Ef 81.Pp 82In situations where it is not possible to sleep, for example because locks 83are held by the caller, the code path should be restructured to allow the 84allocation to be made in another place. 85.El 86.El 87.Pp 88The contents of allocated memory are uninitialized. 89.Pp 90Unlike Solaris, kmem_alloc(0, flags) is illegal. 91.Pp 92.\" ------------------------------------------------------------ 93.Fn kmem_zalloc 94is the equivalent of 95.Fn kmem_alloc , 96except that it initializes the memory to zero. 97.Pp 98.\" ------------------------------------------------------------ 99.Fn kmem_asprintf 100functions as the well known 101.Fn asprintf 102function, but allocates memory using 103.Fn kmem_alloc . 104This routine can sleep during allocation. 105The size of the allocated area is the length of the returned character string, plus one (for the NUL terminator). 106This must be taken into consideration when freeing the returned area with 107.Fn kmem_free . 108.Pp 109.\" ------------------------------------------------------------ 110.Fn kmem_free 111frees kernel wired memory allocated by 112.Fn kmem_alloc 113or 114.Fn kmem_zalloc 115so that it can be used for other purposes. 116It takes the following arguments. 117.Bl -tag -width kmflags 118.It Fa p 119The pointer to the memory being freed. 120It must be the one returned by 121.Fn kmem_alloc 122or 123.Fn kmem_zalloc . 124.It Fa size 125The size of the memory being freed, in bytes. 126It must be the same as the 127.Fa size 128argument used for 129.Fn kmem_alloc 130or 131.Fn kmem_zalloc 132when the memory was allocated. 133.El 134.Pp 135Freeing 136.Dv NULL 137is illegal. 138.\" ------------------------------------------------------------ 139.Sh NOTES 140Making 141.Dv KM_SLEEP 142allocations while holding mutexes or reader/writer locks is discouraged, as the 143caller can sleep for an unbounded amount of time in order to satisfy the 144allocation. 145This can in turn block other threads that wish to acquire locks held by the 146caller. 147It should be noted that 148.Fn kmem_free 149may also block. 150.Pp 151For some locks this is permissible or even unavoidable. 152For others, particularly locks that may be taken from soft interrupt context, 153it is a serious problem. 154As a general rule it is better not to allow this type of situation to develop. 155One way to circumvent the problem is to make allocations speculative and part 156of a retryable sequence. 157For example: 158.Bd -literal 159 retry: 160 /* speculative unlocked check */ 161 if (need to allocate) { 162 new_item = kmem_alloc(sizeof(*new_item), KM_SLEEP); 163 } else { 164 new_item = NULL; 165 } 166 mutex_enter(lock); 167 /* check while holding lock for true status */ 168 if (need to allocate) { 169 if (new_item == NULL) { 170 mutex_exit(lock); 171 goto retry; 172 } 173 consume(new_item); 174 new_item = NULL; 175 } 176 mutex_exit(lock); 177 if (new_item != NULL) { 178 /* did not use it after all */ 179 kmem_free(new_item, sizeof(*new_item)); 180 } 181.Ed 182.\" ------------------------------------------------------------ 183.Sh OPTIONS 184Kernels compiled with the 185.Dv DEBUG 186option perform CPU intensive sanity checks on kmem operations, 187and include the 188.Dv kmguard 189facility which can be enabled at runtime. 190.Pp 191.Dv kmguard 192adds additional, very high overhead runtime verification to kmem operations. 193To enable it, boot the system with the 194.Fl d 195option, which causes the debugger to be entered early during the kernel 196boot process. 197Issue commands such as the following: 198.Bd -literal 199db\*[Gt] w kmem_guard_depth 0t30000 200db\*[Gt] c 201.Ed 202.Pp 203This instructs 204.Dv kmguard 205to queue up to 60000 (30000*2) pages of unmapped KVA to catch 206use-after-free type errors. 207When 208.Fn kmem_free 209is called, memory backing a freed item is unmapped and the kernel VA 210space pushed onto a FIFO. 211The VA space will not be reused until another 30k items have been freed. 212Until reused the kernel will catch invalid accesses and panic with a page fault. 213Limitations: 214.Bl -bullet 215.It 216It has a severe impact on performance. 217.It 218It is best used on a 64-bit machine with lots of RAM. 219.It 220Allocations larger than PAGE_SIZE bypass the 221.Dv kmguard 222facility. 223.El 224.Pp 225kmguard tries to catch the following types of bugs: 226.Bl -bullet 227.It 228Overflow at time of occurrence, by means of a guard page. 229.It 230Underflow at 231.Fn kmem_free , 232by using a canary value. 233.It 234Invalid pointer or size passed, at 235.Fn kmem_free . 236.El 237.Sh RETURN VALUES 238On success, 239.Fn kmem_alloc 240and 241.Fn kmem_zalloc 242return a pointer to allocated memory. 243Otherwise, 244.Dv NULL 245is returned. 246.\" ------------------------------------------------------------ 247.Sh CODE REFERENCES 248The 249.Nm 250subsystem is implemented within the file 251.Pa sys/kern/subr_kmem.c . 252.\" ------------------------------------------------------------ 253.Sh SEE ALSO 254.Xr intro 9 , 255.Xr memoryallocators 9 , 256.Xr percpu 9 , 257.Xr pool_cache 9 258.\" ------------------------------------------------------------ 259.Sh CAVEATS 260Neither 261.Fn kmem_alloc 262nor 263.Fn kmem_free 264can be used from interrupt context, from a soft interrupt, or from 265a callout. 266Use 267.Xr pool_cache 9 268in these situations. 269.\" ------------------------------------------------------------ 270.Sh SECURITY CONSIDERATIONS 271As the memory allocated by 272.Fn kmem_alloc 273is uninitialized, it can contain security-sensitive data left by its 274previous user. 275It is the caller's responsibility not to expose it to the world. 276