1<h2>device_map</h2>
2<hr>
3<p>
4<strong>Function</strong> - Establish the specified device's memory manager.
5<h3>SYNOPSIS</h3>
6<pre>
7<strong>#include&lt device/device.h&gt</strong>
8
9<strong>kern_return_t   device_map</strong>
10                <strong>(mach_port_t</strong>                             <var>device</var>,
11                 <strong>vm_prot_t</strong>                                 <var>prot</var>,
12                 <strong>vm_offset_t</strong>                             <var>offset</var>,
13                 <strong>vm_size_t</strong>                                 <var>size</var>,
14                 <strong>mach_port_t</strong>                          <var>mem_obj_t</var>,
15                 <strong>boolean_t</strong>                                <var>unmap</var><strong>);</strong>
16</pre>
17<h3>PARAMETERS</h3>
18<dl>
19<p>
20<dt> <var>device</var> 
21<dd>
22[in device send right]
23A device port to the device to be mapped.
24<p>
25<dt> <var>prot</var> 
26<dd>
27[in scalar]
28Protection for the device memory.
29<p>
30<dt> <var>offset</var> 
31<dd>
32[in scalar]
3315~Offset in memory object.
34<p>
35<dt> <var>size</var> 
36<dd>
37[in scalar]
38The size of the device memory object.
39<p>
40<dt> <var>pager</var> 
41<dd>
42[out memory-object send right]
43The returned memory 
44object representative port to a memory manager that represents the
45device.
46<p>
47<dt> <var>unmap</var>
48<dd>
49Unused.
50</dl>
51<h3>DESCRIPTION</h3>
52<p>
53The <strong>device_map</strong> function establishes a memory manager that presents a
54memory object representing a device.  The resulting port is suitable
55for use as the
56memory manager port in a <strong>vm_map</strong> call.  This call is device dependent.
57<h3>NOTES</h3>
58<p>
59Port rights are maintained as follows:
60<ul>
61<li>
62Memory object port: the 
63device memory manager has all rights.
64<li>
65Memory cache control port: the device memory manager has only send rights.
66</ul>
67<p>
68Regardless of how the object is created, the control port is created by 
69the kernel and passed through the memory management interface.
70<p>
71If the device port used is restricted to use by a single identity,
72the generated
73representative port will be likewise restricted.
74<h3>CAUTIONS</h3>
75<p>
76The device memory manager assumes that access to its memory objects will not 
77be propagated to more that one host, and therefore provides no consistency
78guarantees beyond those made by the kernel.
79<p>
80In the event that more than one host attempts to use a device
81memory object, the 
82device memory manager will only record the last set of port names.  Currently, 
83the device memory manager assumes that its clients adhere to
84the initialization 
85and termination protocols in the memory management interface; otherwise, port 
86rights or out-of-line memory from erroneous messages may be allowed to
87accumulate.
88<h3>RETURN VALUES</h3>
89<dl>
90<p>
91<dt> <strong>D_DEVICE_DOWN</strong>
92<dd>
93Device has been shut down
94<p>
95<dt> <strong>D_NO_SUCH_DEVICE</strong>
96<dd>
97No device with that name, or the device is not operational.
98<p>
99<dt> <strong>D_READ_ONLY</strong>
100<dd>
101Data cannot be written to this device.
102</dl>
103<h3>RELATED INFORMATION</h3>
104<p>
105Functions:
106<a href="vm_map.html"><strong>vm_map</strong></a>.
107