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