xnu-2422.1.72.tar.gz

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

<h2>vm_behavior_set</h2>
<hr>
<p>
<strong>Function</strong> - Specify expected access patterns for the target VM region.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   vm_behavior_set</strong>
                <strong>(vm_task_t</strong>                          <var>target_task</var>,
                 <strong>vm_address_t</strong>                           <var>address</var>,
                 <strong>vm_size_t</strong>                                 <var>size</var>,
                 <strong>vm_behavior_t</strong>                         <var>behavior</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>target_task</var> 
<dd>
[in task send right]
The port for the task in whose address space the 
memory object behavior is to be set.
<p>
<dt> <var>address</var> 
<dd>
[in scalar]
The starting address for the memory region.
<p>
<dt> <var>size</var> 
<dd>
[in scalar]
The number of bytes in the region.
<p>
<dt> <var>behavior</var> 
<dd>
[in scalar]
The expected reference pattern for the memory.  Possible
values are:
<dl>
<p>
<dt> <strong>VM_BEHAVIOR_DEFAULT</strong>
<dd>
The system's default behavior.  Assumes strong locality of
reference, so LRU page replacement, possibly with pre-fetch, 
would be appropriate.
<p>
<dt> <strong>VM_BEHAVIOR_RANDOM</strong>
<dd>
No particular order expected.  Assumes weak locality of
reference, so LRU page replacement may be ineffective.
<p>
<dt> <strong>VM_BEHAVIOR_SEQUENTIAL</strong>
<dd>
Forward sequential order.
<p>
<dt> <strong>VM_BEHAVIOR_RSEQNTL</strong>
<dd>
Reverse sequential order.
</dl>
</dl>
<h3>DESCRIPTION</h3>
<p>
The <strong>vm_behavior_set</strong> function informs the kernel of
the expected access
pattern for a region of memory.  The kernel uses this information
to bias its prefetch and page
replacement algorithms.
<p>
The region starts at the beginning of the virtual page containing
<var>address</var>; it ends at the end of the virtual page containing 
<var>address</var> + <var>size</var> - 1.  Because of this 
rounding to virtual page boundaries, the amount of memory affected may be 
greater than <var>size</var>.  Use <strong>host_page_size</strong>
to find the current virtual page size.
<h3>NOTES</h3>
<p>
This interface is machine word length specific because of the virtual address
parameter.
<h3>RETURN VALUES</h3>
<dl>
<p>
<dt> <strong>KERN_INVALID_ADDRESS</strong>
<dd>
The specified address is illegal or reserved.
</dl>
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="vm_region.html"><strong>vm_region</strong></a>,
<a href="host_page_size.html"><strong>host_page_size</strong></a>.