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 133The 134.Fn vm_page_alloc 135family of functions allocate one or more pages of physical memory. 136Most kernel code should not call these functions directly but should instead 137use a kernel memory allocator such as 138.Xr malloc 9 139or 140.Xr uma 9 , 141or should use a higher-level interface to the page cache, such as 142.Xr vm_page_grab 9 . 143.Pp 144All of the functions take a 145.Fa req 146parameter which encodes the allocation priority and optional modifier flags, 147described below. 148The functions whose names do not include 149.Dq noobj 150additionally insert the pages starting at index 151.Fa pindex 152in the 153VM object 154.Fa object . 155The object must be write-locked and not have a page already resident at the 156specified index. 157The functions whose names include 158.Dq domain 159support NUMA-aware allocation by returning pages from the 160.Xr numa 4 161domain specified by 162.Fa domain . 163.Pp 164The 165.Fn vm_page_alloc_after 166and 167.Fn vm_page_alloc_domain_after 168functions behave identically to 169.Fn vm_page_alloc 170and 171.Fn vm_page_alloc_domain , 172respectively, except that they take an additional parameter 173.Fa mpred 174which must be the page resident in 175.Fa object 176with largest index smaller than 177.Fa pindex , 178or 179.Dv NULL 180if no such page exists. 181These functions exist to optimize the common case of loops that allocate 182multiple pages at successive indices within an object. 183.Pp 184The 185.Fn vm_page_alloc_contig 186and 187.Fn vm_page_alloc_noobj_contig 188functions and their NUMA-aware variants allocate a physically contiguous run of 189.Fa npages 190pages which satisfies the specified constraints. 191The 192.Fa low 193and 194.Fa high 195parameters specify a physical address range from which the run is to 196be allocated. 197The 198.Fa alignment 199parameter specifies the requested alignment of the first page in the run 200and must be a power of two. 201If the 202.Fa boundary 203parameter is non-zero, the pages constituting the run will not cross a 204physical address that is a multiple of the parameter value, which must be a 205power of two. 206If 207.Fa memattr 208is not equal to 209.Dv VM_MEMATTR_DEFAULT , 210then mappings of the returned pages created by, e.g., 211.Xr pmap_enter 9 212or 213.Xr pmap_qenter 9 , 214will carry the machine-dependent encoding of the memory attribute. 215Additionally, the direct mapping of the page, if any, will be updated to 216reflect the requested memory attribute. 217.Pp 218The 219.Fn vm_page_alloc_freelist 220and 221.Fn vm_page_alloc_freelist_domain 222functions behave identically to 223.Fn vm_page_alloc_noobj 224and 225.Fn vm_page_alloc_noobj_domain , 226respectively, except that a successful allocation will return a page from the 227specified physical memory freelist. 228These functions are not intended for use outside of the virtual memory 229subsystem and exist only to support the requirements of certain platforms. 230.Sh REQUEST FLAGS 231All page allocator functions accept a 232.Fa req 233parameter that governs certain aspects of the function's behavior. 234.Pp 235The 236.Dv VM_ALLOC_WAITOK , 237.Dv VM_ALLOC_WAITFAIL , 238and 239.Dv VM_ALLOC_NOWAIT 240flags specify the behavior of the allocator if free pages could not be 241immediately allocated. 242The 243.Dv VM_ALLOC_WAITOK 244flag can only be used with the 245.Dq noobj 246variants. 247If 248.Dv VM_ALLOC_NOWAIT 249is specified, then the allocator gives up and returns 250.Dv NULL . 251.Dv VM_ALLOC_NOWAIT 252is specified implicitly if none of the flags are present in the request. 253If either 254.Dv VM_ALLOC_WAITOK 255or 256.Dv VM_ALLOC_WAITFAIL 257is specified, the allocator will put the calling thread to sleep until 258sufficient free pages become available. 259At this point, if 260.Dv VM_ALLOC_WAITFAIL 261is specified the allocator will return 262.Dv NULL , 263and if 264.Dv VM_ALLOC_WAITOK 265is specified the allocator will retry the allocation. 266After a failed 267.Dv VM_ALLOC_WAITFAIL 268allocation returns, the VM object, if any, will have been unlocked while the 269thread was sleeping. 270In this case the VM object write lock will be re-acquired before the function 271call returns. 272.Pp 273.Fa req 274also encodes the allocation request priority. 275By default the page(s) are allocated with no special treatment. 276If the number of available free pages is below a certain watermark, the 277allocation will fail or the allocating thread will sleep, depending on 278the specified wait flag. 279The watermark is computed at boot time and corresponds to a small (less than 280one percent) fraction of the system's total physical memory. 281To 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 284The page can be allocated if the free page count is above the interrupt 285reserved water mark. 286This flag should be used only when the system really needs the page. 287.It Dv VM_ALLOC_INTERRUPT 288The allocation will fail only if zero free pages are available. 289This flag should be used only if the consequences of an allocation failure 290are worse than leaving the system without free memory. 291For example, this flag is used when allocating kernel page table pages, where 292allocation failures trigger a kernel panic. 293.El 294.Pp 295The following optional flags can further modify allocator behavior: 296.Bl -tag -width ".Dv VM_ALLOC_NOBUSY" 297.It Dv VM_ALLOC_SBUSY 298The returned page will be shared-busy. 299This flag may only be specified when allocating pages in a VM object. 300.It Dv VM_ALLOC_NOBUSY 301The returned page will not be busy. 302This flag is implicit when allocating pages without a VM object. 303When allocating pages in a VM object, and neither 304.Dv VM_ALLOC_SBUSY 305nor 306.Dv VM_ALLOC_NOBUSY 307are specified, the returned pages will be exclusively busied. 308.It Dv VM_ALLOC_NODUMP 309The returned page will not be included in any kernel core dumps 310regardless of whether or not it is mapped in to KVA. 311.It Dv VM_ALLOC_WIRED 312The returned page will be wired. 313.It Dv VM_ALLOC_ZERO 314If this flag is specified, the 315.Dq noobj 316variants will return zeroed pages. 317The other allocator interfaces ignore this flag. 318.It Dv VM_ALLOC_NORECLAIM 319If this flag is specified and the request can not be immediately satisfied, 320the allocator will not attempt to break superpage reservations to satisfy the 321allocation. 322This may be useful when the overhead of scanning the reservation queue 323outweighs the cost of a failed allocation. 324This flag may be used only with the 325.Dq contig 326variants, and must not be specified in combination with 327.Dv VM_ALLOC_WAITOK . 328.It Dv VM_ALLOC_COUNT(n) 329Hint that at least 330.Fa n 331pages will be allocated by the caller in the near future. 332.Fa n 333must be no larger than 65535. 334If the system is short of free pages, this hint may cause the kernel 335to reclaim memory more aggressively than it would otherwise. 336.El 337.Sh RETURN VALUES 338If the allocation was successful, a pointer to the 339.Vt struct vm_page 340corresponding to the allocated page is returned. 341If the allocation request specified multiple pages, the returned 342pointer points to an array of 343.Vt struct vm_page 344constituting the run. 345Upon failure, 346.Dv NULL 347is returned. 348Regardless of whether the allocation succeeds or fails, the VM 349object 350.Fa object 351will 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 359This manual page was written by 360.An Chad David Aq Mt davidc@acns.ab.ca . 361