Differential D32035 Diff 97016 share/man/man9/vm_page_alloc.9

Changeset View

Standalone View

View Options

share/man/man9/vm_page_alloc.9

.\" .\"

.\" 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 .\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted provided that the following conditions .\" modification, are permitted provided that the following conditions

.\" are met: .\" are met:

.\" 1. Redistributions of source code must retain the above copyright .\" 1. Redistributions of source code must retain the above copyright

.\" notice(s), this list of conditions and the following disclaimer as .\" notice(s), this list of conditions and the following disclaimer as

.\" the first lines of this file unmodified other than the possible .\" the first lines of this file unmodified other than the possible

.\" addition of one or more copyright notices. .\" addition of one or more copyright notices.

.\" 2. Redistributions in binary form must reproduce the above copyright .\" 2. Redistributions in binary form must reproduce the above copyright

Show All 9 Lines

.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER

.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH

.\" DAMAGE. .\" DAMAGE.

.\" .\"

.\" $FreeBSD$ .\" $FreeBSD$

.\" .\"

.Dd November 16, 2016 .Dd October 17, 2021

.Dt VM_PAGE_ALLOC 9 .Dt VM_PAGE_ALLOC 9

.Os .Os

.Sh NAME .Sh NAME

.Nm vm_page_alloc .Nm vm_page_alloc

.Nd "allocate a page for a" .Nd "allocate a page of memory"

.Vt vm_object

.Sh SYNOPSIS .Sh SYNOPSIS

.In sys/param.h .In sys/param.h

.In vm/vm.h .In vm/vm.h

.In vm/vm_page.h .In vm/vm_page.h

.Ft vm_page_t .Ft vm_page_t

.Fn vm_page_alloc "vm_object_t object" "vm_pindex_t pindex" "int req" .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 .Sh DESCRIPTION

The The

.Fn vm_page_alloc .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

.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 functions take a

alcUnsubmitted

Done

.Xr vm_page_grab 9 .

.Pp

- All of the function variants take a

+ All of the functions take a

.Fa req

alc:

.Fa req

parameter which encodes the allocation priority and optional modifier flags,

described below.

The functions whose names do not include

.Dq noobj

additionally insert the pages starting at index

alcUnsubmitted

Done

described below.

- The functions not containing a

+ The functions whose names do not include

.Dq noobj

- identifier additionally insert the pages starting at index

+ additionally insert the pages starting at index

.Fa pindex

alc:

.Fa pindex .Fa pindex

within in the

VM object

.Fa object . .Fa object .

It is assumed that a page has not already been allocated at The object must be write-locked and not have a page already resident at the

.Fa pindex . specified index.

The page returned is inserted into the object, unless The functions whose names include

.Dv VM_ALLOC_NOOBJ .Dq domain

is specified in the support NUMA-aware allocation by returning pages from the

alcUnsubmitted

Done

VM object

- .Fa object ,

- which must be write-locked.

- The object must not already have a page resident at the specified index.

+ .Fa object .

+ The object must be write-locked and not have a page already resident at the specified index.

Each allocation function has a

alc:

.Fa req . .Xr numa 4

domain specified by

.Fa domain .

kibUnsubmitted

Done

I believe it would be somewhat helpful to expand 'anonymous' there as meaning 'not belonging to an object' as opposed to 'belonging to OBJ_ANON object'

kib: I believe it would be somewhat helpful to expand 'anonymous' there as meaning 'not belonging to…

alcUnsubmitted

Done

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

+ The functions whose names include

+ .Dq domain

+ support NUMA-aware allocation by returning pages from the

.Xr numa 4

alc:

.Pp .Pp

The

.Fn vm_page_alloc_after

and

.Fn vm_page_alloc_domain_after

functions behave identically to

.Fn vm_page_alloc .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 ,

.Dv NULL

if no such page exists.

These functions exist to optimize the common case of loops that allocate

alcUnsubmitted

Done

if no such page exists.

- These functions exist solely to provide an optimization for loops which may

+ These functions exist to optimize the common case of loops that

allocate multiple pages at successive indices within an object.

alc:

multiple pages at successive indices within an object.

.Pp .Pp

Its arguments are:

