1.\" $NetBSD: kmem.9,v 1.14 2013/11/26 20:47:26 rmind 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 November 26, 2013 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.\" --- 49.Ft void * 50.Fn kmem_intr_alloc \ 51"size_t size" "km_flag_t kmflags" 52.Ft void * 53.Fn kmem_intr_zalloc \ 54"size_t size" "km_flag_t kmflags" 55.Ft void 56.Fn kmem_intr_free \ 57"void *p" "size_t size" 58.\" --- 59.Ft char * 60.Fn kmem_asprintf \ 61"const char *fmt" "..." 62.\" ------------------------------------------------------------ 63.Pp 64.Cd "options DEBUG" 65.Sh DESCRIPTION 66.Fn kmem_alloc 67allocates kernel wired memory. 68It takes the following arguments. 69.Bl -tag -width kmflags 70.It Fa size 71Specify the size of allocation in bytes. 72.It Fa kmflags 73Either of the following: 74.Bl -tag -width KM_NOSLEEP 75.It KM_SLEEP 76If the allocation cannot be satisfied immediately, sleep until enough 77memory is available. 78.It KM_NOSLEEP 79Don't sleep. 80Immediately return 81.Dv NULL 82if there is not enough memory available. 83It should only be used when failure to allocate will not have harmful, 84user-visible effects. 85.Pp 86.Bf -symbolic 87Use of 88.Dv KM_NOSLEEP 89is strongly discouraged as it can create transient, hard to debug failures 90that occur when the system is under memory pressure. 91.Ef 92.Pp 93In situations where it is not possible to sleep, for example because locks 94are held by the caller, the code path should be restructured to allow the 95allocation to be made in another place. 96.El 97.El 98.Pp 99The contents of allocated memory are uninitialized. 100.Pp 101Unlike Solaris, kmem_alloc(0, flags) is illegal. 102.Pp 103.\" ------------------------------------------------------------ 104.Fn kmem_zalloc 105is the equivalent of 106.Fn kmem_alloc , 107except that it initializes the memory to zero. 108.Pp 109.\" ------------------------------------------------------------ 110.Fn kmem_asprintf 111functions as the well known 112.Fn asprintf 113function, but allocates memory using 114.Fn kmem_alloc . 115This routine can sleep during allocation. 116The size of the allocated area is the length of the returned character string, plus one (for the NUL terminator). 117This must be taken into consideration when freeing the returned area with 118.Fn kmem_free . 119.Pp 120.\" ------------------------------------------------------------ 121.Fn kmem_free 122frees kernel wired memory allocated by 123.Fn kmem_alloc 124or 125.Fn kmem_zalloc 126so that it can be used for other purposes. 127It takes the following arguments. 128.Bl -tag -width kmflags 129.It Fa p 130The pointer to the memory being freed. 131It must be the one returned by 132.Fn kmem_alloc 133or 134.Fn kmem_zalloc . 135.It Fa size 136The size of the memory being freed, in bytes. 137It must be the same as the 138.Fa size 139argument used for 140.Fn kmem_alloc 141or 142.Fn kmem_zalloc 143when the memory was allocated. 144.El 145.Pp 146Freeing 147.Dv NULL 148is illegal. 149.Pp 150.\" ------------------------------------------------------------ 151.Fn kmem_intr_alloc , 152.Fn kmem_intr_zalloc 153and 154.Fn kmem_intr_free 155are the equivalents of the above kmem routines which can be called 156from the interrupt context. 157These routines are for the special cases. 158Normally, 159.Xr pool_cache 9 160should be used for memory allocation from interrupt context. 161.\" ------------------------------------------------------------ 162.Sh NOTES 163Making 164.Dv KM_SLEEP 165allocations while holding mutexes or reader/writer locks is discouraged, as the 166caller can sleep for an unbounded amount of time in order to satisfy the 167allocation. 168This can in turn block other threads that wish to acquire locks held by the 169caller. 170It should be noted that 171.Fn kmem_free 172may also block. 173.Pp 174For some locks this is permissible or even unavoidable. 175For others, particularly locks that may be taken from soft interrupt context, 176it is a serious problem. 177As a general rule it is better not to allow this type of situation to develop. 178One way to circumvent the problem is to make allocations speculative and part 179of a retryable sequence. 180For example: 181.Bd -literal 182 retry: 183 /* speculative unlocked check */ 184 if (need to allocate) { 185 new_item = kmem_alloc(sizeof(*new_item), KM_SLEEP); 186 } else { 187 new_item = NULL; 188 } 189 mutex_enter(lock); 190 /* check while holding lock for true status */ 191 if (need to allocate) { 192 if (new_item == NULL) { 193 mutex_exit(lock); 194 goto retry; 195 } 196 consume(new_item); 197 new_item = NULL; 198 } 199 mutex_exit(lock); 200 if (new_item != NULL) { 201 /* did not use it after all */ 202 kmem_free(new_item, sizeof(*new_item)); 203 } 204.Ed 205.\" ------------------------------------------------------------ 206.Sh OPTIONS 207Kernels compiled with the 208.Dv DEBUG 209option perform CPU intensive sanity checks on kmem operations, 210and include the 211.Dv kmguard 212facility which can be enabled at runtime. 213.Pp 214.Dv kmguard 215adds additional, very high overhead runtime verification to kmem operations. 216To enable it, boot the system with the 217.Fl d 218option, which causes the debugger to be entered early during the kernel 219boot process. 220Issue commands such as the following: 221.Bd -literal 222db\*[Gt] w kmem_guard_depth 0t30000 223db\*[Gt] c 224.Ed 225.Pp 226This instructs 227.Dv kmguard 228to queue up to 60000 (30000*2) pages of unmapped KVA to catch 229use-after-free type errors. 230When 231.Fn kmem_free 232is called, memory backing a freed item is unmapped and the kernel VA 233space pushed onto a FIFO. 234The VA space will not be reused until another 30k items have been freed. 235Until reused the kernel will catch invalid accesses and panic with a page fault. 236Limitations: 237.Bl -bullet 238.It 239It has a severe impact on performance. 240.It 241It is best used on a 64-bit machine with lots of RAM. 242.It 243Allocations larger than PAGE_SIZE bypass the 244.Dv kmguard 245facility. 246.El 247.Pp 248kmguard tries to catch the following types of bugs: 249.Bl -bullet 250.It 251Overflow at time of occurrence, by means of a guard page. 252.It 253Underflow at 254.Fn kmem_free , 255by using a canary value. 256.It 257Invalid pointer or size passed, at 258.Fn kmem_free . 259.El 260.Sh RETURN VALUES 261On success, 262.Fn kmem_alloc 263and 264.Fn kmem_zalloc 265return a pointer to allocated memory. 266Otherwise, 267.Dv NULL 268is returned. 269.\" ------------------------------------------------------------ 270.Sh CODE REFERENCES 271The 272.Nm 273subsystem is implemented within the file 274.Pa sys/kern/subr_kmem.c . 275.\" ------------------------------------------------------------ 276.Sh SEE ALSO 277.Xr intro 9 , 278.Xr memoryallocators 9 , 279.Xr percpu 9 , 280.Xr pool_cache 9 , 281.Xr uvm_km 9 282.\" ------------------------------------------------------------ 283.Sh CAVEATS 284Neither 285.Fn kmem_alloc 286nor 287.Fn kmem_free 288can be used from interrupt context, from a soft interrupt, or from 289a callout. 290Use 291.Xr pool_cache 9 292in these situations. 293.\" ------------------------------------------------------------ 294.Sh SECURITY CONSIDERATIONS 295As the memory allocated by 296.Fn kmem_alloc 297is uninitialized, it can contain security-sensitive data left by its 298previous user. 299It is the caller's responsibility not to expose it to the world. 300