6. External Memory Management

6.1 Memory Object Server

Function: boolean_t memory_object_server (msg_header_t *in_msg, msg_header_t *out_msg)

Function: boolean_t memory_object_default_server (msg_header_t *in_msg, msg_header_t *out_msg)

Function: boolean_t seqnos_memory_object_server (msg_header_t *in_msg, msg_header_t *out_msg)

Function: boolean_t seqnos_memory_object_default_server (msg_header_t *in_msg, msg_header_t *out_msg)

A memory manager is a server task that responds to specific messages from the kernel in order to handle memory management functions for the kernel.

In order to isolate the memory manager from the specifics of message formatting, the remote procedure call generator produces a procedure, memory_object_server, to handle a received message. This function does all necessary argument handling, and actually calls one of the following functions: memory_object_init, memory_object_data_write, memory_object_data_return, memory_object_data_request, memory_object_data_unlock, memory_object_lock_completed, memory_object_copy, memory_object_terminate. The default memory manager may get two additional requests from the kernel: memory_object_create and memory_object_data_initialize. The remote procedure call generator produces a procedure memory_object_default_server to handle those functions specific to the default memory manager.

The seqnos_memory_object_server and seqnos_memory_object_default_server differ from memory_object_server and memory_object_default_server in that they supply message sequence numbers to the server interfaces. They call the seqnos_memory_object_* functions, which complement the memory_object_* set of functions.

The return value from the memory_object_server function indicates that the message was appropriate to the memory management interface (returning TRUE), or that it could not handle this message (returning FALSE).

The in_msg argument is the message that has been received from the kernel. The out_msg is a reply message, but this is not used for this server.

The function returns TRUE to indicate that the message in question was applicable to this interface, and that the appropriate routine was called to interpret the message. It returns FALSE to indicate that the message did not apply to this interface, and that no other action was taken.

6.2 Memory Object Creation

Function: kern_return_t memory_object_init (memory_object_t memory_object, memory_object_control_t memory_control, memory_object_name_t memory_object_name, vm_size_t memory_object_page_size)

Function: kern_return_t seqnos_memory_object_init (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, memory_object_name_t memory_object_name, vm_size_t memory_object_page_size)

The function memory_object_init serves as a notification that the kernel has been asked to map the given memory object into a task's virtual address space. Additionally, it provides a port on which the memory manager may issue cache management requests, and a port which the kernel will use to name this data region. In the event that different each will perform a memory_object_init call with new request and name ports. The virtual page size that is used by the calling kernel is included for planning purposes.

When the memory manager is prepared to accept requests for data for this object, it must call memory_object_ready with the attribute. Otherwise the kernel will not process requests on this object. To reject all mappings of this object, the memory manager may use memory_object_destroy.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) memory_object_name is a port used by the kernel to refer to the memory object data in reponse to vm_region calls. memory_object_page_size is the page size to be used by this kernel. All data sizes in calls involving this kernel must be an integral multiple of the page size. Note that different kernels, indicated by a different memory_control, may have different page sizes.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

Function: kern_return_t memory_object_ready (memory_object_control_t memory_control, boolean_t may_cache_object, memory_object_copy_strategy_t copy_strategy)

The function memory_object_ready informs the kernel that the memory manager is ready to receive data or unlock requests on behalf of the clients. The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. If may_cache_object is set, the kernel may keep data associated with this memory object, even after virtual memory references to it are gone.

copy_strategy tells how the kernel should copy regions of the associated memory object. There are three possible caching strategies: MEMORY_OBJECT_COPY_NONE which specifies that nothing special should be done when data in the object is copied; MEMORY_OBJECT_COPY_CALL which specifies that the memory manager should be notified via a memory_object_copy call before any part of the object is copied; and MEMORY_OBJECT_COPY_DELAY which guarantees that the memory manager does not externally modify the data so that the kernel can use its normal copy-on-write algorithms. MEMORY_OBJECT_COPY_DELAY is the strategy most commonly used.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

6.3 Memory Object Termination

Function: kern_return_t memory_object_terminate (memory_object_t memory_object, memory_object_control_t memory_control, memory_object_name_t memory_object_name)

