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