--- name: "vm_page_alloc" section: "9" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/vm_page_alloc" --- # vm\_page\_alloc(9) allocate a page of memory ## NAME **vm\_page\_alloc** – allocate a page of memory ## SYNOPSIS **#include \** **#include \** **#include \** *vm\_page\_t*\ **vm\_page\_alloc**(*vm\_object\_t object*, *vm\_pindex\_t pindex*, *int req*); *vm\_page\_t*\ **vm\_page\_alloc\_after**(*vm\_object\_t object*, *vm\_pindex\_t pindex*, *int req*, *vm\_page\_t mpred*); *vm\_page\_t*\ **vm\_page\_alloc\_contig**(*vm\_object\_t object*, *vm\_pindex\_t pindex*, *int req*, *u\_long npages*, *vm\_paddr\_t low*, *vm\_paddr\_t high*, *u\_long alignment*, *vm\_paddr\_t boundary*, *vm\_memattr\_t memattr*); *vm\_page\_t*\ **vm\_page\_alloc\_contig\_domain**(*vm\_object\_t object*, *vm\_pindex\_t pindex*, *int req*, *u\_long npages*, *vm\_paddr\_t low*, *vm\_paddr\_t high*, *u\_long alignment*, *vm\_paddr\_t boundary*, *vm\_memattr\_t memattr*); *vm\_page\_t*\ **vm\_page\_alloc\_domain**(*vm\_object\_t object*, *vm\_pindex\_t pindex*, *int domain*, *int req*); *vm\_page\_t*\ **vm\_page\_alloc\_domain\_after**(*vm\_object\_t object*, *vm\_pindex\_t pindex*, *int domain*, *int req*, *vm\_page\_t mpred*); *vm\_page\_t*\ **vm\_page\_alloc\_noobj**(*int req*); *vm\_page\_t*\ **vm\_page\_alloc\_noobj\_contig**(*int req*, *u\_long npages*, *vm\_paddr\_t low*, *vm\_paddr\_t high*, *u\_long alignment*, *vm\_paddr\_t boundary*, *vm\_memattr\_t memattr*); *vm\_page\_t*\ **vm\_page\_alloc\_noobj\_contig\_domain**(*int domain*, *int req*, *u\_long npages*, *vm\_paddr\_t low*, *vm\_paddr\_t high*, *u\_long alignment*, *vm\_paddr\_t boundary*, *vm\_memattr\_t memattr*); *vm\_page\_t*\ **vm\_page\_alloc\_noobj\_domain**(*int domain*, *int req*); ## DESCRIPTION The **vm\_page\_alloc**() family of functions allocate one or more pages of physical memory. Most kernel code should not call these functions directly but should instead use a kernel memory allocator such as [malloc(9)](/malloc/9.md) or [uma(9)](/uma/9.md), or should use a higher-level interface to the page cache, such as [vm\_page\_grab(9)](/vm_page_grab/9.md). All of the functions take a *req* parameter which encodes the allocation priority and optional modifier flags, described below. The functions whose names do not include “noobj” additionally insert the pages starting at index *pindex* in the VM object *object*. The object must be write-locked and not have a page already resident at the specified index. The functions whose names include “domain” support NUMA-aware allocation by returning pages from the [numa(4)](/numa/4.md) domain specified by *domain*. The **vm\_page\_alloc\_after**() and **vm\_page\_alloc\_domain\_after**() functions behave identically to **vm\_page\_alloc**() and **vm\_page\_alloc\_domain**(), respectively, except that they take an additional parameter *mpred* which must be the page resident in *object* with largest index smaller than *pindex*, or NULL if no such page exists. These functions exist to optimize the common case of loops that allocate multiple pages at successive indices within an object. The **vm\_page\_alloc\_contig**() and **vm\_page\_alloc\_noobj\_contig**() functions and their NUMA-aware variants allocate a physically contiguous run of *npages* pages which satisfies the specified constraints. The *low* and *high* parameters specify a physical address range from which the run is to be allocated. The *alignment* parameter specifies the requested alignment of the first page in the run and must be a power of two. If the *boundary* parameter is non-zero, the pages constituting the run will not cross a physical address that is a multiple of the parameter value, which must be a power of two. If *memattr* is not equal to VM\_MEMATTR\_DEFAULT, then mappings of the returned pages created by, e.g., [pmap\_enter(9)](/pmap_enter/9.md) or [pmap\_qenter(9)](/pmap_qenter/9.md), will carry the machine-dependent encoding of the memory attribute. Additionally, the direct mapping of the page, if any, will be updated to reflect the requested memory attribute. ## REQUEST FLAGS All page allocator functions accept a *req* parameter that governs certain aspects of the function's behavior. The VM\_ALLOC\_WAITOK, VM\_ALLOC\_WAITFAIL, and VM\_ALLOC\_NOWAIT flags specify the behavior of the allocator if free pages could not be immediately allocated. The VM\_ALLOC\_WAITOK flag can only be used with the “noobj” variants. If VM\_ALLOC\_NOWAIT is specified, then the allocator gives up and returns NULL. VM\_ALLOC\_NOWAIT is specified implicitly if none of the flags are present in the request. If either VM\_ALLOC\_WAITOK or VM\_ALLOC\_WAITFAIL is specified, the allocator will put the calling thread to sleep until sufficient free pages become available. At this point, if VM\_ALLOC\_WAITFAIL is specified the allocator will return NULL, and if VM\_ALLOC\_WAITOK is specified the allocator will retry the allocation. After a failed VM\_ALLOC\_WAITFAIL allocation returns, the VM object, if any, will have been unlocked while the thread was sleeping. In this case the VM object write lock will be re-acquired before the function call returns. *req* also encodes the allocation request priority. By default the page(s) are allocated with no special treatment. If the number of available free pages is below a certain watermark, the allocation will fail or the allocating thread will sleep, depending on the specified wait flag. The watermark is computed at boot time and corresponds to a small (less than one percent) fraction of the system's total physical memory. To allocate memory more aggressively, one of following flags may be specified. - VM\_ALLOC\_SYSTEM The page can be allocated if the free page count is above the interrupt reserved water mark. This flag should be used only when the system really needs the page. - VM\_ALLOC\_INTERRUPT The allocation will fail only if zero free pages are available. This flag should be used only if the consequences of an allocation failure are worse than leaving the system without free memory. For example, this flag is used when allocating kernel page table pages, where allocation failures trigger a kernel panic. The following optional flags can further modify allocator behavior: - VM\_ALLOC\_SBUSY The returned page will be shared-busy. This flag may only be specified when allocating pages in a VM object. - VM\_ALLOC\_NOBUSY The returned page will not be busy. This flag is implicit when allocating pages without a VM object. When allocating pages in a VM object, and neither VM\_ALLOC\_SBUSY nor VM\_ALLOC\_NOBUSY are specified, the returned pages will be exclusively busied. - VM\_ALLOC\_NODUMP The returned page will not be included in any kernel core dumps regardless of whether or not it is mapped in to KVA. - VM\_ALLOC\_WIRED The returned page will be wired. - VM\_ALLOC\_ZERO If this flag is specified, the “noobj” variants will return zeroed pages. The other allocator interfaces ignore this flag. - VM\_ALLOC\_NORECLAIM If this flag is specified and the request can not be immediately satisfied, the allocator will not attempt to break superpage reservations to satisfy the allocation. This may be useful when the overhead of scanning the reservation queue outweighs the cost of a failed allocation. This flag may be used only with the “contig” variants, and must not be specified in combination with VM\_ALLOC\_WAITOK. - VM\_ALLOC\_COUNT(n) Hint that at least *n* pages will be allocated by the caller in the near future. *n* must be no larger than 65535. If the system is short of free pages, this hint may cause the kernel to reclaim memory more aggressively than it would otherwise. - VM\_ALLOC\_NOFREE The caller asserts that the returned page will never be released. If this flag is specified, the allocator will try to fetch a page from a special per-domain arena in order to curb long-term physical memory fragmentation. ## RETURN VALUES If the allocation was successful, a pointer to the *struct* *vm\_page* corresponding to the allocated page is returned. If the allocation request specified multiple pages, the returned pointer points to an array of *struct* *vm\_page* constituting the run. Upon failure, NULL is returned. Regardless of whether the allocation succeeds or fails, the VM object *object* will be write-locked upon return. ## SEE ALSO [numa(4)](/numa/4.md), [malloc(9)](/malloc/9.md), [uma(9)](/uma/9.md), [vm\_page\_grab(9)](/vm_page_grab/9.md), vm\_page\_sbusy(9) ## AUTHORS This manual page was written by Chad David ⟨*davidc@acns.ab.ca*⟩.