2 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
3 .\" All rights reserved.
5 .\" This code is derived from software contributed to The NetBSD Foundation
6 .\" by Paul Kranenburg.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
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.
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.
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 $
39 .Dd September 22, 2013
44 .Nm kmalloc_cachealign ,
47 .Nm kmalloc_raise_limit ,
50 .Nd kernel memory management routines
55 .Fn kmalloc "unsigned long size" "struct malloc_type *type" "int flags"
57 .Fn kmalloc_cachealign "unsigned long size" "struct malloc_type *type" "int flags"
59 .Fn kfree "void *addr" "struct malloc_type *type"
61 .Fn krealloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
63 .Fn kmalloc_raise_limit "struct malloc_type *type" "size_t bytes"
64 .Fn MALLOC_DECLARE type
68 .Fn MALLOC_DEFINE type shortdesc longdesc
72 function allocates uninitialized memory in kernel address space for an
73 object whose size is specified by
75 .Fn kmalloc_cachealign
78 except that the allocated memory will be cache line size aligned.
82 function releases memory at address
84 that was previously allocated by
87 The memory is not zeroed.
88 The kernel implementation of
97 function changes the size of the previously allocated memory referenced by
102 The contents of the memory are unchanged up to the lesser of the new and
104 Note that the returned value may differ from
106 If the requested memory cannot be allocated,
108 is returned and the memory referenced by
110 is valid and unchanged.
117 function behaves identically to
119 for the specified size.
121 .Fn kmalloc_raise_limit
122 is used to increase the internal pool limit to
124 Under most of the cases
125 the default internal pool limit should be more than enough,
126 so this function is currently rarely used and must be used with care.
128 Unlike its standard C library counterpart
130 the kernel version takes two more arguments.
133 argument further qualifies
135 operational characteristics as follows:
136 .Bl -tag -width indent
138 Causes the allocated memory to be set to all zeros.
146 if the request cannot be immediately fulfilled due to resource shortage.
149 is required when running in an interrupt context.
151 Indicates that it is OK to wait for resources.
152 If the request cannot be immediately fulfilled, the current process is put
153 to sleep to wait for resources to be released by other processes.
154 Before the internal pool limit is reached,
159 functions cannot return
164 If the internal pool limit is reached and
166 is not specified along with
168 the system will panic.
169 If the internal pool limit is reached and
171 is specified along with
179 instead of panicing the system.
183 to dig into the system's reserved free pages looking for enough room to
184 perform the allocation.
185 This is typically used in interrupts where you cannot afford
188 Before the internal pool limit is reached,
193 functions cannot return
198 If the internal pool limit is reached and
200 is not specified along with
202 the system will panic.
203 If the internal pool limit is reached and
205 is specified along with
213 instead of panicing the system.
215 Indicates that the system can dig into its reserve in order to obtain the
217 This option used to be called
219 but has been renamed to something more obvious.
220 This option has been deprecated and is slowly being removed from the kernel,
221 and so should not be used with any new code.
223 Rounds up the size to the nearest power of 2.
225 This flag is usually specified along with
229 so when the interal pool limit is reached,
233 functions will not panic the system,
237 This flag is usually used on the kernel code path that is triggered by
238 user space programs' requests.
241 Exactly one of either
250 argument is used to perform statistics on memory usage, and for
252 It can be used to identify multiple allocations.
253 The statistics can be examined by
265 .Bd -literal -offset indent
266 /* sys/something/foo_extern.h */
268 MALLOC_DECLARE(M_FOOBUF);
270 /* sys/something/foo_main.c */
272 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
274 /* sys/something/foo_subr.c */
277 buf = kmalloc(sizeof *buf, M_FOOBUF, M_NOWAIT);
280 .Sh IMPLEMENTATION NOTES
281 The memory allocator allocates memory in chunks that have size a power
282 of two for requests up to the size of a page of memory.
283 For larger requests, one or more pages is allocated.
284 The allocated memory will be at least 8 bytes aligned.
285 While it should not be relied upon, this information may be useful for
286 optimizing the efficiency of memory use.
292 functions return a kernel virtual address that is suitably aligned for
293 storage of any type of object, or
295 if the request could not be satisfied (implying that
301 A kernel compiled with the
303 configuration option attempts to detect memory corruption caused by
304 such things as writing outside the allocated area and imbalanced calls to the
309 Failing consistency checks will cause a panic or a system console