1.\" $NetBSD: pmap.9,v 1.18 2002/09/27 07:46:37 wiz Exp $ 2.\" 3.\" Copyright (c) 2000, 2001, 2002 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 27, 2002 38.Dt PMAP 9 39.Os 40.Sh NAME 41.Nm pmap 42.Nd machine-dependent portion of the virtual memory system 43.Sh SYNOPSIS 44.Fd #include \*[Lt]sys/param.h\*[Gt] 45.Fd #include \*[Lt]uvm/uvm_extern.h\*[Gt] 46.Ft void 47.Fn "pmap_init" "void" 48.Ft void 49.Fn "pmap_virtual_space" "vaddr_t *vstartp" "vaddr_t *vendp" 50.Ft vaddr_t 51.Fn "pmap_steal_memory" "vsize_t size" "vaddr_t *vstartp" "vaddr_t *vendp" 52.Ft pmap_t 53.Fn "pmap_kernel" "void" 54.Ft pmap_t 55.Fn "pmap_create" "void" 56.Ft void 57.Fn "pmap_destroy" "pmap_t pmap" 58.Ft void 59.Fn "pmap_reference" "pmap_t pmap" 60.Ft void 61.Fn "pmap_fork" "pmap_t src_map" "pmap_t dst_map" 62.Ft long 63.Fn "pmap_resident_count" "pmap_t pmap" 64.Ft long 65.Fn "pmap_wired_count" "pmap_t pmap" 66.Ft vaddr_t 67.Fn "pmap_growkernel" "vaddr_t maxkvaddr" 68.Ft int 69.Fn "pmap_enter" "pmap_t pmap" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" \ 70 "int flags" 71.Ft void 72.Fn "pmap_remove" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" 73.Ft void 74.Fn "pmap_remove_all" "pmap_t pmap" 75.Ft void 76.Fn "pmap_protect" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" "vm_prot_t prot" 77.Ft void 78.Fn "pmap_unwire" "pmap_t pmap" "vaddr_t va" 79.Ft boolean_t 80.Fn "pmap_extract" "pmap_t pmap" "vaddr_t va" "paddr_t *pap" 81.Ft void 82.Fn "pmap_kenter_pa" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" 83.Ft void 84.Fn "pmap_kremove" "vaddr_t va" "vsize_t size" 85.Ft void 86.Fn "pmap_copy" "pmap_t dst_map" "pmap_t src_map" "vaddr_t dst_addr" \ 87 "vsize_t len" "vaddr_t src_addr" 88.Ft void 89.Fn "pmap_collect" "pmap_t pmap" 90.Ft void 91.Fn "pmap_update" "pmap_t pmap" 92.Ft void 93.Fn "pmap_activate" "struct proc *p" 94.Ft void 95.Fn "pmap_deactivate" "struct proc *p" 96.Ft void 97.Fn "pmap_zero_page" "paddr_t pa" 98.Ft void 99.Fn "pmap_copy_page" "paddr_t src" "paddr_t dst" 100.Ft void 101.Fn "pmap_page_protect" "struct vm_page *pg" "vm_prot_t prot" 102.Ft boolean_t 103.Fn "pmap_clear_modify" "struct vm_page *pg" 104.Ft boolean_t 105.Fn "pmap_clear_reference" "struct vm_page *pg" 106.Ft boolean_t 107.Fn "pmap_is_modified" "struct vm_page *pg" 108.Ft boolean_t 109.Fn "pmap_is_referenced" "struct vm_page *pg" 110.Ft paddr_t 111.Fn "pmap_phys_address" "int cookie" 112.Ft vaddr_t 113.Fn "PMAP_MAP_POOLPAGE" "paddr_t pa" 114.Ft paddr_t 115.Fn "PMAP_UNMAP_POOLPAGE" "vaddr_t va" 116.Sh DESCRIPTION 117The 118.Nm 119module is the machine-dependent portion of the 120.Nx 121virtual memory system 122.Xr uvm 9 . 123The purpose of the 124.Nm 125module is to manage physical address maps, to program the 126memory management hardware on the system, and perform any 127cache operations necessary to ensure correct operation of 128the virtual memory system. 129The 130.Nm 131module is also responsible for maintaining certain information 132required by 133.Xr uvm 9 . 134.Pp 135In order to cope with hardware architectures that make the 136invalidation of virtual address mappings expensive (e.g. 137TLB invalidations, TLB shootdown operations for multiple 138processors), the 139.Nm 140module is allowed to delay mapping invalidation or protection 141operations until such time as they are actually necessary. 142The functions that are allowed to delay such actions are 143.Fn pmap_enter , 144.Fn pmap_remove , 145.Fn pmap_protect , 146.Fn pmap_kenter_pa , 147and 148.Fn pmap_kremove . 149Callers of these functions must use the 150.Fn pmap_update 151function to notify the 152.Nm 153module that the mappings need to be made correct. 154Since the 155.Nm 156module is provided with information as to which processors are 157using a given physical map, the 158.Nm 159module may use whatever optimizations it has available to reduce 160the expense of virtual-to-physical mapping synchronization. 161.Ss HEADER FILES AND DATA STRUCTURES 162Machine-dependent code must provide the header file 163.Aq Pa machine/pmap.h . 164This file contains the definition of the 165.Dv pmap 166structure: 167.Bd -literal -offset indent 168struct pmap { 169 /* Contents defined by pmap implementation. */ 170}; 171typedef struct pmap *pmap_t; 172.Ed 173.Pp 174This header file may also define other data structures that the 175.Nm 176implementation uses. 177.Pp 178Note that all prototypes for 179.Nm 180interface functions are provided by the header file 181.Aq Pa uvm/uvm_pmap.h . 182It is possible to override this behavior by defining the 183C pre-processor macro 184.Dq PMAP_EXCLUDE_DECLS . 185This may be used to add a layer of indirection to 186.Nm 187API calls, for handling different MMU types in a single 188.Nm 189module, for example. 190If the 191.Dq PMAP_EXCLUDE_DECLS 192macro is defined, 193.Aq Pa machine/pmap.h 194.Em must 195provide function prototypes in a block like so: 196.Bd -literal -offset indent 197#ifdef _KERNEL /* not exposed to user namespace */ 198__BEGIN_DECLS /* make safe for C++ */ 199/* Prototypes go here. */ 200__END_DECLS 201#endif /* _KERNEL */ 202.Ed 203.Pp 204The header file 205.Aq Pa uvm/uvm_pmap.h 206defines a structure for tracking 207.Nm 208statistics (see below). 209This structure is defined as: 210.Bd -literal -offset indent 211struct pmap_statistics { 212 long resident_count; /* number of mapped pages */ 213 long wired_count; /* number of wired pages */ 214}; 215.Ed 216.Ss WIRED MAPPINGS 217The 218.Nm 219module is based on the premise that all information contained 220in the physical maps it manages is redundant. 221That is, physical map information may be 222.Dq forgotten 223by the 224.Nm 225module in the event that it is necessary to do so; it can be rebuilt 226by 227.Xr uvm 9 228by taking a page fault. 229There is one exception to this rule: so-called 230.Dq wired 231mappings may not be forgotten. 232Wired mappings are those for which either no high-level information 233exists with which to rebuild the mapping, or mappings which are needed 234by critical sections of code where taking a page fault is unacceptable. 235Information about which mappings are wired is provided to the 236.Nm 237module when a mapping is established. 238.Ss MODIFIED/REFERENCED INFORMATION 239The 240.Nm 241module is required to keep track of whether or not a page managed 242by the virtual memory system has been referenced or modified. 243This information is used by 244.Xr uvm 9 245to determine what happens to the page when scanned by the 246pagedaemon. 247.Pp 248Many CPUs provide hardware support for tracking 249modified/referenced information. 250However, many CPUs, particularly modern RISC CPUs, do not. 251On CPUs which lack hardware support for modified/referenced tracking, the 252.Nm 253module must emulate it in software. 254There are several strategies for doing this, and the best strategy 255depends on the CPU. 256.Pp 257The 258.Dq referenced 259attribute is used by the pagedaemon to determine if a page is 260.Dq active . 261Active pages are not candidates for re-use in the page replacement algorithm. 262Accurate referenced information is not required for correct operation; if 263supplying referenced information for a page is not feasible, then the 264.Nm 265implementation should always consider the 266.Dq referenced 267attribute to be FALSE. 268.Pp 269The 270.Dq modified 271attribute is used by the pagedaemon to determine if a page needs 272to be cleaned (written to backing store; swap space, a regular file, etc.). 273Accurate modified information 274.Em must 275be provided by the 276.Nm 277module for correct operation of the virtual memory system. 278.Pp 279Note that modified/referenced information is only tracked for 280pages managed by the virtual memory system (i.e., pages for 281which a vm_page structure exists). 282In addition, only 283.Dq managed 284mappings of those pages have modified/referenced tracking. 285Mappings entered with the 286.Fn pmap_enter 287function are 288.Dq managed 289mappings. 290It is possible for 291.Dq unmanaged 292mappings of a page to be created, using the 293.Fn pmap_kenter_pa 294function. 295The use of 296.Dq unmanaged 297mappings should be limited to code which may execute in interrupt context 298(for example, the kernel memory allocator), or to enter mappings for 299physical addresses which are not managed by the virtual memory system. 300.Dq Unmanaged 301mappings may only be entered into the kernel's virtual address space. 302This constraint is placed on the callers of the 303.Fn pmap_kenter_pa 304and 305.Fn pmap_kremove 306functions so that the 307.Nm 308implementation need not block interrupts when manipulating data 309structures or holding locks. 310.Pp 311Also note that the modified/referenced information must be tracked 312on a per-page basis; they are not attributes of a mapping, but attributes 313of a page. 314Therefore, even after all mappings for a given page have 315been removed, the modified/referenced information for that page 316.Em must 317be preserved. 318The only time the modified/referenced attributes may 319be cleared is when the virtual memory system explicitly calls the 320.Fn pmap_clear_modify 321and 322.Fn pmap_clear_reference 323functions. 324These functions must also change any internal state necessary to detect 325the page being modified or referenced again after the modified or 326referenced state is cleared. 327(Prior to 328.Nx 1.6 , 329.Nm 330implementations could get away without this because UVM (and Mach VM 331before that) always called 332.Fn pmap_page_protect 333before clearing the modified or referenced state, but UVM has been changed 334to not do this anymore, so all 335.Nm 336implementations must now handle this.) 337.Ss STATISTICS 338The 339.Nm 340is required to keep statistics as to the number of 341.Dq resident 342pages and the number of 343.Dq wired 344pages. 345.Pp 346A 347.Dq resident 348page is one for which a mapping exists. 349This statistic is used to compute the resident size of a process and 350enforce resource limits. 351Only pages (whether managed by the virtual memory system or not) 352which are mapped into a physical map should be counted in the resident 353count. 354.Pp 355A 356.Dq wired 357page is one for which a wired mapping exists. 358This statistic is used to enforce resource limits. 359.Pp 360Note that it is recommended (though not required) that the 361.Nm 362implementation utilize the 363.Dv pmap_statistics 364structure in the tracking of 365.Nm 366statistics by placing it inside the 367.Dv pmap 368structure and adjusting the counts when mappings are established, changed, 369or removed. 370This avoids potentially expensive data structure traversals when the 371statistics are queried. 372.Ss REQUIRED FUNCTIONS 373This section describes functions that a 374.Nm 375module must provide to the virtual memory system. 376.Bl -tag -width indent -offset indent 377.It void Fn "pmap_init" "void" 378This function initializes the 379.Nm 380module. 381It is called by 382.Fn uvm_init 383to initialize any data structures that the module needs to 384manage physical maps. 385.It pmap_t Fn "pmap_kernel" "void" 386Return a pointer to the 387.Dv pmap 388structure that maps the kernel virtual address space. 389.Pp 390Note that this function may be provided as a C pre-processor macro. 391.It void Fn "pmap_virtual_space" "vaddr_t *vstartp" "vaddr_t *vendp" 392The 393.Fn pmap_virtual_space 394function is called to determine the initial kernel virtual address 395space beginning and end. 396These values are used to create the kernel's virtual memory map. 397The function must set 398.Fa *vstartp 399to the first kernel virtual address that will be managed by 400.Xr uvm 9 , 401and must set 402.Fa *vendp 403to the last kernel virtual address that will be managed by 404.Xr uvm 9 . 405.Pp 406If the 407.Fn pmap_growkernel 408feature is used by a 409.Nm 410implementation, then 411.Fa *vendp 412should be set to the maximum kernel virtual address allowed by the 413implementation. 414If 415.Fn pmap_growkernel 416is not used, then 417.Fa *vendp 418.Em must 419be set to the maximum kernel virtual address that can be mapped with 420the resources currently allocated to map the kernel virtual address 421space. 422.It pmap_t Fn "pmap_create" "void" 423Create a physical map and return it to the caller. 424The reference count on the new map is 1. 425.It void Fn "pmap_destroy" "pmap_t pmap" 426Drop the reference count on the specified physical map. 427If the reference count drops to 0, all resources associated with the 428physical map are released and the physical map destroyed. 429In the case of a drop-to-0, no mappings will exist in the map. 430The 431.Nm 432implementation may assert this. 433.It void Fn "pmap_reference" "pmap_t pmap" 434Increment the reference count on the specified physical map. 435.It long Fn "pmap_resident_count" "pmap_t pmap" 436Query the 437.Dq resident pages 438statistic for 439.Fa pmap . 440.Pp 441Note that this function may be provided as a C pre-processor macro. 442.It long Fn "pmap_wired_count" "pmap_t pmap" 443Query the 444.Dq wired pages" 445statistic for 446.Fa pmap . 447.Pp 448Note that this function may be provided as a C pre-processor macro. 449.It int Fn "pmap_enter" "pmap_t pmap" "vaddr_t va" "paddr_t pa" \ 450 "vm_prot_t prot" "int flags" 451Create a mapping in physical map 452.Fa pmap 453for the physical address 454.Fa pa 455at the virtual address 456.Fa va 457with protection specified by bits in 458.Fa prot : 459.Bl -tag -width "VM_PROT_EXECUTE " -offset indent 460.It VM_PROT_READ 461The mapping must allow reading. 462.It VM_PROT_WRITE 463The mapping must allow writing. 464.It VM_PROT_EXECUTE 465The page mapped contains instructions that will be executed by the 466processor. 467.El 468.Pp 469The 470.Fa flags 471argument contains protection bits (the same bits as used in the 472.Fa prot 473argument) indicating the type of access that caused the mapping to 474be created. 475This information may be used to seed modified/referenced 476information for the page being mapped, possibly avoiding redundant faults 477on platforms that track modified/referenced information in software. 478Other information provided by 479.Fa flags : 480.Bl -tag -width "PMAP_CANFAIL " -offset indent 481.It PMAP_WIRED 482The mapping being created is a wired mapping. 483.It PMAP_CANFAIL 484The call to 485.Fn pmap_enter 486is allowed to fail. 487If this flag is 488.Em not 489set, and the 490.Fn pmap_enter 491call is unable to create the mapping, perhaps due to insufficient 492resources, the 493.Nm 494module must panic. 495.El 496.Pp 497The access type provided in the 498.Fa flags 499argument will never exceed the protection specified by 500.Fa prot . 501The 502.Nm 503implementation may assert this. 504Note that on systems that do not provide hardware support for 505tracking modified/referenced information, modified/referenced 506information for the page 507.Em must 508be seeded with the access type provided in 509.Fa flags 510if the PMAP_WIRED flag is set. 511This is to prevent a fault for the purpose of tracking 512modified/referenced information from occurring while the system is in 513a critical section where a fault would be unacceptable. 514.Pp 515Note that 516.Fn pmap_enter 517is sometimes called to enter a mapping at a virtual address 518for which a mapping already exists. 519In this situation, the implementation must take whatever action is 520necessary to invalidate the previous mapping before entering the new one. 521.Pp 522Also note that 523.Fn pmap_enter 524is sometimes called to change the protection for a pre-existing 525mapping, or to change the 526.Dq wired 527attribute for a pre-existing mapping. 528.Pp 529The 530.Fn pmap_enter 531function returns 0 on success or an error code indicating the mode 532of failure. 533.It void Fn "pmap_remove" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" 534Remove mappings from the virtual address range 535.Fa sva 536to 537.Fa eva 538from the specified physical map. 539.It void Fn "pmap_remove_all" "pmap_t pmap" 540This function is a hint to the 541.Nm pmap 542implementation that all entries in 543.Fa pmap 544will be removed before any more entries are entered. 545Following this call, there will be 546.Fn pmap_remove 547calls resulting in every mapping being removed, followed by either 548.Fn pmap_destroy 549or 550.Fn pmap_update . 551No other 552.Nm pmap 553interfaces which take 554.Fa pmap 555as an argument will be called during this process. 556Other interfaces which might need to access 557.Fa pmap 558(such as 559.Fn pmap_page_protect ) 560are permitted during this process. 561.Pp 562The 563.Nm pmap 564implementation is free to either remove all the 565.Nm pmap Ns 's 566mappings immediately in 567.Fn pmap_remove_all , 568or to use the knowledge of the upcoming 569.Fn pmap_remove 570calls to optimize the removals (or to just ignore this call). 571.Pp 572.It void Fn "pmap_protect" "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" \ 573 "vm_prot_t prot" 574Set the protection of the mappings in the virtual address range 575.Fa sva 576to 577.Fa eva 578in the specified physical map. 579.It void Fn "pmap_unwire" "pmap_t pmap" "vaddr_t va" 580Clear the 581.Dq wired 582attribute on the mapping for virtual address 583.Fa va . 584.It boolean_t Fn "pmap_extract" "pmap_t pmap" "vaddr_t va" "paddr_t *pap" 585This function extracts a mapping from the specified physical map. 586It serves two purposes: to determine if a mapping exists for the specified 587virtual address, and to determine what physical address is mapped at the 588specified virtual address. 589.Pp 590The 591.Fn pmap_extract 592function returns FALSE if a mapping for 593.Fa va 594does not exist. 595Otherwise, it returns TRUE and places the physical address mapped at 596.Fa va 597into 598.Fa *pap 599if the 600.Fa pap 601argument is non-NULL. 602.It void Fn "pmap_kenter_pa" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" 603Enter an 604.Dq unmanaged 605mapping for physical address 606.Fa pa 607at virtual address 608.Fa va 609with protection 610.Fa prot 611into the kernel physical map. 612Mappings of this type are always 613.Dq wired , 614and are unaffected by routines that alter the protection of pages 615(such as 616.Fn pmap_page_protect ) . 617Such mappings are also not included in the gathering of modified/referenced 618information about a page. 619Mappings entered with 620.Fn pmap_kenter_pa 621by machine-independent code 622.Em must not 623have execute permission, as the 624data structures required to track execute permission of a page may not 625be available to 626.Fn pmap_kenter_pa . 627Machine-independent code is not allowed to enter a mapping with 628.Fn pmap_kenter_pa 629at a virtual address for which a valid mapping already exists. 630Mappings created with 631.Fn pmap_kenter_pa 632may be removed only with a call to 633.Fn pmap_kremove . 634.Pp 635Note that 636.Fn pmap_kenter_pa 637must be safe for use in interrupt context. 638.Fn splvm 639blocks interrupts that might cause 640.Fn pmap_kenter_pa 641to be called. 642.It void Fn "pmap_kremove" "vaddr_t va" "vsize_t size" 643Remove all mappings starting at virtual address 644.Fa va 645for 646.Fa size 647bytes from the kernel physical map. 648All mappings that are removed must be the 649.Dq unmanaged 650type created with 651.Fn pmap_kenter_pa . 652The implementation may assert this. 653.It void Fn "pmap_copy" "pmap_t dst_map" "pmap_t src_map" "vaddr_t dst_addr" \ 654 "vsize_t len" "vaddr_t src_addr" 655This function copies the mappings starting at 656.Fa src_addr 657in 658.Fa src_map 659for 660.Fa len 661bytes into 662.Fa dst_map 663starting at 664.Fa dst_addr . 665.Pp 666Note that while this function is required to be provided by a 667.Nm 668implementation, it is not actually required to do anything. 669.Fn pmap_copy 670is merely advisory (it is used in the 671.Xr fork 2 672path to 673.Dq pre-fault 674the child's address space). 675.It void Fn "pmap_collect" "pmap_t pmap" 676This function is called just before a process is swapped out to 677allow the 678.Nm 679module to release resources used to map the process's address space. 680The implementation may choose to remove physical mappings in order 681to free e.g. page tables back to the system. 682Note, however, that wired mappings must 683.Em not 684be removed when 685.Fn pmap_collect 686is called. 687.Pp 688Note that while this function is required to be provided by a 689.Nm 690implementation, it is not actually required to do anything. 691.Fn pmap_collect 692is merely advisory. 693It is recommended, however, that 694.Fn pmap_collect 695be fully implemented by a 696.Nm 697implementation. 698.It void Fn "pmap_update" "pmap_t pmap" 699This function is used to inform the 700.Nm 701module that all physical mappings, for the specified pmap, must now be 702correct. 703That is, all delayed virtual-to-physical mappings updates (such as TLB 704invalidation or address space identifier updates) must be completed. 705This routine must be used after calls to 706.Fn pmap_enter , 707.Fn pmap_remove , 708.Fn pmap_protect , 709.Fn pmap_kenter_pa , 710and 711.Fn pmap_kremove 712in order to ensure correct operation of the virtual memory system. 713.Pp 714If a 715.Nm 716implementation does not delay virtual-to-physical mapping updates, 717.Fn pmap_update 718has no operation. 719In this case, the call may be deleted using a C pre-processor macro in 720.Aq Pa machine/pmap.h . 721.It void Fn "pmap_activate" "struct proc *p" 722Activate the physical map used by process 723.Fa p . 724This is called by the virtual memory system when the the 725virtual memory context for a process is changed, and is also 726often used by machine-dependent context switch code to program 727the memory management hardware with the process's page table 728base, etc. 729Note that 730.Fn pmap_activate 731may not always be called when 732.Fa p 733is the current process. 734.Fn pmap_activate 735must be able to handle this scenario. 736.It void Fn "pmap_deactivate" "struct proc *p" 737Deactivate the physical map used by process 738.Fa p . 739It is generally used in conjunction with 740.Fn pmap_activate . 741Like 742.Fn pmap_activate , 743.Fn pmap_deactivate 744may not always be called when 745.Fa p 746is the current process. 747.It void Fn "pmap_zero_page" "paddr_t pa" 748Zero the PAGE_SIZE sized region starting at physical address 749.Fa pa . 750The 751.Nm 752implementation must take whatever steps are necessary to map the 753page to a kernel-accessible address and zero the page. 754It is suggested that implementations use an optimized zeroing algorithm, 755as the performance of this function directly impacts page fault performance. 756The implementation may assume that the region is 757PAGE_SIZE aligned and exactly PAGE_SIZE bytes in length. 758.Pp 759Note that the cache configuration of the platform should also be 760considered in the implementation of 761.Fn pmap_zero_page . 762For example, on systems with a physically-addressed cache, the cache 763load caused by zeroing the page will not be wasted, as the zeroing is 764usually done on-demand. 765However, on systems with a virtually-addressed cached, the cache load 766caused by zeroing the page 767.Em will 768be wasted, as the page will be mapped at a virtual address which is 769different from that used to zero the page. 770In the virtually-addressed cache case, care should also be taken to 771avoid cache alias problems. 772.It void Fn "pmap_copy_page" "paddr_t src" "paddr_t dst" 773Copy the PAGE_SIZE sized region starting at physical address 774.Fa src 775to the same sized region starting at physical address 776.Fa dst . 777The 778.Nm 779implementation must take whatever steps are necessary to map the 780source and destination pages to a kernel-accessible address and 781perform the copy. 782It is suggested that implementations use an optimized copy algorithm, 783as the performance of this function directly impacts page fault performance. 784The implementation may assume that both regions are PAGE_SIZE aligned 785and exactly PAGE_SIZE bytes in length. 786.Pp 787The same cache considerations that apply to 788.Fn pmap_zero_page 789apply to 790.Fn pmap_copy_page . 791.It void Fn "pmap_page_protect" "struct vm_page *pg" "vm_prot_t prot" 792Lower the permissions for all mappings of the page 793.Fa pg 794to 795.Fa prot . 796This function is used by the virtual memory system to implement 797copy-on-write (called with VM_PROT_READ set in 798.Fa prot ) 799and to revoke all mappings when cleaning a page (called with 800no bits set in 801.Fa prot ) . 802Access permissions must never be added to a page as a result of 803this call. 804.It boolean_t Fn "pmap_clear_modify" "struct vm_page *pg" 805Clear the 806.Dq modified 807attribute on the page 808.Fa pg . 809.Pp 810The 811.Fn pmap_clear_modify 812function returns TRUE or FALSE indicating whether or not the 813.Dq modified 814attribute was set on the page before it was cleared. 815.Pp 816Note that this function may be provided as a C pre-processor macro. 817.It boolean_t Fn "pmap_clear_reference" "struct vm_page *pg" 818Clear the 819.Dq referenced 820attribute on the page 821.Fa pg . 822.Pp 823The 824.Fn pmap_clear_reference 825function returns TRUE or FALSE indicating whether or not the 826.Dq referenced 827attribute was set on the page before it was cleared. 828.Pp 829Note that this function may be provided as a C pre-processor macro. 830.It boolean_t Fn "pmap_is_modified" "struct vm_page *pg" 831Test whether or not the 832.Dq modified 833attribute is set on page 834.Fa pg . 835.Pp 836Note that this function may be provided as a C pre-processor macro. 837.It boolean_t Fn "pmap_is_referenced" "struct vm_page *pg" 838Test whether or not the 839.Dq referenced 840attribute is set on page 841.Fa pg . 842.Pp 843Note that this function may be provided as a C pre-processor macro. 844.It paddr_t Fn "pmap_phys_address" "int cookie" 845Convert a cookie returned by a device 846.Fn mmap 847function into a physical address. 848This function is provided to accommodate systems which have physical 849address spaces larger than can be directly addressed by the platform's 850.Fa paddr_t 851type. 852The existence of this function is highly dubious, and it is 853expected that this function will be removed from the 854.Nm pmap 855API in a future release of 856.Nx . 857.Pp 858Note that this function may be provided as a C pre-processor macro. 859.El 860.Ss OPTIONAL FUNCTIONS 861This section describes several optional functions in the 862.Nm 863API. 864.Bl -tag -width indent -offset indent 865.It vaddr_t Fn "pmap_steal_memory" "vsize_t size" "vaddr_t *vstartp" \ 866 "vaddr_t *vendp" 867This function is a bootstrap memory allocator, which may be provided 868as an alternative to the bootstrap memory allocator used within 869.Xr uvm 9 870itself. 871It is particularly useful on systems which provide e.g. a direct-mapped 872memory segment. 873This function works by stealing pages from the (to be) managed memory 874pool, which has already been provided to 875.Xr uvm 9 876in the vm_physmem[] array. 877The pages are then mapped, or otherwise made accessible to the kernel, 878in a machine-dependent way. 879The memory must be zeroed by 880.Fn pmap_steal_memory . 881Note that memory allocated with 882.Fn pmap_steal_memory 883will never be freed, and mappings made by 884.Fn pmap_steal_memory 885must never be 886.Dq forgotten . 887.Pp 888Note that 889.Fn pmap_steal_memory 890should not be used as a general-purpose early-startup memory 891allocation routine. 892It is intended to be used only by the 893.Fn uvm_pageboot_alloc 894routine and its supporting routines. 895If you need to allocate memory before the virtual memory system is 896initialized, use 897.Fn uvm_pageboot_alloc . 898See 899.Xr uvm 9 900for more information. 901.Pp 902The 903.Fn pmap_steal_memory 904function returns the kernel-accessible address of the allocated memory. 905If no memory can be allocated, or if allocated memory cannot be mapped, 906the function must panic. 907.Pp 908If the 909.Fn pmap_steal_memory 910function uses address space from the range provided to 911.Xr uvm 9 912by the 913.Fn pmap_virtual_space 914call, then 915.Fn pmap_steal_memory 916must adjust 917.Fa *vstartp 918and 919.Fa *vendp 920upon return. 921.Pp 922The 923.Fn pmap_steal_memory 924function is enabled by defining the C pre-processor macro 925.Dq PMAP_STEAL_MEMORY 926in 927.Aq Pa machine/pmap.h . 928.It vaddr_t Fn "pmap_growkernel" "vaddr_t maxkvaddr" 929Management of the kernel virtual address space is complicated by the 930fact that it is not always safe to wait for resources with which to 931map a kernel virtual address. 932However, it is not always desirable to pre-allocate all resources 933necessary to map the entire kernel virtual address space. 934.Pp 935The 936.Fn pmap_growkernel 937interface is designed to help alleviate this problem. 938The virtual memory startup code may choose to allocate an initial set 939of mapping resources (e.g., page tables) and set an internal variable 940indicating how much kernel virtual address space can be mapped using 941those initial resources. 942Then, when the virtual memory system wishes to map something 943at an address beyond that initial limit, it calls 944.Fn pmap_growkernel 945to pre-allocate more sources with which to create the mapping. 946Note that once additional kernel virtual address space mapping resources 947have been allocated, they should not be freed; it is likely they will 948be needed again. 949.Pp 950The 951.Fn pmap_growkernel 952function returns the new maximum kernel virtual address that can be mapped 953with the resources it has available. 954If new resources cannot be allocated, 955.Fn pmap_growkernel 956must panic. 957.Pp 958The 959.Fn pmap_growkernel 960function is enabled by defining the C pre-processor macro 961.Dq PMAP_GROWKERNEL 962in 963.Aq Pa machine/pmap.h . 964.It void Fn "pmap_fork" "pmap_t src_map" "pmap_t dst_map" 965Some 966.Nm 967implementations may need to keep track of other information not 968directly related to the virtual address space. 969For example, on the i386 port, the Local Descriptor Table state of a 970process is associated with the pmap (this is due to the fact that 971applications manipulate the Local Descriptor Table directly expect it 972to be logically associated with the virtual memory state of the process). 973.Pp 974The 975.Fn pmap_fork 976function is provided as a way to associate information from 977.Fa src_map 978with 979.Fa dst_map 980when a 981.Dv vmspace 982is forked. 983.Fn pmap_fork 984is called from 985.Fn uvmspace_fork . 986.Pp 987The 988.Fn pmap_fork 989function is enabled by defining the C pre-processor macro 990.Dq PMAP_FORK 991in 992.Aq Pa machine/pmap.h . 993.It vaddr_t Fn "PMAP_MAP_POOLPAGE" "paddr_t pa" 994This function is used by the 995.Xr pool 9 996memory pool manager. 997Pools allocate backing pages one at a time. 998This is provided as a means to use hardware features such as a 999direct-mapped memory segment to map the pages used by the 1000.Xr pool 9 1001allocator. 1002This can lead to better performance by e.g. reducing TLB contention. 1003.Pp 1004.Fn PMAP_MAP_POOLPAGE 1005returns the kernel-accessible address of the page being mapped. 1006It must always succeed. 1007.Pp 1008The use of 1009.Fn PMAP_MAP_POOLPAGE 1010is enabled by defining it as a C pre-processor macro in 1011.Aq Pa machine/pmap.h . 1012If 1013.Fn PMAP_MAP_POOLPAGE 1014is defined, 1015.Fn PMAP_UNMAP_POOLPAGE 1016must also be defined. 1017.Pp 1018The following is an example of how to define 1019.Fn PMAP_MAP_POOLPAGE : 1020.Bd -literal -offset indent 1021#define PMAP_MAP_POOLPAGE(pa) MIPS_PHYS_TO_KSEG0((pa)) 1022.Ed 1023.Pp 1024This takes the physical address of a page and returns the KSEG0 1025address of that page on a MIPS processor. 1026.It paddr_t Fn "PMAP_UNMAP_POOLPAGE" "vaddr_t va" 1027This function is the inverse of 1028.Fn PMAP_MAP_POOLPAGE . 1029.Pp 1030.Fn PMAP_UNMAP_POOLPAGE 1031returns the physical address of the page corresponding to the 1032provided kernel-accessible address. 1033.Pp 1034The use of 1035.Fn PMAP_UNMAP_POOLPAGE 1036is enabled by defining it as a C pre-processor macro in 1037.Aq Pa machine/pmap.h . 1038If 1039.Fn PMAP_UNMAP_POOLPAGE 1040is defined, 1041.Fn PMAP_MAP_POOLPAGE 1042must also be defined. 1043.Pp 1044The following is an example of how to define 1045.Fn PMAP_UNMAP_POOLPAGE : 1046.Bd -literal -offset indent 1047#define PMAP_UNMAP_POOLPAGE(pa) MIPS_KSEG0_TO_PHYS((va)) 1048.Ed 1049.Pp 1050This takes the KSEG0 address of a previously-mapped pool page 1051and returns the physical address of that page on a MIPS processor. 1052.El 1053.Sh SEE ALSO 1054.Xr uvm 9 1055.Sh HISTORY 1056The 1057.Nm 1058module was originally part of the design of the virtual memory system 1059in the Mach Operating System. 1060The goal was to provide a clean separation between the machine-independent 1061and the machine-dependent portions of the virtual memory system, in 1062stark contrast to the original 1063.Bx 3 1064virtual memory system, which was specific to the VAX. 1065.Pp 1066Between 1067.Bx 4.3 1068and 1069.Bx 4.4 , 1070the Mach virtual memory system, including the 1071.Nm 1072API, was ported to 1073.Bx 1074and included in the 1075.Bx 4.4 1076release. 1077.Pp 1078.Nx 1079inherited the 1080.Bx 1081version of the Mach virtual memory system. 1082.Nx 1.4 1083was the first 1084.Nx 1085release with the new 1086.Xr uvm 9 1087virtual memory system, which included several changes to the 1088.Nm 1089API. 1090Since the introduction of 1091.Xr uvm 9 , 1092the 1093.Nm 1094API has evolved further. 1095.Sh AUTHORS 1096The original Mach VAX 1097.Nm 1098module was written by 1099.An Avadis Tevanian, Jr. 1100and 1101.An Michael Wayne Young . 1102.Pp 1103.An Mike Hibler 1104did the integration of the Mach virtual memory system into 1105.Bx 4.4 1106and implemented a 1107.Nm 1108module for the Motorola 68020+68851/68030/68040. 1109.Pp 1110The 1111.Nm 1112API as it exists in 1113.Nx 1114is derived from 1115.Bx 4.4 , 1116and has been modified by 1117.An Chuck Cranor , 1118.An Charles M. Hannum , 1119.An Chuck Silvers , 1120.An Wolfgang Solfrank , 1121.An Bill Sommerfeld , 1122and 1123.An Jason R. Thorpe . 1124.Pp 1125The author of this document is 1126.An Jason R. Thorpe 1127.Aq thorpej@netbsd.org . 1128.Sh BUGS 1129The use and definition of 1130.Fn pmap_activate 1131and 1132.Fn pmap_deactivate 1133needs to be reexamined. 1134.Pp 1135The use of 1136.Fn pmap_copy 1137needs to be reexamined. 1138Empirical evidence suggests that performance of the system suffers when 1139.Fn pmap_copy 1140actually performs its defined function. 1141This is largely due to the fact that the copy of the virtual-to-physical 1142mappings is wasted if the process calls 1143.Xr execve 2 1144after 1145.Xr fork 2 . 1146For this reason, it is recommended that 1147.Nm 1148implementations leave the body of the 1149.Fn pmap_copy 1150function empty for now. 1151