xnu-1504.15.3.tar.gz

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

<h2>memory_object_create</h2>
<hr>
<p>
<strong>Function</strong> - Request that the default pager handle management requests on the specified memory object.
<h3>SYNOPSIS</h3>
<pre>
<strong>kern_return_t   memory_object_create</strong>
                <strong>(memory_object_t</strong>                          <var>pager</var>,
                 <strong>memory_object_t</strong>              <var>new_memory_object</var>,
                 <strong>vm_size_t</strong>                      <var>new_object_size</var>,
                 <strong>memory_object_control_t</strong>            <var>new_control</var>,
                 <strong>vm_size_t</strong>                        <var>new_page_size</var><strong>);</strong>


<strong>kern_return_t   seqnos_memory_object_create</strong>
                <strong>(memory_object_t</strong>                          <var>pager</var>,
                 <strong>mach_port_seqno_t</strong>                        <var>seqno</var>,
                 <strong>memory_object_t</strong>              <var>new_memory_object</var>,
                 <strong>vm_size_t</strong>                      <var>new_object_size</var>,
                 <strong>memory_object_control_t</strong>            <var>new_control</var>,
                 <strong>vm_size_t</strong>                        <var>new_page_size</var><strong>);</strong>
</pre>
<h3>PARAMETERS</h3>
<dl>
<p>
<dt> <var>pager</var> 
<dd>
[in default-pager (receive) right]
The default memory manager service 
port.
<p>
<dt> <var>seqno</var> 
<dd>
[in scalar]
The sequence number of this message relative to the pager 
port.
<p>
<dt> <var>new_memory_object</var> 
<dd>
[in abstract-memory-object receive right]
The port representing the 
new abstract memory object created by the kernel.
<p>
<dt> <var>new_object_size</var> 
<dd>
[in scalar]
The expected size for the new object, in bytes.
<p>
<dt> <var>new_control</var> 
<dd>
[in memory-cache-control send right]
The memory cache control port 
to be used by the memory manager when making cache management 
requests for the new object.
<p>
<dt> <var>new_page_size</var> 
<dd>
[in scalar]
The page size used by the kernel.  All calls involving this
kernel must use data sizes that are integral multiples of this page size.
</dl>
<h3>DESCRIPTION</h3>
<p>
A <strong>memory_object_create</strong> function is called as the result
of a message from the 
kernel requesting that the default memory manager accept responsibility
for the 
new memory object created by the kernel.  The kernel makes this
call only to the 
system default memory manager.
<p>
The new memory object initially consists of zero-filled pages.  Only memory 
pages that are actually written are provided to the memory manager.  When
processing <strong>memory_object_data_request</strong> calls from the
kernel, the default
memory manager must use <strong>memory_object_data_unavailable</strong>
for any pages that have not been written previously.
<p>
The kernel does not expect a reply to this call.  The kernel assumes that the
default memory manager will be ready to handle data requests to this object and 
does not need the confirmation of a <strong>memory_object_change_attributes</strong> call.
<h3>NOTES</h3>
<p>
The kernel requires memory objects to provide temporary backing storage for 
zero-filled memory created by <strong>vm_allocate</strong> calls, issued
by both user tasks and 
the kernel itself.  The kernel allocates an abstract memory object port to
represent the temporary backing storage and uses <strong>memory_object_create</strong>
to pass the 
new memory object to the default memory manager, which provides the storage.
<p>
The default memory manager is a trusted system component that is identified to 
the kernel at system initialization time.  The default memory manager can also 
be changed at run time using the <strong>host_default_memory_manager</strong> call.
<p>
The contents of a kernel-created (as opposed to a user-created) memory object 
can be modified only in main memory.  The default memory manager must not 
change the contents of a temporary memory object, or allow unrelated tasks to 
access the memory object, control, or name port.
<p>
The kernel provides the size of a temporary memory object based on the
allocated size.  Since the object is not mapped by other tasks,
the object will not grow 
by explicit action.  However, the kernel may coalesce adjacent
temporary objects 
in such a way that this object may appear to grow.  As such,
the supplied object 
size is merely a hint as to the maximum size.
<h3>RETURN VALUES</h3>
<p>
Only generic errors apply.
<h3>RELATED INFORMATION</h3>
<p>
Functions:
<a href="DP_object_create.html"><strong>default_pager_object_create</strong></a>,
<a href="MO_data_initialize.html"><strong>memory_object_data_initialize</strong></a>,
<a href="MO_data_unavailable.html"><strong>memory_object_data_unavailable</strong></a>,
<a href="MO_default_server.html"><strong>memory_object_default_server</strong></a>,
<a href="SMO_default_server.html"><strong>seqnos_memory_object_default_server</strong></a>.