xref: /xnu-11417.121.6/osfmk/man/memory_object_lock_request.html (revision a1e26a70f38d1d7daa7b49b258e2f8538ad81650)

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