1.\" $OpenBSD: uvm_pagealloc.9,v 1.2 2019/12/05 15:58:27 jmc Exp $ 2.\" $NetBSD: uvm.9,v 1.14 2000/06/29 06:08:44 mrg Exp $ 3.\" 4.\" Copyright (c) 1998 Matthew R. Green 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 21.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 22.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 23.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 24.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd $Mdocdate: December 5 2019 $ 29.Dt UVM_PAGEALLOC 9 30.Os 31.Sh NAME 32.Nm uvm_pagealloc , 33.Nm uvm_pagerealloc , 34.Nm uvm_pagefree , 35.Nm uvm_pglistalloc , 36.Nm uvm_pglistfree , 37.Nm uvm_page_physload 38.Nd physical memory allocator 39.Sh SYNOPSIS 40.In sys/param.h 41.In uvm/uvm.h 42.Ft struct vm_page * 43.Fn uvm_pagealloc "struct uvm_object *uobj" "voff_t off" "struct vm_anon *anon" "int flags" 44.Ft void 45.Fn uvm_pagerealloc "struct vm_page *pg" "struct uvm_object *newobj" "voff_t newoff" 46.Ft void 47.Fn uvm_pagefree "struct vm_page *pg" 48.Ft int 49.Fn uvm_pglistalloc "psize_t size" "paddr_t low" "paddr_t high" "paddr_t alignment" "paddr_t boundary" "struct pglist *rlist" "int nsegs" "int flags" 50.Ft void 51.Fn uvm_pglistfree "struct pglist *list" 52.Ft void 53.Fn uvm_page_physload "paddr_t start" "paddr_t end" "paddr_t avail_start" "paddr_t avail_end" "int free_list" 54.Sh DESCRIPTION 55The 56.Fn uvm_pagealloc 57function allocates a page of memory at virtual address 58.Fa off 59in either the object 60.Fa uobj 61or the anonymous memory 62.Fa anon , 63or returns 64.Dv NULL 65if no pages are free. 66Only one of 67.Fa anon 68and 69.Fa uobj 70can be non 71.Dv NULL . 72The 73.Fa flags 74can be any of: 75.Bd -literal 76#define UVM_PGA_USERESERVE 0x0001 /* ok to use reserve pages */ 77#define UVM_PGA_ZERO 0x0002 /* returned page must be zeroed */ 78.Ed 79.Pp 80The 81.Dv UVM_PGA_USERESERVE 82flag means to allocate a page even if that will result in the number of 83free pages being lower than 84.Dv uvmexp.reserve_pagedaemon 85(if the current thread is the pagedaemon) or 86.Dv uvmexp.reserve_kernel 87(if the current thread is not the pagedaemon). 88The 89.Dv UVM_PGA_ZERO 90flag causes the returned page to be filled with zeroes, either by allocating it 91from a pool of pre-zeroed pages or by zeroing it in-line as necessary. 92.Pp 93The 94.Fn uvm_pagerealloc 95function reallocates page 96.Fa pg 97to a new object 98.Fa newobj , 99at a new offset 100.Fa newoff . 101.Pp 102The 103.Fn uvm_pagefree 104function frees the physical page 105.Fa pg . 106.Pp 107The 108.Fn uvm_pglistalloc 109function allocates a list of pages for size 110.Fa size 111byte under various constraints. 112.Fa low 113and 114.Fa high 115describe the lowest and highest addresses acceptable for the list. 116If 117.Fa alignment 118is non-zero, it describes the required alignment of the list, in 119power-of-two notation. 120If 121.Fa boundary 122is non-zero, no segment of the list may cross this power-of-two 123boundary, relative to zero. 124.Fa nsegs 125is the maximum number of physically contiguous segments. 126The allocated memory is returned in the 127.Fa rlist 128list. 129The 130.Fa flags 131can be any of: 132.Bd -literal 133#define UVM_PLA_WAITOK 0x0001 /* may sleep */ 134#define UVM_PLA_NOWAIT 0x0002 /* can't sleep */ 135#define UVM_PLA_ZERO 0x0004 /* zero all pages before returning */ 136.Ed 137.Pp 138The 139.Dv UVM_PLA_WAITOK 140flag means that the function may sleep while trying to allocate the list of 141pages (this is currently ignored). 142Conversely, the 143.Dv UVM_PLA_NOWAIT 144flag signifies that the function may not sleep while allocating. 145It is an error not to provide one of the above flags. 146Optionally, one may also specify the 147.Dv UVM_PLA_ZERO 148flag to receive zeroed memory in the page list. 149.Pp 150The 151.Fn uvm_pglistfree 152function frees the list of pages pointed to by 153.Fa list . 154.Pp 155The 156.Fn uvm_page_physload 157function loads physical memory segments into VM space on the specified 158.Fa free_list . 159.Fn uvm_page_physload 160must be called at system boot time to set up physical memory management pages. 161The arguments describe the 162.Fa start 163and 164.Fa end 165of the physical addresses of the segment, and the available start and end 166addresses of pages not already in use. 167.\" XXX expand on "system boot time"! 168.Sh SEE ALSO 169.Xr uvm_km_alloc 9 170