Function: kern_return_t seqnos_memory_object_terminate (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, memory_object_name_t memory_object_name)

The function memory_object_terminate indicates that the kernel has completed its use of the given memory object. All rights to the memory object control and name ports are included, so that the memory manager can destroy them (using mach_port_deallocate) after doing appropriate bookkeeping. The kernel will terminate a memory object only after all address space mappings of that memory object have been deallocated, or upon explicit request by the memory manager.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) memory_object_name is a port used by the kernel to refer to the memory object data in reponse to vm_region calls.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

Function: kern_return_t memory_object_destroy (memory_object_control_t memory_control, kern_return_t reason)

The function memory_object_destroy tells the kernel to shut down the memory object. As a result of this call the kernel will no longer support paging activity or any memory_object calls on this object, and all rights to the memory object port, the memory control port and the memory name port will be returned to the memory manager in a memory_object_terminate call. If the memory manager is concerned that any modified cached data be returned to it before the object is terminated, it should call memory_object_lock_request with should_flush set and a lock value of VM_PROT_WRITE before making this call.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. reason is an error code indicating why the object must be destroyed.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

6.4 Memory Objects and Data

Function: kern_return_t memory_object_data_return (memory_object_t memory_object, memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t data, vm_size_t data_count, boolean_t dirty, boolean_t kernel_copy)

Function: kern_return_t seqnos_memory_object_data_return (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t data, vm_size_t data_count, boolean_t dirty, boolean_t kernel_copy)

The function memory_object_data_return provides the memory manager with data that has been modified while cached in physical memory. Once the memory manager no longer needs this data (e.g., it has been written to another storage medium), it should be deallocated using vm_deallocate.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) offset is the offset within a memory object to which this call refers. This will be page aligned. data is the data which has been modified while cached in physical memory. data_count is the amount of data to be written, in bytes. This will be an integral number of memory object pages.

The kernel will also use this call to return precious pages. If an unmodified precious age is returned, dirty is set to FALSE, otherwise it is TRUE. If kernel_copy is TRUE, the kernel kept a copy of the page. Precious data remains precious if the kernel keeps a copy. The indication that the kernel kept a copy is only a hint if the data is not precious; the cleaned copy may be discarded without further notifying the manager.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

Function: kern_return_t memory_object_data_request (memory_object_t memory_object, memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t length, vm_prot_t desired_access)

Function: kern_return_t seqnos_memory_object_data_request (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t length, vm_prot_t desired_access)

The function memory_object_data_request is a request for data from the specified memory object, for at least the access specified. The memory manager is expected to return at least the specified data, with as much access as it can allow, using memory_object_data_supply. If the memory manager is unable to provide the data (for example, because of a hardware error), it may use the memory_object_data_error call. The memory_object_data_unavailable call may be used to tell the kernel to supply zero-filled memory for this region.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) offset is the offset within a memory object to which this call refers. This will be page aligned. length is the number of bytes of data, starting at offset, to which this call refers. This will be an integral number of memory object pages. desired_access is a protection value describing the memory access modes which must be permitted on the specified cached data. One or more of: VM_PROT_READ, VM_PROT_WRITE or VM_PROT_EXECUTE.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

Function: kern_return_t memory_object_data_supply (memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t data, vm_size_t data_count, vm_prot_t lock_value, boolean_t precious, mach_port_t reply)

The function memory_object_data_supply supplies the kernel with data for the specified memory object. Ordinarily, memory managers should only provide data in reponse to memory_object_data_request calls from the kernel (but they may provide data in advance as desired). When data already held by this kernel is provided again, the new data is ignored. The kernel may not provide any data (or protection) consistency among pages with different virtual page alignments within the same object.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. offset is an offset within a memory object in bytes. This must be page aligned. data is the data that is being provided to the kernel. This is a pointer to the data. data_count is the amount of data to be provided. Only whole virtual pages of data can be accepted; partial pages will be discarded.

