[apple/xnu.git] / osfmk / man / memory_object_lock_request.html

<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