1.\" 2.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 3.\" All rights reserved. 4.\" 5.\" This code is derived from software contributed to The NetBSD Foundation 6.\" by Paul Kranenburg. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. All advertising materials mentioning features or use of this software 17.\" must display the following acknowledgement: 18.\" This product includes software developed by the NetBSD 19.\" Foundation, Inc. and its contributors. 20.\" 4. Neither the name of The NetBSD Foundation nor the names of its 21.\" contributors may be used to endorse or promote products derived 22.\" from this software without specific prior written permission. 23.\" 24.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 25.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 26.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 27.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 28.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 29.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 31.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 32.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 33.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 34.\" POSSIBILITY OF SUCH DAMAGE. 35.\" 36.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ 37.\" $FreeBSD: src/share/man/man9/malloc.9,v 1.42 2005/02/22 17:20:20 brueffer Exp $ 38.\" 39.Dd September 22, 2013 40.Dt KMALLOC 9 41.Os 42.Sh NAME 43.Nm kmalloc , 44.Nm kmalloc_cachealign , 45.Nm kfree , 46.Nm krealloc , 47.Nm kmalloc_raise_limit , 48.Nm MALLOC_DEFINE , 49.Nm MALLOC_DECLARE 50.Nd kernel memory management routines 51.Sh SYNOPSIS 52.In sys/types.h 53.In sys/malloc.h 54.Ft void * 55.Fn kmalloc "unsigned long size" "struct malloc_type *type" "int flags" 56.Ft void * 57.Fn kmalloc_cachealign "unsigned long size" "struct malloc_type *type" "int flags" 58.Ft void 59.Fn kfree "void *addr" "struct malloc_type *type" 60.Ft void * 61.Fn krealloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 62.Ft void 63.Fn kmalloc_raise_limit "struct malloc_type *type" "size_t bytes" 64.Fn MALLOC_DECLARE type 65.In sys/param.h 66.In sys/malloc.h 67.In sys/kernel.h 68.Fn MALLOC_DEFINE type shortdesc longdesc 69.Sh DESCRIPTION 70The 71.Fn kmalloc 72function allocates uninitialized memory in kernel address space for an 73object whose size is specified by 74.Fa size . 75.Fn kmalloc_cachealign 76function is same as 77.Fn kmalloc 78except that the allocated memory will be cache line size aligned. 79.Pp 80The 81.Fn kfree 82function releases memory at address 83.Fa addr 84that was previously allocated by 85.Fn kmalloc 86for re-use. 87The memory is not zeroed. 88The kernel implementation of 89.Fn kfree 90does not allow 91.Fa addr 92to be 93.Dv NULL . 94.Pp 95The 96.Fn krealloc 97function changes the size of the previously allocated memory referenced by 98.Fa addr 99to 100.Fa size 101bytes. 102The contents of the memory are unchanged up to the lesser of the new and 103old sizes. 104Note that the returned value may differ from 105.Fa addr . 106If the requested memory cannot be allocated, 107.Dv NULL 108is returned and the memory referenced by 109.Fa addr 110is valid and unchanged. 111If 112.Fa addr 113is 114.Dv NULL , 115the 116.Fn krealloc 117function behaves identically to 118.Fn kmalloc 119for the specified size. 120.Pp 121.Fn kmalloc_raise_limit 122is used to increase the internal pool limit to 123.Fa bytes . 124Under most of the cases 125the default internal pool limit should be more than enough, 126so this function is currently rarely used and must be used with care. 127.Pp 128Unlike its standard C library counterpart 129.Pq Xr malloc 3 , 130the kernel version takes two more arguments. 131The 132.Fa flags 133argument further qualifies 134.Fn kmalloc Ns 's 135operational characteristics as follows: 136.Bl -tag -width indent 137.It Dv M_ZERO 138Causes the allocated memory to be set to all zeros. 139.It Dv M_NOWAIT 140Causes 141.Fn kmalloc 142and 143.Fn krealloc , 144to return 145.Dv NULL 146if the request cannot be immediately fulfilled due to resource shortage. 147Note that 148.Dv M_NOWAIT 149is required when running in an interrupt context. 150.It Dv M_WAITOK 151Indicates that it is OK to wait for resources. 152If the request cannot be immediately fulfilled, the current process is put 153to sleep to wait for resources to be released by other processes. 154Before the internal pool limit is reached, 155the 156.Fn kmalloc 157and 158.Fn krealloc , 159functions cannot return 160.Dv NULL 161if 162.Dv M_WAITOK 163is specified. 164If the internal pool limit is reached and 165.Dv M_NULLOK 166is not specified along with 167.Dv M_WAITOK , 168the system will panic. 169If the internal pool limit is reached and 170.Dv M_NULLOK 171is specified along with 172.Dv M_WAITOK , 173the 174.Fn kmalloc 175and 176.Fn krealloc , 177functions return 178.Dv NULL 179instead of panicing the system. 180.It Dv M_INTWAIT 181Indicates 182.Fn kmalloc 183to dig into the system's reserved free pages looking for enough room to 184perform the allocation. 185This is typically used in interrupts where you cannot afford 186.Fn kmalloc 187to fail. 188Before the internal pool limit is reached, 189the 190.Fn kmalloc 191and 192.Fn krealloc , 193functions cannot return 194.Dv NULL 195if 196.Dv M_INTWAIT 197is specified. 198If the internal pool limit is reached and 199.Dv M_NULLOK 200is not specified along with 201.Dv M_INTWAIT , 202the system will panic. 203If the internal pool limit is reached and 204.Dv M_NULLOK 205is specified along with 206.Dv M_INTWAIT , 207the 208.Fn kmalloc 209and 210.Fn krealloc , 211functions return 212.Dv NULL 213instead of panicing the system. 214.It Dv M_USE_RESERVE 215Indicates that the system can dig into its reserve in order to obtain the 216requested memory. 217This option used to be called 218.Dv M_KERNEL 219but has been renamed to something more obvious. 220This option has been deprecated and is slowly being removed from the kernel, 221and so should not be used with any new code. 222.It Dv M_POWEROF2 223Rounds up the size to the nearest power of 2. 224.It Dv M_NULLOK 225This flag is usually specified along with 226.Dv M_WAITOK 227or 228.Dv M_INTWAIT , 229so when the interal pool limit is reached, 230.Fn kmalloc 231and 232.Fn krealloc , 233functions will not panic the system, 234instead, 235.Dv NULL 236will be returned. 237This flag is usually used on the kernel code path that is triggered by 238user space programs' requests. 239.El 240.Pp 241Exactly one of either 242.Dv M_WAITOK , 243.Dv M_INTWAIT 244or 245.Dv M_NOWAIT 246must be specified. 247.Pp 248The 249.Fa type 250argument is used to perform statistics on memory usage, and for 251basic sanity checks. 252It can be used to identify multiple allocations. 253The statistics can be examined by 254.Sq vmstat -m . 255.Pp 256A 257.Fa type 258is defined using the 259.Va malloc_type_t 260typedef via the 261.Fn MALLOC_DECLARE 262and 263.Fn MALLOC_DEFINE 264macros. 265.Bd -literal -offset indent 266/* sys/something/foo_extern.h */ 267 268MALLOC_DECLARE(M_FOOBUF); 269 270/* sys/something/foo_main.c */ 271 272MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 273 274/* sys/something/foo_subr.c */ 275 276\&... 277buf = kmalloc(sizeof *buf, M_FOOBUF, M_NOWAIT); 278 279.Ed 280.Sh IMPLEMENTATION NOTES 281The memory allocator allocates memory in chunks that have size a power 282of two for requests up to the size of a page of memory. 283For larger requests, one or more pages is allocated. 284The allocated memory will be at least 8 bytes aligned. 285While it should not be relied upon, this information may be useful for 286optimizing the efficiency of memory use. 287.Sh RETURN VALUES 288The 289.Fn kmalloc 290and 291.Fn krealloc , 292functions return a kernel virtual address that is suitably aligned for 293storage of any type of object, or 294.Dv NULL 295if the request could not be satisfied (implying that 296.Dv M_NOWAIT 297or 298.Dv M_NULLOK 299was set). 300.Sh DIAGNOSTICS 301A kernel compiled with the 302.Dv INVARIANTS 303configuration option attempts to detect memory corruption caused by 304such things as writing outside the allocated area and imbalanced calls to the 305.Fn kmalloc 306and 307.Fn kfree 308functions. 309Failing consistency checks will cause a panic or a system console 310message. 311.Sh SEE ALSO 312.Xr vmstat 8 , 313.Xr contigmalloc 9 , 314.Xr memory 9 , 315.Xr vnode 9 316