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