188cf6634SMike Pritchard.\" 288cf6634SMike Pritchard.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 388cf6634SMike Pritchard.\" All rights reserved. 488cf6634SMike Pritchard.\" 588cf6634SMike Pritchard.\" This code is derived from software contributed to The NetBSD Foundation 688cf6634SMike Pritchard.\" by Paul Kranenburg. 788cf6634SMike Pritchard.\" 888cf6634SMike Pritchard.\" Redistribution and use in source and binary forms, with or without 988cf6634SMike Pritchard.\" modification, are permitted provided that the following conditions 1088cf6634SMike Pritchard.\" are met: 1188cf6634SMike Pritchard.\" 1. Redistributions of source code must retain the above copyright 1288cf6634SMike Pritchard.\" notice, this list of conditions and the following disclaimer. 1388cf6634SMike Pritchard.\" 2. Redistributions in binary form must reproduce the above copyright 1488cf6634SMike Pritchard.\" notice, this list of conditions and the following disclaimer in the 1588cf6634SMike Pritchard.\" documentation and/or other materials provided with the distribution. 1688cf6634SMike Pritchard.\" 3. All advertising materials mentioning features or use of this software 1788cf6634SMike Pritchard.\" must display the following acknowledgement: 1888cf6634SMike Pritchard.\" This product includes software developed by the NetBSD 1988cf6634SMike Pritchard.\" Foundation, Inc. and its contributors. 2088cf6634SMike Pritchard.\" 4. Neither the name of The NetBSD Foundation nor the names of its 2188cf6634SMike Pritchard.\" contributors may be used to endorse or promote products derived 2288cf6634SMike Pritchard.\" from this software without specific prior written permission. 2388cf6634SMike Pritchard.\" 2488cf6634SMike Pritchard.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 2588cf6634SMike Pritchard.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 2688cf6634SMike Pritchard.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 2788cf6634SMike Pritchard.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 2888cf6634SMike Pritchard.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 2988cf6634SMike Pritchard.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 3088cf6634SMike Pritchard.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 3188cf6634SMike Pritchard.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 3288cf6634SMike Pritchard.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 3388cf6634SMike Pritchard.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 3488cf6634SMike Pritchard.\" POSSIBILITY OF SUCH DAMAGE. 3588cf6634SMike Pritchard.\" 36cc4a02e2SMatthew Dillon.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ 377f3dea24SPeter Wemm.\" $FreeBSD$ 385bf6ab83SNik Clayton.\" 3988cf6634SMike Pritchard.Dd June 16, 1996 4088cf6634SMike Pritchard.Dt MALLOC 9 413d45e180SRuslan Ermilov.Os 4288cf6634SMike Pritchard.Sh NAME 4388cf6634SMike Pritchard.Nm malloc , 4488cf6634SMike Pritchard.Nm MALLOC , 4588cf6634SMike Pritchard.Nm free , 4688cf6634SMike Pritchard.Nm FREE 4788cf6634SMike Pritchard.Nd kernel memory management routines 4888cf6634SMike Pritchard.Sh SYNOPSIS 4932eef9aeSRuslan Ermilov.In sys/types.h 5032eef9aeSRuslan Ermilov.In sys/malloc.h 5188cf6634SMike Pritchard.Ft void * 522a94e401SPoul-Henning Kamp.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" 532a94e401SPoul-Henning Kamp.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type *type" "int flags" 5488cf6634SMike Pritchard.Ft void 552a94e401SPoul-Henning Kamp.Fn free "void *addr" "struct malloc_type *type" 562a94e401SPoul-Henning Kamp.Fn FREE "void *addr" "struct malloc_type *type" 5744a8ff31SArchie Cobbs.Ft void * 5844a8ff31SArchie Cobbs.Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 5944a8ff31SArchie Cobbs.Ft void * 6044a8ff31SArchie Cobbs.Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" 6188cf6634SMike Pritchard.Sh DESCRIPTION 6288cf6634SMike PritchardThe 6388cf6634SMike Pritchard.Fn malloc 6488cf6634SMike Pritchardfunction allocates uninitialized memory in kernel address space for an 6588cf6634SMike Pritchardobject whose size is specified by 6688cf6634SMike Pritchard.Fa size . 6744a8ff31SArchie Cobbs.Pp 6860dca836SPhilippe CharnierThe 6988cf6634SMike Pritchard.Fn free 7060dca836SPhilippe Charnierfunction releases memory at address 7188cf6634SMike Pritchard.Fa addr 7288cf6634SMike Pritchardthat was previously allocated by 7388cf6634SMike Pritchard.Fn malloc 7444a8ff31SArchie Cobbsfor re-use. 7544a8ff31SArchie CobbsThe memory is not zeroed. 7644a8ff31SArchie CobbsIf 7744a8ff31SArchie Cobbs.Fa addr 7844a8ff31SArchie Cobbsis 7944a8ff31SArchie Cobbs.Dv NULL , 8044a8ff31SArchie Cobbsthen 8144a8ff31SArchie Cobbs.Fn free 8244a8ff31SArchie Cobbsdoes nothing. 8344a8ff31SArchie Cobbs.Pp 8444a8ff31SArchie CobbsThe 8544a8ff31SArchie Cobbs.Fn realloc 8644a8ff31SArchie Cobbsfunction changes the size of the previously allocated memory referenced by 8744a8ff31SArchie Cobbs.Fa addr 8844a8ff31SArchie Cobbsto 8944a8ff31SArchie Cobbs.Fa size 9044a8ff31SArchie Cobbsbytes. 9144a8ff31SArchie CobbsThe contents of the memory are unchanged up to the lesser of the new and 9244a8ff31SArchie Cobbsold sizes. 9344a8ff31SArchie CobbsNote that the returned value may differ from 9444a8ff31SArchie Cobbs.Fa addr . 9544a8ff31SArchie CobbsIf the requested memory cannot be allocated, 9644a8ff31SArchie Cobbs.Dv NULL 9744a8ff31SArchie Cobbsis returned and the memory referenced by 9844a8ff31SArchie Cobbs.Fa addr 9944a8ff31SArchie Cobbsis valid and unchanged. 10044a8ff31SArchie CobbsIf 10144a8ff31SArchie Cobbs.Fa addr 10244a8ff31SArchie Cobbsis 10344a8ff31SArchie Cobbs.Dv NULL , 10444a8ff31SArchie Cobbsthe 10544a8ff31SArchie Cobbs.Fn realloc 10644a8ff31SArchie Cobbsfunction behaves identically to 10744a8ff31SArchie Cobbs.Fn malloc 10844a8ff31SArchie Cobbsfor the specified size. 10944a8ff31SArchie Cobbs.Pp 11044a8ff31SArchie CobbsThe 11144a8ff31SArchie Cobbs.Fn reallocf 112c2f7105cSRuslan Ermilovfunction is identical to 113c2f7105cSRuslan Ermilov.Fn realloc 114c2f7105cSRuslan Ermilovexcept that it 11544a8ff31SArchie Cobbswill free the passed pointer when the requested memory cannot be allocated. 11644a8ff31SArchie Cobbs.Pp 11788cf6634SMike PritchardThe 11888cf6634SMike Pritchard.Fn MALLOC 11988cf6634SMike Pritchardmacro variant is functionally equivalent to 12088cf6634SMike Pritchard.Bd -literal -offset indent 12188cf6634SMike Pritchard(space) = (cast)malloc((u_long)(size), type, flags) 12288cf6634SMike Pritchard.Ed 12388cf6634SMike Pritchard.Pp 12488cf6634SMike Pritchardand the 12588cf6634SMike Pritchard.Fn FREE 12688cf6634SMike Pritchardmacro variant is equivalent to 12788cf6634SMike Pritchard.Bd -literal -offset indent 12888cf6634SMike Pritchardfree((addr), type) 12988cf6634SMike Pritchard.Ed 13088cf6634SMike Pritchard.Pp 13188cf6634SMike PritchardUnlike its standard C library counterpart 13288cf6634SMike Pritchard.Pq Xr malloc 3 , 13388cf6634SMike Pritchardthe kernel version takes two more arguments. The 13488cf6634SMike Pritchard.Fa flags 13588cf6634SMike Pritchardargument further qualifies 136b74e63f2SRuslan Ermilov.Fn malloc Ns 's 13788cf6634SMike Pritchardoperational characteristics as follows: 138367f1374SMatthew Dillon.Bl -tag -width indent 1391921a06dSPoul-Henning Kamp.It Dv M_ZERO 1401921a06dSPoul-Henning KampCauses the allocated memory to be set to all zeros. 14188cf6634SMike Pritchard.It Dv M_NOWAIT 14288cf6634SMike PritchardCauses 14344a8ff31SArchie Cobbs.Fn malloc , 14444a8ff31SArchie Cobbs.Fn realloc , 145c2f7105cSRuslan Ermilovand 14644a8ff31SArchie Cobbs.Fn reallocf 14788cf6634SMike Pritchardto return 14888cf6634SMike Pritchard.Dv NULL 14988cf6634SMike Pritchardif the request cannot be immediately fulfilled due to resource shortage. 15044a8ff31SArchie CobbsOtherwise, the current process may be put to sleep to wait for 15144a8ff31SArchie Cobbsresources to be released by other processes. 152367f1374SMatthew DillonIf this flag is set, 15388cf6634SMike Pritchard.Fn malloc 154367f1374SMatthew Dillonwill return 155367f1374SMatthew Dillon.Dv NULL 156074ad115SRuslan Ermilovrather than block. 15744a8ff31SArchie CobbsNote that 15844a8ff31SArchie Cobbs.Dv M_NOWAIT 1591e73455bSTom Rhodesis defined to be 0, meaning that blocking operation is the default. 1601e73455bSTom RhodesAlso note that 1611e73455bSTom Rhodes.Dv M_NOWAIT 16244a8ff31SArchie Cobbsis required when running in an interrupt context. 1631e73455bSTom Rhodes.Pp 1641e73455bSTom RhodesProgrammers should be careful not to confuse 1651e73455bSTom Rhodes.Dv M_NOWAIT , 1661e73455bSTom Rhodesthe 1671e73455bSTom Rhodes.Fn malloc 1681e73455bSTom Rhodesflag, with 1691e73455bSTom Rhodes.Dv M_DONTWAIT , 1701e73455bSTom Rhodesan 1711e73455bSTom Rhodes.Xr mbuf 9 1721e73455bSTom Rhodesallocation flag, which is not a valid argument to 1731e73455bSTom Rhodes.Fn malloc . 1741e73455bSTom Rhodes.It Dv M_WAITOK 1751e73455bSTom RhodesIndicates that it is Ok to wait for resources. It is unconveniently 1761e73455bSTom Rhodesdefined as 0 so care should be taken never to compare against this value 1771e73455bSTom Rhodesdirectly or try to AND it as a flag. The default operation is to block 1781e73455bSTom Rhodesuntil the memory allocation succeeds. 17960dca836SPhilippe CharnierThe 18044a8ff31SArchie Cobbs.Fn malloc , 18144a8ff31SArchie Cobbs.Fn realloc , 18244a8ff31SArchie Cobbsand 18344a8ff31SArchie Cobbs.Fn reallocf 18460dca836SPhilippe Charnierfunctions can only return 185367f1374SMatthew Dillon.Dv NULL 186367f1374SMatthew Dillonif 187367f1374SMatthew Dillon.Dv M_NOWAIT 188367f1374SMatthew Dillonis specified. 189cc4a02e2SMatthew Dillon.It Dv M_USE_RESERVE 190cc4a02e2SMatthew DillonIndicates that the system can dig into its reserve in order to obtain the 191cc4a02e2SMatthew Dillonrequested memory. This option used to be called M_KERNEL but has been 192a63e7820SJohn Baldwinrenamed to something more obvious. This option has been deprecated and is 193cc4a02e2SMatthew Dillonslowly being removed from the kernel, and so should not be used with any new 194cc4a02e2SMatthew Dillonprogramming. 19588cf6634SMike Pritchard.El 19688cf6634SMike Pritchard.Pp 19788cf6634SMike PritchardThe 19888cf6634SMike Pritchard.Fa type 1992a94e401SPoul-Henning Kampargument is used to perform statistics on memory usage, and for 2002a94e401SPoul-Henning Kampbasic sanity checks. 2012a94e401SPoul-Henning KampThe statistics can be examined by 20288cf6634SMike Pritchard.Sq vmstat -m . 2032a94e401SPoul-Henning Kamp.Pp 2042a94e401SPoul-Henning KampA 2052a94e401SPoul-Henning Kamp.Fa type 2062a94e401SPoul-Henning Kampis defined using the 2072a94e401SPoul-Henning Kamp.Va malloc_type_t 208cc4a02e2SMatthew Dillontypedef via the 209cc4a02e2SMatthew Dillon.Fn MALLOC_DECLARE 210cc4a02e2SMatthew Dillonand 211cc4a02e2SMatthew Dillon.Fn MALLOC_DEFINE 212cc4a02e2SMatthew Dillonmacros. 2132a94e401SPoul-Henning Kamp.Bd -literal -offset indent 2142a94e401SPoul-Henning Kamp/* sys/something/foo_extern.h */ 2152a94e401SPoul-Henning Kamp 216cc4a02e2SMatthew DillonMALLOC_DECLARE(M_FOOBUF); 2172a94e401SPoul-Henning Kamp 2182a94e401SPoul-Henning Kamp/* sys/something/foo_main.c */ 2192a94e401SPoul-Henning Kamp 220cc4a02e2SMatthew DillonMALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); 2212a94e401SPoul-Henning Kamp 2222a94e401SPoul-Henning Kamp/* sys/something/foo_subr.c */ 2232a94e401SPoul-Henning Kamp 2243136363fSRuslan Ermilov\&... 2250b014ec5SPoul-Henning KampMALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT); 2262a94e401SPoul-Henning Kamp 227367f1374SMatthew Dillon.Ed 22888cf6634SMike Pritchard.Sh RETURN VALUES 22960dca836SPhilippe CharnierThe 23044a8ff31SArchie Cobbs.Fn malloc , 23144a8ff31SArchie Cobbs.Fn realloc , 23244a8ff31SArchie Cobbsand 23344a8ff31SArchie Cobbs.Fn reallocf 23460dca836SPhilippe Charnierfunctions return a kernel virtual address that is suitably aligned for 23560dca836SPhilippe Charnierstorage of any type of object, or 236367f1374SMatthew Dillon.Dv NULL 23744a8ff31SArchie Cobbsif the request could not be satisfied (implying that 238367f1374SMatthew Dillon.Dv M_NOWAIT 23944a8ff31SArchie Cobbswas set). 24044a8ff31SArchie Cobbs.Sh IMPLEMENTATION NOTES 24144a8ff31SArchie CobbsThe memory allocator allocates memory in chunks that have size a power 24244a8ff31SArchie Cobbsof two for requests up to the size of a page of memory. 24344a8ff31SArchie CobbsFor larger requests, one or more pages is allocated. 24444a8ff31SArchie CobbsWhile it should not be relied upon, this information may be useful for 24544a8ff31SArchie Cobbsoptimizing the efficiency of memory use. 24679525d59SAlfred Perlstein.Pp 24779525d59SAlfred PerlsteinMalloc flags documented above should 24879525d59SAlfred Perlstein.Em NOT 24979525d59SAlfred Perlsteinbe used with 25079525d59SAlfred Perlstein.Xr mbuf 9 25179525d59SAlfred Perlsteinroutines as it will cause undesired results. 25279525d59SAlfred Perlstein.Pp 25379525d59SAlfred PerlsteinAny calls to 25479525d59SAlfred Perlstein.Fn malloc 25579525d59SAlfred Perlsteinor 25679525d59SAlfred Perlstein.Fn free 25779525d59SAlfred Perlsteinwhen holding a 25879525d59SAlfred Perlstein.Xr vnode 9 25979525d59SAlfred Perlsteininterlock, will cause a LOR (Lock Order Reversal) due to the 26079525d59SAlfred Perlsteininterwining of VM Objects and Vnodes. 26188cf6634SMike Pritchard.Sh SEE ALSO 26263264a55SSheldon Hearn.Xr vmstat 8 , 26379525d59SAlfred Perlstein.Xr vnode 9 26488cf6634SMike Pritchard.Sh DIAGNOSTICS 26588cf6634SMike PritchardA kernel compiled with the 26688cf6634SMike Pritchard.Dv DIAGNOSTIC 26743d1df33SAlexander Langerconfiguration option attempts to detect memory corruption caused by 26888cf6634SMike Pritchardsuch things as writing outside the allocated area and imbalanced calls to the 26988cf6634SMike Pritchard.Fn malloc 27088cf6634SMike Pritchardand 27188cf6634SMike Pritchard.Fn free 2721111b49cSSheldon Hearnfunctions. 2731111b49cSSheldon HearnFailing consistency checks will cause a panic or a system console 27488cf6634SMike Pritchardmessage: 27588cf6634SMike Pritchard.Bl -bullet -offset indent -compact 27688cf6634SMike Pritchard.Pp 27788cf6634SMike Pritchard.It 27888cf6634SMike Pritchardpanic: 27988cf6634SMike Pritchard.Dq malloc: bogus type 28088cf6634SMike Pritchard.It 28188cf6634SMike Pritchardpanic: 28288cf6634SMike Pritchard.Dq malloc: allocation too large 28388cf6634SMike Pritchard.It 28488cf6634SMike Pritchardpanic: 28588cf6634SMike Pritchard.Dq malloc: wrong bucket 28688cf6634SMike Pritchard.It 28788cf6634SMike Pritchardpanic: 28888cf6634SMike Pritchard.Dq malloc: lost data 28988cf6634SMike Pritchard.It 29088cf6634SMike Pritchardpanic: 29188cf6634SMike Pritchard.Dq free: address 0x%x out of range 29288cf6634SMike Pritchard.It 29388cf6634SMike Pritchardpanic: 29488cf6634SMike Pritchard.Dq free: type %d out of range 29588cf6634SMike Pritchard.It 29688cf6634SMike Pritchardpanic: 29788cf6634SMike Pritchard.Dq free: unaligned addr Aq description of object 29888cf6634SMike Pritchard.It 29988cf6634SMike Pritchardpanic: 30088cf6634SMike Pritchard.Dq free: item modified 30188cf6634SMike Pritchard.It 30288cf6634SMike Pritchardpanic: 30388cf6634SMike Pritchard.Dq free: multiple free[s] 30488cf6634SMike Pritchard.It 30588cf6634SMike Pritchard.Dq Data modified on freelist: Aq description of object 30688cf6634SMike Pritchard.El 307