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