xnu-3789.1.32.tar.gz

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

<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>.