.Bl -tag -width ".Fa object"

.It Fa object

The VM object to allocate the page for.

The The

.Fa object .Fn vm_page_alloc_contig

must be locked if and

kibUnsubmitted

Done

Perhaps mention that VM_ALLOC_WAITOK is invalid for obj != NULL there?
Otherwise it is still looking somewhat self-contradicting to me.

kib: Perhaps mention that VM_ALLOC_WAITOK is invalid for obj != NULL there? Otherwise it is still…

.Dv VM_ALLOC_NOOBJ .Fn vm_page_alloc_noobj_contig

is not specified. functions and their NUMA-aware variants allocate a physically contiguous run of

.It Fa pindex .Fa npages

The index into the object at which the page should be inserted. pages which satisfies the specified constraints.

alcUnsubmitted

Done

.Fn vm_page_alloc_noobj_contig

- functions and their NUMA-aware variants allocate a run of

+ functions and their NUMA-aware variants allocate a physically contiguous run of

.Fa npages

- physically contiguous pages which satisfies the specified constraints.

+ pages which satisfies the specified constraints.

The

.Fa low

alc:

.It Fa req The

The bitwise-inclusive OR of a class and any optional flags indicating .Fa low

how the page should be allocated. 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.

.Fa memattr

is not equal to

.Dv VM_MEMATTR_DEFAULT ,

then mappings of the returned pages created by, e.g.,

.Xr pmap_enter 9

alcUnsubmitted

Done

More importantly, we set the md_page field that is read by a future call to a mapping function, e.g., pmap_enter, pmap_qenter, etc., when creating a PTE so that the PTE encodes the right memory attributes.

alc: More importantly, we set the md_page field that is read by a future call to a mapping function…

.Xr pmap_qenter 9 ,

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.

.Pp .Pp

Exactly one of the following classes must be specified: 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

alcUnsubmitted

Done

.Fa req

- parameter describing certain parameters of the allocation.

+ parameter that governs certain aspects of the function's behavior.

.Pp

The

.Dv VM_ALLOC_WAITOK ,

alc:

subsystem and exist only to support the requirements of certain platforms.

.Sh REQUEST FLAGS

All page allocator functions accept a

.Fa req

parameter that governs certain aspects of the function's behavior.

.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.

alcUnsubmitted

Done

.Dq noobj

- allocator interfaces.

+ variants.

.Dv VM_ALLOC_NOWAIT

alc:

The

.Dv VM_ALLOC_WAITOK

flag can only be used with the

.Dq noobj

variants.

.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

.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

alcUnsubmitted

Done

.Dv VM_ALLOC_WAITOK

- is specified the allocator will re-attempt the allocation.

+ is specified the allocator will retry the allocation.

After a failed

alc:

is specified the allocator will return

kibUnsubmitted

Done

This statement somewhat contradict the previous sentence. If you mean that VM_ALLOC_WAITOK can be only used with noobj allocators, then why state that it unlocks the object?

kib: This statement somewhat contradict the previous sentence. If you mean that VM_ALLOC_WAITOK can…

kibUnsubmitted

Not Done

This text still leaves the same issue present. At least I find the text self-contradicting or confusing at best. You cannot unlock object when noobj allocator is used.

kib: This text still leaves the same issue present. At least I find the text self-contradicting or…

markjAuthorUnsubmitted

Done

This is why I included "if any". I could perhaps expand it to, "if one is specified by the interface" but I am not sure how to make it less confusing.

markj: This is why I included "if any". I could perhaps expand it to, "if one is specified by the…

kibUnsubmitted

Not Done

You are saying that VM_ALLOC_WAITOK is only valid for _noobj functions, right? Why not to say it outright when the flag is listed instead at the end, after you said that !noobj + VM_ALLOC_WAITOK relock (which is not true because you should not pass VM_ALLOC_WAITOK at all).

kib: You are saying that VM_ALLOC_WAITOK is only valid for _noobj functions, right? Why not to say…

.Dv NULL ,

and if

.Dv VM_ALLOC_WAITOK

alcUnsubmitted

Done

To avoid confusion, this should explicitly describe the status of the lock upon return.

