Go to the first, previous, next, last section, table of contents.

Memory Objects and Data

Function: kern_return_t memory_object_data_return (mach_port_t memory_object, mach_port_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 (mach_port_t memory_object, mach_port_seqno_t seqno, mach_port_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 (mach_port_t memory_object, mach_port_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 (mach_port_t memory_object, mach_port_seqno_t seqno, mach_port_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 (mach_port_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 (mach_port_t memory_object, mach_port_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 (mach_port_t memory_object, mach_port_seqno_t seqno, mach_port_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 (mach_port_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 (mach_port_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 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 (mach_port_t old_memory_object, mach_port_t old_memory_control, vm_offset_t offset, vm_size_t length, mach_port_t new_memory_object)

Function: kern_return_t seqnos_memory_object_copy (mach_port_t old_memory_object, mach_port_seqno_t seqno, mach_port_t old_memory_control, vm_offset_t offset, vm_size_t length, mach_port_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.

Function: kern_return_t memory_object_data_provided (mach_port_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.

Go to the first, previous, next, last section, table of contents.