xnu-2422.1.72.tar.gz

[apple/xnu.git] / osfmk / man / vm_map.html

<h2>vm_map</h2>
<hr>
<p>
<strong>Function</strong> - Map the specified memory object to a region of virtual memory.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   vm_map</strong>
                <strong>(vm_task_t</strong>                          <var>target_task</var>,
                 <strong>vm_address_t</strong>                           <var>address</var>,
                 <strong>vm_size_t</strong>                                 <var>size</var>,
                 <strong>vm_address_t</strong>                              <var>mask</var>,
                 <strong>boolean_t</strong>                             <var>anywhere</var>,
                 <strong>memory_object_t</strong>                  <var>memory_object</var>,
                 <strong>vm_offset_t</strong>                             <var>offset</var>,
                 <strong>boolean_t</strong>                                 <var>copy</var>,
                 <strong>vm_prot_t</strong>                       <var>cur_protection</var>,
                 <strong>vm_prot_t</strong>                       <var>max_protection</var>,
                 <strong>vm_inherit_t</strong>                       <var>inheritance</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>target_task</var> 
<dd>
[in task send right]
The port for the task in whose address space the 
memory object is to be mapped.
<p>
<dt> <var>address</var> 
<dd>
[pointer to in/out scalar]
The starting address for the mapped object. 
The mapped object will start at the beginning of the page containing 
<var>address</var>.  If there is not enough room following the address, the kernel 
does not map the object.  The kernel returns the starting address
actually used for the mapped object.
<p>
<dt> <var>size</var> 
<dd>
[in scalar]
The number of bytes to allocate for the object.  The kernel 
rounds this number up to an integral number of virtual pages.
<p>
<dt> <var>mask</var> 
<dd>
[in scalar]
Alignment restrictions for starting address.  Bits turned on in 
the mask will not be turned on in the starting address.
<p>
<dt> <var>anywhere</var> 
<dd>
[in scalar]
Placement indicator.  The valid values are:
<dl>
<p>
<dt> <strong>TRUE</strong>
<dd>
The kernel allocates the region in the next unused space that 
is sufficient within the address space.  The kernel returns the 
starting address actually used in <var>address</var>.
<p>
<dt> <strong>FALSE</strong>
<dd>
The kernel allocates the region starting at <var>address</var> unless that 
space is already allocated.
</dl>
<p>
<dt> <var>memory_object</var> 
<dd>
[in memory-object send right]
The port naming the 
memory object.  If <strong>MEMORY_OBJECT_NULL</strong> is
specified, the kernel allocates zero-filled memory, as with <strong>vm_allocate</strong>.
<p>
<dt> <var>offset</var> 
<dd>
[in scalar]
An offset within the memory object, in bytes.  The kernel 
maps <var>address</var> to the specified offset.
<p>
<dt> <var>copy</var> 
<dd>
[in scalar]
Copy indicator.  If true, the kernel copies the region of the 
memory object to the specified task's address space.  If false, the region 
is directly mapped.
<p>
<dt> <var>cur_protection</var> 
<dd>
[in scalar]
The initial current protection for the region.  Valid values are 
obtained by or'ing together the following values:
<dl>
<p>
<dt> <strong>VM_PROT_READ</strong>
<dd>
Allows read access.
<p>
<dt> <strong>VM_PROT_WRITE</strong>
<dd>
Allows write access.
<p>
<dt> <strong>VM_PROT_EXECUTE</strong>
<dd>
Allows execute access.
</dl>
<p>
<dt> <var>max_protection</var> 
<dd>
[in scalar]
The maximum protection for the region.  Values are the same 
as for <var>cur_protection</var>.
<p>
<dt> <var>inheritance</var> 
<dd>
[in scalar]
The initial inheritance attribute for the region.  Valid values 
are:
<dl>
<p>
<dt> <strong>VM_INHERIT_SHARE</strong>
<dd>
Allows child tasks to share the region.
<p>
<dt> <strong>VM_INHERIT_COPY</strong>
<dd>
Gives child tasks a copy of the region.
<p>
<dt> <strong>VM_INHERIT_NONE</strong>
<dd>
Provides no access to the region for child tasks.
</dl>
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>vm_map</strong> function maps a portion of the specified
memory object into the 
virtual address space belonging to <var>target_task</var>.  The target task
can be the calling 
task or another task, identified by its task kernel port.
<p>
The portion of the memory object mapped is determined by <var>offset</var> 
and <var>size</var>.  The 
kernel maps <var>address</var> to the offset, so that an access to the memory
starts at the offset in the object.
<p>
The <var>mask</var> parameter specifies additional alignment restrictions on 
the kernel's selection of the starting address.  Uses for this mask include:
<ul>
<li>
Forcing the memory address alignment for a mapping to be the same as the 
alignment within the memory object.
<li>
Quickly finding the beginning of an allocated region by performing bit
arithmetic on an address known to be in the region.
<li>
Emulating a larger virtual page size.
</ul>
<p>
The <var>cur_protection</var>, <var>max_protection</var>, and <var>inheritance</var>
parameters set the
protection and inheritance attributes for the mapped object.
As a rule, at least the
maximum protection should be specified so that a server can make
a restricted (for 
example, read-only) mapping in a client atomically.  The current
protection and 
inheritance parameters are provided for convenience so that the
caller does not 
have to call <strong>vm_inherit</strong> and <strong>vm_protect</strong> separately.
<p>
The same memory object can be mapped more than once and by more than one 
task.  If an object is mapped by multiple tasks, the kernel maintains
consistency 
for all the mappings if they use the same page alignment for <var>offset</var> 
and are on 
the same host.  In this case, the virtual memory to which the
object is mapped is 
shared by all the tasks.  Changes made by one task in its address space are
visible to all the other tasks.
The call will not return until the
memory object is ready for 
use.
<h3>NOTES</h3>
<p>
<strong>vm_map</strong> allocates a region in a task's address space
and maps the specified 
memory object to this region.  <strong>vm_allocate</strong> allocates
a zero-filled temporary
region in a task's address space.
<p>
Before a memory object can be mapped, a port naming it must be acquired from 
the memory manager serving it.
<p>
This interface is machine word length specific because of the virtual address
parameter.
<h3>CAUTIONS</h3>
<p>
Do not attempt to map a memory object unless it has been provided by a
memory manager that implements the memory object interface. 
If another type of port 
is specified, a thread that accesses the mapped virtual memory may become
permanently hung or may receive a memory exception.
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>KERN_NO_SPACE</strong>
<dd>
There is not enough space in the task's address space to allocate the 
new region for the memory object.
<p>
<dt> <strong>KERN_PROTECTION_FAILURE</strong>
<dd>
<var>max_protection</var> or <var>cur_protection</var> exceeds 
that permitted by <var>memory_object</var>.
<p>
<dt> <strong>KERN_INVALID_OBJECT</strong>
<dd>
The memory manager failed to map the memory object.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="vm_allocate.html"><strong>vm_allocate</strong></a>,
<a href="vm_remap.html"><strong>vm_remap</strong></a>.