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