From: "Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
To: Dave Martin <Dave.Martin@arm.com>
Cc: linux-arch@vger.kernel.org, linux-man@vger.kernel.org,
Catalin Marinas <catalin.marinas@arm.com>,
mtk.manpages@gmail.com, Will Deacon <will@kernel.org>,
linux-arm-kernel@lists.infradead.org
Subject: Re: [PATCH v2 4/6] prctl.2: Add SVE prctls (arm64)
Date: Tue, 9 Jun 2020 13:39:03 +0200 [thread overview]
Message-ID: <77b02e4a-bfcf-90ef-90ca-73e878b7b649@gmail.com> (raw)
In-Reply-To: <1590614258-24728-5-git-send-email-Dave.Martin@arm.com>
Hi Dave,
I've not applied this patch yet, in case you want to make
some changes in response to Will's comments.
I think all of the rest of the patches in the series are now
applied (and pushed to master).
Thanks,
Michael
On 5/27/20 11:17 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 v1:
>
> * Minor rewordings and typo fixes.
>
> * Fix typo'd #define names.
>
> * Add type annotation for PR_SVE_SET_VL arg2.
>
> * Clarify return value semantics of PR_SVE_SET_VL
>
> * Add note to say that the args for PR_SVE_GET_VL are ignored.
>
> * Note for PR_SVE_SET_VL that the PR_SVE_VL_LEN_MASK field specifies
> an upper bound on what vector length to set, not an exact value.
>
> * Rework PR_SVE_SET_VL arg2 description to enumerate all possible flag
> combinations rather than describing the flags independently.
>
> Coming up with a clear description of each flag that is independent
> of the description of the other flag turns out to be hard.
>
> * In lieu of having a separate man page to cross reference for detailed
> guidance, cross-reference the kernel documentation.
>
> * Avoid confusing cross-reference to PR_SVE_SET_VL when describing the
> return value of PR_SVE_GET_VL.
>
> * Clarify error conditions for PR_SVE_SET_VL and PR_SVE_GET_VL, and
> move detail to the individual prctl descriptions to keep related
> content close together while minimising duplication.
>
> * Add safety warning. This is deliberately vague, pending ongoing
> discussions with libc folks.
> ---
> man2/prctl.2 | 160 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 160 insertions(+)
>
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index cab9915..91df7c8 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1291,6 +1291,148 @@ 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,
> +.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,
> +which may differ from the current configuration if
> +.B PR_SVE_SET_VL_ONEXEC
> +was specified.
> +The value is encoded in the same way as the return value of
> +.BR PR_SVE_GET_VL .
> +.IP
> +The configuration (including any pending deferred change)
> +is inherited across
> +.BR fork (2)
> +and
> +.BR clone (2).
> +.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.
> +.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_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
> @@ -1534,6 +1676,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 ,
> @@ -1817,6 +1961,22 @@ and unused arguments to
> .BR prctl ()
> are not 0.
> .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/
_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel
next prev parent reply other threads:[~2020-06-09 11:39 UTC|newest]
Thread overview: 37+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-27 21:17 [PATCH v2 0/6] prctl.2 man page updates for Linux 5.6 Dave Martin
2020-05-27 21:17 ` [PATCH v2 1/6] prctl.2: ffix use literal hyphens when referencing kernel docs Dave Martin
2020-05-28 6:05 ` Michael Kerrisk (man-pages)
2020-05-27 21:17 ` [PATCH v2 2/6] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls Dave Martin
2020-05-28 7:01 ` Michael Kerrisk (man-pages)
2020-06-01 13:51 ` Dave Martin
2020-06-09 11:00 ` Michael Kerrisk (man-pages)
2020-05-27 21:17 ` [PATCH v2 3/6] prctl.2: Add PR_SPEC_DISABLE_NOEXEC " Dave Martin
2020-05-28 6:57 ` Michael Kerrisk (man-pages)
2020-05-28 13:45 ` Waiman Long
2020-05-27 21:17 ` [PATCH v2 4/6] prctl.2: Add SVE prctls (arm64) Dave Martin
2020-06-09 9:57 ` Will Deacon
2020-06-09 14:11 ` Dave Martin
2020-06-09 14:49 ` Will Deacon
2020-06-10 9:44 ` Dave Martin
2020-06-10 10:16 ` Will Deacon
2020-06-10 12:48 ` Dave Martin
2020-06-09 11:39 ` Michael Kerrisk (man-pages) [this message]
2020-06-10 9:45 ` Dave Martin
2020-05-27 21:17 ` [PATCH v2 5/6] prctl.2: Add PR_PAC_RESET_KEYS (arm64) Dave Martin
2020-06-09 10:02 ` Will Deacon
2020-06-09 11:03 ` Michael Kerrisk (man-pages)
2020-06-09 11:36 ` Michael Kerrisk (man-pages)
2020-06-09 14:16 ` Dave Martin
2020-06-09 18:11 ` Michael Kerrisk (man-pages)
2020-05-27 21:17 ` [RFC PATCH v2 6/6] prctl.2: Add tagged address ABI control prctls (arm64) Dave Martin
2020-06-09 11:04 ` Michael Kerrisk (man-pages)
2020-06-09 13:38 ` Will Deacon
2020-06-09 17:22 ` Catalin Marinas
2020-06-10 10:06 ` Dave Martin
2020-06-10 15:26 ` Catalin Marinas
2020-06-10 16:42 ` Dave Martin
2020-06-10 17:42 ` Catalin Marinas
2020-06-15 14:51 ` Dave Martin
2020-06-24 9:54 ` Michael Kerrisk (man-pages)
2020-06-24 10:29 ` Dave Martin
2020-05-28 7:11 ` [PATCH v2 0/6] prctl.2 man page updates for Linux 5.6 Michael Kerrisk (man-pages)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=77b02e4a-bfcf-90ef-90ca-73e878b7b649@gmail.com \
--to=mtk.manpages@gmail.com \
--cc=Dave.Martin@arm.com \
--cc=catalin.marinas@arm.com \
--cc=linux-arch@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-man@vger.kernel.org \
--cc=will@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).