xref: /dragonfly/share/man/man9/kmalloc.9 (revision 36a3d1d6) 
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.\" $DragonFly: src/share/man/man9/kmalloc.9,v 1.8 2008/01/19 08:23:17 swildner Exp $
39.\"
40.Dd January 15, 2010
41.Dt KMALLOC 9
42.Os
43.Sh NAME
44.Nm kmalloc ,
45.Nm MALLOC ,
46.Nm kfree ,
47.Nm FREE ,
48.Nm krealloc ,
49.Nm MALLOC_DEFINE ,
50.Nm MALLOC_DECLARE
51.Nd kernel memory management routines
52.Sh SYNOPSIS
53.In sys/types.h
54.In sys/malloc.h
55.Ft void *
56.Fn kmalloc "unsigned long size" "struct malloc_type *type" "int flags"
57.Fn MALLOC space cast "unsigned long size" "struct malloc_type *type" "int flags"
58.Ft void
59.Fn kfree "void *addr" "struct malloc_type *type"
60.Fn FREE "void *addr" "struct malloc_type *type"
61.Ft void *
62.Fn krealloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
63.Fn MALLOC_DECLARE type
64.In sys/param.h
65.In sys/malloc.h
66.In sys/kernel.h
67.Fn MALLOC_DEFINE type shortdesc longdesc
68.Sh DESCRIPTION
69The
70.Fn kmalloc
71function allocates uninitialized memory in kernel address space for an
72object whose size is specified by
73.Fa size .
74.Pp
75The
76.Fn kfree
77function releases memory at address
78.Fa addr
79that was previously allocated by
80.Fn kmalloc
81for re-use.
82The memory is not zeroed.
83The kernel implementation of
84.Fn kfree
85does not allow
86.Fa addr
87to be
88.Dv NULL .
89.Pp
90The
91.Fn krealloc
92function changes the size of the previously allocated memory referenced by
93.Fa addr
94to
95.Fa size
96bytes.
97The contents of the memory are unchanged up to the lesser of the new and
98old sizes.
99Note that the returned value may differ from
100.Fa addr .
101If the requested memory cannot be allocated,
102.Dv NULL
103is returned and the memory referenced by
104.Fa addr
105is valid and unchanged.
106If
107.Fa addr
108is
109.Dv NULL ,
110the
111.Fn krealloc
112function behaves identically to
113.Fn kmalloc
114for the specified size.
115.Pp
116The
117.Fn MALLOC
118macro variant is functionally equivalent to
119.Bd -literal -offset indent
120(space) = (cast)kmalloc((u_long)(size), type, flags)
121.Ed
122.Pp
123and the
124.Fn FREE
125macro variant is equivalent to
126.Bd -literal -offset indent
127kfree((addr), type)
128.Ed
129.Pp
130Unlike its standard C library counterpart
131.Pq Xr malloc 3 ,
132the kernel version takes two more arguments.
133The
134.Fa flags
135argument further qualifies
136.Fn kmalloc Ns 's
137operational characteristics as follows:
138.Bl -tag -width indent
139.It Dv M_ZERO
140Causes the allocated memory to be set to all zeros.
141.It Dv M_NOWAIT
142Causes
143.Fn kmalloc
144and
145.Fn krealloc ,
146to return
147.Dv NULL
148if the request cannot be immediately fulfilled due to resource shortage.
149Note that
150.Dv M_NOWAIT
151is required when running in an interrupt context.
152.It Dv M_WAITOK
153Indicates that it is OK to wait for resources.
154If the request cannot be immediately fulfilled, the current process is put
155to sleep to wait for resources to be released by other processes.
156The
157.Fn kmalloc
158and
159.Fn krealloc ,
160functions cannot return
161.Dv NULL
162if
163.Dv M_WAITOK
164is specified.
165.It Dv M_INTWAIT
166Indicates
167.Fn kmalloc
168to dig into the system's reserved free pages looking for enough room to
169perform the allocation.
170This is typically used in interrupts where you cannot afford
171.Fn kmalloc
172to fail.
173.It Dv M_USE_RESERVE
174Indicates that the system can dig into its reserve in order to obtain the
175requested memory.
176This option used to be called
177.Dv M_KERNEL
178but has been renamed to something more obvious.
179This option has been deprecated and is slowly being removed from the kernel,
180and so should not be used with any new code.
181.El
182.Pp
183Exactly one of either
184.Dv M_WAITOK
185or
186.Dv M_NOWAIT
187must be specified.
188.Pp
189The
190.Fa type
191argument is used to perform statistics on memory usage, and for
192basic sanity checks.
193It can be used to identify multiple allocations.
194The statistics can be examined by
195.Sq vmstat -m .
196.Pp
197A
198.Fa type
199is defined using the
200.Va malloc_type_t
201typedef via the
202.Fn MALLOC_DECLARE
203and
204.Fn MALLOC_DEFINE
205macros.
206.Bd -literal -offset indent
207/* sys/something/foo_extern.h */
208
209MALLOC_DECLARE(M_FOOBUF);
210
211/* sys/something/foo_main.c */
212
213MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
214
215/* sys/something/foo_subr.c */
216
217\&...
218MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
219
220.Ed
221.Sh IMPLEMENTATION NOTES
222The memory allocator allocates memory in chunks that have size a power
223of two for requests up to the size of a page of memory.
224For larger requests, one or more pages is allocated.
225While it should not be relied upon, this information may be useful for
226optimizing the efficiency of memory use.
227.Sh RETURN VALUES
228The
229.Fn kmalloc
230and
231.Fn krealloc ,
232functions return a kernel virtual address that is suitably aligned for
233storage of any type of object, or
234.Dv NULL
235if the request could not be satisfied (implying that
236.Dv M_NOWAIT
237was set).
238.Sh DIAGNOSTICS
239A kernel compiled with the
240.Dv INVARIANTS
241configuration option attempts to detect memory corruption caused by
242such things as writing outside the allocated area and imbalanced calls to the
243.Fn kmalloc
244and
245.Fn kfree
246functions.
247Failing consistency checks will cause a panic or a system console
248message.
249.Sh SEE ALSO
250.Xr vmstat 8 ,
251.Xr contigmalloc 9 ,
252.Xr vnode 9
253