lock_value is a protection value indicating those forms of access that should not be permitted to the specified cached data. The lock values must be one or more of the set: VM_PROT_NONE, VM_PROT_READ, VM_PROT_WRITE, VM_PROT_EXECUTE and VM_PROT_ALL as defined in `mach/vm_prot.h'.

If precious is FALSE, the kernel treats the data as a temporary and may throw it away if it hasn't been changed. If the precious value is TRUE, the kernel treats its copy as a data repository and promises to return it to the manager; the manager may tell the kernel to throw it away instead by flushing and not cleaning the data (see memory_object_lock_request).

If reply_to is not MACH_PORT_NULL, the kernel will send a completion message to the provided port (see memory_object_supply_completed).

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

Function: kern_return_t memory_object_supply_completed (memory_object_t memory_object, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length, kern_return_t result, vm_offset_t error_offset)

Function: kern_return_t seqnos_memory_object_supply_completed (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length, kern_return_t result, vm_offset_t error_offset)

The function memory_object_supply_completed indicates that a previous memory_object_data_supply has been completed. Note that this call is made on whatever port was specified in the memory_object_data_supply call; that port need not be the memory object port itself. No reply is expected after this call.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) offset is the offset within a memory object to which this call refers. length is the length of the data covered by the lock request. The result parameter indicates what happened during the supply. If it is not KERN_SUCCESS, then error_offset identifies the first offset at which a problem occurred. The pagein operation stopped at this point. Note that the only failures reported by this mechanism are KERN_MEMORY_PRESENT. All other failures (invalid argument, error on pagein of supplied data in manager's address space) cause the entire operation to fail.

Function: kern_return_t memory_object_data_error (memory_object_control_t memory_control, vm_offset_t offset, vm_size_t size, kern_return_t reason)

The function memory_object_data_error indicates that the memory manager cannot return the data requested for the given region, specifying a reason for the error. This is typically used when a hardware error is encountered.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. offset is an offset within a memory object in bytes. This must be page aligned. data is the data that is being provided to the kernel. This is a pointer to the data. size is the amount of cached data (starting at offset) to be handled. This must be an integral number of the memory object page size. reason is an error code indicating what type of error occured.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

Function: kern_return_t memory_object_data_unavailable (memory_object_control_t memory_control, vm_offset_t offset, vm_size_t size, kern_return_t reason)

The function memory_object_data_unavailable indicates that the memory object does not have data for the given region and that the kernel should provide the data for this range. The memory manager may use this call in three different situations.

1. The object was created by memory_object_create and the kernel has not yet provided data for this range (either via a memory_object_data_initialize, memory_object_data_write or a memory_object_data_return for the object.

2. The object was created by an memory_object_data_copy and the kernel should copy this region from the original memory object.

3. The object is a normal user-created memory object and the kernel should supply unlocked zero-filled pages for the range.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. offset is an offset within a memory object, in bytes. This must be page aligned. size is the amount of cached data (starting at offset) to be handled. This must be an integral number of the memory object page size.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

Function: kern_return_t memory_object_copy (memory_object_t old_memory_object, memory_object_control_t old_memory_control, vm_offset_t offset, vm_size_t length, memory_object_t new_memory_object)

Function: kern_return_t seqnos_memory_object_copy (memory_object_t old_memory_object, mach_port_seqno_t seqno, memory_object_control_t old_memory_control, vm_offset_t offset, vm_size_t length, memory_object_t new_memory_object)

The function memory_object_copy indicates that a copy has been made of the specified range of the given original memory object. This call includes only the new memory object itself; a memory_object_init call will be made on the new memory object after the currently cached pages of the original object are prepared. After the memory manager receives the init call, it must reply with the memory_object_ready call to assert the "ready" attribute. The kernel will use the new memory object, control and name ports to refer to the new copy.

This call is made when the original memory object had the caching parameter set to MEMORY_OBJECT_COPY_CALL and a user of the object has asked the kernel to copy it.

Cached pages from the original memory object at the time of the copy operation are handled as follows: Readable pages may be silently copied to the new memory object (with all access permissions). Pages not copied are locked to prevent write access.

The new memory object is temporary, meaning that the memory manager should not change its contents or allow the memory object to be mapped in another client. The memory manager may use the memory_object_data_unavailable call to indicate that the appropriate pages of the original memory object may be used to fulfill the data request.

The argument old_memory_object is the port that represents the old memory object data. old_memory_control is the kernel port for the old object. offset is the offset within a memory object to which this call refers. This will be page aligned. length is the number of bytes of data, starting at offset, to which this call refers. This will be an integral number of memory object pages. new_memory_object is a new memory object created by the kernel; see synopsis for further description. Note that all port rights (including receive rights) are included for the new memory object.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

The remaining interfaces in this section are obsolet.

Function: kern_return_t memory_object_data_write (memory_object_t memory_object, memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t data, vm_size_t data_count)

Function: kern_return_t seqnos_memory_object_data_write (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t data, vm_size_t data_count)

The function memory_object_data_write provides the memory manager with data that has been modified while cached in physical memory. It is the old form of memory_object_data_return. Once the memory manager no longer needs this data (e.g., it has been written to another storage medium), it should be deallocated using vm_deallocate.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) offset is the offset within a memory object to which this call refers. This will be page aligned. data is the data which has been modified while cached in physical memory. data_count is the amount of data to be written, in bytes. This will be an integral number of memory object pages.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

Function: kern_return_t memory_object_data_provided (memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t data, vm_size_t data_count, vm_prot_t lock_value)

The function memory_object_data_provided supplies the kernel with data for the specified memory object. It is the old form of memory_object_data_supply. Ordinarily, memory managers should only provide data in reponse to memory_object_data_request calls from the kernel. The lock_value specifies what type of access will not be allowed to the data range. The lock values must be one or more of the set: VM_PROT_NONE, VM_PROT_READ, VM_PROT_WRITE, VM_PROT_EXECUTE and VM_PROT_ALL as defined in `mach/vm_prot.h'.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. offset is an offset within a memory object in bytes. This must be page aligned. data is the data that is being provided to the kernel. This is a pointer to the data. data_count is the amount of data to be provided. This must be an integral number of memory object pages. lock_value is a protection value indicating those forms of access that should not be permitted to the specified cached data.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

