[v3,1/2] manual: Use more precise wording for memory protection keys

Update the name of the argument in several pkey_*() functions that refers
to access restrictions rather than access rights: change access "rights"
to access "restrictions".

Specify that the result of the pkey_get() should be checked using bitwise
operations rather than plain equals comparison.
---
 manual/memory.texi | 58 +++++++++++++++++++++++++---------------------
 1 file changed, 31 insertions(+), 27 deletions(-)

On 01/11/24 07:02, Yury Khrustalev wrote:
> Update the name of the argument in several pkey_*() functions that refers
> to access restrictions rather than access rights: change access "rights"
> to access "restrictions".
> 
> Specify that the result of the pkey_get() should be checked using bitwise
> operations rather than plain equals comparison.

LGTM, thanks.

Reviewed-by: Adhemerval Zanella  <adhemerval.zanella@linaro.org>

> ---
>  manual/memory.texi | 58 +++++++++++++++++++++++++---------------------
>  1 file changed, 31 insertions(+), 27 deletions(-)
> 
> diff --git a/manual/memory.texi b/manual/memory.texi
> index 58683ee93d..a39805a8dd 100644
> --- a/manual/memory.texi
> +++ b/manual/memory.texi
> @@ -3077,7 +3077,7 @@ returned by @code{mmap} or @code{mmap64}.
>  @cindex memory protection key
>  @cindex protection key
>  @cindex MPK
> -On some systems, further restrictions can be added to specific pages
> +On some systems, further access restrictions can be added to specific pages
>  using @dfn{memory protection keys}.  These restrictions work as follows:
>  
>  @itemize @bullet
> @@ -3089,27 +3089,27 @@ during memory accesses.  New keys can be allocated with the
>  @code{pkey_mprotect}.
>  
>  @item
> -Each thread has a set of separate access right restriction for each
> -protection key.  These access rights can be manipulated using the
> +Each thread has a set of separate access restrictions for each
> +protection key.  These access restrictions can be manipulated using the
>  @code{pkey_set} and @code{pkey_get} functions.
>  
>  @item
>  During a memory access, the system obtains the protection key for the
> -accessed page and uses that to determine the applicable access rights,
> +accessed page and uses that to determine the applicable access restrictions,
>  as configured for the current thread.  If the access is restricted, a
>  segmentation fault is the result ((@pxref{Program Error Signals}).
>  These checks happen in addition to the @code{PROT_}* protection flags
>  set by @code{mprotect} or @code{pkey_mprotect}.
>  @end itemize
>  
> -New threads and subprocesses inherit the access rights of the current
> +New threads and subprocesses inherit the access restrictions of the current
>  thread.  If a protection key is allocated subsequently, existing threads
>  (except the current) will use an unspecified system default for the
> -access rights associated with newly allocated keys.
> +access restrictions associated with newly allocated keys.
>  
> -Upon entering a signal handler, the system resets the access rights of
> +Upon entering a signal handler, the system resets the access restrictions of
>  the current thread so that pages with the default key can be accessed,
> -but the access rights for other protection keys are unspecified.
> +but the access restrictions for other protection keys are unspecified.
>  
>  Applications are expected to allocate a key once using
>  @code{pkey_alloc}, and apply the key to memory regions which need
> @@ -3151,24 +3151,24 @@ it again:
>  
>  In this example, a negative key value indicates that no key had been
>  allocated, which means that the system lacks support for memory
> -protection keys and it is not necessary to change the the access rights
> +protection keys and it is not necessary to change the the access restrictions
>  of the current thread (because it always has access).
>  
>  Compared to using @code{mprotect} to change the page protection flags,
>  this approach has two advantages: It is thread-safe in the sense that
> -the access rights are only changed for the current thread, so another
> -thread which changes its own access rights concurrently to gain access
> -to the mapping will not suddenly see its access rights revoked.  And
> +the access restrictions are only changed for the current thread, so another
> +thread which changes its own access restrictions concurrently to gain access
> +to the mapping will not suddenly see its access restrictions updated.  And
>  @code{pkey_set} typically does not involve a call into the kernel and a
>  context switch, so it is more efficient.
>  
> -@deftypefun int pkey_alloc (unsigned int @var{flags}, unsigned int @var{restrictions})
> +@deftypefun int pkey_alloc (unsigned int @var{flags}, unsigned int @var{access_restrictions})
>  @standards{Linux, sys/mman.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
>  Allocate a new protection key.  The @var{flags} argument is reserved and
> -must be zero.  The @var{restrictions} argument specifies access rights
> +must be zero.  The @var{access_restrictions} argument specifies access restrictions
>  which are applied to the current thread (as if with @code{pkey_set}
> -below).  Access rights of other threads are not changed.
> +below).  Access restrictions of other threads are not changed.
>  
>  The function returns the new protection key, a non-negative number, or
>  @math{-1} on error.
> @@ -3183,7 +3183,7 @@ The system does not implement memory protection keys.
>  @item EINVAL
>  The @var{flags} argument is not zero.
>  
> -The @var{restrictions} argument is invalid.
> +The @var{access_restrictions} argument is invalid.
>  
>  The system does not implement memory protection keys or runs in a mode
>  in which memory protection keys are disabled.
> @@ -3203,7 +3203,7 @@ in which memory protection keys are disabled.
>  Deallocate the protection key, so that it can be reused by
>  @code{pkey_alloc}.
>  
> -Calling this function does not change the access rights of the freed
> +Calling this function does not change the access restrictions of the freed
>  protection key.  The calling thread and other threads may retain access
>  to it, even if it is subsequently allocated again.  For this reason, it
>  is not recommended to call the @code{pkey_free} function.
> @@ -3251,14 +3251,14 @@ not @math{-1}.
>  @end table
>  @end deftypefun
>  
> -@deftypefun int pkey_set (int @var{key}, unsigned int @var{rights})
> +@deftypefun int pkey_set (int @var{key}, unsigned int @var{access_restrictions})
>  @standards{Linux, sys/mman.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> -Change the access rights of the current thread for memory pages with the
> -protection key @var{key} to @var{rights}.  If @var{rights} is zero, no
> -additional access restrictions on top of the page protection flags are
> -applied.  Otherwise, @var{rights} is a combination of the following
> -flags:
> +Change the access restrictions of the current thread for memory pages with
> +the protection key @var{key} to @var{access_restrictions}.  If
> +@var{access_restrictions} is zero, no additional access restrictions on top of
> +the page protection flags are applied.  Otherwise, @var{access_restrictions} is
> +a combination of the following flags:
>  
>  @vtable @code
>  @item PKEY_DISABLE_WRITE
> @@ -3290,18 +3290,22 @@ function:
>  
>  @table @code
>  @item EINVAL
> -The system does not support the access rights restrictions expressed in
> -the @var{rights} argument.
> +The system does not support the access restrictions expressed in
> +the @var{access_restrictions} argument.
>  @end table
>  @end deftypefun
>  
>  @deftypefun int pkey_get (int @var{key})
>  @standards{Linux, sys/mman.h}
>  @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> -Return the access rights of the current thread for memory pages with
> -protection key @var{key}.  The return value is zero or a combination of
> +Return the access restrictions of the current thread for memory pages
> +with protection key @var{key}.  The return value is zero or a combination of
>  the @code{PKEY_DISABLE_}* flags; see the @code{pkey_set} function.
>  
> +The returned value should be checked for presence or absence of specific flags
> +using bitwise operations.  Comparing the returned value with any of the flags
> +or their combination using equals will almost certainly fail.
> +
>  Calling the @code{pkey_get} function with a protection key which was not
>  allocated by @code{pkey_alloc} results in undefined behavior.  This
>  means that calling this function on systems which do not support memory