Differential D32035 Diff 95585 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 September 23, 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 function variants 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 not containing a

.Dq noobj

identifier 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

.Fa object . VM object

It is assumed that a page has not already been allocated at .Fa object ,

.Fa pindex . which must be write-locked.

The page returned is inserted into the object, unless The object must not already have a page resident at the specified index.

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:

.Dv VM_ALLOC_NOOBJ Each allocation function has a

is specified in the .Dq _domain

.Fa req . variant which allocates a page from the

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:

.Xr numa 4

domain specified by

.Fa domain .

.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 solely to provide an optimization for loops which may

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:

allocate 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

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

.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 control the behavior of the allocator if free pages could not be

immediately allocated.

.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

is specified, the allocator will return

.Dv NULL

and the caller may re-validate VM object state and retry the allocation.

.Fa object .Fa object

must be locked if is not

.Dv VM_ALLOC_NOOBJ .Dv NULL

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…

is not specified. it will have been unlocked during the sleep.

.It Fa pindex If

The index into the object at which the page should be inserted. .Dv VM_ALLOC_WAITOK

.It Fa req was specified, the allocator will retry the allocation internally.

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:

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

how the page should be allocated. .Dv VM_ALLOC_WAITOK

flag is valid only with the

.Dq noobj

allocator functions.

.Pp .Pp

Exactly one of the following classes must be specified: .Fa req

also encodes the allocation request priority, and exactly one of the following

priority classes must be specified:

.Bl -tag -width ".Dv VM_ALLOC_INTERRUPT" .Bl -tag -width ".Dv VM_ALLOC_INTERRUPT"

.It Dv VM_ALLOC_NORMAL .It Dv VM_ALLOC_NORMAL

The page should be allocated with no special treatment. The page should be allocated with no special treatment.

If the number of available free pages is below a watermark, the allocation will

fail or the allocating thread will sleep, depending on the specified wait flag.

.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 the zero free pages are available.

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

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…

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

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:

are specified, the return 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 allocators 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

alcUnsubmitted

Done

.Dq noobj

- allocator interfaces.

+ variants.

.Dv VM_ALLOC_NOWAIT

alc:

.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

.Vt vm_page_t .Vt vm_page_t

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

If the allocation request specified multiple pages, the returned

.Vt vm_page_t

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.

will be a pointer to an array of pages constituting the run.

Upon failure,

.Dv NULL .Dv NULL

is returned. is returned.

.Sh NOTES .Sh SEE ALSO

The pager process is always upgraded to .Xr numa 4 ,

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:

.Dv VM_ALLOC_SYSTEM .Xr malloc 9 ,

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…

unless .Xr uma 9 ,

.Dv VM_ALLOC_INTERRUPT .Xr vm_page_grab 9 ,

is set. .Xr vm_page_sbusy 9

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.

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