osfmk/man/device_map.html

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