share/man/man9/kmalloc.9

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