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