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.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 21.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" POSSIBILITY OF SUCH DAMAGE. 28.\" 29.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ 30.\" $FreeBSD$ 31.\" 32.Dd October 30, 2018 33.Dt MALLOC 9 34.Os 35.Sh NAME 36.Nm malloc , 37.Nm free , 38.Nm realloc , 39.Nm reallocf , 40.Nm MALLOC_DEFINE , 41.Nm MALLOC_DECLARE 42.Nd kernel memory management routines 43.Sh SYNOPSIS 44.In sys/types.h 45.In sys/malloc.h 46.Ft void * 47.Fn malloc "size_t size" "struct malloc_type *type" "int flags" 48.Ft void * 49.Fn mallocarray "size_t nmemb" "size_t size" "struct malloc_type *type" "int flags" 50.Ft void 51.Fn free "void *addr" "struct malloc_type *type" 52.Ft void * 53.Fn realloc "void *addr" "size_t size" "struct malloc_type *type" "int flags" 54.Ft void * 55.Fn reallocf "void *addr" "size_t size" "struct malloc_type *type" "int flags" 56.Fn MALLOC_DECLARE type 57.In sys/param.h 58.In sys/malloc.h 59.In sys/kernel.h 60.Fn MALLOC_DEFINE type shortdesc longdesc 61.In sys/param.h 62.In sys/domainset.h 63.Ft void * 64.Fn malloc_domainset "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags" 65.Ft void 66.Fn free_domain "void *addr" "struct malloc_type *type" 67.Sh DESCRIPTION 68The 69.Fn malloc 70function allocates uninitialized memory in kernel address space for an 71object whose size is specified by 72.Fa size . 73.Pp 74The 75.Fn malloc_domainset 76variant allocates memory from a specific 77.Xr numa 4 78domain using the specified domain selection policy. 79See 80.Xr domainset 9 81for some example policies. 82Memory allocated with this function should be returned with 83.Fn free_domain . 84.Pp 85The 86.Fn mallocarray 87function allocates uninitialized memory in kernel address space for an 88array of 89.Fa nmemb 90entries whose size is specified by 91.Fa size . 92.Pp 93The 94.Fn free 95function releases memory at address 96.Fa addr 97that was previously allocated by 98.Fn malloc 99for re-use. 100The memory is not zeroed. 101If 102.Fa addr 103is 104.Dv NULL , 105then 106.Fn free 107does nothing. 108.Pp 109The 110.Fn realloc 111function changes the size of the previously allocated memory referenced by 112.Fa addr 113to 114.Fa size 115bytes. 116The contents of the memory are unchanged up to the lesser of the new and 117old sizes. 118Note that the returned value may differ from 119.Fa addr . 120If the requested memory cannot be allocated, 121.Dv NULL 122is returned and the memory referenced by 123.Fa addr 124is valid and unchanged. 125If 126.Fa addr 127is 128.Dv NULL , 129the 130.Fn realloc 131function behaves identically to 132.Fn malloc 133for the specified size. 134.Pp 135The 136.Fn reallocf 137function is identical to 138.Fn realloc 139except that it 140will free the passed pointer when the requested memory cannot be allocated. 141.Pp 142Unlike its standard C library counterpart 143.Pq Xr malloc 3 , 144the kernel version takes two more arguments. 145The 146.Fa flags 147argument further qualifies 148.Fn malloc Ns 's 149operational characteristics as follows: 150.Bl -tag -width indent 151.It Dv M_ZERO 152Causes the allocated memory to be set to all zeros. 153.It Dv M_NODUMP 154For allocations greater than page size, causes the allocated 155memory to be excluded from kernel core dumps. 156.It Dv M_NOWAIT 157Causes 158.Fn malloc , 159.Fn realloc , 160and 161.Fn reallocf 162to return 163.Dv NULL 164if the request cannot be immediately fulfilled due to resource shortage. 165Note that 166.Dv M_NOWAIT 167is required when running in an interrupt context. 168.It Dv M_WAITOK 169Indicates that it is OK to wait for resources. 170If the request cannot be immediately fulfilled, the current process is put 171to sleep to wait for resources to be released by other processes. 172The 173.Fn malloc , 174.Fn mallocarray , 175.Fn realloc , 176and 177.Fn reallocf 178functions cannot return 179.Dv NULL 180if 181.Dv M_WAITOK 182is specified. 183If the multiplication of 184.Fa nmemb 185and 186.Fa size 187would cause an integer overflow, the 188.Fn mallocarray 189function induces a panic. 190.It Dv M_USE_RESERVE 191Indicates that the system can use its reserve of memory to satisfy the 192request. 193This option should only be used in combination with 194.Dv M_NOWAIT 195when an allocation failure cannot be tolerated by the caller without 196catastrophic effects on the system. 197.It Dv M_EXEC 198Indicates that the system should allocate executable memory. 199If this flag is not set, the system will not allocate executable memory. 200Not all platforms enforce a distinction between executable and 201non-executable memory. 202.El 203.Pp 204Exactly one of either 205.Dv M_WAITOK 206or 207.Dv M_NOWAIT 208must be specified. 209.Pp 210The 211.Fa type 212argument is used to perform statistics on memory usage, and for 213basic sanity checks. 214It can be used to identify multiple allocations. 215The statistics can be examined by 216.Sq vmstat -m . 217.Pp 218A 219.Fa type 220is defined using 221.Vt "struct malloc_type" 222via the 223.Fn MALLOC_DECLARE 224and 225.Fn MALLOC_DEFINE 226macros. 227.Bd -literal -offset indent 228/* sys/something/foo_extern.h */ 229 230MALLOC_DECLARE(M_FOOBUF); 231 232/* sys/something/foo_main.c */ 233 234MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 235 236/* sys/something/foo_subr.c */ 237 238\&... 239buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT); 240 241.Ed 242.Pp 243In order to use 244.Fn MALLOC_DEFINE , 245one must include 246.In sys/param.h 247(instead of 248.In sys/types.h ) 249and 250.In sys/kernel.h . 251.Sh CONTEXT 252.Fn malloc , 253.Fn realloc 254and 255.Fn reallocf 256may not be called from fast interrupts handlers. 257When called from threaded interrupts, 258.Fa flags 259must contain 260.Dv M_NOWAIT . 261.Pp 262.Fn malloc , 263.Fn realloc 264and 265.Fn reallocf 266may sleep when called with 267.Dv M_WAITOK . 268.Fn free 269never sleeps. 270However, 271.Fn malloc , 272.Fn realloc , 273.Fn reallocf 274and 275.Fn free 276may not be called in a critical section or while holding a spin lock. 277.Pp 278Any calls to 279.Fn malloc 280(even with 281.Dv M_NOWAIT ) 282or 283.Fn free 284when holding a 285.Xr vnode 9 286interlock, will cause a LOR (Lock Order Reversal) due to the 287intertwining of VM Objects and Vnodes. 288.Sh IMPLEMENTATION NOTES 289The memory allocator allocates memory in chunks that have size a power 290of two for requests up to the size of a page of memory. 291For larger requests, one or more pages is allocated. 292While it should not be relied upon, this information may be useful for 293optimizing the efficiency of memory use. 294.Sh RETURN VALUES 295The 296.Fn malloc , 297.Fn realloc , 298and 299.Fn reallocf 300functions return a kernel virtual address that is suitably aligned for 301storage of any type of object, or 302.Dv NULL 303if the request could not be satisfied (implying that 304.Dv M_NOWAIT 305was set). 306.Sh DIAGNOSTICS 307A kernel compiled with the 308.Dv INVARIANTS 309configuration option attempts to detect memory corruption caused by 310such things as writing outside the allocated area and imbalanced calls to the 311.Fn malloc 312and 313.Fn free 314functions. 315Failing consistency checks will cause a panic or a system console 316message. 317.Sh SEE ALSO 318.Xr numa 4 , 319.Xr vmstat 8 , 320.Xr contigmalloc 9 , 321.Xr domainset 9 , 322.Xr memguard 9 , 323.Xr vnode 9 324