Linux-man Archive on lore.kernel.org
 help / color / Atom feed
* [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6
@ 2020-06-24 17:36 Dave Martin
  2020-06-24 17:36 ` [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64) Dave Martin
                   ` (2 more replies)
  0 siblings, 3 replies; 6+ messages in thread
From: Dave Martin @ 2020-06-24 17:36 UTC (permalink / raw)
  To: Michael Kerrisk
  Cc: linux-man, linux-arch, linux-arm-kernel, Catalin Marinas,
	Mark Rutland, Will Deacon, Vincenzo Frascino

A bunch of updates to the prctl(2) man page to fill in missing
prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
fixes).

Patches from the v2 series [1] that have been applied or rejected
already have been dropped.

All that remain here now are the SVE and tagged address ABI controls
for arm64.



[1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/


Dave Martin (2):
  prctl.2: Add SVE prctls (arm64)
  prctl.2: Add tagged address ABI control prctls (arm64)

 man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 331 insertions(+)

-- 
2.1.4


^ permalink raw reply	[flat|nested] 6+ messages in thread

* [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64)
  2020-06-24 17:36 [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6 Dave Martin
@ 2020-06-24 17:36 ` Dave Martin
  2020-06-26 11:23   ` Michael Kerrisk (man-pages)
  2020-06-24 17:36 ` [PATCH v3 2/2] prctl.2: Add tagged address ABI control " Dave Martin
  2020-06-29 11:52 ` [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6 Michael Kerrisk (man-pages)
  2 siblings, 1 reply; 6+ messages in thread
From: Dave Martin @ 2020-06-24 17:36 UTC (permalink / raw)
  To: Michael Kerrisk
  Cc: linux-man, linux-arch, linux-arm-kernel, Catalin Marinas, Will Deacon

Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL
prctls added in Linux 4.15 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Catalin Marinas <catalin.marinas@arm.com>
Cc: Will Deacon <will@kernel.org>

---

Since v2:

 * Clarify that the arg2 enumeration for PR_SVE_SET_VL applies to the
   bith _other than_ the PR_SVE_VL_LEN_MASK bits, rather than to all the
   bits.

 * Clarify return value semantics for PR_SVE_SET_VL, to highlight that
   there is no PR_SVE_SET_VL_ONEXEC in the return value and refer to
   PR_SVE_GET_VL for the rest of the definition.  Also clarify when the
   vector length given in the return value actually takes effect.

 * Reorder some documentation cross-references to avoid ambiguity about
   what they apply to.
---
 man2/prctl.2 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 170 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 88b791b..46ea9d2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1370,6 +1370,158 @@ call failing with the error
 .BR ENXIO .
 For further details, see the kernel source file
 .IR Documentation/admin\-guide/kernel\-parameters.txt .
+.\" prctl PR_SVE_SET_VL
+.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
+.\" linux-5.6/Documentation/arm64/sve.rst
+.TP
+.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
+Configure the thread's SVE vector length,
+as specified by
+.IR "(int) arg2" .
+Arguments
+.IR arg3 ", " arg4 " and " arg5
+are ignored.
+.IP
+The bits of
+.I arg2
+corresponding to
+.B PR_SVE_VL_LEN_MASK
+must be set to the desired vector length in bytes.
+This is interpreted as an upper bound:
+the kernel will select the greatest available vector length
+that does not exceed the value specified.
+In particular, specifying
+.B SVE_VL_MAX
+(defined in
+.I <asm/sigcontext.h>)
+for the
+.B PR_SVE_VL_LEN_MASK
+bits requests the maximum supported vector length.
+.IP
+In addition, the other bits of
+.I arg2
+must be set to one of the following combinations of flags:
+.RS
+.TP
+.B 0
+Perform the change immediately.
+At the next
+.BR execve (2)
+in the thread,
+the vector length will be reset to the value configured in
+.IR /proc/sys/abi/sve_default_vector_length .
+.TP
+.B PR_SVE_VL_INHERIT
+Perform the change immediately.
+Subsequent
+.BR execve (2)
+calls will preserve the new vector length.
+.TP
+.B PR_SVE_SET_VL_ONEXEC
+Defer the change, so that it is performed at the next
+.BR execve (2)
+in the thread.
+Further
+.BR execve (2)
+calls will reset the vector length to the value configured in
+.IR /proc/sys/abi/sve_default_vector_length .
+.TP
+.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT"
+Defer the change, so that it is performed at the next
+.BR execve (2)
+in the thread.
+Further
+.BR execve (2)
+calls will preserve the new vector length.
+.RE
+.IP
+In all cases,
+any previously pending deferred change is canceled.
+.IP
+The call fails with error
+.B EINVAL
+if SVE is not supported on the platform, if
+.I arg2
+is unrecognized or invalid, or the value in the bits of
+.I arg2
+corresponding to
+.B PR_SVE_VL_LEN_MASK
+is outside the range
+.BR SVE_VL_MIN .. SVE_VL_MAX
+or is not a multiple of 16.
+.IP
+On success,
+a nonnegative value is returned that describes the
+.I selected
+configuration.
+If
+.B PR_SVE_SET_VL_ONEXEC
+was included in
+.IR arg2 ,
+then the configuration described by the return value
+will take effect at the next
+.BR execve ().
+Otherwise, the configuration is already in effect when the
+.B PR_SVE_SET_VL
+call returns.
+In either case, the value is encoded in the same way as the return value of
+.BR PR_SVE_GET_VL .
+Note that there is no explicit flag in the return value
+corresponding to
+.BR PR_SVE_SET_VL_ONEXEC .
+.IP
+The configuration (including any pending deferred change)
+is inherited across
+.BR fork (2)
+and
+.BR clone (2).
+.IP
+For more information, see the kernel source file
+.I Documentation/arm64/sve.rst
+.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
+(or
+.I Documentation/arm64/sve.txt
+before Linux 5.3).
+.IP
+.B Warning:
+Because the compiler or run-time environment
+may be using SVE, using this call without the
+.B PR_SVE_SET_VL_ONEXEC
+flag may crash the calling process.
+The conditions for using it safely are complex and system-dependent.
+Don't use it unless you really know what you are doing.
+.\" prctl PR_SVE_GET_VL
+.TP
+.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
+Get the thread's current SVE vector length configuration.
+.IP
+Arguments
+.IR arg2 ", " arg3 ", " arg4 " and " arg5
+are ignored.
+.IP
+Providing that the kernel and platform support SVE
+this operation always succeeds,
+returning a nonnegative value that describes the
+.I current
+configuration.
+The bits corresponding to
+.B PR_SVE_VL_LEN_MASK
+contain the currently configured vector length in bytes.
+The bit corresponding to
+.B PR_SVE_VL_INHERIT
+indicates whether the vector length will be inherited
+across
+.BR execve (2).
+.IP
+Note that there is no way to determine whether there is
+a pending vector length change that has not yet taken effect.
+.IP
+For more information, see the kernel source file
+.I Documentation/arm64/sve.rst
+.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
+(or
+.I Documentation/arm64/sve.txt
+before Linux 5.3).
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1613,6 +1765,8 @@ On success,
 .BR PR_GET_NO_NEW_PRIVS ,
 .BR PR_GET_SECUREBITS ,
 .BR PR_GET_SPECULATION_CTRL ,
+.BR PR_SVE_GET_VL ,
+.BR PR_SVE_SET_VL ,
 .BR PR_GET_THP_DISABLE ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
@@ -1904,6 +2058,22 @@ See the description of
 .B PR_PAC_RESET_KEYS
 above for details.
 .TP
+.B EINVAL
+.I option
+is
+.B PR_SVE_SET_VL
+and the arguments are invalid or unsupported,
+or SVE is not available on this platform.
+See the description of
+.B PR_SVE_SET_VL
+above for details.
+.TP
+.B EINVAL
+.I option
+is
+.B PR_SVE_GET_VL
+and SVE is not available on this platform.
+.TP
 .B ENODEV
 .I option
 was
-- 
2.1.4


^ permalink raw reply	[flat|nested] 6+ messages in thread

* [PATCH v3 2/2] prctl.2: Add tagged address ABI control prctls (arm64)
  2020-06-24 17:36 [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6 Dave Martin
  2020-06-24 17:36 ` [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64) Dave Martin
@ 2020-06-24 17:36 ` Dave Martin
  2020-06-26 11:23   ` Michael Kerrisk (man-pages)
  2020-06-29 11:52 ` [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6 Michael Kerrisk (man-pages)
  2 siblings, 1 reply; 6+ messages in thread
From: Dave Martin @ 2020-06-24 17:36 UTC (permalink / raw)
  To: Michael Kerrisk
  Cc: linux-man, linux-arch, linux-arm-kernel, Vincenzo Frascino

Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and
PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>
Cc: Vincenzo Frascino <vincenzo.frascino@arm.com>

---

Kept Catalin's Reviewed-by, since the changes are pretty minor.

Changes since v2:

 * Clarified type of PR_SET_TAGGED_ADDR_CTRL arg2.

 * Added Linux commit where enforecement of zeroing reserved args was
   added for PR_SET_TAGGED_ADDR_CTRL.

 * Added explicit text regarding how to disable the tagged-address ABI
   globally through sysctl.

 * Rearrange the tagged argument syscall exclusion list so that shmdt()
   isn't called out specially.  The reader probably doesn't care about
   this history here.

 * Minor rewordings.
---
 man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 46ea9d2..cf92f3b 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1522,6 +1522,148 @@ For more information, see the kernel source file
 (or
 .I Documentation/arm64/sve.txt
 before Linux 5.3).
+.\" prctl PR_SET_TAGGED_ADDR_CTRL
+.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
+.TP
+.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
+Controls support for passing tagged userspace addresses to the kernel
+(i.e., addresses where bits 56\(em63 are not all zero).
+.IP
+The level of support is selected by
+.IR "arg2" ,
+which can be one of the following:
+.RS
+.TP
+.B 0
+Addresses that are passed
+for the purpose of being dereferenced by the kernel
+must be untagged.
+.TP
+.B PR_TAGGED_ADDR_ENABLE
+Addresses that are passed
+for the purpose of being dereferenced by the kernel
+may be tagged, with the exceptions summarized below.
+.RE
+.IP
+The remaining arguments
+.IR arg3 ", " arg4 " and " arg5
+must all be zero.
+.\" Enforcement added in
+.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95
+.IP
+On success, the mode specified in
+.I arg2
+is set for the calling thread and the the return value is 0.
+If the arguments are invalid,
+the mode specified in
+.I arg2
+is unrecognized,
+or if this feature is unsupported by the kernel
+or disabled via
+.IR /proc/sys/abi/tagged_addr_disabled ,
+the call fails with
+.BR EINVAL .
+.IP
+In particular, if
+.BR prctl ( PR_SET_TAGGED_ADDR_CTRL ,
+0, 0, 0, 0)
+fails with
+.B EINVAL
+then all addresses passed to the kernel must be untagged.
+.IP
+Irrespective of which mode is set,
+addresses passed to certain interfaces
+must always be untagged:
+.RS
+.IP \(em
+.BR brk (2),
+.BR mmap (2),
+.BR shmat (2),
+.BR shmdt (2),
+and the
+.I new_address
+argument of
+.BR mremap (2).
+.IP
+(Prior to Linux 5.6 these accepted tagged addresses,
+but the behaviour may not be what you expect.
+Don't rely on it.)
+.IP \(em
+\(oqpolymorphic\(cq interfaces
+that accept pointers to arbitrary types cast to a
+.I void *
+or other generic type, specifically
+.BR prctl (2),
+.BR ioctl (2),
+and in general
+.BR setsockopt (2)
+(only certain specific
+.BR setsockopt (2)
+options allow tagged addresses).
+.RE
+.IP
+This list of exclusions may shrink
+when moving from one kernel version to a later kernel version.
+While the kernel may make some guarantees
+for backwards compatibility reasons,
+for the purposes of new software
+the effect of passing tagged addresses to these interfaces
+is unspecified.
+.IP
+The mode set by this call is inherited across
+.BR fork (2)
+and
+.BR clone (2).
+The mode is reset by
+.BR execve (2)
+to 0
+(i.e., tagged addresses not permitted in the user/kernel ABI).
+.IP
+For more information, see the kernel source file
+.IR Documentation/arm64/tagged\-address\-abi.rst .
+.IP
+.B Warning:
+This call is primarily intended for use by the run-time environment.
+A successful
+.B PR_SET_TAGGED_ADDR_CTRL
+call elsewhere may crash the calling process.
+The conditions for using it safely are complex and system-dependent;
+Don't use it unless you know what you are doing.
+.\" prctl PR_GET_TAGGED_ADDR_CTRL
+.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
+.TP
+.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
+Returns the current tagged address mode
+for the calling thread.
+.IP
+Arguments
+.IR arg2 ", " arg3 ", " arg4 " and " arg5
+must all be zero.
+.IP
+If the arguments are invalid
+or this feature is disabled or unsupported by the kernel,
+the call fails with
+.BR EINVAL .
+In particular, if
+.BR prctl ( PR_GET_TAGGED_ADDR_CTRL ,
+0, 0, 0, 0)
+fails with
+.BR EINVAL ,
+then this feature is definitely either unsupported,
+or disabled via
+.IR /proc/sys/abi/tagged_addr_disabled .
+In this case,
+all addresses passed to the kernel must be untagged.
+.IP
+Otherwise, the call returns a nonnegative value
+describing the current tagged address mode,
+encoded in the same way as the
+.I arg2
+argument of
+.BR PR_SET_TAGGED_ADDR_CTRL .
+.IP
+For more information, see the kernel source file
+.IR Documentation/arm64/tagged\-address\-abi.rst .
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1767,6 +1909,7 @@ On success,
 .BR PR_GET_SPECULATION_CTRL ,
 .BR PR_SVE_GET_VL ,
 .BR PR_SVE_SET_VL ,
+.BR PR_GET_TAGGED_ADDR_CTRL ,
 .BR PR_GET_THP_DISABLE ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
@@ -2074,6 +2217,24 @@ is
 .B PR_SVE_GET_VL
 and SVE is not available on this platform.
 .TP
+.B EINVAL
+.I option
+is
+.BR PR_SET_TAGGED_ADDR_CTRL
+and the arguments are invalid or unsupported.
+See the description of
+.B PR_SET_TAGGED_ADDR_CTRL
+above for details.
+.TP
+.B EINVAL
+.I option
+is
+.BR PR_GET_TAGGED_ADDR_CTRL
+and the arguments are invalid or unsupported.
+See the description of
+.B PR_GET_TAGGED_ADDR_CTRL
+above for details.
+.TP
 .B ENODEV
 .I option
 was
-- 
2.1.4


^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64)
  2020-06-24 17:36 ` [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64) Dave Martin
@ 2020-06-26 11:23   ` Michael Kerrisk (man-pages)
  0 siblings, 0 replies; 6+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-06-26 11:23 UTC (permalink / raw)
  To: Dave Martin
  Cc: mtk.manpages, linux-man, linux-arch, linux-arm-kernel,
	Catalin Marinas, Will Deacon

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL
> prctls added in Linux 4.15 for arm64.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> Cc: Catalin Marinas <catalin.marinas@arm.com>
> Cc: Will Deacon <will@kernel.org>
> 
> ---
> 
> Since v2:
> 
>  * Clarify that the arg2 enumeration for PR_SVE_SET_VL applies to the
>    bith _other than_ the PR_SVE_VL_LEN_MASK bits, rather than to all the
>    bits.
> 
>  * Clarify return value semantics for PR_SVE_SET_VL, to highlight that
>    there is no PR_SVE_SET_VL_ONEXEC in the return value and refer to
>    PR_SVE_GET_VL for the rest of the definition.  Also clarify when the
>    vector length given in the return value actually takes effect.
> 
>  * Reorder some documentation cross-references to avoid ambiguity about
>    what they apply to.

Nicely written patch! I've applied locally, but won't push just yet, to
allow for some reviews/acks to come in.

Thanks,

Michael


> ---
>  man2/prctl.2 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 170 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 88b791b..46ea9d2 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1370,6 +1370,158 @@ call failing with the error
>  .BR ENXIO .
>  For further details, see the kernel source file
>  .IR Documentation/admin\-guide/kernel\-parameters.txt .
> +.\" prctl PR_SVE_SET_VL
> +.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
> +.\" linux-5.6/Documentation/arm64/sve.rst
> +.TP
> +.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
> +Configure the thread's SVE vector length,
> +as specified by
> +.IR "(int) arg2" .
> +Arguments
> +.IR arg3 ", " arg4 " and " arg5
> +are ignored.
> +.IP
> +The bits of
> +.I arg2
> +corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +must be set to the desired vector length in bytes.
> +This is interpreted as an upper bound:
> +the kernel will select the greatest available vector length
> +that does not exceed the value specified.
> +In particular, specifying
> +.B SVE_VL_MAX
> +(defined in
> +.I <asm/sigcontext.h>)
> +for the
> +.B PR_SVE_VL_LEN_MASK
> +bits requests the maximum supported vector length.
> +.IP
> +In addition, the other bits of
> +.I arg2
> +must be set to one of the following combinations of flags:
> +.RS
> +.TP
> +.B 0
> +Perform the change immediately.
> +At the next
> +.BR execve (2)
> +in the thread,
> +the vector length will be reset to the value configured in
> +.IR /proc/sys/abi/sve_default_vector_length .
> +.TP
> +.B PR_SVE_VL_INHERIT
> +Perform the change immediately.
> +Subsequent
> +.BR execve (2)
> +calls will preserve the new vector length.
> +.TP
> +.B PR_SVE_SET_VL_ONEXEC
> +Defer the change, so that it is performed at the next
> +.BR execve (2)
> +in the thread.
> +Further
> +.BR execve (2)
> +calls will reset the vector length to the value configured in
> +.IR /proc/sys/abi/sve_default_vector_length .
> +.TP
> +.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT"
> +Defer the change, so that it is performed at the next
> +.BR execve (2)
> +in the thread.
> +Further
> +.BR execve (2)
> +calls will preserve the new vector length.
> +.RE
> +.IP
> +In all cases,
> +any previously pending deferred change is canceled.
> +.IP
> +The call fails with error
> +.B EINVAL
> +if SVE is not supported on the platform, if
> +.I arg2
> +is unrecognized or invalid, or the value in the bits of
> +.I arg2
> +corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +is outside the range
> +.BR SVE_VL_MIN .. SVE_VL_MAX
> +or is not a multiple of 16.
> +.IP
> +On success,
> +a nonnegative value is returned that describes the
> +.I selected
> +configuration.
> +If
> +.B PR_SVE_SET_VL_ONEXEC
> +was included in
> +.IR arg2 ,
> +then the configuration described by the return value
> +will take effect at the next
> +.BR execve ().
> +Otherwise, the configuration is already in effect when the
> +.B PR_SVE_SET_VL
> +call returns.
> +In either case, the value is encoded in the same way as the return value of
> +.BR PR_SVE_GET_VL .
> +Note that there is no explicit flag in the return value
> +corresponding to
> +.BR PR_SVE_SET_VL_ONEXEC .
> +.IP
> +The configuration (including any pending deferred change)
> +is inherited across
> +.BR fork (2)
> +and
> +.BR clone (2).
> +.IP
> +For more information, see the kernel source file
> +.I Documentation/arm64/sve.rst
> +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
> +(or
> +.I Documentation/arm64/sve.txt
> +before Linux 5.3).
> +.IP
> +.B Warning:
> +Because the compiler or run-time environment
> +may be using SVE, using this call without the
> +.B PR_SVE_SET_VL_ONEXEC
> +flag may crash the calling process.
> +The conditions for using it safely are complex and system-dependent.
> +Don't use it unless you really know what you are doing.
> +.\" prctl PR_SVE_GET_VL
> +.TP
> +.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
> +Get the thread's current SVE vector length configuration.
> +.IP
> +Arguments
> +.IR arg2 ", " arg3 ", " arg4 " and " arg5
> +are ignored.
> +.IP
> +Providing that the kernel and platform support SVE
> +this operation always succeeds,
> +returning a nonnegative value that describes the
> +.I current
> +configuration.
> +The bits corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +contain the currently configured vector length in bytes.
> +The bit corresponding to
> +.B PR_SVE_VL_INHERIT
> +indicates whether the vector length will be inherited
> +across
> +.BR execve (2).
> +.IP
> +Note that there is no way to determine whether there is
> +a pending vector length change that has not yet taken effect.
> +.IP
> +For more information, see the kernel source file
> +.I Documentation/arm64/sve.rst
> +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
> +(or
> +.I Documentation/arm64/sve.txt
> +before Linux 5.3).
>  .\"
>  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
> @@ -1613,6 +1765,8 @@ On success,
>  .BR PR_GET_NO_NEW_PRIVS ,
>  .BR PR_GET_SECUREBITS ,
>  .BR PR_GET_SPECULATION_CTRL ,
> +.BR PR_SVE_GET_VL ,
> +.BR PR_SVE_SET_VL ,
>  .BR PR_GET_THP_DISABLE ,
>  .BR PR_GET_TIMING ,
>  .BR PR_GET_TIMERSLACK ,
> @@ -1904,6 +2058,22 @@ See the description of
>  .B PR_PAC_RESET_KEYS
>  above for details.
>  .TP
> +.B EINVAL
> +.I option
> +is
> +.B PR_SVE_SET_VL
> +and the arguments are invalid or unsupported,
> +or SVE is not available on this platform.
> +See the description of
> +.B PR_SVE_SET_VL
> +above for details.
> +.TP
> +.B EINVAL
> +.I option
> +is
> +.B PR_SVE_GET_VL
> +and SVE is not available on this platform.
> +.TP
>  .B ENODEV
>  .I option
>  was
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v3 2/2] prctl.2: Add tagged address ABI control prctls (arm64)
  2020-06-24 17:36 ` [PATCH v3 2/2] prctl.2: Add tagged address ABI control " Dave Martin
@ 2020-06-26 11:23   ` Michael Kerrisk (man-pages)
  0 siblings, 0 replies; 6+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-06-26 11:23 UTC (permalink / raw)
  To: Dave Martin
  Cc: mtk.manpages, linux-man, linux-arch, linux-arm-kernel, Vincenzo Frascino

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and
> PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>
> Cc: Vincenzo Frascino <vincenzo.frascino@arm.com>

Thanks for another nicely written patch! I've applied locally, 
but won't push just yet, to allow for some (more) reviews/acks
to come in.

Thanks,

Michael

> ---
> 
> Kept Catalin's Reviewed-by, since the changes are pretty minor.
> 
> Changes since v2:
> 
>  * Clarified type of PR_SET_TAGGED_ADDR_CTRL arg2.
> 
>  * Added Linux commit where enforecement of zeroing reserved args was
>    added for PR_SET_TAGGED_ADDR_CTRL.
> 
>  * Added explicit text regarding how to disable the tagged-address ABI
>    globally through sysctl.
> 
>  * Rearrange the tagged argument syscall exclusion list so that shmdt()
>    isn't called out specially.  The reader probably doesn't care about
>    this history here.
> 
>  * Minor rewordings.
> ---
>  man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 161 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 46ea9d2..cf92f3b 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1522,6 +1522,148 @@ For more information, see the kernel source file
>  (or
>  .I Documentation/arm64/sve.txt
>  before Linux 5.3).
> +.\" prctl PR_SET_TAGGED_ADDR_CTRL
> +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> +.TP
> +.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
> +Controls support for passing tagged userspace addresses to the kernel
> +(i.e., addresses where bits 56\(em63 are not all zero).
> +.IP
> +The level of support is selected by
> +.IR "arg2" ,
> +which can be one of the following:
> +.RS
> +.TP
> +.B 0
> +Addresses that are passed
> +for the purpose of being dereferenced by the kernel
> +must be untagged.
> +.TP
> +.B PR_TAGGED_ADDR_ENABLE
> +Addresses that are passed
> +for the purpose of being dereferenced by the kernel
> +may be tagged, with the exceptions summarized below.
> +.RE
> +.IP
> +The remaining arguments
> +.IR arg3 ", " arg4 " and " arg5
> +must all be zero.
> +.\" Enforcement added in
> +.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95
> +.IP
> +On success, the mode specified in
> +.I arg2
> +is set for the calling thread and the the return value is 0.
> +If the arguments are invalid,
> +the mode specified in
> +.I arg2
> +is unrecognized,
> +or if this feature is unsupported by the kernel
> +or disabled via
> +.IR /proc/sys/abi/tagged_addr_disabled ,
> +the call fails with
> +.BR EINVAL .
> +.IP
> +In particular, if
> +.BR prctl ( PR_SET_TAGGED_ADDR_CTRL ,
> +0, 0, 0, 0)
> +fails with
> +.B EINVAL
> +then all addresses passed to the kernel must be untagged.
> +.IP
> +Irrespective of which mode is set,
> +addresses passed to certain interfaces
> +must always be untagged:
> +.RS
> +.IP \(em
> +.BR brk (2),
> +.BR mmap (2),
> +.BR shmat (2),
> +.BR shmdt (2),
> +and the
> +.I new_address
> +argument of
> +.BR mremap (2).
> +.IP
> +(Prior to Linux 5.6 these accepted tagged addresses,
> +but the behaviour may not be what you expect.
> +Don't rely on it.)
> +.IP \(em
> +\(oqpolymorphic\(cq interfaces
> +that accept pointers to arbitrary types cast to a
> +.I void *
> +or other generic type, specifically
> +.BR prctl (2),
> +.BR ioctl (2),
> +and in general
> +.BR setsockopt (2)
> +(only certain specific
> +.BR setsockopt (2)
> +options allow tagged addresses).
> +.RE
> +.IP
> +This list of exclusions may shrink
> +when moving from one kernel version to a later kernel version.
> +While the kernel may make some guarantees
> +for backwards compatibility reasons,
> +for the purposes of new software
> +the effect of passing tagged addresses to these interfaces
> +is unspecified.
> +.IP
> +The mode set by this call is inherited across
> +.BR fork (2)
> +and
> +.BR clone (2).
> +The mode is reset by
> +.BR execve (2)
> +to 0
> +(i.e., tagged addresses not permitted in the user/kernel ABI).
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/arm64/tagged\-address\-abi.rst .
> +.IP
> +.B Warning:
> +This call is primarily intended for use by the run-time environment.
> +A successful
> +.B PR_SET_TAGGED_ADDR_CTRL
> +call elsewhere may crash the calling process.
> +The conditions for using it safely are complex and system-dependent;
> +Don't use it unless you know what you are doing.
> +.\" prctl PR_GET_TAGGED_ADDR_CTRL
> +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> +.TP
> +.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
> +Returns the current tagged address mode
> +for the calling thread.
> +.IP
> +Arguments
> +.IR arg2 ", " arg3 ", " arg4 " and " arg5
> +must all be zero.
> +.IP
> +If the arguments are invalid
> +or this feature is disabled or unsupported by the kernel,
> +the call fails with
> +.BR EINVAL .
> +In particular, if
> +.BR prctl ( PR_GET_TAGGED_ADDR_CTRL ,
> +0, 0, 0, 0)
> +fails with
> +.BR EINVAL ,
> +then this feature is definitely either unsupported,
> +or disabled via
> +.IR /proc/sys/abi/tagged_addr_disabled .
> +In this case,
> +all addresses passed to the kernel must be untagged.
> +.IP
> +Otherwise, the call returns a nonnegative value
> +describing the current tagged address mode,
> +encoded in the same way as the
> +.I arg2
> +argument of
> +.BR PR_SET_TAGGED_ADDR_CTRL .
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/arm64/tagged\-address\-abi.rst .
>  .\"
>  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
> @@ -1767,6 +1909,7 @@ On success,
>  .BR PR_GET_SPECULATION_CTRL ,
>  .BR PR_SVE_GET_VL ,
>  .BR PR_SVE_SET_VL ,
> +.BR PR_GET_TAGGED_ADDR_CTRL ,
>  .BR PR_GET_THP_DISABLE ,
>  .BR PR_GET_TIMING ,
>  .BR PR_GET_TIMERSLACK ,
> @@ -2074,6 +2217,24 @@ is
>  .B PR_SVE_GET_VL
>  and SVE is not available on this platform.
>  .TP
> +.B EINVAL
> +.I option
> +is
> +.BR PR_SET_TAGGED_ADDR_CTRL
> +and the arguments are invalid or unsupported.
> +See the description of
> +.B PR_SET_TAGGED_ADDR_CTRL
> +above for details.
> +.TP
> +.B EINVAL
> +.I option
> +is
> +.BR PR_GET_TAGGED_ADDR_CTRL
> +and the arguments are invalid or unsupported.
> +See the description of
> +.B PR_GET_TAGGED_ADDR_CTRL
> +above for details.
> +.TP
>  .B ENODEV
>  .I option
>  was
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 6+ messages in thread

* Re: [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6
  2020-06-24 17:36 [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6 Dave Martin
  2020-06-24 17:36 ` [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64) Dave Martin
  2020-06-24 17:36 ` [PATCH v3 2/2] prctl.2: Add tagged address ABI control " Dave Martin
@ 2020-06-29 11:52 ` Michael Kerrisk (man-pages)
  2 siblings, 0 replies; 6+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-06-29 11:52 UTC (permalink / raw)
  To: Dave Martin
  Cc: mtk.manpages, linux-man, linux-arch, linux-arm-kernel,
	Catalin Marinas, Mark Rutland, Will Deacon, Vincenzo Frascino

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> A bunch of updates to the prctl(2) man page to fill in missing
> prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> fixes).
> 
> Patches from the v2 series [1] that have been applied or rejected
> already have been dropped.
> 
> All that remain here now are the SVE and tagged address ABI controls
> for arm64.
> 
> 
> 
> [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> 
> 
> Dave Martin (2):
>   prctl.2: Add SVE prctls (arm64)
>   prctl.2: Add tagged address ABI control prctls (arm64)
> 
>  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 331 insertions(+)
Thanks. I've pushed these changes to master now.

Cheers,

Michael



-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, back to index

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-06-24 17:36 [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6 Dave Martin
2020-06-24 17:36 ` [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64) Dave Martin
2020-06-26 11:23   ` Michael Kerrisk (man-pages)
2020-06-24 17:36 ` [PATCH v3 2/2] prctl.2: Add tagged address ABI control " Dave Martin
2020-06-26 11:23   ` Michael Kerrisk (man-pages)
2020-06-29 11:52 ` [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6 Michael Kerrisk (man-pages)

Linux-man Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/linux-man/0 linux-man/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 linux-man linux-man/ https://lore.kernel.org/linux-man \
		linux-man@vger.kernel.org
	public-inbox-index linux-man

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-man


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git