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 September 22, 2013
  40 .Dt KMALLOC 9
  41 .Os
  42 .Sh NAME
  43 .Nm kmalloc ,
  44 .Nm kmalloc_cachealign ,
  45 .Nm kfree ,
  46 .Nm krealloc ,
  47 .Nm kmalloc_raise_limit ,
  48 .Nm MALLOC_DEFINE ,
  49 .Nm MALLOC_DECLARE
  50 .Nd kernel memory management routines
  51 .Sh SYNOPSIS
  52 .In sys/types.h
  53 .In sys/malloc.h
  54 .Ft void *
  55 .Fn kmalloc "unsigned long size" "struct malloc_type *type" "int flags"
  56 .Ft void *
  57 .Fn kmalloc_cachealign "unsigned long size" "struct malloc_type *type" "int flags"
  58 .Ft void
  59 .Fn kfree "void *addr" "struct malloc_type *type"
  60 .Ft void *
  61 .Fn krealloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
  62 .Ft void
  63 .Fn kmalloc_raise_limit "struct malloc_type *type" "size_t bytes"
  64 .Fn MALLOC_DECLARE type
  65 .In sys/param.h
  66 .In sys/malloc.h
  67 .In sys/kernel.h
  68 .Fn MALLOC_DEFINE type shortdesc longdesc
  69 .Sh DESCRIPTION
  70 The
  71 .Fn kmalloc
  72 function allocates uninitialized memory in kernel address space for an
  73 object whose size is specified by
  74 .Fa size .
  75 .Fn kmalloc_cachealign
  76 function is same as
  77 .Fn kmalloc
  78 except that the allocated memory will be cache line size aligned.
  79 .Pp
  80 The
  81 .Fn kfree
  82 function releases memory at address
  83 .Fa addr
  84 that was previously allocated by
  85 .Fn kmalloc
  86 for re-use.
  87 The memory is not zeroed.
  88 The kernel implementation of
  89 .Fn kfree
  90 does not allow
  91 .Fa addr
  92 to be
  93 .Dv NULL .
  94 .Pp
  95 The
  96 .Fn krealloc
  97 function changes the size of the previously allocated memory referenced by
  98 .Fa addr
  99 to
 100 .Fa size
 101 bytes.
 102 The contents of the memory are unchanged up to the lesser of the new and
 103 old sizes.
 104 Note that the returned value may differ from
 105 .Fa addr .
 106 If the requested memory cannot be allocated,
 107 .Dv NULL
 108 is returned and the memory referenced by
 109 .Fa addr
 110 is valid and unchanged.
 111 If
 112 .Fa addr
 113 is
 114 .Dv NULL ,
 115 the
 116 .Fn krealloc
 117 function behaves identically to
 118 .Fn kmalloc
 119 for the specified size.
 120 .Pp
 121 .Fn kmalloc_raise_limit
 122 is used to increase the internal pool limit to
 123 .Fa bytes .
 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.
 127 .Pp
 128 Unlike its standard C library counterpart
 129 .Pq Xr malloc 3 ,
 130 the kernel version takes two more arguments.
 131 The
 132 .Fa flags
 133 argument further qualifies
 134 .Fn kmalloc Ns 's
 135 operational characteristics as follows:
 136 .Bl -tag -width indent
 137 .It Dv M_ZERO
 138 Causes the allocated memory to be set to all zeros.
 139 .It Dv M_NOWAIT
 140 Causes
 141 .Fn kmalloc
 142 and
 143 .Fn krealloc ,
 144 to return
 145 .Dv NULL
 146 if the request cannot be immediately fulfilled due to resource shortage.
 147 Note that
 148 .Dv M_NOWAIT
 149 is required when running in an interrupt context.
 150 .It Dv M_WAITOK
 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,
 155 the
 156 .Fn kmalloc
 157 and
 158 .Fn krealloc ,
 159 functions cannot return
 160 .Dv NULL
 161 if
 162 .Dv M_WAITOK
 163 is specified.
 164 If the internal pool limit is reached and
 165 .Dv M_NULLOK
 166 is not specified along with
 167 .Dv M_WAITOK ,
 168 the system will panic.
 169 If the internal pool limit is reached and
 170 .Dv M_NULLOK
 171 is specified along with
 172 .Dv M_WAITOK ,
 173 the
 174 .Fn kmalloc
 175 and
 176 .Fn krealloc ,
 177 functions return
 178 .Dv NULL
 179 instead of panicing the system.
 180 .It Dv M_INTWAIT
 181 Indicates
 182 .Fn kmalloc
 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
 186 .Fn kmalloc
 187 to fail.
 188 Before the internal pool limit is reached,
 189 the
 190 .Fn kmalloc
 191 and
 192 .Fn krealloc ,
 193 functions cannot return
 194 .Dv NULL
 195 if
 196 .Dv M_INTWAIT
 197 is specified.
 198 If the internal pool limit is reached and
 199 .Dv M_NULLOK
 200 is not specified along with
 201 .Dv M_INTWAIT ,
 202 the system will panic.
 203 If the internal pool limit is reached and
 204 .Dv M_NULLOK
 205 is specified along with
 206 .Dv M_INTWAIT ,
 207 the
 208 .Fn kmalloc
 209 and
 210 .Fn krealloc ,
 211 functions return
 212 .Dv NULL
 213 instead of panicing the system.
 214 .It Dv M_USE_RESERVE
 215 Indicates that the system can dig into its reserve in order to obtain the
 216 requested memory.
 217 This option used to be called
 218 .Dv M_KERNEL
 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.
 222 .It Dv M_POWEROF2
 223 Rounds up the size to the nearest power of 2.
 224 .It Dv M_NULLOK
 225 This flag is usually specified along with
 226 .Dv M_WAITOK
 227 or
 228 .Dv M_INTWAIT ,
 229 so when the interal pool limit is reached,
 230 .Fn kmalloc
 231 and
 232 .Fn krealloc ,
 233 functions will not panic the system,
 234 instead,
 235 .Dv NULL
 236 will be returned.
 237 This flag is usually used on the kernel code path that is triggered by
 238 user space programs' requests.
 239 .El
 240 .Pp
 241 Exactly one of either
 242 .Dv M_WAITOK ,
 243 .Dv M_INTWAIT
 244 or
 245 .Dv M_NOWAIT
 246 must be specified.
 247 .Pp
 248 The
 249 .Fa type
 250 argument is used to perform statistics on memory usage, and for
 251 basic sanity checks.
 252 It can be used to identify multiple allocations.
 253 The statistics can be examined by
 254 .Sq vmstat -m .
 255 .Pp
 256 A
 257 .Fa type
 258 is defined using the
 259 .Va malloc_type_t
 260 typedef via the
 261 .Fn MALLOC_DECLARE
 262 and
 263 .Fn MALLOC_DEFINE
 264 macros.
 265 .Bd -literal -offset indent
 266 /* sys/something/foo_extern.h */
 267
 268 MALLOC_DECLARE(M_FOOBUF);
 269
 270 /* sys/something/foo_main.c */
 271
 272 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
 273
 274 /* sys/something/foo_subr.c */
 275
 276 \&...
 277 buf = kmalloc(sizeof *buf, M_FOOBUF, M_NOWAIT);
 278
 279 .Ed
 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.
 287 .Sh RETURN VALUES
 288 The
 289 .Fn kmalloc
 290 and
 291 .Fn krealloc ,
 292 functions return a kernel virtual address that is suitably aligned for
 293 storage of any type of object, or
 294 .Dv NULL
 295 if the request could not be satisfied (implying that
 296 .Dv M_NOWAIT
 297 or
 298 .Dv M_NULLOK
 299 was set).
 300 .Sh DIAGNOSTICS
 301 A kernel compiled with the
 302 .Dv INVARIANTS
 303 configuration option attempts to detect memory corruption caused by
 304 such things as writing outside the allocated area and imbalanced calls to the
 305 .Fn kmalloc
 306 and
 307 .Fn kfree
 308 functions.
 309 Failing consistency checks will cause a panic or a system console
 310 message.
 311 .Sh SEE ALSO
 312 .Xr vmstat 8 ,
 313 .Xr contigmalloc 9 ,
 314 .Xr memory 9 ,
 315 .Xr vnode 9