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 February 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 page 124.Fa m 125is managed, the page must be busied by the caller 126or the owning object must be locked. 127In the later case, the 128.Dv PMAP_ENTER_NOSLEEP 129must be specified by the caller. 130.Pp 131The 132.Fn pmap_enter 133function must handle the multiprocessor TLB consistency for the 134given address. 135.Sh NOTES 136On arm and i386 architectures the existing implementation 137of the 138.Nm 139function is incomplete, only value 0 for 140.Fa psind 141is supported. 142Other supported architectures, except amd64, have 143.Dv pagesizes[] 144array of size 1. 145.Sh RETURN VALUES 146If successful, the 147.Fn pmap_enter 148function returns 149.Er KERN_SUCCESS . 150If the 151.Dv PMAP_ENTER_NOSLEEP 152flag was specified and the resources required for the mapping cannot 153be acquired without sleeping, 154.Dv KERN_RESOURCE_SHORTAGE 155is returned. 156.Sh SEE ALSO 157.Xr pmap 9 158.Sh AUTHORS 159This manual page was first written by 160.An Bruce M Simpson Aq Mt bms@spc.org 161and then rewritten by 162.An Alan Cox Aq Mt alc@FreeBSD.org 163and 164.An Konstantin Belousov Aq Mt kib@FreeBSD.org . 165