1.\" $OpenBSD: uvm_init.9,v 1.7 2023/06/21 21:16:21 cheloha 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.\" XXX this manual sets nS to 1 or 0 in the description, to obtain 29.\" synopsis-like function prototypes. any better way? 30.\" 31.Dd $Mdocdate: June 21 2023 $ 32.Dt UVM_INIT 9 33.Os 34.Sh NAME 35.Nm uvm_init , 36.Nm uvm_init_limits , 37.Nm uvm_setpagesize , 38.Nm uvm_swap_init , 39.Nm uvm_io , 40.Nm uvm_pageout , 41.Nm uao_create , 42.Nm uao_detach , 43.Nm uao_reference , 44.Nm uvm_chgkprot , 45.Nm uvm_kernacc , 46.Nm uvm_meter , 47.Nm uvm_sysctl , 48.Nm uvm_grow , 49.Nm uvm_coredump_walkmap 50.Nd virtual memory system external interface 51.Sh SYNOPSIS 52.In sys/param.h 53.In uvm/uvm.h 54.Sh DESCRIPTION 55The UVM virtual memory system manages access to the computer's memory 56resources. 57User processes and the kernel access these resources through 58UVM's external interface. 59UVM's external interface includes functions that: 60.Pp 61.Bl -hyphen -compact 62.It 63initialise UVM subsystems 64.It 65manage virtual address spaces 66.It 67resolve page faults 68.It 69memory map files and devices 70.It 71perform uio-based I/O to virtual memory 72.It 73allocate and free kernel virtual memory 74.It 75allocate and free physical memory 76.El 77.Pp 78In addition to exporting these services, UVM has two kernel-level processes: 79pagedaemon and swapper. 80The pagedaemon process sleeps until physical memory becomes scarce. 81When that happens, pagedaemon is awoken. 82It scans physical memory, paging out and freeing memory that has not been 83recently used. 84The swapper process swaps in runnable processes that are currently swapped out, 85if there is room. 86.Pp 87UVM has a machine independent and a machine dependent layer. 88See 89.Xr pmap 9 90for the machine dependent layer. 91.Sh INITIALISATION 92.nr nS 1 93.Ft void 94.Fn uvm_init "void" 95.Ft void 96.Fn uvm_init_limits "struct plimit *limit0" 97.Ft void 98.Fn uvm_setpagesize "void" 99.Ft void 100.Fn uvm_swap_init "void" 101.nr nS 0 102.Pp 103The 104.Fn uvm_init 105function sets up the UVM system at system boot time, after the 106copyright has been printed. 107It initialises global state, the page, map, kernel virtual memory state, 108machine-dependent physical map, kernel memory allocator, 109pager and anonymous memory subsystems, and then enables 110paging of kernel objects. 111.Fn uvm_init 112must be called after machine-dependent code has registered some free RAM 113with the 114.Fn uvm_page_physload 115function. 116.Pp 117The 118.Fn uvm_init_limits 119function initialises process limits in the given limit structure. 120This is for use by the system startup for process zero, before any other 121processes are created. 122.Pp 123The 124.Fn uvm_setpagesize 125function initialises the uvmexp members pagesize (if not already done by 126machine-dependent code), pageshift and pagemask. 127It should be called by machine-dependent code early in the 128.Xr pmap_init 9 129call. 130.Pp 131The 132.Fn uvm_swap_init 133function initialises the swap subsystem. 134.Sh VIRTUAL MEMORY I/O 135.nr nS 1 136.Ft int 137.Fn uvm_io "vm_map_t map" "struct uio *uio" 138.nr nS 0 139.Pp 140The 141.Fn uvm_io 142function performs the I/O described in 143.Fa uio 144on the memory described in 145.Fa map . 146.Sh PROCESSES 147.nr nS 1 148.Ft void 149.Fn uvm_pageout "void *arg" 150.nr nS 0 151.Pp 152The 153.Fn uvm_pageout 154function is the main loop for the page daemon. 155The 156.Fa arg 157argument is ignored. 158.Sh MISCELLANEOUS FUNCTIONS 159.nr nS 1 160.Ft struct uvm_object * 161.Fn uao_create "vsize_t size" "int flags" 162.Ft void 163.Fn uao_detach "struct uvm_object *uobj" 164.Ft void 165.Fn uao_reference "struct uvm_object *uobj" 166.Ft boolean_t 167.Fn uvm_chgkprot "caddr_t addr" "size_t len" "int rw" 168.Ft void 169.Fn uvm_kernacc "caddr_t addr" "size_t len" "int rw" 170.Ft void 171.Fn uvm_meter 172.Ft int 173.Fn uvm_sysctl "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp " "size_t newlen" "struct proc *p" 174.Ft int 175.Fn uvm_grow "struct proc *p" "vaddr_t sp" 176.Ft int 177.Fn uvm_coredump_walkmap "struct proc *p" "uvm_coredump_setup_cb *setup" "struct uvm_coredump_walk_cb *walk" "void *cookie" 178.nr nS 0 179.Pp 180The 181.Fn uao_create , 182.Fn uao_detach 183and 184.Fn uao_reference 185functions operate on anonymous memory objects, such as those used to support 186System V shared memory. 187.Fn uao_create 188returns an object of size 189.Fa size 190with flags: 191.Bd -literal 192#define UAO_FLAG_KERNOBJ 0x1 /* create kernel object */ 193#define UAO_FLAG_KERNSWAP 0x2 /* enable kernel swap */ 194.Pp 195.Ed 196which can only be used once each at system boot time. 197.Fn uao_reference 198creates an additional reference to the named anonymous memory object. 199.Fn uao_detach 200removes a reference from the named anonymous memory object, destroying 201it if removing the last reference. 202.Pp 203The 204.Fn uvm_kernacc 205function checks the access at address 206.Fa addr 207to 208.Fa addr + len 209for 210.Fa rw 211access, in the kernel address space. 212.Pp 213The 214.Fn uvm_meter 215function calculates the load average and wakes up the swapper if necessary. 216.Pp 217The 218.Fn uvm_sysctl 219function provides support for the 220.Dv CTL_VM 221domain of the 222.Xr sysctl 2 223hierarchy. 224.Fn uvm_sysctl 225handles the 226.Dv VM_LOADAVG , 227.Dv VM_METER 228and 229.Dv VM_UVMEXP 230calls, which return the current load averages, calculates current VM 231totals, and returns the uvmexp structure respectively. 232The load averages are accessed from userland using the 233.Xr getloadavg 3 234function. 235The uvmexp structure has all global state of the UVM system, and has 236the following members: 237.Bd -literal 238/* vm_page constants */ 239int pagesize; /* size of a page (PAGE_SIZE): must be power of 2 */ 240int pagemask; /* page mask */ 241int pageshift; /* page shift */ 242 243/* vm_page counters */ 244int npages; /* number of pages we manage */ 245int free; /* number of free pages */ 246int active; /* number of active pages */ 247int inactive; /* number of pages that we free'd but may want back */ 248int paging; /* number of pages in the process of being paged out */ 249int wired; /* number of wired pages */ 250 251int zeropages; /* number of zero'd pages */ 252int reserve_pagedaemon; /* number of pages reserved for pagedaemon */ 253int reserve_kernel; /* number of pages reserved for kernel */ 254int unused01; /* formerly anonpages */ 255int vnodepages; /* XXX # of pages used by vnode page cache */ 256int vtextpages; /* XXX # of pages used by vtext vnodes */ 257 258/* pageout params */ 259int freemin; /* min number of free pages */ 260int freetarg; /* target number of free pages */ 261int inactarg; /* target number of inactive pages */ 262int wiredmax; /* max number of wired pages */ 263int anonmin; /* min threshold for anon pages */ 264int vtextmin; /* min threshold for vtext pages */ 265int vnodemin; /* min threshold for vnode pages */ 266int anonminpct; /* min percent anon pages */ 267int vtextminpct;/* min percent vtext pages */ 268int vnodeminpct;/* min percent vnode pages */ 269 270/* swap */ 271int nswapdev; /* number of configured swap devices in system */ 272int swpages; /* number of PAGE_SIZE'ed swap pages */ 273int swpginuse; /* number of swap pages in use */ 274int swpgonly; /* number of swap pages in use, not also in RAM */ 275int nswget; /* number of swap pages moved from disk to RAM */ 276int nanon; /* XXX number total of anon's in system */ 277int unused05; /* formerly nanonneeded */ 278int unused06; /* formerly nfreeanon */ 279 280/* stat counters */ 281int faults; /* page fault count */ 282int traps; /* trap count */ 283int intrs; /* interrupt count */ 284int swtch; /* context switch count */ 285int softs; /* software interrupt count */ 286int syscalls; /* system calls */ 287int pageins; /* pagein operation count */ 288 /* pageouts are in pdpageouts below */ 289int unused07; /* formerly obsolete_swapins */ 290int unused08; /* formerly obsolete_swapouts */ 291int pgswapin; /* pages swapped in */ 292int pgswapout; /* pages swapped out */ 293int forks; /* forks */ 294int forks_ppwait; /* forks where parent waits */ 295int forks_sharevm; /* forks where vmspace is shared */ 296int pga_zerohit; /* pagealloc where zero wanted and zero 297 was available */ 298int pga_zeromiss; /* pagealloc where zero wanted and zero 299 not available */ 300int unused09; /* formerly zeroaborts */ 301 302/* fault subcounters */ 303int fltnoram; /* number of times fault was out of ram */ 304int fltnoanon; /* number of times fault was out of anons */ 305int fltnoamap; /* number of times fault was out of amap chunks */ 306int fltpgwait; /* number of times fault had to wait on a page */ 307int fltpgrele; /* number of times fault found a released page */ 308int fltrelck; /* number of times fault relock called */ 309int fltrelckok; /* number of times fault relock is a success */ 310int fltanget; /* number of times fault gets anon page */ 311int fltanretry; /* number of times fault retrys an anon get */ 312int fltamcopy; /* number of times fault clears "needs copy" */ 313int fltnamap; /* number of times fault maps a neighbor anon page */ 314int fltnomap; /* number of times fault maps a neighbor obj page */ 315int fltlget; /* number of times fault does a locked pgo_get */ 316int fltget; /* number of times fault does an unlocked get */ 317int flt_anon; /* number of times fault anon (case 1a) */ 318int flt_acow; /* number of times fault anon cow (case 1b) */ 319int flt_obj; /* number of times fault is on object page (2a) */ 320int flt_prcopy; /* number of times fault promotes with copy (2b) */ 321int flt_przero; /* number of times fault promotes with zerofill (2b) */ 322 323/* daemon counters */ 324int pdwoke; /* number of times daemon woke up */ 325int pdrevs; /* number of times daemon rev'd clock hand */ 326int pdswout; /* number of times daemon called for swapout */ 327int pdfreed; /* number of pages daemon freed since boot */ 328int pdscans; /* number of pages daemon scanned since boot */ 329int pdanscan; /* number of anonymous pages scanned by daemon */ 330int pdobscan; /* number of object pages scanned by daemon */ 331int pdreact; /* number of pages daemon reactivated since boot */ 332int pdbusy; /* number of times daemon found a busy page */ 333int pdpageouts; /* number of times daemon started a pageout */ 334int pdpending; /* number of times daemon got a pending pagout */ 335int pddeact; /* number of pages daemon deactivates */ 336int unused11; /* formerly pdreanon */ 337int unused12; /* formerly pdrevnode */ 338int unused13; /* formerly pdrevtext */ 339 340int fpswtch; /* FPU context switches */ 341int kmapent; /* number of kernel map entries */ 342.Ed 343.Pp 344The 345.Fn uvm_grow 346function increases the stack segment of process 347.Fa p 348to include 349.Fa sp . 350.Pp 351The 352.Fn uvm_coredump_walkmap 353function supports writing out the memory image of a process in a 354core file. 355It walks the address space for process 356.Fa p 357and counts the number of segments necessary to hold the 358dumpable memory, 359where a segment consists of one or more present pages followed by 360zero or more mapped but not present (zero-fill) pages, 361or just one or more mapped but not present pages. 362It then invokes 363.Fa setup 364with that segment count and the 365.Fa cookie 366argument. 367.Bd -literal 368typedef int uvm_coredump_setup_cb(int nsegment, void *cookie); 369.Ed 370.Pp 371If that returns non-zero then 372.Fn uvm_coredump_walkmap 373returns that value immediately, 374otherwise it invokes 375.Fa walk 376once for each segment, in ascending address order, 377passing it the start of the segment, 378the start of the mapped-but-not-present pages, 379one past the last address in the segment, 380the protection on the segment, 381the index of the segment, 382and the 383.Fa cookie . 384.Bd -literal 385typedef int uvm_coredump_walk_cb(vaddr_t start, vaddr_t realend, 386 vaddr_t end, vm_prot_t prot, int nsegment, void *cookie); 387.Ed 388.Pp 389If a call to 390.Fa walk 391returns non-zero then 392.Fa uvm_coredump_walkmap 393returns that value immediately. 394.Sh NOTES 395The structure and types whose names begin with 396.Dq vm_ 397were named so UVM could coexist with BSD VM during the early 398development stages. 399.Sh SEE ALSO 400.Xr sysctl 2 , 401.Xr getloadavg 3 , 402.Xr kvm 3 , 403.Xr ddb 4 , 404.Xr options 4 , 405.Xr core 5 , 406.Xr pmap 9 407.Rs 408.%A Charles D. Cranor 409.%D August 1998 410.%C St. Louis, Missouri 411.%Q Department of Computer Science, Sever Institute of Technology, Washington University 412.%T Design and Implementation of the UVM Virtual Memory System, D.Sc. dissertation 413.Re 414.Sh HISTORY 415The UVM virtual memory system was developed at Washington University in St. Louis. 416UVM's roots lie partly in the Mach-based 417.Bx 4.4 418VM system, the 419.Fx 420VM system, and the SunOS4 VM system. 421UVM's basic structure is based on the 422.Bx 4.4 423VM system. 424UVM's new anonymous memory system is based on the 425anonymous memory system found in the SunOS4 VM (as described in papers 426published by Sun Microsystems, Inc.). 427UVM also includes a number of features 428new to 429.Bx 430including page loanout, map entry passing, simplified 431copy-on-write, and clustered anonymous memory pageout. 432.Pp 433UVM appeared in 434.Ox 2.9 . 435.Sh AUTHORS 436.An -nosplit 437.An Charles D. Cranor Aq Mt chuck@ccrc.wustl.edu 438designed and implemented UVM. 439.Pp 440.An Matthew Green Aq Mt mrg@eterna.com.au 441wrote the swap-space management code. 442.Pp 443.An Chuck Silvers Aq Mt chuq@chuq.com 444implemented the aobj pager, thus allowing 445UVM to support System V shared memory and process swapping. 446.Pp 447.An Artur Grabowski Aq Mt art@openbsd.org 448handled the logistical issues involved with merging UVM into the 449.Ox 450source tree. 451