Page MenuHomeFreeBSD
Files F111569661

D32035.id96268.diff
No OneTemporary
Actions

D32035.id96268.diff
View Options

Index: share/man/man9/Makefile
===================================================================
--- share/man/man9/Makefile
+++ share/man/man9/Makefile
@@ -2330,6 +2330,17 @@
MLINKS+=vm_map_wire.9 vm_map_wire_mapped.9 \
vm_page_wire.9 vm_page_unwire.9 \
vm_page_wire.9 vm_page_unwire_noq.9
+MLINKS+=vm_page_alloc.9 vm_page_alloc_after.9 \
+ vm_page_alloc.9 vm_page_alloc_contig.9 \
+ vm_page_alloc.9 vm_page_alloc_contig_domain.9 \
+ vm_page_alloc.9 vm_page_alloc_domain.9 \
+ vm_page_alloc.9 vm_page_alloc_domain_after.9 \
+ vm_page_alloc.9 vm_page_alloc_freelist.9 \
+ vm_page_alloc.9 vm_page_alloc_freelist_domain.9 \
+ vm_page_alloc.9 vm_page_alloc_noobj.9 \
+ vm_page_alloc.9 vm_page_alloc_noobj_contig.9 \
+ vm_page_alloc.9 vm_page_alloc_noobj_contig_domain.9 \
+ vm_page_alloc.9 vm_page_alloc_noobj_domain.9
MLINKS+=vm_page_bits.9 vm_page_clear_dirty.9 \
vm_page_bits.9 vm_page_dirty.9 \
vm_page_bits.9 vm_page_is_valid.9 \
Index: share/man/man9/vm_page_alloc.9
===================================================================
--- share/man/man9/vm_page_alloc.9
+++ share/man/man9/vm_page_alloc.9
@@ -1,5 +1,9 @@
.\"
.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
+.\" Copyright (c) 2021 The FreeBSD Foundation
+.\"
+.\" Portions of this documentation were written by Mark Johnston under
+.\" sponsorship from the FreeBSD Foundation.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@@ -26,102 +30,309 @@
.\"
.\" $FreeBSD$
.\"
-.Dd November 16, 2016
+.Dd September 23, 2021
.Dt VM_PAGE_ALLOC 9
.Os
.Sh NAME
.Nm vm_page_alloc
-.Nd "allocate a page for a"
-.Vt vm_object
+.Nd "allocate a page of memory"
.Sh SYNOPSIS
.In sys/param.h
.In vm/vm.h
.In vm/vm_page.h
.Ft vm_page_t
.Fn vm_page_alloc "vm_object_t object" "vm_pindex_t pindex" "int req"
+.Ft vm_page_t
+.Fo vm_page_alloc_after
+.Fa "vm_object_t object"
+.Fa "vm_pindex_t pindex"
+.Fa "int req"
+.Fa "vm_page_t mpred"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_contig
+.Fa "vm_object_t object"
+.Fa "vm_pindex_t pindex"
+.Fa "int req"
+.Fa "u_long npages"
+.Fa "vm_paddr_t low"
+.Fa "vm_paddr_t high"
+.Fa "u_long alignment"
+.Fa "vm_paddr_t boundary"
+.Fa "vm_memattr_t memattr"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_contig_domain
+.Fa "vm_object_t object"
+.Fa "vm_pindex_t pindex"
+.Fa "int req"
+.Fa "u_long npages"
+.Fa "vm_paddr_t low"
+.Fa "vm_paddr_t high"
+.Fa "u_long alignment"
+.Fa "vm_paddr_t boundary"
+.Fa "vm_memattr_t memattr"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_domain
+.Fa "vm_object_t object"
+.Fa "vm_pindex_t pindex"
+.Fa "int domain"
+.Fa "int req"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_domain_after
+.Fa "vm_object_t object"
+.Fa "vm_pindex_t pindex"
+.Fa "int domain"
+.Fa "int req"
+.Fa "vm_page_t mpred"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_freelist
+.Fa "int freelist"
+.Fa "int req"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_freelist_domain
+.Fa "int domain"
+.Fa "int freelist"
+.Fa "int req"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_noobj
+.Fa "int req"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_noobj_contig
+.Fa "int req"
+.Fa "u_long npages"
+.Fa "vm_paddr_t low"
+.Fa "vm_paddr_t high"
+.Fa "u_long alignment"
+.Fa "vm_paddr_t boundary"
+.Fa "vm_memattr_t memattr"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_noobj_contig_domain
+.Fa "int domain"
+.Fa "int req"
+.Fa "u_long npages"
+.Fa "vm_paddr_t low"
+.Fa "vm_paddr_t high"
+.Fa "u_long alignment"
+.Fa "vm_paddr_t boundary"
+.Fa "vm_memattr_t memattr"
+.Fc
+.Ft vm_page_t
+.Fo vm_page_alloc_noobj_domain
+.Fa "int domain"
+.Fa "int req"
+.Fc
.Sh DESCRIPTION
The
.Fn vm_page_alloc
-function allocates a page at
+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
+.Xr malloc 9
+or
+.Xr uma 9 ,
+or should use a higher-level interface to the page cache, such as
+.Xr vm_page_grab 9 .
+.Pp
+All of the function variants take a
+.Fa req
+parameter which encodes the allocation priority and optional modifier flags,
+described below.
+The functions not containing a
+.Dq noobj
+identifier additionally insert the pages starting at index
.Fa pindex
-within
-.Fa object .
-It is assumed that a page has not already been allocated at
-.Fa pindex .
-The page returned is inserted into the object, unless
-.Dv VM_ALLOC_NOOBJ
-is specified in the
-.Fa req .
+in the
+VM object
+.Fa object ,
+which must be write-locked.
+The object must not already have a page resident at the specified index.
+Each allocation function has a
+.Dq _domain
+variant which allocates a page from the
+.Xr numa 4
+domain specified by
+.Fa domain .
.Pp
+The
+.Fn vm_page_alloc_after
+and
+.Fn vm_page_alloc_domain_after
+functions behave identically to
.Fn vm_page_alloc
-will not sleep.
+and
+.Fn vm_page_alloc_domain ,
+respectively, except that they take an additional parameter
+.Fa mpred
+which must be the page resident in
+.Fa object
+with largest index smaller than
+.Fa pindex ,
+or
+.Dv NULL
+if no such page exists.
+These functions exist solely to provide an optimization for loops which may
+allocate multiple pages at successive indices within an object.
.Pp
-Its arguments are:
-.Bl -tag -width ".Fa object"
-.It Fa object
-The VM object to allocate the page for.
The
-.Fa object
-must be locked if
-.Dv VM_ALLOC_NOOBJ
-is not specified.
-.It Fa pindex
-The index into the object at which the page should be inserted.
-.It Fa req
-The bitwise-inclusive OR of a class and any optional flags indicating
-how the page should be allocated.
+.Fn vm_page_alloc_contig
+and
+.Fn vm_page_alloc_noobj_contig
+functions and their NUMA-aware variants allocate a run of
+.Fa npages
+physically contiguous pages which satisfies the specified constraints.
+The
+.Fa low
+and
+.Fa high
+parameters specify a physical address range from which the run is to
+be allocated.
+The
+.Fa alignment
+parameter specifies the requested alignment of the first page in the run
+and must be a power of two.
+If the
+.Fa 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
+.Fa memattr
+is not equal to
+.Dv VM_MEMATTR_DEFAULT ,
+then the direct mapping of the page, if any, will be updated to reflect
+the requested memory mapping attribute.
+.Pp
+The
+.Fn vm_page_alloc_freelist
+and
+.Fn vm_page_alloc_freelist_domain
+functions behave identically to
+.Fn vm_page_alloc_noobj
+and
+.Fn vm_page_alloc_noobj_domain ,
+respectively, except that a successful allocation will return a page from the
+specified physical memory freelist.
+These functions are not intended for use outside of the virtual memory
+subsystem and exist only to support the requirements of certain platforms.
+.Sh REQUEST FLAGS
+All page allocator functions accept a
+.Fa req
+parameter describing certain parameters of the allocation.
+.Pp
+The
+.Dv VM_ALLOC_WAITOK ,
+.Dv VM_ALLOC_WAITFAIL ,
+and
+.Dv VM_ALLOC_NOWAIT
+flags specify the behavior of the allocator if free pages could not be
+immediately allocated.
+The
+.Dv VM_ALLOC_WAITOK
+flag can only be used with the
+.Dq noobj
+allocator interfaces.
+If
+.Dv VM_ALLOC_NOWAIT
+is specified, then the allocator gives up and returns
+.Dv NULL .
+.Dv VM_ALLOC_NOWAIT
+is specified implicitly if none of the flags are present in the request.
+If either
+.Dv VM_ALLOC_WAITOK
+or
+.Dv VM_ALLOC_WAITFAIL
+is specified, the allocator will put the calling thread to sleep until
+sufficient free pages become available.
+At this point, if
+.Dv VM_ALLOC_WAITFAIL
+is specified the allocator will return
+.Dv NULL ,
+and if
+.Dv VM_ALLOC_WAITOK
+is specified the allocator will re-attempt the allocation.
+After a failed
+.Dv VM_ALLOC_WAITFAIL
+allocation returns, the VM object, if any, will have been unlocked while the
+thread was sleeping.
.Pp
-Exactly one of the following classes must be specified:
+.Fa 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.
.Bl -tag -width ".Dv VM_ALLOC_INTERRUPT"
-.It Dv VM_ALLOC_NORMAL
-The page should be allocated with no special treatment.
.It Dv VM_ALLOC_SYSTEM
-The page can be allocated if the cache is empty and the free
-page count is above the interrupt reserved water mark.
+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.
.It Dv VM_ALLOC_INTERRUPT
-.Fn vm_page_alloc
-is being called during an interrupt.
-A page will be returned successfully if the free page count is greater
-than zero.
+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.
.El
.Pp
-The optional flags are:
+The following optional flags can further modify allocator behavior:
.Bl -tag -width ".Dv VM_ALLOC_NOBUSY"
+.It Dv VM_ALLOC_SBUSY
+The returned page will be shared-busy.
+This flag may only be specified when allocating pages in a VM object.
.It Dv VM_ALLOC_NOBUSY
-The returned page will not be exclusive busy.
+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
+.Dv VM_ALLOC_SBUSY
+nor
+.Dv VM_ALLOC_NOBUSY
+are specified, the return pages will be exclusively busied.
.It Dv 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.
-.It Dv VM_ALLOC_NOOBJ
-Do not associate the allocated page with a vm object.
-The
-.Fa object
-argument is ignored.
-.It Dv VM_ALLOC_SBUSY
-The returned page will be shared busy.
.It Dv VM_ALLOC_WIRED
The returned page will be wired.
.It Dv VM_ALLOC_ZERO
-Indicate a preference for a pre-zeroed page.
-There is no guarantee that the returned page will be zeroed, but it
-will have the
-.Dv PG_ZERO
-flag set if it is zeroed.
-.El
+If this flag is specified, the
+.Dq noobj
+allocators will return zeroed pages.
+The other allocator interfaces ignore this flag.
+.It Dv VM_ALLOC_COUNT(n)
+Hint that at least
+.Fa n
+pages will be allocated by the caller in the near future.
+.Fa 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.
.El
.Sh RETURN VALUES
-The
+If the allocation was successful, a pointer to the
+.Vt vm_page_t
+describing the allocated page is returned.
+If the allocation request specified multiple pages, the returned
.Vt vm_page_t
-that was allocated is returned if successful; otherwise,
+will be a pointer to an array of pages constituting the run.
+Upon failure,
.Dv NULL
is returned.
-.Sh NOTES
-The pager process is always upgraded to
-.Dv VM_ALLOC_SYSTEM
-unless
-.Dv VM_ALLOC_INTERRUPT
-is set.
+.Sh SEE ALSO
+.Xr numa 4 ,
+.Xr malloc 9 ,
+.Xr uma 9 ,
+.Xr vm_page_grab 9 ,
+.Xr vm_page_sbusy 9
.Sh AUTHORS
This manual page was written by
.An Chad David Aq Mt davidc@acns.ab.ca .

File Metadata

Mime Type
text/plain
Expires
Thu, Mar 6, 9:49 AM (1 h, 19 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
17012217
Default Alt Text
D32035.id96268.diff (11 KB)

Event Timeline