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 November 21, 2017 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. 217.It Dv M_POWEROF2 218Rounds up the size to the nearest power of 2. 219.It Dv M_NULLOK 220This flag is usually specified along with 221.Dv M_WAITOK 222or 223.Dv M_INTWAIT , 224so when the interal pool limit is reached, 225.Fn kmalloc 226and 227.Fn krealloc , 228functions will not panic the system, 229instead, 230.Dv NULL 231will be returned. 232This flag is usually used on the kernel code path that is triggered by 233user space programs' requests. 234.El 235.Pp 236Exactly one of either 237.Dv M_WAITOK , 238.Dv M_INTWAIT 239or 240.Dv M_NOWAIT 241must be specified. 242.Pp 243The 244.Fa type 245argument is used to perform statistics on memory usage, and for 246basic sanity checks. 247It can be used to identify multiple allocations. 248The statistics can be examined by 249.Sq vmstat -m . 250.Pp 251A 252.Fa type 253is defined using the 254.Va malloc_type_t 255typedef via the 256.Fn MALLOC_DECLARE 257and 258.Fn MALLOC_DEFINE 259macros. 260.Bd -literal -offset indent 261/* sys/something/foo_extern.h */ 262 263MALLOC_DECLARE(M_FOOBUF); 264 265/* sys/something/foo_main.c */ 266 267MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 268 269/* sys/something/foo_subr.c */ 270 271\&... 272buf = kmalloc(sizeof *buf, M_FOOBUF, M_NOWAIT); 273 274.Ed 275.Sh IMPLEMENTATION NOTES 276The memory allocator allocates memory in chunks that have size a power 277of two for requests up to the size of a page of memory. 278For larger requests, one or more pages is allocated. 279The allocated memory will be at least 8 bytes aligned. 280While it should not be relied upon, this information may be useful for 281optimizing the efficiency of memory use. 282.Sh RETURN VALUES 283The 284.Fn kmalloc 285and 286.Fn krealloc , 287functions return a kernel virtual address that is suitably aligned for 288storage of any type of object, or 289.Dv NULL 290if the request could not be satisfied (implying that 291.Dv M_NOWAIT 292or 293.Dv M_NULLOK 294was set). 295.Sh DIAGNOSTICS 296A kernel compiled with the 297.Dv INVARIANTS 298configuration option attempts to detect memory corruption caused by 299such things as writing outside the allocated area and imbalanced calls to the 300.Fn kmalloc 301and 302.Fn kfree 303functions. 304Failing consistency checks will cause a panic or a system console 305message. 306.Sh SEE ALSO 307.Xr vmstat 8 , 308.Xr contigmalloc 9 , 309.Xr kstrdup 9 , 310.Xr memory 9 , 311.Xr vnode 9 312