1.\" $NetBSD: uvm.9,v 1.98 2009/08/03 19:08:48 rmind Exp $ 2.\" 3.\" Copyright (c) 1998 Matthew R. Green 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 20.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 21.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 22.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 23.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd August 3, 2009 28.Dt UVM 9 29.Os 30.Sh NAME 31.Nm uvm 32.Nd virtual memory system external interface 33.Sh SYNOPSIS 34.In sys/param.h 35.In uvm/uvm.h 36.Sh DESCRIPTION 37The UVM virtual memory system manages access to the computer's memory 38resources. 39User processes and the kernel access these resources through 40UVM's external interface. 41UVM's external interface includes functions that: 42.Pp 43.Bl -hyphen -compact 44.It 45initialize UVM sub-systems 46.It 47manage virtual address spaces 48.It 49resolve page faults 50.It 51memory map files and devices 52.It 53perform uio-based I/O to virtual memory 54.It 55allocate and free kernel virtual memory 56.It 57allocate and free physical memory 58.El 59.Pp 60In addition to exporting these services, UVM has two kernel-level processes: 61pagedaemon and swapper. 62The pagedaemon process sleeps until physical memory becomes scarce. 63When that happens, pagedaemon is awoken. 64It scans physical memory, paging out and freeing memory that has not 65been recently used. 66The swapper process swaps in runnable processes that are currently swapped 67out, if there is room. 68.Pp 69There are also several miscellaneous functions. 70.Sh INITIALIZATION 71.Bl -ohang 72.It Ft void 73.Fn uvm_init "void" ; 74.It Ft void 75.Fn uvm_init_limits "struct lwp *l" ; 76.It Ft void 77.Fn uvm_setpagesize "void" ; 78.It Ft void 79.Fn uvm_swap_init "void" ; 80.El 81.Pp 82.Fn uvm_init 83sets up the UVM system at system boot time, after the 84console has been setup. 85It initializes global state, the page, map, kernel virtual memory state, 86machine-dependent physical map, kernel memory allocator, 87pager and anonymous memory sub-systems, and then enables 88paging of kernel objects. 89.Pp 90.Fn uvm_init_limits 91initializes process limits for the named process. 92This is for use by the system startup for process zero, before any 93other processes are created. 94.Pp 95.Fn uvm_setpagesize 96initializes the uvmexp members pagesize (if not already done by 97machine-dependent code), pageshift and pagemask. 98It should be called by machine-dependent code early in the 99.Fn pmap_init 100call (see 101.Xr pmap 9 ) . 102.Pp 103.Fn uvm_swap_init 104initializes the swap sub-system. 105.Sh VIRTUAL ADDRESS SPACE MANAGEMENT 106.Bl -ohang 107.It Ft int 108.Fn uvm_map "struct vm_map *map" "vaddr_t *startp" "vsize_t size" "struct uvm_object *uobj" "voff_t uoffset" "vsize_t align" "uvm_flag_t flags" ; 109.It Ft void 110.Fn uvm_unmap "struct vm_map *map" "vaddr_t start" "vaddr_t end" ; 111.It Ft int 112.Fn uvm_map_pageable "struct vm_map *map" "vaddr_t start" "vaddr_t end" "bool new_pageable" "int lockflags" ; 113.It Ft bool 114.Fn uvm_map_checkprot "struct vm_map *map" "vaddr_t start" "vaddr_t end" "vm_prot_t protection" ; 115.It Ft int 116.Fn uvm_map_protect "struct vm_map *map" "vaddr_t start" "vaddr_t end" "vm_prot_t new_prot" "bool set_max" ; 117.It Ft int 118.Fn uvm_deallocate "struct vm_map *map" "vaddr_t start" "vsize_t size" ; 119.It Ft struct vmspace * 120.Fn uvmspace_alloc "vaddr_t min" "vaddr_t max" "int pageable" ; 121.It Ft void 122.Fn uvmspace_exec "struct lwp *l" "vaddr_t start" "vaddr_t end" ; 123.It Ft struct vmspace * 124.Fn uvmspace_fork "struct vmspace *vm" ; 125.It Ft void 126.Fn uvmspace_free "struct vmspace *vm1" ; 127.It Ft void 128.Fn uvmspace_share "struct proc *p1" "struct proc *p2" ; 129.It Ft void 130.Fn uvmspace_unshare "struct lwp *l" ; 131.It Ft bool 132.Fn uvm_uarea_alloc "vaddr_t *uaddrp" ; 133.It Ft void 134.Fn uvm_uarea_free "vaddr_t uaddr" ; 135.El 136.Pp 137.Fn uvm_map 138establishes a valid mapping in map 139.Fa map , 140which must be unlocked. 141The new mapping has size 142.Fa size , 143which must be a multiple of 144.Dv PAGE_SIZE . 145The 146.Fa uobj 147and 148.Fa uoffset 149arguments can have four meanings. 150When 151.Fa uobj 152is 153.Dv NULL 154and 155.Fa uoffset 156is 157.Dv UVM_UNKNOWN_OFFSET , 158.Fn uvm_map 159does not use the machine-dependent 160.Dv PMAP_PREFER 161function. 162If 163.Fa uoffset 164is any other value, it is used as the hint to 165.Dv PMAP_PREFER . 166When 167.Fa uobj 168is not 169.Dv NULL 170and 171.Fa uoffset 172is 173.Dv UVM_UNKNOWN_OFFSET , 174.Fn uvm_map 175finds the offset based upon the virtual address, passed as 176.Fa startp . 177If 178.Fa uoffset 179is any other value, we are doing a normal mapping at this offset. 180The start address of the map will be returned in 181.Fa startp . 182.Pp 183.Fa align 184specifies alignment of mapping unless 185.Dv UVM_FLAG_FIXED 186is specified in 187.Fa flags . 188.Fa align 189must be a power of 2. 190.Pp 191.Fa flags 192passed to 193.Fn uvm_map 194are typically created using the 195.Fn UVM_MAPFLAG "vm_prot_t prot" "vm_prot_t maxprot" "vm_inherit_t inh" "int advice" "int flags" 196macro, which uses the following values. 197The 198.Fa prot 199and 200.Fa maxprot 201can take are: 202.Bd -literal 203#define UVM_PROT_MASK 0x07 /* protection mask */ 204#define UVM_PROT_NONE 0x00 /* protection none */ 205#define UVM_PROT_ALL 0x07 /* everything */ 206#define UVM_PROT_READ 0x01 /* read */ 207#define UVM_PROT_WRITE 0x02 /* write */ 208#define UVM_PROT_EXEC 0x04 /* exec */ 209#define UVM_PROT_R 0x01 /* read */ 210#define UVM_PROT_W 0x02 /* write */ 211#define UVM_PROT_RW 0x03 /* read-write */ 212#define UVM_PROT_X 0x04 /* exec */ 213#define UVM_PROT_RX 0x05 /* read-exec */ 214#define UVM_PROT_WX 0x06 /* write-exec */ 215#define UVM_PROT_RWX 0x07 /* read-write-exec */ 216.Ed 217.Pp 218The values that 219.Fa inh 220can take are: 221.Bd -literal 222#define UVM_INH_MASK 0x30 /* inherit mask */ 223#define UVM_INH_SHARE 0x00 /* "share" */ 224#define UVM_INH_COPY 0x10 /* "copy" */ 225#define UVM_INH_NONE 0x20 /* "none" */ 226#define UVM_INH_DONATE 0x30 /* "donate" \*[Lt]\*[Lt] not used */ 227.Ed 228.Pp 229The values that 230.Fa advice 231can take are: 232.Bd -literal 233#define UVM_ADV_NORMAL 0x0 /* 'normal' */ 234#define UVM_ADV_RANDOM 0x1 /* 'random' */ 235#define UVM_ADV_SEQUENTIAL 0x2 /* 'sequential' */ 236#define UVM_ADV_MASK 0x7 /* mask */ 237.Ed 238.Pp 239The values that 240.Fa flags 241can take are: 242.Bd -literal 243#define UVM_FLAG_FIXED 0x010000 /* find space */ 244#define UVM_FLAG_OVERLAY 0x020000 /* establish overlay */ 245#define UVM_FLAG_NOMERGE 0x040000 /* don't merge map entries */ 246#define UVM_FLAG_COPYONW 0x080000 /* set copy_on_write flag */ 247#define UVM_FLAG_AMAPPAD 0x100000 /* for bss: pad amap to reduce malloc() */ 248#define UVM_FLAG_TRYLOCK 0x200000 /* fail if we can not lock map */ 249.Ed 250.Pp 251The 252.Dv UVM_MAPFLAG 253macro arguments can be combined with an or operator. 254There are several special purpose macros for checking protection 255combinations, e.g., the 256.Dv UVM_PROT_WX 257macro. 258There are also some additional macros to extract bits from the flags. 259The 260.Dv UVM_PROTECTION , 261.Dv UVM_INHERIT , 262.Dv UVM_MAXPROTECTION 263and 264.Dv UVM_ADVICE 265macros return the protection, inheritance, maximum protection and advice, 266respectively. 267.Fn uvm_map 268returns a standard UVM return value. 269.Pp 270.Fn uvm_unmap 271removes a valid mapping, 272from 273.Fa start 274to 275.Fa end , 276in map 277.Fa map , 278which must be unlocked. 279.Pp 280.Fn uvm_map_pageable 281changes the pageability of the pages in the range from 282.Fa start 283to 284.Fa end 285in map 286.Fa map 287to 288.Fa new_pageable . 289.Fn uvm_map_pageable 290returns a standard UVM return value. 291.Pp 292.Fn uvm_map_checkprot 293checks the protection of the range from 294.Fa start 295to 296.Fa end 297in map 298.Fa map 299against 300.Fa protection . 301This returns either 302.Dv true 303or 304.Dv false . 305.Pp 306.Fn uvm_map_protect 307changes the protection 308.Fa start 309to 310.Fa end 311in map 312.Fa map 313to 314.Fa new_prot , 315also setting the maximum protection to the region to 316.Fa new_prot 317if 318.Fa set_max 319is true. 320This function returns a standard UVM return value. 321.Pp 322.Fn uvm_deallocate 323deallocates kernel memory in map 324.Fa map 325from address 326.Fa start 327to 328.Fa start + size . 329.Pp 330.Fn uvmspace_alloc 331allocates and returns a new address space, with ranges from 332.Fa min 333to 334.Fa max , 335setting the pageability of the address space to 336.Fa pageable . 337.Pp 338.Fn uvmspace_exec 339either reuses the address space of lwp 340.Fa l 341if there are no other references to it, or creates 342a new one with 343.Fn uvmspace_alloc . 344The range of valid addresses in the address space is reset to 345.Fa start 346through 347.Fa end . 348.Pp 349.Fn uvmspace_fork 350creates and returns a new address space based upon the 351.Fa vm1 352address space, typically used when allocating an address space for a 353child process. 354.Pp 355.Fn uvmspace_free 356lowers the reference count on the address space 357.Fa vm , 358freeing the data structures if there are no other references. 359.Pp 360.Fn uvmspace_share 361causes process 362.Pa p2 363to share the address space of 364.Fa p1 . 365.Pp 366.Fn uvmspace_unshare 367ensures that lwp 368.Fa l 369has its own, unshared address space, by creating a new one if 370necessary by calling 371.Fn uvmspace_fork . 372.Pp 373.Fn uvm_uarea_alloc 374allocates virtual space for a u-area (i.e., a kernel stack) and stores 375its virtual address in 376.Fa *uaddrp . 377The return value is 378.Dv true 379if the u-area is already backed by wired physical memory, otherwise 380.Dv false . 381.Pp 382.Fn uvm_uarea_free 383frees a u-area allocated with 384.Fn uvm_uarea_alloc , 385freeing both the virtual space and any physical pages which may have been 386allocated to back that virtual space later. 387.Sh PAGE FAULT HANDLING 388.Bl -ohang 389.It Ft int 390.Fn uvm_fault "struct vm_map *orig_map" "vaddr_t vaddr" "vm_prot_t access_type" ; 391.El 392.Pp 393.Fn uvm_fault 394is the main entry point for faults. 395It takes 396.Fa orig_map 397as the map the fault originated in, a 398.Fa vaddr 399offset into the map the fault occurred, and 400.Fa access_type 401describing the type of access requested. 402.Fn uvm_fault 403returns a standard UVM return value. 404.Sh VIRTUAL MEMORY I/O 405.Bl -ohang 406.It Ft int 407.Fn uvm_io "struct vm_map *map" "struct uio *uio" ; 408.El 409.Pp 410.Fn uvm_io 411performs the I/O described in 412.Fa uio 413on the memory described in 414.Fa map . 415.Sh ALLOCATION OF KERNEL MEMORY 416.Bl -ohang 417.It Ft vaddr_t 418.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" "vsize_t align" "uvm_flag_t flags" ; 419.It Ft void 420.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" "uvm_flag_t flags" ; 421.It Ft struct vm_map * 422.Fn uvm_km_suballoc "struct vm_map *map" "vaddr_t *min" "vaddr_t *max" \ 423"vsize_t size" "int flags" "bool fixed" "struct vm_map *submap" ; 424.El 425.Pp 426.Fn uvm_km_alloc 427allocates 428.Fa size 429bytes of kernel memory in map 430.Fa map . 431The first address of the allocated memory range will be aligned according to the 432.Fa align 433argument 434.Pq specify 0 if no alignment is necessary . 435The alignment must be a multiple of page size. 436The 437.Fa flags 438is a bitwise inclusive OR of the allocation type and operation flags. 439.Pp 440The allocation type should be one of: 441.Bl -tag -width UVM_KMF_PAGEABLE 442.It UVM_KMF_WIRED 443Wired memory. 444.It UVM_KMF_PAGEABLE 445Demand-paged zero-filled memory. 446.It UVM_KMF_VAONLY 447Virtual address only. 448No physical pages are mapped in the allocated region. 449If necessary, it's the caller's responsibility to enter page mappings. 450It's also the caller's responsibility to clean up the mappings before freeing 451the address range. 452.El 453.Pp 454The following operation flags are available: 455.Bl -tag -width UVM_KMF_PAGEABLE 456.It UVM_KMF_CANFAIL 457Can fail even if 458.Dv UVM_KMF_NOWAIT 459is not specified and 460.Dv UVM_KMF_WAITVA 461is specified. 462.It UVM_KMF_ZERO 463Request zero-filled memory. 464Only supported for 465.Dv UVM_KMF_WIRED . 466Shouldn't be used with other types. 467.It UVM_KMF_TRYLOCK 468Fail if we can't lock the map. 469.It UVM_KMF_NOWAIT 470Fail immediately if no memory is available. 471.It UVM_KMF_WAITVA 472Sleep to wait for the virtual address resources if needed. 473.El 474.Pp 475(If neither 476.Dv UVM_KMF_NOWAIT 477nor 478.Dv UVM_KMF_CANFAIL 479are specified and 480.Dv UVM_KMF_WAITVA 481is specified, 482.Fn uvm_km_alloc 483will never fail, but rather sleep indefinitely until the allocation succeeds.) 484.Pp 485Pageability of the pages allocated with 486.Dv UVM_KMF_PAGEABLE 487can be changed by 488.Fn uvm_map_pageable . 489In that case, the entire range must be changed atomically. 490Changing a part of the range is not supported. 491.Pp 492.Fn uvm_km_free 493frees the memory range allocated by 494.Fn uvm_km_alloc . 495.Fa addr 496must be an address returned by 497.Fn uvm_km_alloc . 498.Fa map 499and 500.Fa size 501must be the same as the ones used for the corresponding 502.Fn uvm_km_alloc . 503.Fa flags 504must be the allocation type used for the corresponding 505.Fn uvm_km_alloc . 506.Pp 507.Fn uvm_km_free 508is the only way to free memory ranges allocated by 509.Fn uvm_km_alloc . 510.Fn uvm_unmap 511must not be used. 512.Pp 513.Fn uvm_km_suballoc 514allocates submap from 515.Fa map , 516creating a new map if 517.Fa submap 518is 519.Dv NULL . 520The addresses of the submap can be specified exactly by setting the 521.Fa fixed 522argument to true, which causes the 523.Fa min 524argument to specify the beginning of the address in the submap. 525If 526.Fa fixed 527is false, any address of size 528.Fa size 529will be allocated from 530.Fa map 531and the start and end addresses returned in 532.Fa min 533and 534.Fa max . 535The 536.Fa flags 537are used to initialize the created submap. 538The following flags could be set: 539.Bl -tag -width VM_MAP_PAGEABLE 540.It VM_MAP_PAGEABLE 541Entries in the map may be paged out. 542.It VM_MAP_INTRSAFE 543Map should be interrupt-safe. 544.It VM_MAP_TOPDOWN 545A top-down mapping should be arranged. 546.El 547.Sh ALLOCATION OF PHYSICAL MEMORY 548.Bl -ohang 549.It Ft struct vm_page * 550.Fn uvm_pagealloc "struct uvm_object *uobj" "voff_t off" "struct vm_anon *anon" "int flags" ; 551.It Ft void 552.Fn uvm_pagerealloc "struct vm_page *pg" "struct uvm_object *newobj" "voff_t newoff" ; 553.It Ft void 554.Fn uvm_pagefree "struct vm_page *pg" ; 555.It Ft int 556.Fn uvm_pglistalloc "psize_t size" "paddr_t low" "paddr_t high" "paddr_t alignment" "paddr_t boundary" "struct pglist *rlist" "int nsegs" "int waitok" ; 557.It Ft void 558.Fn uvm_pglistfree "struct pglist *list" ; 559.It Ft void 560.Fn uvm_page_physload "vaddr_t start" "vaddr_t end" "vaddr_t avail_start" "vaddr_t avail_end" "int free_list" ; 561.El 562.Pp 563.Fn uvm_pagealloc 564allocates a page of memory at virtual address 565.Fa off 566in either the object 567.Fa uobj 568or the anonymous memory 569.Fa anon , 570which must be locked by the caller. 571Only one of 572.Fa uobj 573and 574.Fa anon 575can be non 576.Dv NULL . 577Returns 578.Dv NULL 579when no page can be found. 580The flags can be any of 581.Bd -literal 582#define UVM_PGA_USERESERVE 0x0001 /* ok to use reserve pages */ 583#define UVM_PGA_ZERO 0x0002 /* returned page must be zero'd */ 584.Ed 585.Pp 586.Dv UVM_PGA_USERESERVE 587means to allocate a page even if that will result in the number of free pages 588being lower than 589.Dv uvmexp.reserve_pagedaemon 590(if the current thread is the pagedaemon) or 591.Dv uvmexp.reserve_kernel 592(if the current thread is not the pagedaemon). 593.Dv UVM_PGA_ZERO 594causes the returned page to be filled with zeroes, either by allocating it 595from a pool of pre-zeroed pages or by zeroing it in-line as necessary. 596.Pp 597.Fn uvm_pagerealloc 598reallocates page 599.Fa pg 600to a new object 601.Fa newobj , 602at a new offset 603.Fa newoff . 604.Pp 605.Fn uvm_pagefree 606frees the physical page 607.Fa pg . 608If the content of the page is known to be zero-filled, 609caller should set 610.Dv PG_ZERO 611in pg-\*[Gt]flags so that the page allocator will use 612the page to serve future 613.Dv UVM_PGA_ZERO 614requests efficiently. 615.Pp 616.Fn uvm_pglistalloc 617allocates a list of pages for size 618.Fa size 619byte under various constraints. 620.Fa low 621and 622.Fa high 623describe the lowest and highest addresses acceptable for the list. 624If 625.Fa alignment 626is non-zero, it describes the required alignment of the list, in 627power-of-two notation. 628If 629.Fa boundary 630is non-zero, no segment of the list may cross this power-of-two 631boundary, relative to zero. 632.Fa nsegs 633is the maximum number of physically contiguous segments. 634If 635.Fa waitok 636is non-zero, the function may sleep until enough memory is available. 637(It also may give up in some situations, so a non-zero 638.Fa waitok 639does not imply that 640.Fn uvm_pglistalloc 641cannot return an error.) 642The allocated memory is returned in the 643.Fa rlist 644list; the caller has to provide storage only, the list is initialized by 645.Fn uvm_pglistalloc . 646.Pp 647.Fn uvm_pglistfree 648frees the list of pages pointed to by 649.Fa list . 650If the content of the page is known to be zero-filled, 651caller should set 652.Dv PG_ZERO 653in pg-\*[Gt]flags so that the page allocator will use 654the page to serve future 655.Dv UVM_PGA_ZERO 656requests efficiently. 657.Pp 658.Fn uvm_page_physload 659loads physical memory segments into VM space on the specified 660.Fa free_list . 661It must be called at system boot time to set up physical memory 662management pages. 663The arguments describe the 664.Fa start 665and 666.Fa end 667of the physical addresses of the segment, and the available start and end 668addresses of pages not already in use. 669If a system has memory banks of 670different speeds the slower memory should be given a higher 671.Fa free_list 672value. 673.\" XXX expand on "system boot time"! 674.Sh PROCESSES 675.Bl -ohang 676.It Ft void 677.Fn uvm_pageout "void" ; 678.It Ft void 679.Fn uvm_scheduler "void" ; 680.It Ft void 681.Fn uvm_swapin "struct lwp *l" ; 682.El 683.Pp 684.Fn uvm_pageout 685is the main loop for the page daemon. 686.Pp 687.Fn uvm_scheduler 688is the process zero main loop, which is to be called after the 689system has finished starting other processes. 690It handles the swapping in of runnable, swapped out processes in priority 691order. 692.Pp 693.Fn uvm_swapin 694swaps in the named lwp. 695.Sh PAGE LOAN 696.Bl -ohang 697.It Ft int 698.Fn uvm_loan "struct vm_map *map" "vaddr_t start" "vsize_t len" "void *v" "int flags" ; 699.It Ft void 700.Fn uvm_unloan "void *v" "int npages" "int flags" ; 701.El 702.Pp 703.Fn uvm_loan 704loans pages in a map out to anons or to the kernel. 705.Fa map 706should be unlocked, 707.Fa start 708and 709.Fa len 710should be multiples of 711.Dv PAGE_SIZE . 712Argument 713.Fa flags 714should be one of 715.Bd -literal 716#define UVM_LOAN_TOANON 0x01 /* loan to anons */ 717#define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */ 718.Ed 719.Pp 720.Fa v 721should be pointer to array of pointers to 722.Li struct anon 723or 724.Li struct vm_page , 725as appropriate. 726The caller has to allocate memory for the array and 727ensure it's big enough to hold 728.Fa len / PAGE_SIZE 729pointers. 730Returns 0 for success, or appropriate error number otherwise. 731Note that wired pages can't be loaned out and 732.Fn uvm_loan 733will fail in that case. 734.Pp 735.Fn uvm_unloan 736kills loans on pages or anons. 737The 738.Fa v 739must point to the array of pointers initialized by previous call to 740.Fn uvm_loan . 741.Fa npages 742should match number of pages allocated for loan, this also matches 743number of items in the array. 744Argument 745.Fa flags 746should be one of 747.Bd -literal 748#define UVM_LOAN_TOANON 0x01 /* loan to anons */ 749#define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */ 750.Ed 751.Pp 752and should match what was used for previous call to 753.Fn uvm_loan . 754.Sh MISCELLANEOUS FUNCTIONS 755.Bl -ohang 756.It Ft struct uvm_object * 757.Fn uao_create "vsize_t size" "int flags" ; 758.It Ft void 759.Fn uao_detach "struct uvm_object *uobj" ; 760.It Ft void 761.Fn uao_reference "struct uvm_object *uobj" ; 762.It Ft bool 763.Fn uvm_chgkprot "void *addr" "size_t len" "int rw" ; 764.It Ft void 765.Fn uvm_kernacc "void *addr" "size_t len" "int rw" ; 766.It Ft int 767.Fn uvm_vslock "struct vmspace *vs" "void *addr" "size_t len" "vm_prot_t prot" ; 768.It Ft void 769.Fn uvm_vsunlock "struct vmspace *vs" "void *addr" "size_t len" ; 770.It Ft void 771.Fn uvm_meter "void" ; 772.It Ft void 773.Fn uvm_fork "struct lwp *l1" "struct lwp *l2" "bool shared" ; 774.It Ft int 775.Fn uvm_grow "struct proc *p" "vaddr_t sp" ; 776.It Ft void 777.Fn uvn_findpages "struct uvm_object *uobj" "voff_t offset" "int *npagesp" "struct vm_page **pps" "int flags" ; 778.It Ft void 779.Fn uvm_vnp_setsize "struct vnode *vp" "voff_t newsize" ; 780.It Ft void 781.Fn uvm_swap_stats "int cmd" "struct swapent *sep" "int sec" "register_t *retval" ; 782.El 783.Pp 784The 785.Fn uao_create , 786.Fn uao_detach , 787and 788.Fn uao_reference 789functions operate on anonymous memory objects, such as those used to support 790System V shared memory. 791.Fn uao_create 792returns an object of size 793.Fa size 794with flags: 795.Bd -literal 796#define UAO_FLAG_KERNOBJ 0x1 /* create kernel object */ 797#define UAO_FLAG_KERNSWAP 0x2 /* enable kernel swap */ 798.Ed 799.Pp 800which can only be used once each at system boot time. 801.Fn uao_reference 802creates an additional reference to the named anonymous memory object. 803.Fn uao_detach 804removes a reference from the named anonymous memory object, destroying 805it if removing the last reference. 806.Pp 807.Fn uvm_chgkprot 808changes the protection of kernel memory from 809.Fa addr 810to 811.Fa addr + len 812to the value of 813.Fa rw . 814This is primarily useful for debuggers, for setting breakpoints. 815This function is only available with options 816.Dv KGDB . 817.Pp 818.Fn uvm_kernacc 819checks the access at address 820.Fa addr 821to 822.Fa addr + len 823for 824.Fa rw 825access in the kernel address space. 826.Pp 827.Fn uvm_vslock 828and 829.Fn uvm_vsunlock 830control the wiring and unwiring of pages for process 831.Fa p 832from 833.Fa addr 834to 835.Fa addr + len . 836These functions are normally used to wire memory for I/O. 837.Pp 838.Fn uvm_meter 839calculates the load average and wakes up the swapper if necessary. 840.Pp 841.Fn uvm_fork 842forks a virtual address space for process' (old) 843.Fa p1 844and (new) 845.Fa p2 . 846If the 847.Fa shared 848argument is non zero, p1 shares its address space with p2, 849otherwise a new address space is created. 850This function currently has no return value, and thus cannot fail. 851In the future, this function will be changed to allow it to 852fail in low memory conditions. 853.Pp 854.Fn uvm_grow 855increases the stack segment of process 856.Fa p 857to include 858.Fa sp . 859.Pp 860.Fn uvn_findpages 861looks up or creates pages in 862.Fa uobj 863at offset 864.Fa offset , 865marks them busy and returns them in the 866.Fa pps 867array. 868Currently 869.Fa uobj 870must be a vnode object. 871The number of pages requested is pointed to by 872.Fa npagesp , 873and this value is updated with the actual number of pages returned. 874The flags can be 875.Bd -literal 876#define UFP_ALL 0x00 /* return all pages requested */ 877#define UFP_NOWAIT 0x01 /* don't sleep */ 878#define UFP_NOALLOC 0x02 /* don't allocate new pages */ 879#define UFP_NOCACHE 0x04 /* don't return pages which already exist */ 880#define UFP_NORDONLY 0x08 /* don't return PG_READONLY pages */ 881.Ed 882.Pp 883.Dv UFP_ALL 884is a pseudo-flag meaning all requested pages should be returned. 885.Dv UFP_NOWAIT 886means that we must not sleep. 887.Dv UFP_NOALLOC 888causes any pages which do not already exist to be skipped. 889.Dv UFP_NOCACHE 890causes any pages which do already exist to be skipped. 891.Dv UFP_NORDONLY 892causes any pages which are marked PG_READONLY to be skipped. 893.Pp 894.Fn uvm_vnp_setsize 895sets the size of vnode 896.Fa vp 897to 898.Fa newsize . 899Caller must hold a reference to the vnode. 900If the vnode shrinks, pages no longer used are discarded. 901.Pp 902.Fn uvm_swap_stats 903implements the 904.Dv SWAP_STATS 905and 906.Dv SWAP_OSTATS 907operation of the 908.Xr swapctl 2 909system call. 910.Fa cmd 911is the requested command, 912.Dv SWAP_STATS 913or 914.Dv SWAP_OSTATS . 915The function will copy no more than 916.Fa sec 917entries in the array pointed by 918.Fa sep . 919On return, 920.Fa retval 921holds the actual number of entries copied in the array. 922.Sh SYSCTL 923UVM provides support for the 924.Dv CTL_VM 925domain of the 926.Xr sysctl 3 927hierarchy. 928It handles the 929.Dv VM_LOADAVG , 930.Dv VM_METER , 931.Dv VM_UVMEXP , 932and 933.Dv VM_UVMEXP2 934nodes, which return the current load averages, calculates current VM 935totals, returns the uvmexp structure, and a kernel version independent 936view of the uvmexp structure, respectively. 937It also exports a number of tunables that control how much VM space is 938allowed to be consumed by various tasks. 939The load averages are typically accessed from userland using the 940.Xr getloadavg 3 941function. 942The uvmexp structure has all global state of the UVM system, 943and has the following members: 944.Bd -literal 945/* vm_page constants */ 946int pagesize; /* size of a page (PAGE_SIZE): must be power of 2 */ 947int pagemask; /* page mask */ 948int pageshift; /* page shift */ 949 950/* vm_page counters */ 951int npages; /* number of pages we manage */ 952int free; /* number of free pages */ 953int active; /* number of active pages */ 954int inactive; /* number of pages that we free'd but may want back */ 955int paging; /* number of pages in the process of being paged out */ 956int wired; /* number of wired pages */ 957int reserve_pagedaemon; /* number of pages reserved for pagedaemon */ 958int reserve_kernel; /* number of pages reserved for kernel */ 959 960/* pageout params */ 961int freemin; /* min number of free pages */ 962int freetarg; /* target number of free pages */ 963int inactarg; /* target number of inactive pages */ 964int wiredmax; /* max number of wired pages */ 965 966/* swap */ 967int nswapdev; /* number of configured swap devices in system */ 968int swpages; /* number of PAGE_SIZE'ed swap pages */ 969int swpginuse; /* number of swap pages in use */ 970int nswget; /* number of times fault calls uvm_swap_get() */ 971int nanon; /* number total of anon's in system */ 972int nfreeanon; /* number of free anon's */ 973 974/* stat counters */ 975int faults; /* page fault count */ 976int traps; /* trap count */ 977int intrs; /* interrupt count */ 978int swtch; /* context switch count */ 979int softs; /* software interrupt count */ 980int syscalls; /* system calls */ 981int pageins; /* pagein operation count */ 982 /* pageouts are in pdpageouts below */ 983int swapins; /* swapins */ 984int swapouts; /* swapouts */ 985int pgswapin; /* pages swapped in */ 986int pgswapout; /* pages swapped out */ 987int forks; /* forks */ 988int forks_ppwait; /* forks where parent waits */ 989int forks_sharevm; /* forks where vmspace is shared */ 990 991/* fault subcounters */ 992int fltnoram; /* number of times fault was out of ram */ 993int fltnoanon; /* number of times fault was out of anons */ 994int fltpgwait; /* number of times fault had to wait on a page */ 995int fltpgrele; /* number of times fault found a released page */ 996int fltrelck; /* number of times fault relock called */ 997int fltrelckok; /* number of times fault relock is a success */ 998int fltanget; /* number of times fault gets anon page */ 999int fltanretry; /* number of times fault retrys an anon get */ 1000int fltamcopy; /* number of times fault clears "needs copy" */ 1001int fltnamap; /* number of times fault maps a neighbor anon page */ 1002int fltnomap; /* number of times fault maps a neighbor obj page */ 1003int fltlget; /* number of times fault does a locked pgo_get */ 1004int fltget; /* number of times fault does an unlocked get */ 1005int flt_anon; /* number of times fault anon (case 1a) */ 1006int flt_acow; /* number of times fault anon cow (case 1b) */ 1007int flt_obj; /* number of times fault is on object page (2a) */ 1008int flt_prcopy; /* number of times fault promotes with copy (2b) */ 1009int flt_przero; /* number of times fault promotes with zerofill (2b) */ 1010 1011/* daemon counters */ 1012int pdwoke; /* number of times daemon woke up */ 1013int pdrevs; /* number of times daemon rev'd clock hand */ 1014int pdswout; /* number of times daemon called for swapout */ 1015int pdfreed; /* number of pages daemon freed since boot */ 1016int pdscans; /* number of pages daemon scanned since boot */ 1017int pdanscan; /* number of anonymous pages scanned by daemon */ 1018int pdobscan; /* number of object pages scanned by daemon */ 1019int pdreact; /* number of pages daemon reactivated since boot */ 1020int pdbusy; /* number of times daemon found a busy page */ 1021int pdpageouts; /* number of times daemon started a pageout */ 1022int pdpending; /* number of times daemon got a pending pageout */ 1023int pddeact; /* number of pages daemon deactivates */ 1024.Ed 1025.Sh NOTES 1026.Fn uvm_chgkprot 1027is only available if the kernel has been compiled with options 1028.Dv KGDB . 1029.Pp 1030All structure and types whose names begin with 1031.Dq vm_ 1032will be renamed to 1033.Dq uvm_ . 1034.Sh SEE ALSO 1035.Xr swapctl 2 , 1036.Xr getloadavg 3 , 1037.Xr kvm 3 , 1038.Xr sysctl 3 , 1039.Xr ddb 4 , 1040.Xr options 4 , 1041.Xr memoryallocators 9 , 1042.Xr pmap 9 , 1043.Xr ubc 9 1044.Sh HISTORY 1045UVM is a new VM system developed at Washington University in St. Louis 1046(Missouri). 1047UVM's roots lie partly in the Mach-based 1048.Bx 4.4 1049VM system, the 1050.Fx 1051VM system, and the SunOS 4 VM system. 1052UVM's basic structure is based on the 1053.Bx 4.4 1054VM system. 1055UVM's new anonymous memory system is based on the 1056anonymous memory system found in the SunOS 4 VM (as described in papers 1057published by Sun Microsystems, Inc.). 1058UVM also includes a number of features new to 1059.Bx 1060including page loanout, map entry passing, simplified 1061copy-on-write, and clustered anonymous memory pageout. 1062UVM is also further documented in an August 1998 dissertation by 1063Charles D. Cranor. 1064.Pp 1065UVM appeared in 1066.Nx 1.4 . 1067.Sh AUTHORS 1068Charles D. Cranor 1069.Aq chuck@ccrc.wustl.edu 1070designed and implemented UVM. 1071.Pp 1072Matthew Green 1073.Aq mrg@eterna.com.au 1074wrote the swap-space management code and handled the logistical issues 1075involved with merging UVM into the 1076.Nx 1077source tree. 1078.Pp 1079Chuck Silvers 1080.Aq chuq@chuq.com 1081implemented the aobj pager, thus allowing UVM to support System V shared 1082memory and process swapping. 1083