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