xref: /xnu-11215/osfmk/man/device_map.html (revision 186b8fce)

<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>.