1.\" $NetBSD: uvm.9,v 1.36 2002/09/27 07:52:48 wiz 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 vaddr_t 137.Fn uvm_uarea_alloc "void" 138.Ft void 139.Fn uvm_uarea_free "vaddr_t va" 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 returns 363its virtual address. 364.Pp 365.Fn uvm_uarea_free 366frees a u-area allocated with 367.Fn uvm_uarea_alloc , 368freeing both the virtual space and any physical pages which may have been 369allocated to back that virtual space later. 370.Sh PAGE FAULT HANDLING 371.nr nS 1 372.Ft int 373.Fn uvm_fault "struct vm_map *orig_map" "vaddr_t vaddr" "vm_fault_t fault_type" "vm_prot_t access_type" 374.nr nS 0 375.Pp 376.Fn uvm_fault 377is the main entry point for faults. 378It takes 379.Fa orig_map 380as the map the fault originated in, a 381.Fa vaddr 382offset into the map the fault occurred, 383.Fa fault_type 384describing the type of fault, and 385.Fa access_type 386describing the type of access requested. 387.Fn uvm_fault 388returns a standard UVM return value. 389.Sh MEMORY MAPPING FILES AND DEVICES 390.nr nS 1 391.Ft struct uvm_object * 392.Fn uvn_attach "void *arg" "vm_prot_t accessprot" 393.Ft void 394.Fn uvm_vnp_setsize "struct vnode *vp" "voff_t newsize" 395.Ft void * 396.Fn ubc_alloc "struct uvm_object *uobj" "voff_t offset" "vsize_t *lenp" "int flags" 397.Ft void 398.Fn ubc_release "void *va" "int flags" 399.nr nS 0 400.Pp 401.Fn uvn_attach 402attaches a UVM object to vnode 403.Fa arg , 404creating the object if necessary. 405The object is returned. 406.Pp 407.Fn uvm_vnp_setsize 408sets the size of vnode 409.Fa vp 410to 411.Fa newsize . 412Caller must hold a reference to the vnode. 413If the vnode shrinks, pages no longer used are discarded. 414.Pp 415.Fn ubc_alloc 416creates a kernel mappings of 417.Fa uobj 418starting at offset 419.Fa offset . 420the desired length of the mapping is pointed to by 421.Fa lenp , 422but the actual mapping may be smaller than this. 423.Fa lenp 424is updated to contain the actual length mapped. 425The flags must be one of 426.Bd -literal 427#define UBC_READ 0x01 /* mapping will be accessed for read */ 428#define UBC_WRITE 0x02 /* mapping will be accessed for write */ 429.Ed 430.Pp 431Currently, 432.Fa uobj 433must actually be a vnode object. 434Once the mapping is created, it must be accessed only by methods that can 435handle faults, such as 436.Fn uiomove 437or 438.Fn kcopy . 439Page faults on the mapping will result in the vnode's 440.Fn VOP_GETPAGES 441method being called to resolve the fault. 442.Pp 443.Fn ubc_release 444frees the mapping at 445.Fa va 446for reuse. 447The mapping may be cached to speed future accesses to the same region 448of the object. 449The flags are currently unused. 450.Sh VIRTUAL MEMORY I/O 451.nr nS 1 452.Ft int 453.Fn uvm_io "struct vm_map *map" "struct uio *uio" 454.nr nS 0 455.Pp 456.Fn uvm_io 457performs the I/O described in 458.Fa uio 459on the memory described in 460.Fa map . 461.Sh ALLOCATION OF KERNEL MEMORY 462.nr nS 1 463.Ft vaddr_t 464.Fn uvm_km_alloc "struct vm_map *map" "vsize_t size" 465.Ft vaddr_t 466.Fn uvm_km_zalloc "struct vm_map *map" "vsize_t size" 467.Ft vaddr_t 468.Fn uvm_km_alloc1 "struct vm_map *map" "vsize_t size" "boolean_t zeroit" 469.Ft vaddr_t 470.Fn uvm_km_kmemalloc "struct vm_map *map" "struct uvm_object *obj" "vsize_t size" "int flags" 471.Ft vaddr_t 472.Fn uvm_km_valloc "struct vm_map *map" "vsize_t size" 473.Ft vaddr_t 474.Fn uvm_km_valloc_wait "struct vm_map *map" "vsize_t size" 475.Ft struct vm_map * 476.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" 477.Ft void 478.Fn uvm_km_free "struct vm_map *map" "vaddr_t addr" "vsize_t size" 479.Ft void 480.Fn uvm_km_free_wakeup "struct vm_map *map" "vaddr_t addr" "vsize_t size" 481.nr nS 0 482.Pp 483.Fn uvm_km_alloc 484and 485.Fn uvm_km_zalloc 486allocate 487.Fa size 488bytes of wired kernel memory in map 489.Fa map . 490In addition to allocation, 491.Fn uvm_km_zalloc 492zeros the memory. 493Both of these functions are defined as macros in terms of 494.Fn uvm_km_alloc1 , 495and should almost always be used in preference to 496.Fn uvm_km_alloc1 . 497.Pp 498.Fn uvm_km_alloc1 499allocates and returns 500.Fa size 501bytes of wired memory in the kernel map, zeroing the memory if the 502.Fa zeroit 503argument is non-zero. 504.Pp 505.Fn uvm_km_kmemalloc 506allocates and returns 507.Fa size 508bytes of wired kernel memory into 509.Fa obj . 510The flags can be any of: 511.Bd -literal 512#define UVM_KMF_NOWAIT 0x1 /* matches M_NOWAIT */ 513#define UVM_KMF_VALLOC 0x2 /* allocate VA only */ 514#define UVM_KMF_CANFAIL 0x4 /* caller handles failure */ 515#define UVM_KMF_TRYLOCK UVM_FLAG_TRYLOCK /* try locking only */ 516.Ed 517.Pp 518.Dv UVM_KMF_NOWAIT 519causes 520.Fn uvm_km_kmemalloc 521to return immediately if no memory is available. 522.Dv UVM_KMF_VALLOC 523causes no physical pages to be allocated, only virtual space. 524.Dv UVM_KMF_TRYLOCK 525causes 526.Fn uvm_km_kmemalloc 527to use 528.Fn simple_lock_try 529when locking maps. 530.Dv UVM_KMF_CANFAIL 531indicates that 532.Fn uvm_km_kmemalloc 533can return 0 even if 534.Dv UVM_KMF_NOWAIT 535is not specified. 536(If neither 537.Dv UVM_KMF_NOWAIT 538nor 539.Dv UVM_KMF_CANFAIL 540are specified, 541.Fn uvm_km_kmemalloc 542will never fail, but rather sleep indefinitely until the allocation succeeds.) 543.Pp 544.Fn uvm_km_valloc 545and 546.Fn uvm_km_valloc_wait 547return a newly allocated zero-filled address in the kernel map of size 548.Fa size . 549.Fn uvm_km_valloc_wait 550will also wait for kernel memory to become available, if there is a 551memory shortage. 552.Pp 553.Fn uvm_km_free 554and 555.Fn uvm_km_free_wakeup 556free 557.Fa size 558bytes of memory in the kernel map, starting at address 559.Fa addr . 560.Fn uvm_km_free_wakeup 561calls 562.Fn wakeup 563on the map before unlocking the map. 564.Pp 565.Fn uvm_km_suballoc 566allocates submap from 567.Fa map , 568creating a new map if 569.Fa submap 570is 571.Dv NULL . 572The addresses of the submap can be specified exactly by setting the 573.Fa fixed 574argument to non-zero, which causes the 575.Fa min 576argument specify the beginning of the address in the submap. 577If 578.Fa fixed 579is zero, any address of size 580.Fa size 581will be allocated from 582.Fa map 583and the start and end addresses returned in 584.Fa min 585and 586.Fa max . 587If 588.Fa pageable 589is non-zero, entries in the map may be paged out. 590.Sh ALLOCATION OF PHYSICAL MEMORY 591.nr nS 1 592.Ft struct vm_page * 593.Fn uvm_pagealloc "struct uvm_object *uobj" "voff_t off" "struct vm_anon *anon" "int flags" 594.Ft void 595.Fn uvm_pagerealloc "struct vm_page *pg" "struct uvm_object *newobj" "voff_t newoff" 596.Ft void 597.Fn uvm_pagefree "struct vm_page *pg" 598.Ft int 599.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" 600.Ft void 601.Fn uvm_pglistfree "struct pglist *list" 602.Ft void 603.Fn uvm_page_physload "vaddr_t start" "vaddr_t end" "vaddr_t avail_start" "vaddr_t avail_end" "int free_list" 604.nr nS 0 605.Pp 606.Fn uvm_pagealloc 607allocates a page of memory at virtual address 608.Fa off 609in either the object 610.Fa uobj 611or the anonymous memory 612.Fa anon , 613which must be locked by the caller. 614Only one of 615.Fa uobj 616and 617.Fa anon 618can be non 619.Dv NULL . 620Returns 621.Dv NULL 622when no page can be found. 623The flags can be any of 624.Bd -literal 625#define UVM_PGA_USERESERVE 0x0001 /* ok to use reserve pages */ 626#define UVM_PGA_ZERO 0x0002 /* returned page must be zero'd */ 627.Ed 628.Pp 629.Dv UVM_PGA_USERESERVE 630means to allocate a page even if that will result in the number of free pages 631being lower than 632.Dv uvmexp.reserve_pagedaemon 633(if the current thread is the pagedaemon) or 634.Dv uvmexp.reserve_kernel 635(if the current thread is not the pagedaemon). 636.Dv UVM_PGA_ZERO 637causes the returned page to be filled with zeroes, either by allocating it 638from a pool of pre-zeroed pages or by zeroing it in-line as necessary. 639.Pp 640.Fn uvm_pagerealloc 641reallocates page 642.Fa pg 643to a new object 644.Fa newobj , 645at a new offset 646.Fa newoff . 647.Pp 648.Fn uvm_pagefree 649frees the physical page 650.Fa pg . 651.Pp 652.Fn uvm_pglistalloc 653allocates a list of pages for size 654.Fa size 655byte under various constraints. 656.Fa low 657and 658.Fa high 659describe the lowest and highest addresses acceptable for the list. 660If 661.Fa alignment 662is non-zero, it describes the required alignment of the list, in 663power-of-two notation. 664If 665.Fa boundary 666is non-zero, no segment of the list may cross this power-of-two 667boundary, relative to zero. 668.Fa nsegs 669is the maximum number of physically contigous segments. 670If 671.Fa waitok 672is non-zero, the function may sleep until enough memory is available. 673(It also may give up in some situations, so a non-zero 674.Fa waitok 675does not imply that 676.Fn uvm_pglistalloc 677cannot return an error.) 678The allocated memory is returned in the 679.Fa rlist 680list; the caller has to provide storage only, the list is initialized by 681.Fn uvm_pglistalloc . 682.Pp 683.Fn uvm_pglistfree 684frees the list of pages pointed to by 685.Fa list . 686.Pp 687.Fn uvm_page_physload 688loads physical memory segments into VM space on the specified 689.Fa free_list . 690It must be called at system boot time to setup physical memory 691management pages. 692The arguments describe the 693.Fa start 694and 695.Fa end 696of the physical addresses of the segment, and the available start and end 697addresses of pages not already in use. 698.\" XXX expand on "system boot time"! 699.Sh PROCESSES 700.nr nS 1 701.Ft void 702.Fn uvm_pageout "void" 703.Ft void 704.Fn uvm_scheduler "void" 705.Ft void 706.Fn uvm_swapin "struct proc *p" 707.nr nS 0 708.Pp 709.Fn uvm_pageout 710is the main loop for the page daemon. 711.Pp 712.Fn uvm_scheduler 713is the process zero main loop, which is to be called after the 714system has finished starting other processes. 715It handles the swapping in of runnable, swapped out processes in priority 716order. 717.Pp 718.Fn uvm_swapin 719swaps in the named process. 720.Sh PAGE LOAN 721.nr nS 1 722.Ft int 723.Fn uvm_loan "struct vm_map *map" "vaddr_t start" "vsize_t len" "void *v" "int flags" 724.Ft void 725.Fn uvm_unloan "void *v" "int npages" "int flags" 726.nr nS 0 727.Pp 728.Fn uvm_loan 729loans pages in a map out to anons or to the kernel. 730.Fa map 731should be unlocked , 732.Fa start 733and 734.Fa len 735should be multiples of 736.Dv PAGE_SIZE . 737Argument 738.Fa flags 739should be one of 740.Bd -literal 741#define UVM_LOAN_TOANON 0x01 /* loan to anons */ 742#define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */ 743.Ed 744.Pp 745.Fa v 746should be pointer to array of pointers to 747.Li struct anon 748or 749.Li struct vm_page , 750as appropriate. 751The caller has to allocate memory for the array and 752ensure it's big enough to hold 753.Fa len / PAGE_SIZE 754pointers. 755Returns 0 for success, or appropriate error number otherwise. 756.Pp 757.Fn uvm_unloan 758kills loans on pages or anons. 759The 760.Fa v 761must point to the array of pointers initialized by previous call to 762.Fn uvm_loan . 763.Fa npages 764should match number of pages allocated for loan, this also matches 765number of items in the array. 766Argument 767.Fa flags 768should be one of 769.Bd -literal 770#define UVM_LOAN_TOANON 0x01 /* loan to anons */ 771#define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */ 772.Ed 773.Pp 774and should match what was used for previous call to 775.Fn uvm_loan . 776.Sh MISCELLANEOUS FUNCTIONS 777.nr nS 1 778.Ft struct uvm_object * 779.Fn uao_create "vsize_t size" "int flags" 780.Ft void 781.Fn uao_detach "struct uvm_object *uobj" 782.Ft void 783.Fn uao_reference "struct uvm_object *uobj" 784.Pp 785.Ft boolean_t 786.Fn uvm_chgkprot "caddr_t addr" "size_t len" "int rw" 787.Ft void 788.Fn uvm_kernacc "caddr_t addr" "size_t len" "int rw" 789.Ft boolean_t 790.Fn uvm_useracc "caddr_t addr" "size_t len" "int rw" 791.Pp 792.Ft int 793.Fn uvm_vslock "struct proc *p" "caddr_t addr" "size_t len" "vm_prot_t prot" 794.Ft void 795.Fn uvm_vsunlock "struct proc *p" "caddr_t addr" "size_t len" 796.Pp 797.Ft void 798.Fn uvm_meter "void" 799.Ft int 800.Fn uvm_sysctl "int *name" "u_int namelen" "void *oldp" "size_t *oldlenp" "void *newp " "size_t newlen" "struct proc *p" 801.Pp 802.Ft void 803.Fn uvm_fork "struct proc *p1" "struct proc *p2" "boolean_t shared" 804.Ft int 805.Fn uvm_grow "struct proc *p" "vaddr_t sp" 806.Ft int 807.Fn uvm_coredump "struct proc *p" "struct vnode *vp" "struct ucred *cred" "struct core *chdr" 808.Pp 809.Ft void 810.Fn uvn_findpages "struct uvm_object *uobj" "voff_t offset" "int *npagesp" "struct vm_page **pps" "int flags" 811.Pp 812.Ft void 813.Fn uvm_swap_stats "int cmd" "struct swapent *sep" "int sec" "register_t *retval" 814.Pp 815.nr nS 0 816.Pp 817The 818.Fn uao_create , 819.Fn uao_detach 820and 821.Fn uao_reference 822functions operate on anonymous memory objects, such as those used to support 823System V shared memory. 824.Fn uao_create 825returns an object of size 826.Fa size 827with flags: 828.Bd -literal 829#define UAO_FLAG_KERNOBJ 0x1 /* create kernel object */ 830#define UAO_FLAG_KERNSWAP 0x2 /* enable kernel swap */ 831.Ed 832.Pp 833which can only be used once each at system boot time. 834.Fn uao_reference 835creates an additional reference to the named anonymous memory object. 836.Fn uao_detach 837removes a reference from the named anonymous memory object, destroying 838it if removing the last reference. 839.Pp 840.Fn uvm_chgkprot 841changes the protection of kernel memory from 842.Fa addr 843to 844.Fa addr + len 845to the value of 846.Fa rw . 847This is primarily useful for debuggers, for setting breakpoints. 848This function is only available with options 849.Dv KGDB . 850.Pp 851.Fn uvm_kernacc 852and 853.Fn uvm_useracc 854check the access at address 855.Fa addr 856to 857.Fa addr + len 858for 859.Fa rw 860access, in the kernel address space, and the current process' 861address space respectively. 862.Pp 863.Fn uvm_vslock 864and 865.Fn uvm_vsunlock 866control the wiring and unwiring of pages for process 867.Fa p 868from 869.Fa addr 870to 871.Fa addr + len . 872These functions are normally used to wire memory for I/O. 873.Pp 874.Fn uvm_meter 875calculates the load average and wakes up the swapper if necessary. 876.Pp 877.Fn uvm_sysctl 878provides support for the 879.Dv CTL_VM 880domain of the 881.Xr sysctl 3 882hierarchy. 883.Fn uvm_sysctl 884handles the 885.Dv VM_LOADAVG , 886.Dv VM_METER 887and 888.Dv VM_UVMEXP 889calls, which return the current load averages, calculates current VM 890totals, and returns the uvmexp structure respectively. 891The load averages are access from userland using the 892.Xr getloadavg 3 893function. 894The uvmexp structure has all global state of the UVM system, 895and has the following members: 896.Bd -literal 897/* vm_page constants */ 898int pagesize; /* size of a page (PAGE_SIZE): must be power of 2 */ 899int pagemask; /* page mask */ 900int pageshift; /* page shift */ 901 902/* vm_page counters */ 903int npages; /* number of pages we manage */ 904int free; /* number of free pages */ 905int active; /* number of active pages */ 906int inactive; /* number of pages that we free'd but may want back */ 907int paging; /* number of pages in the process of being paged out */ 908int wired; /* number of wired pages */ 909int reserve_pagedaemon; /* number of pages reserved for pagedaemon */ 910int reserve_kernel; /* number of pages reserved for kernel */ 911 912/* pageout params */ 913int freemin; /* min number of free pages */ 914int freetarg; /* target number of free pages */ 915int inactarg; /* target number of inactive pages */ 916int wiredmax; /* max number of wired pages */ 917 918/* swap */ 919int nswapdev; /* number of configured swap devices in system */ 920int swpages; /* number of PAGE_SIZE'ed swap pages */ 921int swpginuse; /* number of swap pages in use */ 922int nswget; /* number of times fault calls uvm_swap_get() */ 923int nanon; /* number total of anon's in system */ 924int nfreeanon; /* number of free anon's */ 925 926/* stat counters */ 927int faults; /* page fault count */ 928int traps; /* trap count */ 929int intrs; /* interrupt count */ 930int swtch; /* context switch count */ 931int softs; /* software interrupt count */ 932int syscalls; /* system calls */ 933int pageins; /* pagein operation count */ 934 /* pageouts are in pdpageouts below */ 935int swapins; /* swapins */ 936int swapouts; /* swapouts */ 937int pgswapin; /* pages swapped in */ 938int pgswapout; /* pages swapped out */ 939int forks; /* forks */ 940int forks_ppwait; /* forks where parent waits */ 941int forks_sharevm; /* forks where vmspace is shared */ 942 943/* fault subcounters */ 944int fltnoram; /* number of times fault was out of ram */ 945int fltnoanon; /* number of times fault was out of anons */ 946int fltpgwait; /* number of times fault had to wait on a page */ 947int fltpgrele; /* number of times fault found a released page */ 948int fltrelck; /* number of times fault relock called */ 949int fltrelckok; /* number of times fault relock is a success */ 950int fltanget; /* number of times fault gets anon page */ 951int fltanretry; /* number of times fault retrys an anon get */ 952int fltamcopy; /* number of times fault clears "needs copy" */ 953int fltnamap; /* number of times fault maps a neighbor anon page */ 954int fltnomap; /* number of times fault maps a neighbor obj page */ 955int fltlget; /* number of times fault does a locked pgo_get */ 956int fltget; /* number of times fault does an unlocked get */ 957int flt_anon; /* number of times fault anon (case 1a) */ 958int flt_acow; /* number of times fault anon cow (case 1b) */ 959int flt_obj; /* number of times fault is on object page (2a) */ 960int flt_prcopy; /* number of times fault promotes with copy (2b) */ 961int flt_przero; /* number of times fault promotes with zerofill (2b) */ 962 963/* daemon counters */ 964int pdwoke; /* number of times daemon woke up */ 965int pdrevs; /* number of times daemon rev'd clock hand */ 966int pdswout; /* number of times daemon called for swapout */ 967int pdfreed; /* number of pages daemon freed since boot */ 968int pdscans; /* number of pages daemon scanned since boot */ 969int pdanscan; /* number of anonymous pages scanned by daemon */ 970int pdobscan; /* number of object pages scanned by daemon */ 971int pdreact; /* number of pages daemon reactivated since boot */ 972int pdbusy; /* number of times daemon found a busy page */ 973int pdpageouts; /* number of times daemon started a pageout */ 974int pdpending; /* number of times daemon got a pending pageout */ 975int pddeact; /* number of pages daemon deactivates */ 976.Ed 977.Pp 978.Fn uvm_fork 979forks a virtual address space for process' (old) 980.Fa p1 981and (new) 982.Fa p2 . 983If the 984.Fa shared 985argument is non zero, p1 shares its address space with p2, 986otherwise a new address space is created. 987This function currently has no return value, and thus cannot fail. 988In the future, this function will be changed to allow it to 989fail in low memory conditions. 990.Pp 991.Fn uvm_grow 992increases the stack segment of process 993.Fa p 994to include 995.Fa sp . 996.Pp 997.Fn uvm_coredump 998generates a coredump on vnode 999.Fa vp 1000for process 1001.Fa p 1002with credentials 1003.Fa cred 1004and core header description in 1005.Fa chdr . 1006.Pp 1007.Fn uvn_findpages 1008looks up or creates pages in 1009.Fa uobj 1010at offset 1011.Fa offset , 1012marks them busy and returns them in the 1013.Fa pps 1014array. 1015Currently 1016.Fa uobj 1017must be a vnode object. 1018The number of pages requested is pointed to by 1019.Fa npagesp , 1020and this value is updated with the actual number of pages returned. 1021The flags can be 1022.Bd -literal 1023#define UFP_ALL 0x00 /* return all pages requested */ 1024#define UFP_NOWAIT 0x01 /* don't sleep */ 1025#define UFP_NOALLOC 0x02 /* don't allocate new pages */ 1026#define UFP_NOCACHE 0x04 /* don't return pages which already exist */ 1027#define UFP_NORDONLY 0x08 /* don't return PG_READONLY pages */ 1028.Ed 1029.Pp 1030.Dv UFP_ALL 1031is a pseudo-flag meaning all requested pages should be returned. 1032.Dv UFP_NOWAIT 1033means that we must not sleep. 1034.Dv UFP_NOALLOC 1035causes any pages which do not already exist to be skipped. 1036.Dv UFP_NOCACHE 1037causes any pages which do already exist to be skipped. 1038.Dv UFP_NORDONLY 1039causes any pages which are marked PG_READONLY to be skipped. 1040.Pp 1041.Fn uvm_swap_stats 1042implements the 1043.Dv SWAP_STATS 1044and 1045.Dv SWAP_OSTATS 1046operation of the 1047.Xr swapctl 2 1048system call. 1049.Fa cmd 1050is the requested command, 1051.Dv SWAP_STATS 1052or 1053.Dv SWAP_OSTATS . 1054The function will copy no more than 1055.Fa sec 1056entries in the array pointed by 1057.Fa sep . 1058On return, 1059.Fa retval 1060holds the actual number of entries copied in the array. 1061.Sh NOTES 1062.Fn uvm_chgkprot 1063is only available if the kernel has been compiled with options 1064.Dv KGDB . 1065.Pp 1066All structure and types whose names begin with 1067.Dq vm_ 1068will be renamed to 1069.Dq uvm_ . 1070.Sh SEE ALSO 1071.Xr swapctl 2 , 1072.Xr getloadavg 3 , 1073.Xr kvm 3 , 1074.Xr sysctl 3 , 1075.Xr ddb 4 , 1076.Xr options 4 , 1077.Xr pmap 9 1078.Sh HISTORY 1079UVM is a new VM system developed at Washington University in St. Louis 1080(Missouri). 1081UVM's roots lie partly in the Mach-based 1082.Bx 4.4 1083VM system, the 1084.Fx 1085VM system, and the SunOS4 VM system. 1086UVM's basic structure is based on the 1087.Bx 4.4 1088VM system. 1089UVM's new anonymous memory system is based on the 1090anonymous memory system found in the SunOS4 VM (as described in papers 1091published by Sun Microsystems, Inc.). 1092UVM also includes a number of feature new to 1093.Bx 1094including page loanout, map entry passing, simplified 1095copy-on-write, and clustered anonymous memory pageout. 1096UVM is also further documented in a August 1998 dissertation by 1097Charles D. Cranor. 1098.Pp 1099UVM appeared in 1100.Nx 1.4 . 1101.Sh AUTHORS 1102Charles D. Cranor 1103.Aq chuck@ccrc.wustl.edu 1104designed and implemented UVM. 1105.Pp 1106Matthew Green 1107.Aq mrg@eterna.com.au 1108wrote the swap-space management code and handled the logistical issues 1109involved with merging UVM into the 1110.Nx 1111source tree. 1112.Pp 1113Chuck Silvers 1114.Aq chuq@chuq.com 1115implemented the aobj pager, thus allowing UVM to support System V shared 1116memory and process swapping. 1117He also designed and implemented the UBC part of UVM, which uses UVM pages 1118to cache vnode data rather than the traditional buffer cache buffers. 1119