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