diff options
Diffstat (limited to 'static/freebsd/man9/vm_page_alloc.9 4.html')
| -rw-r--r-- | static/freebsd/man9/vm_page_alloc.9 4.html | 248 |
1 files changed, 0 insertions, 248 deletions
diff --git a/static/freebsd/man9/vm_page_alloc.9 4.html b/static/freebsd/man9/vm_page_alloc.9 4.html deleted file mode 100644 index b9f43502..00000000 --- a/static/freebsd/man9/vm_page_alloc.9 4.html +++ /dev/null @@ -1,248 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">VM_PAGE_ALLOC(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">VM_PAGE_ALLOC(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">vm_page_alloc</code> — - <span class="Nd">allocate a page of memory</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">vm/vm.h</a>></code> - <br/> - <code class="In">#include <<a class="In">vm/vm_page.h</a>></code></p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc</code>(<var class="Fa" style="white-space: nowrap;">vm_object_t - object</var>, <var class="Fa" style="white-space: nowrap;">vm_pindex_t - pindex</var>, <var class="Fa" style="white-space: nowrap;">int - req</var>);</p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc_after</code>(<var class="Fa">vm_object_t - object</var>, <var class="Fa">vm_pindex_t pindex</var>, <var class="Fa">int - req</var>, <var class="Fa">vm_page_t mpred</var>);</p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc_contig</code>(<var class="Fa">vm_object_t - object</var>, <var class="Fa">vm_pindex_t pindex</var>, <var class="Fa">int - req</var>, <var class="Fa">u_long npages</var>, <var class="Fa">vm_paddr_t - low</var>, <var class="Fa">vm_paddr_t high</var>, <var class="Fa">u_long - alignment</var>, <var class="Fa">vm_paddr_t boundary</var>, - <var class="Fa">vm_memattr_t memattr</var>);</p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc_contig_domain</code>(<var class="Fa">vm_object_t - object</var>, <var class="Fa">vm_pindex_t pindex</var>, <var class="Fa">int - req</var>, <var class="Fa">u_long npages</var>, <var class="Fa">vm_paddr_t - low</var>, <var class="Fa">vm_paddr_t high</var>, <var class="Fa">u_long - alignment</var>, <var class="Fa">vm_paddr_t boundary</var>, - <var class="Fa">vm_memattr_t memattr</var>);</p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc_domain</code>(<var class="Fa">vm_object_t - object</var>, <var class="Fa">vm_pindex_t pindex</var>, <var class="Fa">int - domain</var>, <var class="Fa">int req</var>);</p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc_domain_after</code>(<var class="Fa">vm_object_t - object</var>, <var class="Fa">vm_pindex_t pindex</var>, <var class="Fa">int - domain</var>, <var class="Fa">int req</var>, <var class="Fa">vm_page_t - mpred</var>);</p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc_noobj</code>(<var class="Fa">int - req</var>);</p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc_noobj_contig</code>(<var class="Fa">int - req</var>, <var class="Fa">u_long npages</var>, <var class="Fa">vm_paddr_t - low</var>, <var class="Fa">vm_paddr_t high</var>, <var class="Fa">u_long - alignment</var>, <var class="Fa">vm_paddr_t boundary</var>, - <var class="Fa">vm_memattr_t memattr</var>);</p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc_noobj_contig_domain</code>(<var class="Fa">int - domain</var>, <var class="Fa">int req</var>, <var class="Fa">u_long - npages</var>, <var class="Fa">vm_paddr_t low</var>, - <var class="Fa">vm_paddr_t high</var>, <var class="Fa">u_long - alignment</var>, <var class="Fa">vm_paddr_t boundary</var>, - <var class="Fa">vm_memattr_t memattr</var>);</p> -<p class="Pp"><var class="Ft">vm_page_t</var> - <br/> - <code class="Fn">vm_page_alloc_noobj_domain</code>(<var class="Fa">int - domain</var>, <var class="Fa">int req</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The - <a class="permalink" href="#vm_page_alloc"><code class="Fn" id="vm_page_alloc">vm_page_alloc</code></a>() - 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 <a class="Xr">malloc(9)</a> or - <a class="Xr">uma(9)</a>, or should use a higher-level interface to the page - cache, such as <a class="Xr">vm_page_grab(9)</a>.</p> -<p class="Pp">All of the functions take a <var class="Fa">req</var> 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 <var class="Fa">pindex</var> - in the VM object <var class="Fa">object</var>. 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 <a class="Xr">numa(4)</a> domain - specified by <var class="Fa">domain</var>.</p> -<p class="Pp" id="vm_page_alloc_after">The - <a class="permalink" href="#vm_page_alloc_after"><code class="Fn">vm_page_alloc_after</code></a>() - and - <a class="permalink" href="#vm_page_alloc_domain_after"><code class="Fn" id="vm_page_alloc_domain_after">vm_page_alloc_domain_after</code></a>() - functions behave identically to <code class="Fn">vm_page_alloc</code>() and - <a class="permalink" href="#vm_page_alloc_domain"><code class="Fn" id="vm_page_alloc_domain">vm_page_alloc_domain</code></a>(), - respectively, except that they take an additional parameter - <var class="Fa">mpred</var> which must be the page resident in - <var class="Fa">object</var> with largest index smaller than - <var class="Fa">pindex</var>, or <code class="Dv">NULL</code> 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.</p> -<p class="Pp" id="vm_page_alloc_contig">The - <a class="permalink" href="#vm_page_alloc_contig"><code class="Fn">vm_page_alloc_contig</code></a>() - and - <a class="permalink" href="#vm_page_alloc_noobj_contig"><code class="Fn" id="vm_page_alloc_noobj_contig">vm_page_alloc_noobj_contig</code></a>() - functions and their NUMA-aware variants allocate a physically contiguous run - of <var class="Fa">npages</var> pages which satisfies the specified - constraints. The <var class="Fa">low</var> and <var class="Fa">high</var> - parameters specify a physical address range from which the run is to be - allocated. The <var class="Fa">alignment</var> parameter specifies the - requested alignment of the first page in the run and must be a power of two. - If the <var class="Fa">boundary</var> 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 - <var class="Fa">memattr</var> is not equal to - <code class="Dv">VM_MEMATTR_DEFAULT</code>, then mappings of the returned - pages created by, e.g., <a class="Xr">pmap_enter(9)</a> or - <a class="Xr">pmap_qenter(9)</a>, 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.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="REQUEST_FLAGS"><a class="permalink" href="#REQUEST_FLAGS">REQUEST - FLAGS</a></h1> -<p class="Pp">All page allocator functions accept a <var class="Fa">req</var> - parameter that governs certain aspects of the function's behavior.</p> -<p class="Pp">The <code class="Dv">VM_ALLOC_WAITOK</code>, - <code class="Dv">VM_ALLOC_WAITFAIL</code>, and - <code class="Dv">VM_ALLOC_NOWAIT</code> flags specify the behavior of the - allocator if free pages could not be immediately allocated. The - <code class="Dv">VM_ALLOC_WAITOK</code> flag can only be used with the - “noobj” variants. If <code class="Dv">VM_ALLOC_NOWAIT</code> - is specified, then the allocator gives up and returns - <code class="Dv">NULL</code>. <code class="Dv">VM_ALLOC_NOWAIT</code> is - specified implicitly if none of the flags are present in the request. If - either <code class="Dv">VM_ALLOC_WAITOK</code> or - <code class="Dv">VM_ALLOC_WAITFAIL</code> is specified, the allocator will - put the calling thread to sleep until sufficient free pages become - available. At this point, if <code class="Dv">VM_ALLOC_WAITFAIL</code> is - specified the allocator will return <code class="Dv">NULL</code>, and if - <code class="Dv">VM_ALLOC_WAITOK</code> is specified the allocator will - retry the allocation. After a failed - <code class="Dv">VM_ALLOC_WAITFAIL</code> 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.</p> -<p class="Pp"><var class="Fa">req</var> 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.</p> -<dl class="Bl-tag"> - <dt id="VM_ALLOC_SYSTEM"><a class="permalink" href="#VM_ALLOC_SYSTEM"><code class="Dv">VM_ALLOC_SYSTEM</code></a></dt> - <dd>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.</dd> - <dt id="VM_ALLOC_INTERRUPT"><a class="permalink" href="#VM_ALLOC_INTERRUPT"><code class="Dv">VM_ALLOC_INTERRUPT</code></a></dt> - <dd>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.</dd> -</dl> -<p class="Pp">The following optional flags can further modify allocator - behavior:</p> -<dl class="Bl-tag"> - <dt id="VM_ALLOC_SBUSY"><a class="permalink" href="#VM_ALLOC_SBUSY"><code class="Dv">VM_ALLOC_SBUSY</code></a></dt> - <dd>The returned page will be shared-busy. This flag may only be specified - when allocating pages in a VM object.</dd> - <dt id="VM_ALLOC_NOBUSY"><a class="permalink" href="#VM_ALLOC_NOBUSY"><code class="Dv">VM_ALLOC_NOBUSY</code></a></dt> - <dd>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 <code class="Dv">VM_ALLOC_SBUSY</code> nor - <code class="Dv">VM_ALLOC_NOBUSY</code> are specified, the returned pages - will be exclusively busied.</dd> - <dt id="VM_ALLOC_NODUMP"><a class="permalink" href="#VM_ALLOC_NODUMP"><code class="Dv">VM_ALLOC_NODUMP</code></a></dt> - <dd>The returned page will not be included in any kernel core dumps regardless - of whether or not it is mapped in to KVA.</dd> - <dt id="VM_ALLOC_WIRED"><a class="permalink" href="#VM_ALLOC_WIRED"><code class="Dv">VM_ALLOC_WIRED</code></a></dt> - <dd>The returned page will be wired.</dd> - <dt id="VM_ALLOC_ZERO"><a class="permalink" href="#VM_ALLOC_ZERO"><code class="Dv">VM_ALLOC_ZERO</code></a></dt> - <dd>If this flag is specified, the “noobj” variants will return - zeroed pages. The other allocator interfaces ignore this flag.</dd> - <dt id="VM_ALLOC_NORECLAIM"><a class="permalink" href="#VM_ALLOC_NORECLAIM"><code class="Dv">VM_ALLOC_NORECLAIM</code></a></dt> - <dd>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 - <code class="Dv">VM_ALLOC_WAITOK</code>.</dd> - <dt id="VM_ALLOC_COUNT(n)"><a class="permalink" href="#VM_ALLOC_COUNT(n)"><code class="Dv">VM_ALLOC_COUNT(n)</code></a></dt> - <dd>Hint that at least <var class="Fa">n</var> pages will be allocated by the - caller in the near future. <var class="Fa">n</var> 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.</dd> - <dt id="VM_ALLOC_NOFREE"><a class="permalink" href="#VM_ALLOC_NOFREE"><code class="Dv">VM_ALLOC_NOFREE</code></a></dt> - <dd>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.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp">If the allocation was successful, a pointer to the - <var class="Vt">struct vm_page</var> corresponding to the allocated page is - returned. If the allocation request specified multiple pages, the returned - pointer points to an array of <var class="Vt">struct vm_page</var> - constituting the run. Upon failure, <code class="Dv">NULL</code> is - returned. Regardless of whether the allocation succeeds or fails, the VM - object <var class="Fa">object</var> will be write-locked upon return.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">numa(4)</a>, <a class="Xr">malloc(9)</a>, - <a class="Xr">uma(9)</a>, <a class="Xr">vm_page_grab(9)</a>, - <a class="Xr">vm_page_sbusy(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">This manual page was written by <span class="An">Chad David</span> - <<a class="Mt" href="mailto:davidc@acns.ab.ca">davidc@acns.ab.ca</a>>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">August 4, 2024</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |