summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRichard Braun <rbraun@sceen.net>2016-12-24 02:37:13 +0100
committerRichard Braun <rbraun@sceen.net>2016-12-24 02:37:13 +0100
commit49547a4a10aa594c669dbf4199e2609f84e63a3c (patch)
tree384cc5c762e777b100803ad3a0b83deb5e1b0af7
parent2b0f19f602e08fd9d37268233b962674fd592634 (diff)
doc: update documentation about wiring
* doc/mach.texi: Describe vm_wire_all, and add more information about vm_wire and vm_protect.
-rw-r--r--doc/mach.texi41
1 files changed, 41 insertions, 0 deletions
diff --git a/doc/mach.texi b/doc/mach.texi
index d2b88d1f..756731e6 100644
--- a/doc/mach.texi
+++ b/doc/mach.texi
@@ -3204,6 +3204,9 @@ interface allows write access to require @code{VM_PROT_READ} and
@code{VM_PROT_WRITE} permission and execute access to require
@code{VM_PROT_READ} permission.
+If a region is wired, changing its protection also updates the
+access types for which no page faults must occur.
+
The function returns @code{KERN_SUCCESS} if the memory was successfully
protected, @code{KERN_INVALID_ADDRESS} if an invalid or non-allocated
address was specified and @code{KERN_PROTECTION_FAILURE} if an attempt
@@ -3257,6 +3260,13 @@ included in access. Data memory can be made non-pageable (wired) with a
access argument of @code{VM_PROT_READ | VM_PROT_WRITE}. A special case
is that @code{VM_PROT_NONE} makes the memory pageable.
+Wiring doesn't stack, i.e. a single call to @code{vm_wire} with
+@var{access} @code{VM_PROT_NONE} unwires the specified range,
+regardless of how many times it was previously wired. Conversely,
+a single call to @code{vm_wire} with @var{access}
+@code{VM_PROT_READ | VM_PROT_WRITE} wires the specified range,
+regardless of how many times it was previously unwired.
+
The function returns @code{KERN_SUCCESS} if the call succeeded,
@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,
@@ -3270,6 +3280,37 @@ 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.
@end deftypefun
+@deftypefun kern_return_t vm_wire_all (@w{host_t @var{host}}, @w{vm_task_t @var{target_task}}, @w{vm_wire_t @var{flags}})
+The function @code{vm_wire_all} allows applications to control
+memory pageability, as with @code{vm_wire}, but applies to all
+current and/or future mappings.
+
+The argument @var{flags} are bit values, combined with bitwise-or.
+
+@table @code
+@item VM_WIRE_CURRENT
+All currently existing entries are wired, with access types matching
+their protection.
+
+@item VM_WIRE_FUTURE
+All future entries are automatically wired, with access types matching
+their protection.
+@end table
+
+If flags specifies no bits (@code{VM_WIRE_NONE}), all current entries
+are unwired, and future entries are no longer automatically wired.
+
+The function returns @code{KERN_SUCCESS} if the call succeeded,
+@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,
+and @code{KERN_INVALID_VALUE} if @var{flags} specifies invalid bits.
+
+The @code{vm_wire_all} 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.
+@end deftypefun
+
@deftypefun kern_return_t vm_machine_attribute (@w{vm_task_t @var{task}}, @w{vm_address_t @var{address}}, @w{vm_size_t @var{size}}, @w{vm_prot_t @var{access}}, @w{vm_machine_attribute_t @var{attribute}}, @w{vm_machine_attribute_val_t @var{value}})
The function @code{vm_machine_attribute} specifies machine-specific
attributes for a VM mapping, such as cachability, migrability,