6.5 Memory Object Locking

Function: kern_return_t memory_object_lock_request (memory_object_control_t memory_control, vm_offset_t offset, vm_size_t size, memory_object_return_t should_clean, boolean_t should_flush, vm_prot_t lock_value, mach_port_t reply_to)

The function memory_object_lock_request allows a memory manager to make cache management requests. As specified in arguments to the call, the kernel will:

• clean (i.e., write back using memory_object_data_supply or memory_object_data_write) any cached data which has been modified since the last time it was written

• flush (i.e., remove any uses of) that data from memory

• lock (i.e., prohibit the specified uses of) the cached data

Locks applied to cached data are not cumulative; new lock values override previous ones. Thus, data may also be unlocked using this primitive. The lock values must be one or more of the following values: VM_PROT_NONE, VM_PROT_READ, VM_PROT_WRITE, VM_PROT_EXECUTE and VM_PROT_ALL as defined in `mach/vm_prot.h'.

Only data which is cached at the time of this call is affected. When a running thread requires a prohibited access to cached data, the kernel will issue a memory_object_data_unlock call specifying the forms of access required.

Once all of the actions requested by this call have been completed, the kernel issues a memory_object_lock_completed call on the specified reply port.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. offset is an offset within a memory object, in bytes. This must be page aligned. size is the amount of cached data (starting at offset) to be handled. This must be an integral number of the memory object page size. If should_clean is set, modified data should be written back to the memory manager. If should_flush is set, the specified cached data should be invalidated, and all uses of that data should be revoked. lock_value is a protection value indicating those forms of access that should not be permitted to the specified cached data. reply_to is a port on which a memory_object_lock_comleted call should be issued, or MACH_PORT_NULL if no acknowledgement is desired.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

Function: kern_return_t memory_object_lock_completed (memory_object_t memory_object, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length)

Function: kern_return_t seqnos_memory_object_lock_completed (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length)

The function memory_object_lock_completed indicates that a previous memory_object_lock_request has been completed. Note that this call is made on whatever port was specified in the memory_object_lock_request call; that port need not be the memory object port itself. No reply is expected after this call.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) offset is the offset within a memory object to which this call refers. length is the length of the data covered by the lock request.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

Function: kern_return_t memory_object_data_unlock (memory_object_t memory_object, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length, vm_prot_t desired_access)

Function: kern_return_t seqnos_memory_object_data_unlock (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, vm_offset_t offset, vm_size_t length, vm_prot_t desired_access)

The function memory_object_data_unlock is a request that the memory manager permit at least the desired access to the specified data cached by the kernel. A call to memory_object_lock_request is expected in response.

The argument memory_object is the port that represents the memory object data, as supplied to the kernel in a vm_map call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) offset is the offset within a memory object to which this call refers. This will be page aligned. length is the number of bytes of data, starting at offset, to which this call refers. This will be an integral number of memory object pages. desired_access a protection value describing the memory access modes which must be permitted on the specified cached data. One or more of: VM_PROT_READ, VM_PROT_WRITE or VM_PROT_EXECUTE.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

6.6 Memory Object Attributes

Function: kern_return_t memory_object_get_attributes (memory_object_control_t memory_control, boolean_t *object_ready, boolean_t *may_cache_object, memory_object_copy_strategy_t *copy_strategy)

The function memory_object_get_attribute retrieves the current attributes associated with the memory object.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. If object_ready is set, the kernel may issue new data and unlock requests on the associated memory object. If may_cache_object is set, the kernel may keep data associated with this memory object, even after virtual memory references to it are gone. copy_strategy tells how the kernel should copy regions of the associated memory object.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

Function: kern_return_t memory_object_change_attributes (memory_object_control_t memory_control, boolean_t may_cache_object, memory_object_copy_strategy_t copy_strategy, mach_port_t reply_to)

The function memory_object_change_attribute sets performance-related attributes for the specified memory object. If the caching attribute is asserted, the kernel is permitted (and encouraged) to maintain cached data for this memory object even after no virtual address space contains this data.

There are three possible caching strategies: MEMORY_OBJECT_COPY_NONE which specifies that nothing special should be done when data in the object is copied; MEMORY_OBJECT_COPY_CALL which specifies that the memory manager should be notified via a memory_object_copy call before any part of the object is copied; and MEMORY_OBJECT_COPY_DELAY which guarantees that the memory manager does not externally modify the data so that the kernel can use its normal copy-on-write algorithms. MEMORY_OBJECT_COPY_DELAY is the strategy most commonly used.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. If may_cache_object is set, the kernel may keep data associated with this memory object, even after virtual memory references to it are gone. copy_strategy tells how the kernel should copy regions of the associated memory object. reply_to is a port on which a memory_object_change_comleted call will be issued upon completion of the attribute change, or MACH_PORT_NULL if no acknowledgement is desired.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

Function: kern_return_t memory_object_change_completed (memory_object_t memory_object, boolean_t may_cache_object, memory_object_copy_strategy_t copy_strategy)

Function: kern_return_t seqnos_memory_object_change_completed (memory_object_t memory_object, mach_port_seqno_t seqno, boolean_t may_cache_object, memory_object_copy_strategy_t copy_strategy)

The function memory_object_change_completed indicates the completion of an attribute change call.

The following interface is obsoleted by memory_object_ready and memory_object_change_attributes. If the old form memory_object_set_attributes is used to make a memory object ready, the kernel will write back data using the old memory_object_data_write interface rather than memory_object_data_return..

Function: kern_return_t memory_object_set_attributes (memory_object_control_t memory_control, boolean object_ready, boolean_t may_cache_object, memory_object_copy_strategy_t copy_strategy)

The function memory_object_set_attribute controls how the the memory object. The kernel will only make data or unlock requests when the ready attribute is asserted. If the caching attribute is asserted, the kernel is permitted (and encouraged) to maintain cached data for this memory object even after no virtual address space contains this data.

There are three possible caching strategies: MEMORY_OBJECT_COPY_NONE which specifies that nothing special should be done when data in the object is copied; MEMORY_OBJECT_COPY_CALL which specifies that the memory manager should be notified via a memory_object_copy call before any part of the object is copied; and MEMORY_OBJECT_COPY_DELAY which guarantees that the memory manager does not externally modify the data so that the kernel can use its normal copy-on-write algorithms. MEMORY_OBJECT_COPY_DELAY is the strategy most commonly used.

The argument memory_control is the port, provided by the kernel in a memory_object_init call, to which cache management requests may be issued. If object_ready is set, the kernel may issue new data and unlock requests on the associated memory object. If may_cache_object is set, the kernel may keep data associated with this memory object, even after virtual memory references to it are gone. copy_strategy tells how the kernel should copy regions of the associated memory object.

This routine does not receive a reply message (and consequently has no return value), so only message transmission errors apply.

6.7 Default Memory Manager

Function: kern_return_t vm_set_default_memory_manager (host_t host, mach_port_t *default_manager)

The function vm_set_default_memory_manager sets the kernel's default memory manager. It sets the port to which newly-created temporary memory objects are delivered by memory_object_create to the host. The old memory manager port is returned. If default_manager is MACH_PORT_NULL then this routine just returns the current default manager port without changing it.

The argument host is a task port to the kernel whose default memory manager is to be changed. default_manager is an in/out parameter. As input, default_manager is the port that the new memory manager is listening on for memory_object_create calls. As output, it is the old default memory manager's port.

The function returns KERN_SUCCESS if the new memory manager is installed, and KERN_INVALID_ARGUMENT if this task does not have the privileges required for this call.

Function: kern_return_t memory_object_create (memory_object_t old_memory_object, memory_object_t new_memory_object, vm_size_t new_object_size, memory_object_control_t new_control, memory_object_name_t new_name, vm_size_t new_page_size)

Function: kern_return_t seqnos_memory_object_create (memory_object_t old_memory_object, mach_port_seqno_t seqno, memory_object_t new_memory_object, vm_size_t new_object_size, memory_object_control_t new_control, memory_object_name_t new_name, vm_size_t new_page_size)

The function memory_object_create is a request that the given memory manager accept responsibility for the given memory object created by the kernel. This call will only be made to the system default memory manager. The memory object in question initially consists of zero-filled memory; only memory pages that are actually written will ever be provided to memory_object_data_request calls, the default memory manager must use memory_object_data_unavailable for any pages that have not previously been written.

No reply is expected after this call. Since this call is directed to the default memory manager, the kernel assumes that it will be ready to handle data requests to this object and does not need the confirmation of a memory_object_set_attributes call.

The argument old_memory_object is a memory object provided by the default memory manager on which the kernel can make memory_object_create calls. new_memory_object is a new memory object created by the kernel; see synopsis for further description. Note that all port rights (including receive rights) are included for the new memory object. new_object_size is the maximum size of the new object. new_control is a port, created by the kernel, on which a memory manager may issue cache management requests for the new object. new_name a port used by the kernel to refer to the new memory object data in response to vm_region calls. new_page_size is the page size to be used by this kernel. All data sizes in calls involving this kernel must be an integral multiple of the page size. Note that different kernels, indicated by different a memory_control, may have different page sizes.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.

Function: kern_return_t memory_object_data_initialize (memory_object_t memory_object, memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t data, vm_size_t data_count)

Function: kern_return_t seqnos_memory_object_data_initialize (memory_object_t memory_object, mach_port_seqno_t seqno, memory_object_control_t memory_control, vm_offset_t offset, vm_offset_t data, vm_size_t data_count)

The function memory_object_data_initialize provides the memory manager with initial data for a kernel-created memory object. If the memory manager already has been supplied data (by a previous memory_object_data_initialize, memory_object_data_write or memory_object_data_return), then this data should be ignored. Otherwise, this call behaves exactly as does memory_object_data_return on memory objects created by the kernel via memory_object_create and thus will only be made to default memory managers. This call will not be made on objects created via memory_object_copy.

The argument memory_object the port that represents the memory object data, as supplied by the kernel in a memory_object_create call. memory_control is the request port to which a response is requested. (In the event that a memory object has been supplied to more than one the kernel that has made the request.) offset is the offset within a memory object to which this call refers. This will be page aligned. data os the data which has been modified while cached in physical memory. data_count is the amount of data to be written, in bytes. This will be an integral number of memory object pages.

The function should return KERN_SUCCESS, but since this routine is called by the kernel, which does not wait for a reply message, this value is ignored.