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