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

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