1.\" 2.\" Copyright (c) 2003 Bruce M Simpson <bms@spc.org> 3.\" Copyright (c) 2014 The FreeBSD Foundation 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 AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, 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.\" $FreeBSD$ 28.\" 29.Dd December 16, 2018 30.Dt PMAP_ENTER 9 31.Os 32.Sh NAME 33.Nm pmap_enter 34.Nd insert a virtual page into a physical map 35.Sh SYNOPSIS 36.In sys/param.h 37.In vm/vm.h 38.In vm/pmap.h 39.Ft int 40.Fo pmap_enter 41.Fa "pmap_t pmap" "vm_offset_t va" "vm_page_t m" "vm_prot_t prot" 42.Fa "u_int flags" "int8_t psind" 43.Fc 44.Sh DESCRIPTION 45The 46.Fn pmap_enter 47function creates a mapping in the physical map 48.Fa pmap 49from the virtual address 50.Fa va 51to the physical page 52.Fa m 53with the protection 54.Fa prot . 55Any previous mapping at the virtual address 56.Fa va 57is destroyed. 58.Pp 59The 60.Fa flags 61argument may have the following values: 62.Bl -tag -width ".Dv PMAP_ENTER_NOSLEEP" 63.It Dv VM_PROT_READ 64A read access to the given virtual address triggered the call. 65.It Dv VM_PROT_WRITE 66A write access to the given virtual address triggered the call. 67.It Dv VM_PROT_EXECUTE 68An execute access to the given virtual address triggered the call. 69.It Dv PMAP_ENTER_WIRED 70The mapping should be marked as wired. 71.It Dv PMAP_ENTER_NOSLEEP 72This function may not sleep during creation of the mapping. 73If the mapping cannot be created without sleeping, an appropriate 74Mach VM error is returned. 75.El 76If the 77.Dv PMAP_ENTER_NOSLEEP 78flag is not specified, this function must create the requested mapping 79before returning. 80It may not fail. 81In order to create the requested mapping, this function may destroy 82any non-wired mapping in any pmap. 83.Pp 84The 85.Fa psind 86parameter specifies the page size that should be used by the mapping. 87The supported page sizes are described by the global array 88.Dv pagesizes[] . 89The desired page size is specified by passing the index of the array 90element that equals the desired page size. 91.Pp 92When the 93.Fn pmap_enter 94function destroys or updates a managed mapping, including an existing 95mapping at virtual address 96.Fa va , 97it updates the 98.Ft vm_page 99structure corresponding to the previously mapped physical page. 100If the physical page was accessed through the managed mapping, 101then the 102.Ft vm_page 103structure's 104.Dv PGA_REFERENCED 105aflag is set. 106If the physical page was modified through the managed mapping, then the 107.Fn vm_page_dirty 108function is called on the 109.Ft vm_page 110structure. 111.Pp 112The 113.Dv PGA_WRITEABLE 114aflag must be set for the page 115.Fa m 116if the new mapping is managed and writeable. 117It is advised to clear 118.Dv PGA_WRITEABLE 119for destroyed mappings if the implementation can ensure 120that no other writeable managed mappings for the previously 121mapped pages exist. 122.Pp 123If the request modifies an existing mapping to use a different physical 124page, an implementation of 125.Nm 126must invalidate the previous mapping before installing the new one. 127This ensures that all threads sharing the pmap keep a consistent 128view of the mapping, which is necessary for the correct handling 129of CoW (copy on write) faults. 130.Pp 131If the page 132.Fa m 133is managed, the page must be busied by the caller 134or the owning object must be locked. 135In the later case, the 136.Dv PMAP_ENTER_NOSLEEP 137must be specified by the caller. 138.Pp 139The 140.Fn pmap_enter 141function must handle the multiprocessor TLB consistency for the 142given address. 143.Sh NOTES 144On arm and i386 architectures the existing implementation 145of the 146.Nm 147function is incomplete, only value 0 for 148.Fa psind 149is supported. 150Other supported architectures, except amd64, have 151.Dv pagesizes[] 152array of size 1. 153.Sh RETURN VALUES 154If successful, the 155.Fn pmap_enter 156function returns 157.Er KERN_SUCCESS . 158If the 159.Dv PMAP_ENTER_NOSLEEP 160flag was specified and the resources required for the mapping cannot 161be acquired without sleeping, 162.Dv KERN_RESOURCE_SHORTAGE 163is returned. 164.Sh SEE ALSO 165.Xr pmap 9 166.Sh AUTHORS 167This manual page was first written by 168.An Bruce M Simpson Aq Mt bms@spc.org 169and then rewritten by 170.An Alan Cox Aq Mt alc@FreeBSD.org 171and 172.An Konstantin Belousov Aq Mt kib@FreeBSD.org . 173