Go to the first, previous, next, last section, table of contents.
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_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.
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 different memory_controls, 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
memory_object_data_copy and the
kernel should copy this region from the original 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. 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.
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.
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.
memory_object_lock_request allows a memory manager
to make cache management requests. As specified in arguments to the
call, the kernel will:
memory_object_data_supply)
any cached data which has been modified since the last time it was
written
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.
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.
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.
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.
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.
memory_object_change_completed indicates the
completion of an attribute change call.
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.
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 memory_controls, 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.
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
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.
Go to the first, previous, next, last section, table of contents.