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 November 21, 2017
  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 .It Dv M_POWEROF2
 218 Rounds up the size to the nearest power of 2.
 219 .It Dv M_NULLOK
 220 This flag is usually specified along with
 221 .Dv M_WAITOK
 222 or
 223 .Dv M_INTWAIT ,
 224 so when the interal pool limit is reached,
 225 .Fn kmalloc
 226 and
 227 .Fn krealloc ,
 228 functions will not panic the system,
 229 instead,
 230 .Dv NULL
 231 will be returned.
 232 This flag is usually used on the kernel code path that is triggered by
 233 user space programs' requests.
 234 .El
 235 .Pp
 236 Exactly one of either
 237 .Dv M_WAITOK ,
 238 .Dv M_INTWAIT
 239 or
 240 .Dv M_NOWAIT
 241 must be specified.
 242 .Pp
 243 The
 244 .Fa type
 245 argument is used to perform statistics on memory usage, and for
 246 basic sanity checks.
 247 It can be used to identify multiple allocations.
 248 The statistics can be examined by
 249 .Sq vmstat -m .
 250 .Pp
 251 A
 252 .Fa type
 253 is defined using the
 254 .Va malloc_type_t
 255 typedef via the
 256 .Fn MALLOC_DECLARE
 257 and
 258 .Fn MALLOC_DEFINE
 259 macros.
 260 .Bd -literal -offset indent
 261 /* sys/something/foo_extern.h */
 262
 263 MALLOC_DECLARE(M_FOOBUF);
 264
 265 /* sys/something/foo_main.c */
 266
 267 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
 268
 269 /* sys/something/foo_subr.c */
 270
 271 \&...
 272 buf = kmalloc(sizeof *buf, M_FOOBUF, M_NOWAIT);
 273
 274 .Ed
 275 .Sh IMPLEMENTATION NOTES
 276 The memory allocator allocates memory in chunks that have size a power
 277 of two for requests up to the size of a page of memory.
 278 For larger requests, one or more pages is allocated.
 279 The allocated memory will be at least 8 bytes aligned.
 280 While it should not be relied upon, this information may be useful for
 281 optimizing the efficiency of memory use.
 282 .Sh RETURN VALUES
 283 The
 284 .Fn kmalloc
 285 and
 286 .Fn krealloc ,
 287 functions return a kernel virtual address that is suitably aligned for
 288 storage of any type of object, or
 289 .Dv NULL
 290 if the request could not be satisfied (implying that
 291 .Dv M_NOWAIT
 292 or
 293 .Dv M_NULLOK
 294 was set).
 295 .Sh DIAGNOSTICS
 296 A kernel compiled with the
 297 .Dv INVARIANTS
 298 configuration option attempts to detect memory corruption caused by
 299 such things as writing outside the allocated area and imbalanced calls to the
 300 .Fn kmalloc
 301 and
 302 .Fn kfree
 303 functions.
 304 Failing consistency checks will cause a panic or a system console
 305 message.
 306 .Sh SEE ALSO
 307 .Xr vmstat 8 ,
 308 .Xr contigmalloc 9 ,
 309 .Xr kstrdup 9 ,
 310 .Xr memory 9 ,
 311 .Xr vnode 9