share/man/man9/vm_page_alloc.9

   1 .\"
   2 .\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
   3 .\" Copyright (c) 2021 The FreeBSD Foundation
   4 .\"
   5 .\" Portions of this documentation were written by Mark Johnston under
   6 .\" sponsorship from the FreeBSD Foundation.
   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(s), this list of conditions and the following disclaimer as
  13 .\"    the first lines of this file unmodified other than the possible
  14 .\"    addition of one or more copyright notices.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice(s), this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  20 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  21 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  22 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  23 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  25 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  26 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  29 .\" DAMAGE.
  30 .\"
  31 .\" $FreeBSD$
  32 .\"
  33 .Dd November 11, 2021
  34 .Dt VM_PAGE_ALLOC 9
  35 .Os
  36 .Sh NAME
  37 .Nm vm_page_alloc
  38 .Nd "allocate a page of memory"
  39 .Sh SYNOPSIS
  40 .In sys/param.h
  41 .In vm/vm.h
  42 .In vm/vm_page.h
  43 .Ft vm_page_t
  44 .Fn vm_page_alloc "vm_object_t object" "vm_pindex_t pindex" "int req"
  45 .Ft vm_page_t
  46 .Fo vm_page_alloc_after
  47 .Fa "vm_object_t object"
  48 .Fa "vm_pindex_t pindex"
  49 .Fa "int req"
  50 .Fa "vm_page_t mpred"
  51 .Fc
  52 .Ft vm_page_t
  53 .Fo vm_page_alloc_contig
  54 .Fa "vm_object_t object"
  55 .Fa "vm_pindex_t pindex"
  56 .Fa "int req"
  57 .Fa "u_long npages"
  58 .Fa "vm_paddr_t low"
  59 .Fa "vm_paddr_t high"
  60 .Fa "u_long alignment"
  61 .Fa "vm_paddr_t boundary"
  62 .Fa "vm_memattr_t memattr"
  63 .Fc
  64 .Ft vm_page_t
  65 .Fo vm_page_alloc_contig_domain
  66 .Fa "vm_object_t object"
  67 .Fa "vm_pindex_t pindex"
  68 .Fa "int req"
  69 .Fa "u_long npages"
  70 .Fa "vm_paddr_t low"
  71 .Fa "vm_paddr_t high"
  72 .Fa "u_long alignment"
  73 .Fa "vm_paddr_t boundary"
  74 .Fa "vm_memattr_t memattr"
  75 .Fc
  76 .Ft vm_page_t
  77 .Fo vm_page_alloc_domain
  78 .Fa "vm_object_t object"
  79 .Fa "vm_pindex_t pindex"
  80 .Fa "int domain"
  81 .Fa "int req"
  82 .Fc
  83 .Ft vm_page_t
  84 .Fo vm_page_alloc_domain_after
  85 .Fa "vm_object_t object"
  86 .Fa "vm_pindex_t pindex"
  87 .Fa "int domain"
  88 .Fa "int req"
  89 .Fa "vm_page_t mpred"
  90 .Fc
  91 .Ft vm_page_t
  92 .Fo vm_page_alloc_freelist
  93 .Fa "int freelist"
  94 .Fa "int req"
  95 .Fc
  96 .Ft vm_page_t
  97 .Fo vm_page_alloc_freelist_domain
  98 .Fa "int domain"
  99 .Fa "int freelist"
 100 .Fa "int req"
 101 .Fc
 102 .Ft vm_page_t
 103 .Fo vm_page_alloc_noobj
 104 .Fa "int req"
 105 .Fc
 106 .Ft vm_page_t
 107 .Fo vm_page_alloc_noobj_contig
 108 .Fa "int req"
 109 .Fa "u_long npages"
 110 .Fa "vm_paddr_t low"
 111 .Fa "vm_paddr_t high"
 112 .Fa "u_long alignment"
 113 .Fa "vm_paddr_t boundary"
 114 .Fa "vm_memattr_t memattr"
 115 .Fc
 116 .Ft vm_page_t
 117 .Fo vm_page_alloc_noobj_contig_domain
 118 .Fa "int domain"
 119 .Fa "int req"
 120 .Fa "u_long npages"
 121 .Fa "vm_paddr_t low"
 122 .Fa "vm_paddr_t high"
 123 .Fa "u_long alignment"
 124 .Fa "vm_paddr_t boundary"
 125 .Fa "vm_memattr_t memattr"
 126 .Fc
 127 .Ft vm_page_t
 128 .Fo vm_page_alloc_noobj_domain
 129 .Fa "int domain"
 130 .Fa "int req"
 131 .Fc
 132 .Sh DESCRIPTION
 133 The
 134 .Fn vm_page_alloc
 135 family of functions allocate one or more pages of physical memory.
 136 Most kernel code should not call these functions directly but should instead
 137 use a kernel memory allocator such as
 138 .Xr malloc 9
 139 or
 140 .Xr uma 9 ,
 141 or should use a higher-level interface to the page cache, such as
 142 .Xr vm_page_grab 9 .
 143 .Pp
 144 All of the functions take a
 145 .Fa req
 146 parameter which encodes the allocation priority and optional modifier flags,
 147 described below.
 148 The functions whose names do not include
 149 .Dq noobj
 150 additionally insert the pages starting at index
 151 .Fa pindex
 152 in the
 153 VM object
 154 .Fa object .
 155 The object must be write-locked and not have a page already resident at the
 156 specified index.
 157 The functions whose names include
 158 .Dq domain
 159 support NUMA-aware allocation by returning pages from the
 160 .Xr numa 4
 161 domain specified by
 162 .Fa domain .
 163 .Pp
 164 The
 165 .Fn vm_page_alloc_after
 166 and
 167 .Fn vm_page_alloc_domain_after
 168 functions behave identically to
 169 .Fn vm_page_alloc
 170 and
 171 .Fn vm_page_alloc_domain ,
 172 respectively, except that they take an additional parameter
 173 .Fa mpred
 174 which must be the page resident in
 175 .Fa object
 176 with largest index smaller than
 177 .Fa pindex ,
 178 or
 179 .Dv NULL
 180 if no such page exists.
 181 These functions exist to optimize the common case of loops that allocate
 182 multiple pages at successive indices within an object.
 183 .Pp
 184 The
 185 .Fn vm_page_alloc_contig
 186 and
 187 .Fn vm_page_alloc_noobj_contig
 188 functions and their NUMA-aware variants allocate a physically contiguous run of
 189 .Fa npages
 190 pages which satisfies the specified constraints.
 191 The
 192 .Fa low
 193 and
 194 .Fa high
 195 parameters specify a physical address range from which the run is to
 196 be allocated.
 197 The
 198 .Fa alignment
 199 parameter specifies the requested alignment of the first page in the run
 200 and must be a power of two.
 201 If the
 202 .Fa boundary
 203 parameter is non-zero, the pages constituting the run will not cross a
 204 physical address that is a multiple of the parameter value, which must be a
 205 power of two.
 206 If
 207 .Fa memattr
 208 is not equal to
 209 .Dv VM_MEMATTR_DEFAULT ,
 210 then mappings of the returned pages created by, e.g.,
 211 .Xr pmap_enter 9
 212 or
 213 .Xr pmap_qenter 9 ,
 214 will carry the machine-dependent encoding of the memory attribute.
 215 Additionally, the direct mapping of the page, if any, will be updated to
 216 reflect the requested memory attribute.
 217 .Pp
 218 The
 219 .Fn vm_page_alloc_freelist
 220 and
 221 .Fn vm_page_alloc_freelist_domain
 222 functions behave identically to
 223 .Fn vm_page_alloc_noobj
 224 and
 225 .Fn vm_page_alloc_noobj_domain ,
 226 respectively, except that a successful allocation will return a page from the
 227 specified physical memory freelist.
 228 These functions are not intended for use outside of the virtual memory
 229 subsystem and exist only to support the requirements of certain platforms.
 230 .Sh REQUEST FLAGS
 231 All page allocator functions accept a
 232 .Fa req
 233 parameter that governs certain aspects of the function's behavior.
 234 .Pp
 235 The
 236 .Dv VM_ALLOC_WAITOK ,
 237 .Dv VM_ALLOC_WAITFAIL ,
 238 and
 239 .Dv VM_ALLOC_NOWAIT
 240 flags specify the behavior of the allocator if free pages could not be
 241 immediately allocated.
 242 The
 243 .Dv VM_ALLOC_WAITOK
 244 flag can only be used with the
 245 .Dq noobj
 246 variants.
 247 If
 248 .Dv VM_ALLOC_NOWAIT
 249 is specified, then the allocator gives up and returns
 250 .Dv NULL .
 251 .Dv VM_ALLOC_NOWAIT
 252 is specified implicitly if none of the flags are present in the request.
 253 If either
 254 .Dv VM_ALLOC_WAITOK
 255 or
 256 .Dv VM_ALLOC_WAITFAIL
 257 is specified, the allocator will put the calling thread to sleep until
 258 sufficient free pages become available.
 259 At this point, if
 260 .Dv VM_ALLOC_WAITFAIL
 261 is specified the allocator will return
 262 .Dv NULL ,
 263 and if
 264 .Dv VM_ALLOC_WAITOK
 265 is specified the allocator will retry the allocation.
 266 After a failed
 267 .Dv VM_ALLOC_WAITFAIL
 268 allocation returns, the VM object, if any, will have been unlocked while the
 269 thread was sleeping.
 270 In this case the VM object write lock will be re-acquired before the function
 271 call returns.
 272 .Pp
 273 .Fa req
 274 also encodes the allocation request priority.
 275 By default the page(s) are allocated with no special treatment.
 276 If the number of available free pages is below a certain watermark, the
 277 allocation will fail or the allocating thread will sleep, depending on
 278 the specified wait flag.
 279 The watermark is computed at boot time and corresponds to a small (less than
 280 one percent) fraction of the system's total physical memory.
 281 To allocate memory more aggressively, one of following flags may be specified.
 282 .Bl -tag -width ".Dv VM_ALLOC_INTERRUPT"
 283 .It Dv VM_ALLOC_SYSTEM
 284 The page can be allocated if the free page count is above the interrupt
 285 reserved water mark.
 286 This flag should be used only when the system really needs the page.
 287 .It Dv VM_ALLOC_INTERRUPT
 288 The allocation will fail only if zero free pages are available.
 289 This flag should be used only if the consequences of an allocation failure
 290 are worse than leaving the system without free memory.
 291 For example, this flag is used when allocating kernel page table pages, where
 292 allocation failures trigger a kernel panic.
 293 .El
 294 .Pp
 295 The following optional flags can further modify allocator behavior:
 296 .Bl -tag -width ".Dv VM_ALLOC_NOBUSY"
 297 .It Dv VM_ALLOC_SBUSY
 298 The returned page will be shared-busy.
 299 This flag may only be specified when allocating pages in a VM object.
 300 .It Dv VM_ALLOC_NOBUSY
 301 The returned page will not be busy.
 302 This flag is implicit when allocating pages without a VM object.
 303 When allocating pages in a VM object, and neither
 304 .Dv VM_ALLOC_SBUSY
 305 nor
 306 .Dv VM_ALLOC_NOBUSY
 307 are specified, the returned pages will be exclusively busied.
 308 .It Dv VM_ALLOC_NODUMP
 309 The returned page will not be included in any kernel core dumps
 310 regardless of whether or not it is mapped in to KVA.
 311 .It Dv VM_ALLOC_WIRED
 312 The returned page will be wired.
 313 .It Dv VM_ALLOC_ZERO
 314 If this flag is specified, the
 315 .Dq noobj
 316 variants will return zeroed pages.
 317 The other allocator interfaces ignore this flag.
 318 .It Dv VM_ALLOC_NORECLAIM
 319 If this flag is specified and the request can not be immediately satisfied,
 320 the allocator will not attempt to break superpage reservations to satisfy the
 321 allocation.
 322 This may be useful when the overhead of scanning the reservation queue
 323 outweighs the cost of a failed allocation.
 324 This flag may be used only with the
 325 .Dq contig
 326 variants, and must not be specified in combination with
 327 .Dv VM_ALLOC_WAITOK .
 328 .It Dv VM_ALLOC_COUNT(n)
 329 Hint that at least
 330 .Fa n
 331 pages will be allocated by the caller in the near future.
 332 .Fa n
 333 must be no larger than 65535.
 334 If the system is short of free pages, this hint may cause the kernel
 335 to reclaim memory more aggressively than it would otherwise.
 336 .El
 337 .Sh RETURN VALUES
 338 If the allocation was successful, a pointer to the
 339 .Vt struct vm_page
 340 corresponding to the allocated page is returned.
 341 If the allocation request specified multiple pages, the returned
 342 pointer points to an array of
 343 .Vt struct vm_page
 344 constituting the run.
 345 Upon failure,
 346 .Dv NULL
 347 is returned.
 348 Regardless of whether the allocation succeeds or fails, the VM
 349 object
 350 .Fa object
 351 will be write-locked upon return.
 352 .Sh SEE ALSO
 353 .Xr numa 4 ,
 354 .Xr malloc 9 ,
 355 .Xr uma 9 ,
 356 .Xr vm_page_grab 9 ,
 357 .Xr vm_page_sbusy 9
 358 .Sh AUTHORS
 359 This manual page was written by
 360 .An Chad David Aq Mt davidc@acns.ab.ca .