osfmk/man/memory_object_data_supply.html

   1 <h2>memory_object_data_supply</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Provide kernel with data previously requested by the kernel's Memory Management facility.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   memory_object_data_supply</strong>
   8                 <strong>(mem_object_control_port_t</strong>       <var>memory_control</var>,
   9                  <strong>vm_offset_t</strong>                             <var>offset</var>,
  10                  <strong>pointer_t</strong>                                 <var>data</var>,
  11                  <strong>mach_msg_type_number_t</strong>              <var>data_count</var>,
  12                  <strong>boolean_t</strong>                           <var>deallocate</var>,
  13                  <strong>vm_prot_t</strong>                           <var>lock_value</var>,
  14                  <strong>boolean_t</strong>                             <var>precious</var>,
  15                  <strong>mach_port_t</strong>                         <var>reply_port</var><strong>);</strong>
  16 </pre>
  17 <h3>PARAMETERS</h3>
  18 <dl>
  19 <dt> <var>memory_control</var>
  20 <dd>
  21 [in memory-cache-control send right]
  22 The memory cache control port
  23 to be used by the memory manager for cache management requests.
  24 This port is provided by the kernel in a <strong>memory_object_init</strong>
  25      or <strong>memory_object_create</strong> call.
  26 <p>
  27 <p>
  28 <dt> <var>offset</var>
  29 <dd>
  30 [in scalar]
  31 The offset within the memory object, in bytes.
  32 <p>
  33 <p>
  34 <dt> <var>data</var>
  35 <dd>
  36 [pointer to page aligned in array of bytes]
  37 The address of the data
  38 being provided to the kernel.
  39 <p>
  40 <p>
  41 <dt> <var>data_count</var>
  42 <dd>
  43 [in scalar]
  44 The amount of data to be provided.  The number must be an
  45 integral number of memory object pages.
  46 <p>
  47 <p>
  48 <dt> <var>deallocate</var>
  49 <dd>
  50 [in scalar]
  51 If <strong>TRUE</strong>, the pages to be copied (starting at data) will be
  52 deallocated from the memory manager's address space as a result of
  53 being copied into the message, allowing the pages to be moved into the
  54 kernel instead of being physically copied.
  55 <p>
  56 <p>
  57 <dt> <var>lock_value</var>
  58 <dd>
  59 [in scalar]
  60 One or more forms of access <var>not</var> permitted for the specified
  61 data.  Valid values are:
  62 <dl>
  63 <p>
  64 <p>
  65 <dt> <strong>VM_PROT_NONE</strong>
  66 <dd>
  67 Prohibits no access (that is, all forms of access are permitted).
  68 <p>
  69 <p>
  70 <dt> <strong>VM_PROT_READ</strong>
  71 <dd>
  72 Prohibits read access.
  73 <p>
  74 <p>
  75 <dt> <strong>VM_PROT_WRITE</strong>
  76 <dd>
  77 Prohibits write access.
  78 <p>
  79 <p>
  80 <dt> <strong>VM_PROT_EXECUTE</strong>
  81 <dd>
  82 Prohibits execute access.
  83 <p>
  84 <p>
  85 <dt> <strong>VM_PROT_ALL</strong>
  86 <dd>
  87 Prohibits all forms of access.
  88 </dl>
  89 <p>
  90 <p>
  91 <dt> <var>precious</var>
  92 <dd>
  93 [in scalar]
  94 If <strong>TRUE</strong>, the pages being supplied are "precious," that is,
  95 the memory manager is not (necessarily) retaining its own copy.  These
  96 pages must be returned to the manager when evicted from memory,
  97 even if not modified.
  98 <p>
  99 <p>
 100 <dt> <var>reply_port</var>
 101 <dd>
 102 [in reply receive (to be converted to send) right]
 103 A port to which the
 104 kernel should send a <strong>memory_object_supply_completed</strong> to indicate
 105 the status of the accepted data.  <strong>MACH_PORT_NULL</strong> is allowed.  The
 106 reply message indicates which pages have been accepted.
 107 </dl>
 108 <h3>DESCRIPTION</h3>
 109 <p>
 110 The <strong>memory_object_data_supply</strong> function supplies the
 111 kernel with a range of
 112 data for the specified memory object.  A memory manager can only provide data
 113 that was requested by a <strong>memory_object_data_request</strong>
 114 call from the kernel.
 115 <h3>NOTES</h3>
 116 <p>
 117 The kernel accepts only integral numbers of pages.  It discards
 118 any partial pages
 119 without notification.
 120 <h3>CAUTIONS</h3>
 121 <p>
 122 A memory manager must be careful that it not attempt to provide data that has
 123 not been explicitly requested.  In particular, a memory manager
 124 must ensure that
 125 it does not provide writable data again before it receives back modifications
 126 from the kernel.  This may require that the memory manager remember which
 127 pages it has provided, or that it exercise other cache control functions (via
 128 <strong>memory_object_lock_request</strong>) before proceeding.  The kernel prohibits the
 129 overwriting of live data pages and will not accept pages it has not requested.
 130 <h3>RETURN VALUES</h3>
 131 <p>
 132 Only generic errors apply.
 133 <h3>RELATED INFORMATION</h3>
 134 <p>
 135 Functions:
 136 <a href="memory_object_data_error.html"><strong>memory_object_data_error</strong></a>,
 137 <a href="memory_object_data_request.html"><strong>memory_object_data_request</strong></a>,
 138 <a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
 139 <a href="memory_object_lock_request.html"><strong>memory_object_lock_request</strong></a>,
 140 <a href="MO_supply_completed.html"><strong>memory_object_supply_completed</strong></a>.