1.\" $OpenBSD: pmap.9,v 1.21 2025/01/19 22:14:45 kettenis Exp $ 2.\" 3.\" Copyright (c) 2001, 2002, 2003 CubeSoft Communications, Inc. 4.\" <http://www.csoft.org> 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 17.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 19.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 20.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 21.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 23.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING 24.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE 25.\" POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd $Mdocdate: January 19 2025 $ 28.Dt PMAP_INIT 9 29.Os 30.Sh NAME 31.Nm pmap_init , 32.Nm pmap_enter , 33.Nm pmap_kenter_pa , 34.Nm pmap_remove , 35.Nm pmap_kremove , 36.Nm pmap_unwire , 37.Nm pmap_protect , 38.Nm pmap_page_protect , 39.Nm pmap_is_modified , 40.Nm pmap_clear_modify , 41.Nm pmap_is_referenced , 42.Nm pmap_clear_reference , 43.Nm pmap_copy_page , 44.Nm pmap_zero_page , 45.Nm pmap_create , 46.Nm pmap_reference , 47.Nm pmap_destroy , 48.Nm pmap_steal_memory , 49.Nm pmap_growkernel , 50.Nm pmap_update , 51.Nm pmap_collect , 52.Nm pmap_populate , 53.Nm pmap_virtual_space 54.Nd machine dependent interface to the MMU 55.Sh SYNOPSIS 56.In machine/pmap.h 57.Sh DESCRIPTION 58The architecture-dependent 59.Nm pmap 60module describes how the physical mapping is done between the user-processes 61and kernel virtual addresses and the physical addresses of the main memory, 62providing machine-dependent translation and access tables that are used 63directly or indirectly by the memory-management hardware. 64The 65.Nm pmap 66layer can be viewed as a big array of mapping entries that are indexed by 67virtual address to produce a physical address and flags. 68These flags describe 69the page's protection, whether the page has been referenced or modified and 70other characteristics. 71.Pp 72The 73.Nm pmap 74interface is consistent across all platforms and hides the way page mappings 75are stored. 76.Sh INITIALIZATION 77.nr nS 1 78.Ft void 79.Fn pmap_init "void" 80.nr nS 0 81.Pp 82The 83.Fn pmap_init 84function is called from the machine-independent 85.Xr uvm_init 9 86initialization code, when the MMU is enabled. 87.Sh PAGE MANAGEMENT 88Modified/referenced information is only tracked for pages managed by UVM 89(pages for which a vm_page structure exists). 90Only managed mappings of those pages have modified/referenced tracking. 91The use of unmanaged mappings should be limited to code which may execute 92in interrupt context (such as 93.Xr malloc 9 ) 94or to enter mappings for physical addresses which are not managed by UVM. 95This allows 96.Nm pmap 97modules to avoid blocking interrupts when manipulating data structures or 98holding locks. 99Unmanaged mappings may only be entered into the kernel's virtual address space. 100The modified/referenced bits must be tracked on a per-page basis, as they 101are not attributes of a mapping, but attributes of a page. 102Therefore, even after all mappings for a given page have been removed, the 103modified/referenced bits for that page must be preserved. 104The only time the modified/referenced bits may be cleared is when UVM 105explicitly calls the 106.Fn pmap_clear_modify 107and 108.Fn pmap_clear_reference 109functions. 110These functions must also change any internal state necessary to detect 111the page being modified or referenced again after the modified/referenced 112state is cleared. 113.Pp 114Mappings entered by 115.Fn pmap_enter 116are managed, mappings entered by 117.Fn pmap_kenter_pa 118are not. 119.Sh MAPPING ALLOCATION 120.nr nS 1 121.Ft int 122.Fn pmap_enter "pmap_t pmap" "vaddr_t va" "paddr_t pa" "vm_prot_t prot" \ 123 "int flags" 124.Ft void 125.Fn pmap_kenter_pa "vaddr_t va" "paddr_t pa" "vm_prot_t prot" 126.Ft void 127.Fn pmap_remove "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" 128.Ft void 129.Fn pmap_kremove "vaddr_t va" "vsize_t size" 130.nr nS 0 131.Pp 132The 133.Fn pmap_enter 134function creates a managed mapping for physical page 135.Fa pa 136at the specified virtual address 137.Fa va 138in the target physical map 139.Fa pmap 140with protection specified by 141.Fa prot : 142.Bl -tag -width "PROT_WRITE" 143.It PROT_READ 144The mapping must allow reading. 145.It PROT_WRITE 146The mapping must allow writing. 147.It PROT_EXEC 148The page mapped contains instructions that will be executed by the 149processor. 150.El 151.Pp 152The 153.Fa flags 154argument contains protection bits (the same bits used in the 155.Fa prot 156argument) indicating the type of access that caused the mapping to 157be created. 158This information may be used to seed modified/referenced 159information for the page being mapped, possibly avoiding redundant 160faults on platforms that track modified/referenced information in 161software. 162Other information provided by 163.Fa flags : 164.Bl -tag -width "PMAP_CANFAIL" 165.It PMAP_WIRED 166The mapping being created is a wired mapping. 167.It PMAP_CANFAIL 168The call to 169.Fn pmap_enter 170is allowed to fail. 171If this flag is not set, and the 172.Fn pmap_enter 173call is unable to create the mapping, perhaps due to insufficient 174resources, the 175.Nm pmap 176module must panic. 177.El 178.Pp 179The access type provided in the 180.Fa flags 181argument will never exceed the protection specified by 182.Fa prot . 183.Pp 184The 185.Fn pmap_enter 186function is called by the fault routine to establish a mapping for 187the page being faulted in. 188If 189.Fn pmap_enter 190is called to enter a mapping at a virtual address for which a mapping 191already exists, the previous mapping must be invalidated. 192.Fn pmap_enter 193is sometimes called to change the protection for a pre-existing mapping, 194or to change the 195.Dq wired 196attribute for a pre-existing mapping. 197.Pp 198The 199.Fn pmap_kenter_pa 200function creates an unmanaged mapping of physical address 201.Fa pa 202at the specified virtual address 203.Fa va 204with the protection specified by 205.Fa prot . 206.Pp 207The 208.Fn pmap_remove 209function removes the range of virtual addresses 210.Fa sva 211to 212.Fa eva 213from 214.Fa pmap , 215assuming proper alignment. 216.Fn pmap_remove 217is called during an unmap 218operation to remove low-level machine dependent mappings. 219.Pp 220The 221.Fn pmap_kremove 222function removes an unmanaged mapping at virtual address 223.Fa va 224of size 225.Fa size . 226.Pp 227A call to 228.Fn pmap_update 229must be made after 230.Fn pmap_kenter_pa 231or 232.Fn pmap_kremove 233to notify the 234.Nm pmap 235layer that the mappings need to be made correct. 236.Sh ACCESS PROTECTION 237.nr nS 1 238.Ft void 239.Fn pmap_unwire "pmap_t pmap" "vaddr_t va" 240.Ft void 241.Fn pmap_protect "pmap_t pmap" "vaddr_t sva" "vaddr_t eva" "vm_prot_t prot" 242.Ft void 243.Fn pmap_page_protect "struct vm_page *pg" "vm_prot_t prot" 244.nr nS 0 245.Pp 246The 247.Fn pmap_unwire 248function clears the wired attribute for a map/virtual-address pair. 249The mapping must already exist in 250.Fa pmap . 251.Pp 252The 253.Fn pmap_protect 254function sets the physical protection on range 255.Fa sva 256to 257.Fa eva , 258in 259.Fa pmap . 260.Pp 261The 262.Fn pmap_protect 263function is called during a copy-on-write operation to write protect 264copy-on-write memory, and when paging out a page to remove all mappings 265of a page. 266The 267.Fn pmap_page_protect 268function sets the permission for all mapping to page 269.Fa pg . 270The 271.Fn pmap_page_protect 272function is called before a pageout operation to ensure that all pmap 273references to a page are removed. 274.Sh PHYSICAL PAGE-USAGE INFORMATION 275.nr nS 1 276.Ft boolean_t 277.Fn pmap_is_modified "struct vm_page *pg" 278.Ft boolean_t 279.Fn pmap_clear_modify "struct vm_page *pg" 280.Ft boolean_t 281.Fn pmap_is_referenced "struct vm_page *pg" 282.Ft boolean_t 283.Fn pmap_clear_reference "struct vm_page *pg" 284.nr nS 0 285.Pp 286The 287.Fn pmap_is_modified 288and 289.Fn pmap_clear_modify 290functions read/set the modify bits on the specified physical page 291.Fa pg . 292The 293.Fn pmap_is_referenced 294and 295.Fn pmap_clear_reference 296functions read/set the reference bits on the specified physical page 297.Fa pg . 298.Pp 299The 300.Fn pmap_is_referenced 301and 302.Fn pmap_is_modified 303functions are called by the pagedaemon when looking for pages to free. 304The 305.Fn pmap_clear_referenced 306and 307.Fn pmap_clear_modify 308functions are called by the pagedaemon to help identification of pages 309that are no longer in demand. 310.Sh PHYSICAL PAGE INITIALIZATION 311.nr nS 1 312.Ft void 313.Fn pmap_copy_page "struct vm_page *src" "struct vm_page *dst" 314.Ft void 315.Fn pmap_zero_page "struct vm_page *page" 316.nr nS 0 317.Pp 318The 319.Fn pmap_copy_page 320function copies the content of the physical page 321.Fa src 322to physical page 323.Fa dst . 324.Pp 325The 326.Fn pmap_zero_page 327function fills 328.Fa page 329with zeroes. 330.Sh INTERNAL DATA STRUCTURE MANAGEMENT 331.nr nS 1 332.Ft pmap_t 333.Fn pmap_create "void" 334.Ft void 335.Fn pmap_reference "pmap_t pmap" 336.Ft void 337.Fn pmap_destroy "pmap_t pmap" 338.nr nS 0 339.Pp 340The 341.Fn pmap_create 342function creates an instance of the 343.Em pmap 344structure. 345.Pp 346The 347.Fn pmap_reference 348function increments the reference count on 349.Fa pmap . 350.Pp 351The 352.Fn pmap_destroy 353function decrements the reference count on physical map 354.Fa pmap 355and retires it from service if the count drops to zero, assuming 356it contains no valid mappings. 357.Sh OPTIONAL FUNCTIONS 358.nr nS 1 359.Ft vaddr_t 360.Fn pmap_steal_memory "vsize_t size" "vaddr_t *vstartp" "vaddr_t *vendp" 361.Ft vaddr_t 362.Fn pmap_growkernel "vaddr_t maxkvaddr" 363.Ft void 364.Fn pmap_update "pmap_t pmap" 365.Ft void 366.Fn pmap_collect "pmap_t pmap" 367.Ft void 368.Fn pmap_populate "pmap_t pmap" "vaddr_t va" 369.Ft void 370.Fn pmap_virtual_space "vaddr_t *vstartp" "vaddr_t *vendp" 371.nr nS 0 372.Pp 373Wired memory allocation before the virtual memory system is bootstrapped 374is accomplished by the 375.Fn pmap_steal_memory 376function. 377After that point, the kernel memory allocation routines should be used. 378.Pp 379The 380.Fn pmap_growkernel 381function can preallocate kernel page tables to a specified virtual address. 382.Pp 383The 384.Fn pmap_update 385function notifies the 386.Nm pmap 387module to force processing of all delayed actions for all pmaps. 388.Pp 389The 390.Fn pmap_populate 391function makes sure the resources necessary for mapping the specified 392virtual address 393.Fa va 394are allocated in the target physical map 395.Fa pmap . 396.Pp 397The 398.Fn pmap_collect 399function informs the 400.Nm pmap 401module that the given 402.Em pmap 403is not expected to be used for some time, giving the 404.Nm pmap 405module a chance to prioritize. 406The initial bounds of the kernel virtual address space are returned by 407.Fn pmap_virtual_space . 408.Sh SEE ALSO 409.Xr fork 2 , 410.Xr uvm_init 9 411.Sh HISTORY 412The 413.Bx 4.4 414.Nm pmap 415module is based on Mach 3.0. 416The introduction of UVM 417left the 418.Nm pmap 419interface unchanged for the most part. 420.Sh BUGS 421Ifdefs must be documented. 422.Pp 423.Fn pmap_update 424should be mandatory. 425