osfmk/man/vm_map.html

   1 <h2>vm_map</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Map the specified memory object to a region of virtual memory.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   vm_map</strong>
   8                 <strong>(vm_task_t</strong>                          <var>target_task</var>,
   9                  <strong>vm_address_t</strong>                           <var>address</var>,
  10                  <strong>vm_size_t</strong>                                 <var>size</var>,
  11                  <strong>vm_address_t</strong>                              <var>mask</var>,
  12                  <strong>boolean_t</strong>                             <var>anywhere</var>,
  13                  <strong>memory_object_t</strong>                  <var>memory_object</var>,
  14                  <strong>vm_offset_t</strong>                             <var>offset</var>,
  15                  <strong>boolean_t</strong>                                 <var>copy</var>,
  16                  <strong>vm_prot_t</strong>                       <var>cur_protection</var>,
  17                  <strong>vm_prot_t</strong>                       <var>max_protection</var>,
  18                  <strong>vm_inherit_t</strong>                       <var>inheritance</var><strong>);</strong>
  19 </pre>
  20 <h3>PARAMETERS</h3>
  21 <dl>
  22 <p>
  23 <dt> <var>target_task</var>
  24 <dd>
  25 [in task send right]
  26 The port for the task in whose address space the
  27 memory object is to be mapped.
  28 <p>
  29 <dt> <var>address</var>
  30 <dd>
  31 [pointer to in/out scalar]
  32 The starting address for the mapped object.
  33 The mapped object will start at the beginning of the page containing
  34 <var>address</var>.  If there is not enough room following the address, the kernel
  35 does not map the object.  The kernel returns the starting address
  36 actually used for the mapped object.
  37 <p>
  38 <dt> <var>size</var>
  39 <dd>
  40 [in scalar]
  41 The number of bytes to allocate for the object.  The kernel
  42 rounds this number up to an integral number of virtual pages.
  43 <p>
  44 <dt> <var>mask</var>
  45 <dd>
  46 [in scalar]
  47 Alignment restrictions for starting address.  Bits turned on in
  48 the mask will not be turned on in the starting address.
  49 <p>
  50 <dt> <var>anywhere</var>
  51 <dd>
  52 [in scalar]
  53 Placement indicator.  The valid values are:
  54 <dl>
  55 <p>
  56 <dt> <strong>TRUE</strong>
  57 <dd>
  58 The kernel allocates the region in the next unused space that
  59 is sufficient within the address space.  The kernel returns the
  60 starting address actually used in <var>address</var>.
  61 <p>
  62 <dt> <strong>FALSE</strong>
  63 <dd>
  64 The kernel allocates the region starting at <var>address</var> unless that
  65 space is already allocated.
  66 </dl>
  67 <p>
  68 <dt> <var>memory_object</var>
  69 <dd>
  70 [in memory-object send right]
  71 The port naming the
  72 memory object.  If <strong>MEMORY_OBJECT_NULL</strong> is
  73 specified, the kernel allocates zero-filled memory, as with <strong>vm_allocate</strong>.
  74 <p>
  75 <dt> <var>offset</var>
  76 <dd>
  77 [in scalar]
  78 An offset within the memory object, in bytes.  The kernel
  79 maps <var>address</var> to the specified offset.
  80 <p>
  81 <dt> <var>copy</var>
  82 <dd>
  83 [in scalar]
  84 Copy indicator.  If true, the kernel copies the region of the
  85 memory object to the specified task's address space.  If false, the region
  86 is directly mapped.
  87 <p>
  88 <dt> <var>cur_protection</var>
  89 <dd>
  90 [in scalar]
  91 The initial current protection for the region.  Valid values are
  92 obtained by or'ing together the following values:
  93 <dl>
  94 <p>
  95 <dt> <strong>VM_PROT_READ</strong>
  96 <dd>
  97 Allows read access.
  98 <p>
  99 <dt> <strong>VM_PROT_WRITE</strong>
 100 <dd>
 101 Allows write access.
 102 <p>
 103 <dt> <strong>VM_PROT_EXECUTE</strong>
 104 <dd>
 105 Allows execute access.
 106 </dl>
 107 <p>
 108 <dt> <var>max_protection</var>
 109 <dd>
 110 [in scalar]
 111 The maximum protection for the region.  Values are the same
 112 as for <var>cur_protection</var>.
 113 <p>
 114 <dt> <var>inheritance</var>
 115 <dd>
 116 [in scalar]
 117 The initial inheritance attribute for the region.  Valid values
 118 are:
 119 <dl>
 120 <p>
 121 <dt> <strong>VM_INHERIT_SHARE</strong>
 122 <dd>
 123 Allows child tasks to share the region.
 124 <p>
 125 <dt> <strong>VM_INHERIT_COPY</strong>
 126 <dd>
 127 Gives child tasks a copy of the region.
 128 <p>
 129 <dt> <strong>VM_INHERIT_NONE</strong>
 130 <dd>
 131 Provides no access to the region for child tasks.
 132 </dl>
 133 </dl>
 134 <h3>DESCRIPTION</h3>
 135 <p>
 136 The <strong>vm_map</strong> function maps a portion of the specified
 137 memory object into the
 138 virtual address space belonging to <var>target_task</var>.  The target task
 139 can be the calling
 140 task or another task, identified by its task kernel port.
 141 <p>
 142 The portion of the memory object mapped is determined by <var>offset</var>
 143 and <var>size</var>.  The
 144 kernel maps <var>address</var> to the offset, so that an access to the memory
 145 starts at the offset in the object.
 146 <p>
 147 The <var>mask</var> parameter specifies additional alignment restrictions on
 148 the kernel's selection of the starting address.  Uses for this mask include:
 149 <ul>
 150 <li>
 151 Forcing the memory address alignment for a mapping to be the same as the
 152 alignment within the memory object.
 153 <li>
 154 Quickly finding the beginning of an allocated region by performing bit
 155 arithmetic on an address known to be in the region.
 156 <li>
 157 Emulating a larger virtual page size.
 158 </ul>
 159 <p>
 160 The <var>cur_protection</var>, <var>max_protection</var>, and <var>inheritance</var>
 161 parameters set the
 162 protection and inheritance attributes for the mapped object.
 163 As a rule, at least the
 164 maximum protection should be specified so that a server can make
 165 a restricted (for
 166 example, read-only) mapping in a client atomically.  The current
 167 protection and
 168 inheritance parameters are provided for convenience so that the
 169 caller does not
 170 have to call <strong>vm_inherit</strong> and <strong>vm_protect</strong> separately.
 171 <p>
 172 The same memory object can be mapped more than once and by more than one
 173 task.  If an object is mapped by multiple tasks, the kernel maintains
 174 consistency
 175 for all the mappings if they use the same page alignment for <var>offset</var>
 176 and are on
 177 the same host.  In this case, the virtual memory to which the
 178 object is mapped is
 179 shared by all the tasks.  Changes made by one task in its address space are
 180 visible to all the other tasks.
 181 The call will not return until the
 182 memory object is ready for
 183 use.
 184 <h3>NOTES</h3>
 185 <p>
 186 <strong>vm_map</strong> allocates a region in a task's address space
 187 and maps the specified
 188 memory object to this region.  <strong>vm_allocate</strong> allocates
 189 a zero-filled temporary
 190 region in a task's address space.
 191 <p>
 192 Before a memory object can be mapped, a port naming it must be acquired from
 193 the memory manager serving it.
 194 <p>
 195 This interface is machine word length specific because of the virtual address
 196 parameter.
 197 <h3>CAUTIONS</h3>
 198 <p>
 199 Do not attempt to map a memory object unless it has been provided by a
 200 memory manager that implements the memory object interface.
 201 If another type of port
 202 is specified, a thread that accesses the mapped virtual memory may become
 203 permanently hung or may receive a memory exception.
 204 <h3>RETURN VALUES</h3>
 205 <dl>
 206 <p>
 207 <dt> <strong>KERN_NO_SPACE</strong>
 208 <dd>
 209 There is not enough space in the task's address space to allocate the
 210 new region for the memory object.
 211 <p>
 212 <dt> <strong>KERN_PROTECTION_FAILURE</strong>
 213 <dd>
 214 <var>max_protection</var> or <var>cur_protection</var> exceeds
 215 that permitted by <var>memory_object</var>.
 216 <p>
 217 <dt> <strong>KERN_INVALID_OBJECT</strong>
 218 <dd>
 219 The memory manager failed to map the memory object.
 220 </dl>
 221 <h3>RELATED INFORMATION</h3>
 222 <p>
 223 Functions:
 224 <a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
 225 <a href="vm_remap.html"><strong>vm_remap</strong></a>.