-<h2>memory_object_lock_request</h2>
\r<hr>
\r<p>
\r<strong>Function</strong> - Restrict access to memory object data.
\r<h3>SYNOPSIS</h3>
\r<pre>
\r<strong>kern_return_t memory_object_lock_request</strong>
\r <strong>(memory_object_control_t</strong> <var>memory_control</var>,
\r <strong>vm_offset_t</strong> <var>offset</var>,
\r <strong>vm_size_t</strong> <var>size</var>,
\r <strong>memory_object_return_t</strong> <var>should_return</var>,
\r <strong>boolean_t</strong> <var>should_flush</var>,
\r <strong>vm_prot_t</strong> <var>lock_value</var>,
\r <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong>
\r</pre>
\r<h3>PARAMETERS</h3>
\r<dl>
\r<p>
\r<dt> <var>memory_control</var>
\r<dd>
\r[in memory-cache-control send right]
\rThe memory cache control port
\rto be used by the memory manager for cache management requests.
\rThis port is provided by the kernel in a <strong>memory_object_init</strong> call.
\r<p>
\r<dt> <var>offset</var>
\r<dd>
\r[in scalar]
\rThe offset within the memory object, in bytes.
\r<p>
\r<dt> <var>size</var>
\r<dd>
\r[in scalar]
\rThe number of bytes of data (starting at <var>offset</var>) to be
\raffected. The number must convert to an integral number of memory object
\rpages.
\r<p>
\r<dt> <var>should_return</var>
\r<dd>
\r[in scalar]
\rClean indicator. Values are:
\r<dl>
\r<p>
\r<dt> <strong>MEMORY_OBJECT_RETURN_NONE</strong>
\r<dd>
\rDon't return any pages. If <var>should_flush</var> is <strong>TRUE</strong>, pages will
\rbe discarded.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_RETURN_DIRTY</strong>
\r<dd>
\rReturn only dirty (modified) pages. If <var>should_flush</var> is <strong>TRUE</strong>,
\rprecious pages will be discarded; otherwise, the kernel
\rmaintains responsibility for precious pages.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_RETURN_ALL</strong>
\r<dd>
\rBoth dirty and precious pages are returned. If <var>should_flush</var> is
\r<strong>FALSE</strong>, the kernel maintains responsibility for the precious
\rpages.
\r<p>
\r<dt> <strong>MEMORY_OBJECT_RETURN_ANYTHING</strong>
\r<dd>
\rAny resident pages are returned. If <var>should_flush</var> is <strong>TRUE</strong>,
\rprecious pages will be discarded; otherwise, the kernel
\rmaintains responsibility for precious pages.
\r</dl>
\r<p>
\r<dt> <var>should_flush</var>
\r<dd>
\r[in scalar]
\rFlush indicator. If true, the kernel discards all pages within
\rthe range.
\r<p>
\r<dt> <var>lock_value</var>
\r<dd>
\r[in scalar]
\rOne or more forms of access <var>not</var> permitted for the specified
\rdata. Valid values are:
\r<dl>
\r<p>
\r<dt> <strong>VM_PROT_NO_CHANGE</strong>
\r<dd>
\rDo not change the protection of any pages.
\r<p>
\r<dt> <strong>VM_PROT_NONE</strong>
\r<dd>
\rProhibits no access (that is, all forms of access are permitted).
\r<p>
\r<dt> <strong>VM_PROT_READ</strong>
\r<dd>
\rProhibits read access.
\r<p>
\r<dt> <strong>VM_PROT_WRITE</strong>
\r<dd>
\rProhibits write access.
\r<p>
\r<dt> <strong>VM_PROT_EXECUTE</strong>
\r<dd>
\rProhibits execute access.
\r<p>
\r<dt> <strong>VM_PROT_ALL</strong>
\r<dd>
\rProhibits all forms of access.
\r</dl>
\r<p>
\r<dt> <var>reply_port</var>
\r<dd>
\r[in reply receive (to be converted to send) right]
\rThe response port to
\rbe used by the kernel on a call to <strong>memory_object_lock_completed</strong>,
\ror <strong>MACH_PORT_NULL</strong> if no response is required.
\r</dl>
\r<h3>DESCRIPTION</h3>
\r<p>
\rThe <strong>memory_object_lock_request</strong> function allows the memory manager to
\rmake the following requests of the kernel:
\r<ul>
\r<li>
\rClean the pages within the specified range by writing back all changed (that
\ris, dirty) and precious pages. The kernel uses the
\r<strong>memory_object_data_return</strong> call to write back the data.
\rThe <var>should_return</var> parameter must be set to
\rnon-zero.
\r <p>
\r<li>
\rFlush all cached data within the specified range. The kernel invalidates the
\rrange of data and revokes all uses of that data. The <var>should_flush</var>
\rparameter must be set to true.
\r <p>
\r<li>
\rAlter access restrictions specified in the <strong>memory_object_data_supply</strong>
\rcall
\ror a previous <strong>memory_object_lock_request</strong> call. The
\r<var>lock_value</var> parameter
\rmust specify the new access restrictions. Note that this parameter can be
\rused to unlock previously locked data.
\r</ul>
\r<p>
\rOnce the kernel performs all of the actions requested by this
\rcall, it issues a
\r<strong>memory_object_lock_completed</strong> call using the <var>reply_to</var> port.
\r<h3>NOTES</h3>
\r<p>
\rThe <strong>memory_object_lock_request</strong> call affects only data
\rthat is cached at the
\rtime of the call. Access restrictions cannot be applied to pages
\rfor which data
\rhas not been provided.
\r<p>
\rWhen a running thread requires an access that is currently prohibited,
\rthe kernel
\rissues a <strong>memory_object_data_unlock</strong> call specifying
\rthe access required. The
\rmemory manager can then use <strong>memory_object_lock_request</strong> to relax its
\raccess restrictions on the data.
\r<p>
\rTo indicate that an unlock request is invalid (that is, requires
\rpermission that can
\rnever be granted), the memory manager must first flush the page. When the
\rkernel requests the data again with the higher permission, the
\rmemory manager can
\rindicate the error by responding with a call to
\r<strong>memory_object_data_error</strong>.
\r<h3>RETURN VALUES</h3>
\r<p>
\rOnly generic errors apply.
\r<h3>RELATED INFORMATION</h3>
\r<p>
\rFunctions:
\r<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
\r<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock</strong></a>,
\r<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>.
\r\r\ No newline at end of file
+<h2>memory_object_lock_request</h2>
+<hr>
+<p>
+<strong>Function</strong> - Restrict access to memory object data.
+<h3>SYNOPSIS</h3>
+<pre>
+<strong>kern_return_t memory_object_lock_request</strong>
+ <strong>(memory_object_control_t</strong> <var>memory_control</var>,
+ <strong>vm_offset_t</strong> <var>offset</var>,
+ <strong>vm_size_t</strong> <var>size</var>,
+ <strong>memory_object_return_t</strong> <var>should_return</var>,
+ <strong>boolean_t</strong> <var>should_flush</var>,
+ <strong>vm_prot_t</strong> <var>lock_value</var>,
+ <strong>mach_port_t</strong> <var>reply_port</var><strong>);</strong>
+</pre>
+<h3>PARAMETERS</h3>
+<dl>
+<p>
+<dt> <var>memory_control</var>
+<dd>
+[in memory-cache-control send right]
+The memory cache control port
+to be used by the memory manager for cache management requests.
+This port is provided by the kernel in a <strong>memory_object_init</strong> call.
+<p>
+<dt> <var>offset</var>
+<dd>
+[in scalar]
+The offset within the memory object, in bytes.
+<p>
+<dt> <var>size</var>
+<dd>
+[in scalar]
+The number of bytes of data (starting at <var>offset</var>) to be
+affected. The number must convert to an integral number of memory object
+pages.
+<p>
+<dt> <var>should_return</var>
+<dd>
+[in scalar]
+Clean indicator. Values are:
+<dl>
+<p>
+<dt> <strong>MEMORY_OBJECT_RETURN_NONE</strong>
+<dd>
+Don't return any pages. If <var>should_flush</var> is <strong>TRUE</strong>, pages will
+be discarded.
+<p>
+<dt> <strong>MEMORY_OBJECT_RETURN_DIRTY</strong>
+<dd>
+Return only dirty (modified) pages. If <var>should_flush</var> is <strong>TRUE</strong>,
+precious pages will be discarded; otherwise, the kernel
+maintains responsibility for precious pages.
+<p>
+<dt> <strong>MEMORY_OBJECT_RETURN_ALL</strong>
+<dd>
+Both dirty and precious pages are returned. If <var>should_flush</var> is
+<strong>FALSE</strong>, the kernel maintains responsibility for the precious
+pages.
+<p>
+<dt> <strong>MEMORY_OBJECT_RETURN_ANYTHING</strong>
+<dd>
+Any resident pages are returned. If <var>should_flush</var> is <strong>TRUE</strong>,
+precious pages will be discarded; otherwise, the kernel
+maintains responsibility for precious pages.
+</dl>
+<p>
+<dt> <var>should_flush</var>
+<dd>
+[in scalar]
+Flush indicator. If true, the kernel discards all pages within
+the range.
+<p>
+<dt> <var>lock_value</var>
+<dd>
+[in scalar]
+One or more forms of access <var>not</var> permitted for the specified
+data. Valid values are:
+<dl>
+<p>
+<dt> <strong>VM_PROT_NO_CHANGE</strong>
+<dd>
+Do not change the protection of any pages.
+<p>
+<dt> <strong>VM_PROT_NONE</strong>
+<dd>
+Prohibits no access (that is, all forms of access are permitted).
+<p>
+<dt> <strong>VM_PROT_READ</strong>
+<dd>
+Prohibits read access.
+<p>
+<dt> <strong>VM_PROT_WRITE</strong>
+<dd>
+Prohibits write access.
+<p>
+<dt> <strong>VM_PROT_EXECUTE</strong>
+<dd>
+Prohibits execute access.
+<p>
+<dt> <strong>VM_PROT_ALL</strong>
+<dd>
+Prohibits all forms of access.
+</dl>
+<p>
+<dt> <var>reply_port</var>
+<dd>
+[in reply receive (to be converted to send) right]
+The response port to
+be used by the kernel on a call to <strong>memory_object_lock_completed</strong>,
+or <strong>MACH_PORT_NULL</strong> if no response is required.
+</dl>
+<h3>DESCRIPTION</h3>
+<p>
+The <strong>memory_object_lock_request</strong> function allows the memory manager to
+make the following requests of the kernel:
+<ul>
+<li>
+Clean the pages within the specified range by writing back all changed (that
+is, dirty) and precious pages. The kernel uses the
+<strong>memory_object_data_return</strong> call to write back the data.
+The <var>should_return</var> parameter must be set to
+non-zero.
+ <p>
+<li>
+Flush all cached data within the specified range. The kernel invalidates the
+range of data and revokes all uses of that data. The <var>should_flush</var>
+parameter must be set to true.
+ <p>
+<li>
+Alter access restrictions specified in the <strong>memory_object_data_supply</strong>
+call
+or a previous <strong>memory_object_lock_request</strong> call. The
+<var>lock_value</var> parameter
+must specify the new access restrictions. Note that this parameter can be
+used to unlock previously locked data.
+</ul>
+<p>
+Once the kernel performs all of the actions requested by this
+call, it issues a
+<strong>memory_object_lock_completed</strong> call using the <var>reply_to</var> port.
+<h3>NOTES</h3>
+<p>
+The <strong>memory_object_lock_request</strong> call affects only data
+that is cached at the
+time of the call. Access restrictions cannot be applied to pages
+for which data
+has not been provided.
+<p>
+When a running thread requires an access that is currently prohibited,
+the kernel
+issues a <strong>memory_object_data_unlock</strong> call specifying
+the access required. The
+memory manager can then use <strong>memory_object_lock_request</strong> to relax its
+access restrictions on the data.
+<p>
+To indicate that an unlock request is invalid (that is, requires
+permission that can
+never be granted), the memory manager must first flush the page. When the
+kernel requests the data again with the higher permission, the
+memory manager can
+indicate the error by responding with a call to
+<strong>memory_object_data_error</strong>.
+<h3>RETURN VALUES</h3>
+<p>
+Only generic errors apply.
+<h3>RELATED INFORMATION</h3>
+<p>
+Functions:
+<a href="memory_object_data_supply.html"><strong>memory_object_data_supply</strong></a>,
+<a href="memory_object_data_unlock.html"><strong>memory_object_data_unlock</strong></a>,
+<a href="MO_lock_completed.html"><strong>memory_object_lock_completed</strong></a>.
+
projects / apple / xnu.git / blobdiff