share/man/man9/pmap_enter.9

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