osfmk/man/memory_object_lock_request.html

   1 <h2>memory_object_lock_request</h2>
   2 <hr>
   3 <p>
   4 <strong>Function</strong> - Restrict access to memory object data.
   5 <h3>SYNOPSIS</h3>
   6 <pre>
   7 <strong>kern_return_t   memory_object_lock_request</strong>
   8                 <strong>(memory_object_control_t</strong>         <var>memory_control</var>,
   9                  <strong>vm_offset_t</strong>                             <var>offset</var>,
  10                  <strong>vm_size_t</strong>                                 <var>size</var>,
  11                  <strong>memory_object_return_t</strong>           <var>should_return</var>,
  12                  <strong>boolean_t</strong>                         <var>should_flush</var>,
  13                  <strong>vm_prot_t</strong>                           <var>lock_value</var>,
  14                  <strong>mach_port_t</strong>                         <var>reply_port</var><strong>);</strong>
  15 </pre>
  16 <h3>PARAMETERS</h3>
  17 <dl>
  18 <p>
  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> call.
  25 <p>
  26 <dt> <var>offset</var>
  27 <dd>
  28 [in scalar]
  29 The offset within the memory object, in bytes.
  30 <p>
  31 <dt> <var>size</var>
  32 <dd>
  33 [in scalar]
  34 The number of bytes of data (starting at <var>offset</var>) to be
  35 affected.  The number must convert to an integral number of memory object
  36 pages.
  37 <p>
  38 <dt> <var>should_return</var>
  39 <dd>
  40 [in scalar]
  41 Clean indicator.  Values are:
  42 <dl>
  43 <p>
  44 <dt> <strong>MEMORY_OBJECT_RETURN_NONE</strong>
  45 <dd>
  46 Don't return any pages.  If <var>should_flush</var> is <strong>TRUE</strong>, pages will
  47 be discarded.
  48 <p>
  49 <dt> <strong>MEMORY_OBJECT_RETURN_DIRTY</strong>
  50 <dd>
  51 Return only dirty (modified) pages.  If <var>should_flush</var> is <strong>TRUE</strong>,
  52 precious pages will be discarded; otherwise, the kernel
  53 maintains responsibility for precious pages.
  54 <p>
  55 <dt> <strong>MEMORY_OBJECT_RETURN_ALL</strong>
  56 <dd>
  57 Both dirty and precious pages are returned.  If <var>should_flush</var> is
  58 <strong>FALSE</strong>, the kernel maintains responsibility for the precious
  59 pages.
  60 <p>
  61 <dt> <strong>MEMORY_OBJECT_RETURN_ANYTHING</strong>
  62 <dd>
  63 Any resident pages are returned.   If <var>should_flush</var> is <strong>TRUE</strong>,
  64 precious pages will be discarded; otherwise, the kernel
  65 maintains responsibility for precious pages.
  66 </dl>
  67 <p>
  68 <dt> <var>should_flush</var>
  69 <dd>
  70 [in scalar]
  71 Flush indicator.  If true, the kernel discards all pages within
  72 the range.
  73 <p>
  74 <dt> <var>lock_value</var>
  75 <dd>
  76 [in scalar]
  77 One or more forms of access <var>not</var> permitted for the specified
  78 data.  Valid values are:
  79 <dl>
  80 <p>
  81 <dt> <strong>VM_PROT_NO_CHANGE</strong>
  82 <dd>
  83 Do not change the protection of any pages.
  84 <p>
  85 <dt> <strong>VM_PROT_NONE</strong>
  86 <dd>
  87 Prohibits no access (that is, all forms of access are permitted).
  88 <p>
  89 <dt> <strong>VM_PROT_READ</strong>
  90 <dd>
  91 Prohibits read access.
  92 <p>
  93 <dt> <strong>VM_PROT_WRITE</strong>
  94 <dd>
  95 Prohibits write access.
  96 <p>
  97 <dt> <strong>VM_PROT_EXECUTE</strong>
  98 <dd>
  99 Prohibits execute access.
 100 <p>
 101 <dt> <strong>VM_PROT_ALL</strong>
 102 <dd>
 103 Prohibits all forms of access.
 104 </dl>
 105 <p>
 106 <dt> <var>reply_port</var>
 107 <dd>
 108 [in reply receive (to be converted to send) right]
 109 The response port to
 110 be used by the kernel on a call to <strong>memory_object_lock_completed</strong>,
 111 or <strong>MACH_PORT_NULL</strong> if no response is required.
 112 </dl>
 113 <h3>DESCRIPTION</h3>
 114 <p>
 115 The <strong>memory_object_lock_request</strong> function allows the memory manager to
 116 make the following requests of the kernel:
 117 <ul>
 118 <li>
 119 Clean the pages within the specified range by writing back all changed (that
 120 is, dirty) and precious pages.  The kernel uses the
 121 <strong>memory_object_data_return</strong> call to write back the data.
 122 The <var>should_return</var> parameter must be set to
 123 non-zero.
 124      <p>
 125 <li>
 126 Flush all cached data within the specified range.  The kernel invalidates the
 127 range of data and revokes all uses of that data.  The <var>should_flush</var>
 128 parameter must be set to true.
 129      <p>
 130 <li>
 131 Alter access restrictions specified in the <strong>memory_object_data_supply</strong>
 132 call
 133 or a previous <strong>memory_object_lock_request</strong> call.  The
 134 <var>lock_value</var> parameter
 135 must specify the new access restrictions.  Note that this parameter can be
 136 used to unlock previously locked data.
 137 </ul>
 138 <p>
 139 Once the kernel performs all of the actions requested by this
 140 call, it issues a
 141 <strong>memory_object_lock_completed</strong> call using the <var>reply_to</var> port.
 142 <h3>NOTES</h3>
 143 <p>
 144 The <strong>memory_object_lock_request</strong> call affects only data
 145 that is cached at the
 146 time of the call.  Access restrictions cannot be applied to pages
 147 for which data
 148 has not been provided.
 149 <p>
 150 When a running thread requires an access that is currently prohibited,
 151 the kernel
 152 issues a <strong>memory_object_data_unlock</strong> call specifying
 153 the access required.  The
 154 memory manager can then use <strong>memory_object_lock_request</strong> to relax its
 155 access restrictions on the data.
 156 <p>
 157 To indicate that an unlock request is invalid (that is, requires
 158 permission that can
 159 never be granted), the memory manager must first flush the page.  When the
 160 kernel requests the data again with the higher permission, the
 161 memory manager can
 162 indicate the error by responding with a call to
 163 <strong>memory_object_data_error</strong>.
 164 <h3>RETURN VALUES</h3>
 165 <p>
 166 Only generic errors apply.
 167 <h3>RELATED INFORMATION</h3>
 168 <p>
 169 Functions:
 170 <a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
 171 <a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock</strong></a>,
 172 <a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>.
 173