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 . 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,310 @@ .\" .\" $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 +.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 control the behavior of the allocator if free pages could not be +immediately allocated. +If +.Dv VM_ALLOC_NOWAIT +is specified, then the allocator gives up and returns +.Dv NULL . +If +.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 the caller may re-validate VM object state and retry the allocation. +If .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. +is not +.Dv NULL +it will have been unlocked during the sleep. +If +.Dv VM_ALLOC_WAITOK +was specified, the allocator will retry the allocation internally. +The +.Dv VM_ALLOC_WAITOK +flag is valid only with the +.Dq noobj +allocator functions. .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" .It Dv VM_ALLOC_NORMAL 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 -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 the 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 .