--- Gnu-Mach/doc/mach.texi 2020/09/02 04:49:15 1.1.1.3 +++ Gnu-Mach/doc/mach.texi 2020/09/02 04:55:33 1.1.1.6 @@ -3241,14 +3241,15 @@ successfully set and @code{KERN_INVALID_ non-allocated address was specified. @end deftypefun -@deftypefun kern_return_t vm_wire (@w{host_priv_t @var{host_priv}}, @w{vm_task_t @var{target_task}}, @w{vm_address_t @var{address}}, @w{vm_size_t @var{size}}, @w{vm_prot_t @var{access}}) -The function @code{vm_wire} allows privileged applications to control -memory pageability. @var{host_priv} is the privileged host port for the +@deftypefun kern_return_t vm_wire (@w{host_t @var{host}}, @w{vm_task_t @var{target_task}}, @w{vm_address_t @var{address}}, @w{vm_size_t @var{size}}, @w{vm_prot_t @var{access}}) +The function @code{vm_wire} allows applications to control +memory pageability. @var{host} is the host port for the host on which @var{target_task} resides. @var{address} is the starting address, which will be rounded down to a page boundary. @var{size} is the size in bytes of the region for which protection is to change, and will be rounded up to give a page boundary. @var{access} specifies the -types of accesses that must not cause page faults. +types of accesses that must not cause page faults. If the host port is +not privileged, the amount of memory is limited per task. The semantics of a successful @code{vm_wire} operation are that memory in the specified range will not cause page faults for any accesses @@ -3257,15 +3258,13 @@ access argument of @code{VM_PROT_READ | is that @code{VM_PROT_NONE} makes the memory pageable. The function returns @code{KERN_SUCCESS} if the call succeeded, -@code{KERN_INVALID_HOST} if @var{host_priv} was not the privileged host +@code{KERN_INVALID_HOST} if @var{host} was not a valid host port, @code{KERN_INVALID_TASK} if @var{task} was not a valid task, @code{KERN_INVALID_VALUE} if @var{access} specified an invalid access -mode, @code{KERN_FAILURE} if some memory in the specified range is not -present or has an inappropriate protection value, and -@code{KERN_INVALID_ARGUMENT} if unwiring (@var{access} is -@code{VM_PROT_NONE}) and the memory is not already wired. +mode, and @code{KERN_NO_SPACE} if some memory in the specified range +is not present or has an inappropriate protection value. -The @code{vm_wire} call is actually an RPC to @var{host_priv}, normally +The @code{vm_wire} call is actually an RPC to @var{host}, normally a send right for a privileged host port, but potentially any send right. In addition to the normal diagnostic return codes from the call's server (normally the kernel), the call may return @code{mach_msg} return codes. @@ -3366,7 +3365,7 @@ exception. @var{target_task} is the task to be affected. The starting address is @var{address}. If the @var{anywhere} option is used, this address is -used as a starting hint. The address actually allocated will be returned in +ignored. The address actually allocated will be returned in @var{address}. @var{size} is the number of bytes to allocate (rounded by the system in a machine dependent way). The alignment restriction is specified by @var{mask}. Bits asserted in this mask must not be @@ -3478,7 +3477,7 @@ formatting, the remote procedure call ge @code{memory_object_server}, to handle a received message. This function does all necessary argument handling, and actually calls one of the following functions: @code{memory_object_init}, -@code{memory_object_data_write}, @code{memory_object_data_return}, +@code{memory_object_data_return}, @code{memory_object_data_request}, @code{memory_object_data_unlock}, @code{memory_object_lock_completed}, @code{memory_object_copy}, @code{memory_object_terminate}. The @strong{default memory manager} may @@ -3525,8 +3524,8 @@ each will perform a @code{memory_object_ 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 @code{memory_object_ready} with the attribute. +When the memory manager is prepared to accept requests for data for +this object, it must call @code{memory_object_ready}. Otherwise the kernel will not process requests on this object. To reject all mappings of this object, the memory manager may use @code{memory_object_destroy}. @@ -3783,7 +3782,7 @@ use this call in three different situati @item The object was created by @code{memory_object_create} and the kernel has not yet provided data for this range (either via a -@code{memory_object_data_initialize}, @code{memory_object_data_write} or +@code{memory_object_data_initialize}, or a @code{memory_object_data_return} for the object. @item @@ -3849,57 +3848,6 @@ is called by the kernel, which does not value is ignored. @end deftypefun -The remaining interfaces in this section are obsolete. - -@deftypefun kern_return_t memory_object_data_write (@w{memory_object_t @var{memory_object}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}}) -@deftypefunx kern_return_t seqnos_memory_object_data_write (@w{memory_object_t @var{memory_object}}, @w{mach_port_seqno_t @var{seqno}}, @w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}}) -The function @code{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 @code{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 -@code{vm_deallocate}. - -The argument @var{memory_object} is the port that represents the memory -object data, as supplied to the kernel in a @code{vm_map} call. -@var{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.) @var{offset} is the -offset within a memory object to which this call refers. This will be -page aligned. @var{data} is the data which has been modified while -cached in physical memory. @var{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 @code{KERN_SUCCESS}, but since this routine -is called by the kernel, which does not wait for a reply message, this -value is ignored. -@end deftypefun - -@deftypefun kern_return_t memory_object_data_provided (@w{memory_object_control_t @var{memory_control}}, @w{vm_offset_t @var{offset}}, @w{vm_offset_t @var{data}}, @w{vm_size_t @var{data_count}}, @w{vm_prot_t @var{lock_value}}) -The function @code{memory_object_data_provided} supplies the kernel with -data for the specified memory object. It is the old form of -@code{memory_object_data_supply}. Ordinarily, memory managers should -only provide data in response to @code{memory_object_data_request} calls -from the kernel. The @var{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: @code{VM_PROT_NONE}, @code{VM_PROT_READ}, -@code{VM_PROT_WRITE}, @code{VM_PROT_EXECUTE} and @code{VM_PROT_ALL} as -defined in @file{mach/vm_prot.h}. - -The argument @var{memory_control} is the port, provided by the kernel in -a @code{memory_object_init} call, to which cache management requests may -be issued. @var{offset} is an offset within a memory object in bytes. -This must be page aligned. @var{data} is the data that is being -provided to the kernel. This is a pointer to the data. -@var{data_count} is the amount of data to be provided. This must be an -integral number of memory object pages. @var{lock_value} is a -protection value indicating those forms of access that should -@strong{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. -@end deftypefun - @node Memory Object Locking @section Memory Object Locking @@ -3910,8 +3858,7 @@ to make cache management requests. As s call, the kernel will: @itemize @item -clean (i.e., write back using @code{memory_object_data_supply} or -@code{memory_object_data_write}) any cached data which has been modified +clean (i.e., write back using @code{memory_object_data_supply} any cached data which has been modified since the last time it was written @item @@ -4024,11 +3971,12 @@ return value), so only message transmiss @end deftypefun @deftypefun kern_return_t memory_object_change_attributes (@w{memory_object_control_t @var{memory_control}}, @w{boolean_t @var{may_cache_object}}, @w{memory_object_copy_strategy_t @var{copy_strategy}}, @w{mach_port_t @var{reply_to}}) -The function @code{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. +The function @code{memory_object_change_attribute} informs the kernel +that the memory manager is ready to receive data or unlock requests on +behalf of the clients and 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: @code{MEMORY_OBJECT_COPY_NONE} which specifies that nothing special @@ -4065,44 +4013,6 @@ completion of an attribute change call. @c port. @end deftypefun -The following interface is obsoleted by @code{memory_object_ready} and -@code{memory_object_change_attributes}. If the old form -@code{memory_object_set_attributes} is used to make a memory object -ready, the kernel will write back data using the old -@code{memory_object_data_write} interface rather than -@code{memory_object_data_return}.. - -@deftypefun kern_return_t memory_object_set_attributes (@w{memory_object_control_t @var{memory_control}}, @w{boolean @var{object_ready}}, @w{boolean_t @var{may_cache_object}}, @w{memory_object_copy_strategy_t @var{copy_strategy}}) -The function @code{memory_object_set_attribute} controls how 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: -@code{MEMORY_OBJECT_COPY_NONE} which specifies that nothing special -should be done when data in the object is copied; -@code{MEMORY_OBJECT_COPY_CALL} which specifies that the memory manager -should be notified via a @code{memory_object_copy} call before any part -of the object is copied; and @code{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. -@code{MEMORY_OBJECT_COPY_DELAY} is the strategy most commonly used. - -The argument @var{memory_control} is the port, provided by the kernel in -a @code{memory_object_init} call, to which cache management requests may -be issued. If @var{object_ready} is set, the kernel may issue new data -and unlock requests on the associated memory object. If -@var{may_cache_object} is set, the kernel may keep data associated with -this memory object, even after virtual memory references to it are gone. -@var{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. -@end deftypefun - @node Default Memory Manager @section Default Memory Manager @@ -4141,7 +4051,7 @@ 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 @code{memory_object_set_attributes} call. +of a @code{memory_object_ready} call. The argument @var{old_memory_object} is a memory object provided by the default memory manager on which the kernel can make @@ -4168,7 +4078,7 @@ value is ignored. The function @code{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 -@code{memory_object_data_initialize}, @code{memory_object_data_write} or +@code{memory_object_data_initialize}, or @code{memory_object_data_return}), then this data should be ignored. Otherwise, this call behaves exactly as does @code{memory_object_data_return} on memory objects created by the kernel