alc: To avoid confusion, this should explicitly describe the status of the lock upon return.

is specified the allocator will retry 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.

In this case the VM object write lock will be re-acquired before the function

call returns.

.Pp

.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" .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 .It Dv VM_ALLOC_SYSTEM

The page can be allocated if the cache is empty and the free The page can be allocated if the free page count is above the interrupt

page count is above the interrupt reserved water mark. reserved water mark.

This flag should be used only when the system really needs the page. This flag should be used only when the system really needs the page.

.It Dv VM_ALLOC_INTERRUPT .It Dv VM_ALLOC_INTERRUPT

.Fn vm_page_alloc The allocation will fail only if zero free pages are available.

is being called during an interrupt. This flag should be used only if the consequences of an allocation failure

A page will be returned successfully if the free page count is greater are worse than leaving the system without free memory.

than zero. For example, this flag is used when allocating kernel page table pages, where

kibUnsubmitted

Done

I think this is misleading, because even VM_ALLOC_INTERRUPT allocations can fail. Might be it is better to say something along lines 'if a way to handle allocation failure at the caller is worse than consuming the last free page'. Then you could mention kernel page table page allocation as an example.

kib: I think this is misleading, because even VM_ALLOC_INTERRUPT allocations can fail. Might be it…

allocation failures trigger a kernel panic.

.El .El

.Pp .Pp

The optional flags are: The following optional flags can further modify allocator behavior:

bcrUnsubmitted

Done

s/behaviour/behavior/
American English in our docs

bcr: s/behaviour/behavior/ American English in our docs

.Bl -tag -width ".Dv VM_ALLOC_NOBUSY" .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 .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.

kibUnsubmitted

Done

when allocating pages without a VM object ? It sound too strange to me.

kib: `when allocating pages without a VM object` ? It sound too strange to me.

When allocating pages in a VM object, and neither

.Dv VM_ALLOC_SBUSY

nor

.Dv VM_ALLOC_NOBUSY

are specified, the returned pages will be exclusively busied.

.It Dv VM_ALLOC_NODUMP .It Dv VM_ALLOC_NODUMP

The returned page will not be included in any kernel core dumps The returned page will not be included in any kernel core dumps

regardless of whether or not it is mapped in to KVA. 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 .It Dv VM_ALLOC_WIRED

The returned page will be wired. The returned page will be wired.

.It Dv VM_ALLOC_ZERO .It Dv VM_ALLOC_ZERO

Indicate a preference for a pre-zeroed page. If this flag is specified, the

There is no guarantee that the returned page will be zeroed, but it .Dq noobj

will have the variants will return zeroed pages.

alcUnsubmitted

Done

.Dq noobj

- allocators will return zeroed pages.

+ variants will return zeroed pages.

The other allocator interfaces ignore this flag.

alc:

.Dv PG_ZERO The other allocator interfaces ignore this flag.

flag set if it is zeroed. .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 .El

.El

.Sh RETURN VALUES .Sh RETURN VALUES

The If the allocation was successful, a pointer to the

alcUnsubmitted

Done

I find this confusing because vm_page_t is itself a pointer type.

alc: I find this confusing because vm_page_t is itself a pointer type.

.Vt vm_page_t .Vt struct vm_page

that was allocated is returned if successful; otherwise, corresponding to the allocated page is returned.

If the allocation request specified multiple pages, the returned

pointer points to an array of

.Vt struct vm_page

constituting the run.

Upon failure,

.Dv NULL .Dv NULL

is returned. is returned.

.Sh NOTES Regardless of whether the allocation succeeds or fails, the VM

The pager process is always upgraded to object

.Dv VM_ALLOC_SYSTEM .Fa object

unless will be write-locked upon return.

.Dv VM_ALLOC_INTERRUPT .Sh SEE ALSO

is set. .Xr numa 4 ,

.Xr malloc 9 ,

.Xr uma 9 ,

.Xr vm_page_grab 9 ,

.Xr vm_page_sbusy 9

.Sh AUTHORS .Sh AUTHORS

This manual page was written by This manual page was written by

.An Chad David Aq Mt davidc@acns.ab.ca . .An Chad David Aq Mt davidc@acns.ab.ca .