xnu-4903.221.2.tar.gz

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

<h2>device_map</h2>
<hr>
<p>
<strong>Function</strong> - Establish the specified device's memory manager.
<h3>SYNOPSIS</h3>
<pre>
<strong>#include&lt device/device.h&gt</strong>

<strong>kern_return_t   device_map</strong>
                <strong>(mach_port_t</strong>                             <var>device</var>,
                 <strong>vm_prot_t</strong>                                 <var>prot</var>,
                 <strong>vm_offset_t</strong>                             <var>offset</var>,
                 <strong>vm_size_t</strong>                                 <var>size</var>,
                 <strong>mach_port_t</strong>                          <var>mem_obj_t</var>,
                 <strong>boolean_t</strong>                                <var>unmap</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>device</var> 
<dd>
[in device send right]
A device port to the device to be mapped.
<p>
<dt> <var>prot</var> 
<dd>
[in scalar]
Protection for the device memory.
<p>
<dt> <var>offset</var> 
<dd>
[in scalar]
15~Offset in memory object.
<p>
<dt> <var>size</var> 
<dd>
[in scalar]
The size of the device memory object.
<p>
<dt> <var>pager</var> 
<dd>
[out memory-object send right]
The returned memory 
object representative port to a memory manager that represents the
device.
<p>
<dt> <var>unmap</var>
<dd>
Unused.
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>device_map</strong> function establishes a memory manager that presents a
memory object representing a device.  The resulting port is suitable
for use as the
memory manager port in a <strong>vm_map</strong> call.  This call is device dependent.
<h3>NOTES</h3>
<p>
Port rights are maintained as follows:
<ul>
<li>
Memory object port: the 
device memory manager has all rights.
<li>
Memory cache control port: the device memory manager has only send rights.
</ul>
<p>
Regardless of how the object is created, the control port is created by 
the kernel and passed through the memory management interface.
<p>
If the device port used is restricted to use by a single identity,
the generated
representative port will be likewise restricted.
<h3>CAUTIONS</h3>
<p>
The device memory manager assumes that access to its memory objects will not 
be propagated to more that one host, and therefore provides no consistency
guarantees beyond those made by the kernel.
<p>
In the event that more than one host attempts to use a device
memory object, the 
device memory manager will only record the last set of port names.  Currently, 
the device memory manager assumes that its clients adhere to
the initialization 
and termination protocols in the memory management interface; otherwise, port 
rights or out-of-line memory from erroneous messages may be allowed to
accumulate.
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>D_DEVICE_DOWN</strong>
<dd>
Device has been shut down
<p>
<dt> <strong>D_NO_SUCH_DEVICE</strong>
<dd>
No device with that name, or the device is not operational.
<p>
<dt> <strong>D_READ_ONLY</strong>
<dd>
Data cannot be written to this device.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="vm_map.html"><strong>vm_map</strong></a>.