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 kfree , 45.Nm krealloc , 46.Nm kmalloc_raise_limit , 47.Nm MALLOC_DEFINE , 48.Nm MALLOC_DECLARE 49.Nd kernel memory management routines 50.Sh SYNOPSIS 51.In sys/types.h 52.In sys/malloc.h 53.Ft void * 54.Fn kmalloc "unsigned long size" "struct malloc_type *type" "int flags" 55.Ft void * 56.Fn kmalloc_cachealign "unsigned long size" "struct malloc_type *type" "int flags" 57.Ft void 58.Fn kfree "void *addr" "struct malloc_type *type" 59.Ft void * 60.Fn krealloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 61.Ft void 62.Fn kmalloc_raise_limit "struct malloc_type *type" "size_t bytes" 63.Fn MALLOC_DECLARE type 64.In sys/param.h 65.In sys/malloc.h 66.In sys/kernel.h 67.Fn MALLOC_DEFINE type shortdesc longdesc 68.Sh DESCRIPTION 69The 70.Fn kmalloc 71function allocates uninitialized memory in kernel address space for an 72object whose size is specified by 73.Fa size . 74.Fn kmalloc_cachealign 75function is same as 76.Fn kmalloc 77except that the allocated memory will be cache line size aligned. 78.Pp 79The 80.Fn kfree 81function releases memory at address 82.Fa addr 83that was previously allocated by 84.Fn kmalloc 85for re-use. 86The memory is not zeroed. 87The kernel implementation of 88.Fn kfree 89does not allow 90.Fa addr 91to be 92.Dv NULL . 93.Pp 94The 95.Fn krealloc 96function changes the size of the previously allocated memory referenced by 97.Fa addr 98to 99.Fa size 100bytes. 101The contents of the memory are unchanged up to the lesser of the new and 102old sizes. 103Note that the returned value may differ from 104.Fa addr . 105If the requested memory cannot be allocated, 106.Dv NULL 107is returned and the memory referenced by 108.Fa addr 109is valid and unchanged. 110If 111.Fa addr 112is 113.Dv NULL , 114the 115.Fn krealloc 116function behaves identically to 117.Fn kmalloc 118for the specified size. 119.Pp 120.Fn kmalloc_raise_limit 121is used to increase the internal pool limit to 122.Fa bytes . 123Under most of the cases 124the default internal pool limit should be more than enough, 125so this function is currently rarely used and must be used with care. 126.Pp 127Unlike its standard C library counterpart 128.Pq Xr malloc 3 , 129the kernel version takes two more arguments. 130The 131.Fa flags 132argument further qualifies 133.Fn kmalloc Ns 's 134operational characteristics as follows: 135.Bl -tag -width indent 136.It Dv M_ZERO 137Causes the allocated memory to be set to all zeros. 138.It Dv M_NOWAIT 139Causes 140.Fn kmalloc 141and 142.Fn krealloc , 143to return 144.Dv NULL 145if the request cannot be immediately fulfilled due to resource shortage. 146Note that 147.Dv M_NOWAIT 148is required when running in an interrupt context. 149.It Dv M_WAITOK 150Indicates that it is OK to wait for resources. 151If the request cannot be immediately fulfilled, the current process is put 152to sleep to wait for resources to be released by other processes. 153Before the internal pool limit is reached, 154the 155.Fn kmalloc 156and 157.Fn krealloc , 158functions cannot return 159.Dv NULL 160if 161.Dv M_WAITOK 162is specified. 163If the internal pool limit is reached and 164.Dv M_NULLOK 165is not specified along with 166.Dv M_WAITOK , 167the system will panic. 168If the internal pool limit is reached and 169.Dv M_NULLOK 170is specified along with 171.Dv M_WAITOK , 172the 173.Fn kmalloc 174and 175.Fn krealloc , 176functions return 177.Dv NULL 178instead of panicing the system. 179.It Dv M_INTWAIT 180Indicates 181.Fn kmalloc 182to dig into the system's reserved free pages looking for enough room to 183perform the allocation. 184This is typically used in interrupts where you cannot afford 185.Fn kmalloc 186to fail. 187Before the internal pool limit is reached, 188the 189.Fn kmalloc 190and 191.Fn krealloc , 192functions cannot return 193.Dv NULL 194if 195.Dv M_INTWAIT 196is specified. 197If the internal pool limit is reached and 198.Dv M_NULLOK 199is not specified along with 200.Dv M_INTWAIT , 201the system will panic. 202If the internal pool limit is reached and 203.Dv M_NULLOK 204is specified along with 205.Dv M_INTWAIT , 206the 207.Fn kmalloc 208and 209.Fn krealloc , 210functions return 211.Dv NULL 212instead of panicing the system. 213.It Dv M_USE_RESERVE 214Indicates that the system can dig into its reserve in order to obtain the 215requested memory. 216This option used to be called 217.Dv M_KERNEL 218but has been renamed to something more obvious. 219This option has been deprecated and is slowly being removed from the kernel, 220and so should not be used with any new code. 221.It Dv M_POWEROF2 222Rounds up the size to the nearest power of 2. 223.It Dv M_NULLOK 224This flag is usually specified along with 225.Dv M_WAITOK 226or 227.Dv M_INTWAIT , 228so when the interal pool limit is reached, 229.Fn kmalloc 230and 231.Fn krealloc , 232functions will not panic the system, 233instead, 234.Dv NULL 235will be returned. 236This flag is usually used on the kernel code path that is triggered by 237user space programs' requests. 238.El 239.Pp 240Exactly one of either 241.Dv M_WAITOK , 242.Dv M_INTWAIT 243or 244.Dv M_NOWAIT 245must be specified. 246.Pp 247The 248.Fa type 249argument is used to perform statistics on memory usage, and for 250basic sanity checks. 251It can be used to identify multiple allocations. 252The statistics can be examined by 253.Sq vmstat -m . 254.Pp 255A 256.Fa type 257is defined using the 258.Va malloc_type_t 259typedef via the 260.Fn MALLOC_DECLARE 261and 262.Fn MALLOC_DEFINE 263macros. 264.Bd -literal -offset indent 265/* sys/something/foo_extern.h */ 266 267MALLOC_DECLARE(M_FOOBUF); 268 269/* sys/something/foo_main.c */ 270 271MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 272 273/* sys/something/foo_subr.c */ 274 275\&... 276buf = kmalloc(sizeof *buf, M_FOOBUF, M_NOWAIT); 277 278.Ed 279.Sh IMPLEMENTATION NOTES 280The memory allocator allocates memory in chunks that have size a power 281of two for requests up to the size of a page of memory. 282For larger requests, one or more pages is allocated. 283The allocated memory will be at least 8 bytes aligned. 284While it should not be relied upon, this information may be useful for 285optimizing the efficiency of memory use. 286.Sh RETURN VALUES 287The 288.Fn kmalloc 289and 290.Fn krealloc , 291functions return a kernel virtual address that is suitably aligned for 292storage of any type of object, or 293.Dv NULL 294if the request could not be satisfied (implying that 295.Dv M_NOWAIT 296or 297.Dv M_NULLOK 298was set). 299.Sh DIAGNOSTICS 300A kernel compiled with the 301.Dv INVARIANTS 302configuration option attempts to detect memory corruption caused by 303such things as writing outside the allocated area and imbalanced calls to the 304.Fn kmalloc 305and 306.Fn kfree 307functions. 308Failing consistency checks will cause a panic or a system console 309message. 310.Sh SEE ALSO 311.Xr vmstat 8 , 312.Xr contigmalloc 9 , 313.Xr memory 9 , 314.Xr vnode 9 315