* [PATCH 0/5] riscv: Fixes for vector extension documentation
@ 2023-05-14 9:04 Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 1/5] Documentation: riscv: vector: Separate SPDX license identifier and page title Bagas Sanjaya
` (4 more replies)
0 siblings, 5 replies; 8+ messages in thread
From: Bagas Sanjaya @ 2023-05-14 9:04 UTC (permalink / raw
To: Linux Documentation, Linux RISC-V, Linux Kernel Mailing List
Cc: Jonathan Corbet, Paul Walmsley, Palmer Dabbelt, Albert Ou,
Bagas Sanjaya, Vincent Chen, Andy Chiu, Greentime Hu
Here are documentation fixes for vector extension support. The first
two fixes kernel test robot report [1], while the rest is bullet lists
fixup.
[1]: https://lore.kernel.org/linux-doc/202305141409.bEBvlSY4-lkp@intel.com/
Bagas Sanjaya (5):
Documentation: riscv: vector: Separate SPDX license identifier and
page title
Documentation: riscv: vector: Wrap control_argument struct definition
in code block
Documentation: riscv: vector: Use bullet lists for prctl list
Documentation: riscv: vector: Use bullet lists for prctl() return
values
Documentation: riscv: vector: Fix bullet list usage on sysctl section
Documentation/riscv/vector.rst | 66 ++++++++++++++++++----------------
1 file changed, 35 insertions(+), 31 deletions(-)
base-commit: aab772f330541c3876484bcff439bb39b2784cf7
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH 1/5] Documentation: riscv: vector: Separate SPDX license identifier and page title
2023-05-14 9:04 [PATCH 0/5] riscv: Fixes for vector extension documentation Bagas Sanjaya
@ 2023-05-14 9:04 ` Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 2/5] Documentation: riscv: vector: Wrap control_argument struct definition in code block Bagas Sanjaya
` (3 subsequent siblings)
4 siblings, 0 replies; 8+ messages in thread
From: Bagas Sanjaya @ 2023-05-14 9:04 UTC (permalink / raw
To: Linux Documentation, Linux RISC-V, Linux Kernel Mailing List
Cc: Jonathan Corbet, Paul Walmsley, Palmer Dabbelt, Albert Ou,
Bagas Sanjaya, Vincent Chen, Andy Chiu, Greentime Hu,
kernel test robot
kernel test robot reports htmldocs warning:
Documentation/riscv/vector.rst:2: WARNING: Explicit markup ends without a blank line; unexpected unindent.
Add a blank line separator between SPDX tag and doc title to fix above warning.
Fixes: 412c68cfeeb178 ("riscv: Add documentation for Vector")
Reported-by: kernel test robot <lkp@intel.com>
Closes: https://lore.kernel.org/linux-doc/202305141409.bEBvlSY4-lkp@intel.com/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
Documentation/riscv/vector.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/riscv/vector.rst b/Documentation/riscv/vector.rst
index d4d626721921aa..acc97508ccb249 100644
--- a/Documentation/riscv/vector.rst
+++ b/Documentation/riscv/vector.rst
@@ -1,4 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0
+
=========================================
Vector Extension Support for RISC-V Linux
=========================================
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 2/5] Documentation: riscv: vector: Wrap control_argument struct definition in code block
2023-05-14 9:04 [PATCH 0/5] riscv: Fixes for vector extension documentation Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 1/5] Documentation: riscv: vector: Separate SPDX license identifier and page title Bagas Sanjaya
@ 2023-05-14 9:04 ` Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 3/5] Documentation: riscv: vector: Use bullet lists for prctl list Bagas Sanjaya
` (2 subsequent siblings)
4 siblings, 0 replies; 8+ messages in thread
From: Bagas Sanjaya @ 2023-05-14 9:04 UTC (permalink / raw
To: Linux Documentation, Linux RISC-V, Linux Kernel Mailing List
Cc: Jonathan Corbet, Paul Walmsley, Palmer Dabbelt, Albert Ou,
Bagas Sanjaya, Vincent Chen, Andy Chiu, Greentime Hu,
kernel test robot
kernel test robot reports htmldocs warning:
Documentation/riscv/vector.rst:45: WARNING: Definition list ends without a blank line; unexpected unindent.
The warning is due to definition of control_argument struct, written
unformatted. Wrap it in code block with C syntax highlighting to fix the
warning.
Fixes: 412c68cfeeb178 ("riscv: Add documentation for Vector")
Reported-by: kernel test robot <lkp@intel.com>
Closes: https://lore.kernel.org/oe-kbuild-all/202305141409.bEBvlSY4-lkp@intel.com/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
Documentation/riscv/vector.rst | 18 ++++++++++--------
1 file changed, 10 insertions(+), 8 deletions(-)
diff --git a/Documentation/riscv/vector.rst b/Documentation/riscv/vector.rst
index acc97508ccb249..178b3f3f452462 100644
--- a/Documentation/riscv/vector.rst
+++ b/Documentation/riscv/vector.rst
@@ -36,14 +36,16 @@ prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
be interpreted as the following structure, and accessed by 3 masks
respectively.
- struct control_argument {
- // Located by PR_RISCV_V_VSTATE_CTRL_CUR_MASK
- int current_enablement_status : 2;
- // Located by PR_RISCV_V_VSTATE_CTRL_NEXT_MASK
- int next_enablement_status : 2;
- // Located by PR_RISCV_V_VSTATE_CTRL_INHERIT
- bool inherit_mode : 1;
- }
+ .. code-block:: c
+
+ struct control_argument {
+ // Located by PR_RISCV_V_VSTATE_CTRL_CUR_MASK
+ int current_enablement_status : 2;
+ // Located by PR_RISCV_V_VSTATE_CTRL_NEXT_MASK
+ int next_enablement_status : 2;
+ // Located by PR_RISCV_V_VSTATE_CTRL_INHERIT
+ bool inherit_mode : 1;
+ }
The 3 masks, PR_RISCV_V_VSTATE_CTRL_CUR_MASK,
PR_RISCV_V_VSTATE_CTRL_NEXT_MASK, and PR_RISCV_V_VSTATE_CTRL_INHERIT
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 3/5] Documentation: riscv: vector: Use bullet lists for prctl list
2023-05-14 9:04 [PATCH 0/5] riscv: Fixes for vector extension documentation Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 1/5] Documentation: riscv: vector: Separate SPDX license identifier and page title Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 2/5] Documentation: riscv: vector: Wrap control_argument struct definition in code block Bagas Sanjaya
@ 2023-05-14 9:04 ` Bagas Sanjaya
2023-05-14 9:49 ` Conor Dooley
2023-05-14 9:04 ` [PATCH 4/5] Documentation: riscv: vector: Use bullet lists for prctl() return values Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 5/5] Documentation: riscv: vector: Fix bullet list usage on sysctl section Bagas Sanjaya
4 siblings, 1 reply; 8+ messages in thread
From: Bagas Sanjaya @ 2023-05-14 9:04 UTC (permalink / raw
To: Linux Documentation, Linux RISC-V, Linux Kernel Mailing List
Cc: Jonathan Corbet, Paul Walmsley, Palmer Dabbelt, Albert Ou,
Bagas Sanjaya, Vincent Chen, Andy Chiu, Greentime Hu
The documentation lists two userspace prctl() calls. Use bullet
lists for the listing.
Fixes: 412c68cfeeb178 ("riscv: Add documentation for Vector")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
Documentation/riscv/vector.rst | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/Documentation/riscv/vector.rst b/Documentation/riscv/vector.rst
index 178b3f3f452462..c7bd701c7963b6 100644
--- a/Documentation/riscv/vector.rst
+++ b/Documentation/riscv/vector.rst
@@ -13,7 +13,7 @@ order to support the use of the RISC-V Vector Extension.
Two new prctl() calls are added to allow programs to manage the enablement
status for the use of Vector in userspace:
-prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
+* prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
Sets the Vector enablement status of the calling thread, where the control
argument consists of two 2-bit enablement statuses and a bit for inheritance
@@ -89,7 +89,7 @@ prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
* Every successful call overwrites a previous setting for the calling
thread.
-prctl(PR_RISCV_V_SET_CONTROL)
+* prctl(PR_RISCV_V_SET_CONTROL)
Gets the same Vector enablement status for the calling thread. Setting for
next execve() call and the inheritance bit are all OR-ed together.
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 4/5] Documentation: riscv: vector: Use bullet lists for prctl() return values
2023-05-14 9:04 [PATCH 0/5] riscv: Fixes for vector extension documentation Bagas Sanjaya
` (2 preceding siblings ...)
2023-05-14 9:04 ` [PATCH 3/5] Documentation: riscv: vector: Use bullet lists for prctl list Bagas Sanjaya
@ 2023-05-14 9:04 ` Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 5/5] Documentation: riscv: vector: Fix bullet list usage on sysctl section Bagas Sanjaya
4 siblings, 0 replies; 8+ messages in thread
From: Bagas Sanjaya @ 2023-05-14 9:04 UTC (permalink / raw
To: Linux Documentation, Linux RISC-V, Linux Kernel Mailing List
Cc: Jonathan Corbet, Paul Walmsley, Palmer Dabbelt, Albert Ou,
Bagas Sanjaya, Vincent Chen, Andy Chiu, Greentime Hu
Use bullet lists on return values of prctl() calls to follow other
listings (bit lists and enablement status). This should convey purposes
of listing things.
Fixes: 412c68cfeeb178 ("riscv: Add documentation for Vector")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
Documentation/riscv/vector.rst | 16 +++++++++-------
1 file changed, 9 insertions(+), 7 deletions(-)
diff --git a/Documentation/riscv/vector.rst b/Documentation/riscv/vector.rst
index c7bd701c7963b6..4624e5b9bef4cc 100644
--- a/Documentation/riscv/vector.rst
+++ b/Documentation/riscv/vector.rst
@@ -74,11 +74,12 @@ status for the use of Vector in userspace:
PR_RISCV_V_VSTATE_CTRL_NEXT_MASK and PR_RISCV_V_VSTATE_CTRL_INHERIT.
This setting persists across changes in the system-wide default value.
- Return value: return 0 on success, or a negative error value:
- EINVAL: Vector not supported, invalid enablement status for current or
- next mask
- EPERM: Turning off Vector in PR_RISCV_V_VSTATE_CTRL_CUR_MASK if Vector
- was enabled for the calling thread.
+ Return value:
+ * 0 on success;
+ * EINVAL: Vector not supported, invalid enablement status for current or
+ next mask;
+ * EPERM: Turning off Vector in PR_RISCV_V_VSTATE_CTRL_CUR_MASK if Vector
+ was enabled for the calling thread.
On success:
* A valid setting for PR_RISCV_V_VSTATE_CTRL_CUR_MASK takes place
@@ -94,8 +95,9 @@ status for the use of Vector in userspace:
Gets the same Vector enablement status for the calling thread. Setting for
next execve() call and the inheritance bit are all OR-ed together.
- Return value: a nonnegative value on success, or a negative error value:
- EINVAL: Vector not supported.
+ Return value:
+ * a nonnegative value on success;
+ * EINVAL: Vector not supported.
2. System runtime configuration (sysctl)
-----------------------------------------
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply related [flat|nested] 8+ messages in thread
* [PATCH 5/5] Documentation: riscv: vector: Fix bullet list usage on sysctl section
2023-05-14 9:04 [PATCH 0/5] riscv: Fixes for vector extension documentation Bagas Sanjaya
` (3 preceding siblings ...)
2023-05-14 9:04 ` [PATCH 4/5] Documentation: riscv: vector: Use bullet lists for prctl() return values Bagas Sanjaya
@ 2023-05-14 9:04 ` Bagas Sanjaya
4 siblings, 0 replies; 8+ messages in thread
From: Bagas Sanjaya @ 2023-05-14 9:04 UTC (permalink / raw
To: Linux Documentation, Linux RISC-V, Linux Kernel Mailing List
Cc: Jonathan Corbet, Paul Walmsley, Palmer Dabbelt, Albert Ou,
Bagas Sanjaya, Vincent Chen, Andy Chiu, Greentime Hu
Prose sentences are better written as normal paragraph instead of
using bullet lists.
Also, use bullet list for list of riscv_v_default_allow values.
Fixes: 412c68cfeeb178 ("riscv: Add documentation for Vector")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
Documentation/riscv/vector.rst | 27 +++++++++++++--------------
1 file changed, 13 insertions(+), 14 deletions(-)
diff --git a/Documentation/riscv/vector.rst b/Documentation/riscv/vector.rst
index 4624e5b9bef4cc..f752826871b0e2 100644
--- a/Documentation/riscv/vector.rst
+++ b/Documentation/riscv/vector.rst
@@ -102,25 +102,24 @@ status for the use of Vector in userspace:
2. System runtime configuration (sysctl)
-----------------------------------------
- * To mitigate the ABI impact of expansion of the signal stack, a
- policy mechanism is provided to the administrators, distro maintainers, and
- developers to control the default Vector enablement status for userspace
- processes:
+To mitigate the ABI impact of expansion of the signal stack, a
+policy mechanism is provided to the administrators, distro maintainers, and
+developers to control the default Vector enablement status for userspace
+processes in form of sysctl knob:
-/proc/sys/abi/riscv_v_default_allow
+* /proc/sys/abi/riscv_v_default_allow
Writing the text representation of 0 or 1 to this file sets the default
- system enablement status for new starting userspace programs. A valid value
- should be:
+ system enablement status for new starting userspace programs. Valid values
+ are:
- 0: Do not allow Vector code to be executed as the default for new processes.
-
- 1: Allow Vector code to be executed as the default for new processes.
+ * 0: Do not allow Vector code to be executed as the default for new processes.
+ * 1: Allow Vector code to be executed as the default for new processes.
Reading this file returns the current system default enablement status.
-* At every execve() call, a new enablement status of the new process is set to
- the system default, unless:
+ At every execve() call, a new enablement status of the new process is set to
+ the system default, unless:
* PR_RISCV_V_VSTATE_CTRL_INHERIT is set for the calling process, and the
setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not
@@ -129,5 +128,5 @@ status for the use of Vector in userspace:
* The setting in PR_RISCV_V_VSTATE_CTRL_NEXT_MASK is not
PR_RISCV_V_VSTATE_CTRL_DEFAULT.
-* Modifying the system default enablement status does not affect the enablement
- status of any existing process of thread that do not make an execve() call.
+ Modifying the system default enablement status does not affect the enablement
+ status of any existing process of thread that do not make an execve() call.
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH 3/5] Documentation: riscv: vector: Use bullet lists for prctl list
2023-05-14 9:04 ` [PATCH 3/5] Documentation: riscv: vector: Use bullet lists for prctl list Bagas Sanjaya
@ 2023-05-14 9:49 ` Conor Dooley
2023-05-16 14:28 ` Andy Chiu
0 siblings, 1 reply; 8+ messages in thread
From: Conor Dooley @ 2023-05-14 9:49 UTC (permalink / raw
To: Bagas Sanjaya
Cc: Linux Documentation, Linux RISC-V, Linux Kernel Mailing List,
Jonathan Corbet, Paul Walmsley, Palmer Dabbelt, Albert Ou,
Vincent Chen, Andy Chiu, Greentime Hu
[-- Attachment #1: Type: text/plain, Size: 2277 bytes --]
Hey Bagas,
On Sun, May 14, 2023 at 04:04:30PM +0700, Bagas Sanjaya wrote:
> The documentation lists two userspace prctl() calls. Use bullet
> lists for the listing.
>
> Fixes: 412c68cfeeb178 ("riscv: Add documentation for Vector")
Firstly, these fixes commit hashes would not be stable as this series
has been applied to riscv/for-next [1]. But also, from this commit
onwards, things seem like stylistic comments that would be undeserving
of a Fixes: tag to begin with.
Perhaps you'd be better off suggesting these changes in response to the
original thread [2], so that it goes in "correctly" in the first place?
Andy has to re-submit anyway as there are a few bugs that crept in in
the most recent revision of his series.
Thanks,
Conor.
1 - https://git.kernel.org/pub/scm/linux/kernel/git/riscv/linux.git/log/?h=for-next
2 - https://lore.kernel.org/linux-riscv/20230509103033.11285-25-andy.chiu@sifive.com/
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
> Documentation/riscv/vector.rst | 4 ++--
> 1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/riscv/vector.rst b/Documentation/riscv/vector.rst
> index 178b3f3f452462..c7bd701c7963b6 100644
> --- a/Documentation/riscv/vector.rst
> +++ b/Documentation/riscv/vector.rst
> @@ -13,7 +13,7 @@ order to support the use of the RISC-V Vector Extension.
> Two new prctl() calls are added to allow programs to manage the enablement
> status for the use of Vector in userspace:
>
> -prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
> +* prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
>
> Sets the Vector enablement status of the calling thread, where the control
> argument consists of two 2-bit enablement statuses and a bit for inheritance
> @@ -89,7 +89,7 @@ prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
> * Every successful call overwrites a previous setting for the calling
> thread.
>
> -prctl(PR_RISCV_V_SET_CONTROL)
> +* prctl(PR_RISCV_V_SET_CONTROL)
>
> Gets the same Vector enablement status for the calling thread. Setting for
> next execve() call and the inheritance bit are all OR-ed together.
> --
> An old man doll... just what I always wanted! - Clara
>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]
^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH 3/5] Documentation: riscv: vector: Use bullet lists for prctl list
2023-05-14 9:49 ` Conor Dooley
@ 2023-05-16 14:28 ` Andy Chiu
0 siblings, 0 replies; 8+ messages in thread
From: Andy Chiu @ 2023-05-16 14:28 UTC (permalink / raw
To: Conor Dooley
Cc: Bagas Sanjaya, Linux Documentation, Linux RISC-V,
Linux Kernel Mailing List, Jonathan Corbet, Paul Walmsley,
Palmer Dabbelt, Albert Ou, Vincent Chen, Greentime Hu
Hi Bagas,
On Sun, May 14, 2023 at 5:49 PM Conor Dooley <conor@kernel.org> wrote:
>
> Hey Bagas,
>
> On Sun, May 14, 2023 at 04:04:30PM +0700, Bagas Sanjaya wrote:
> > The documentation lists two userspace prctl() calls. Use bullet
> > lists for the listing.
> >
> > Fixes: 412c68cfeeb178 ("riscv: Add documentation for Vector")
>
> Firstly, these fixes commit hashes would not be stable as this series
> has been applied to riscv/for-next [1]. But also, from this commit
> onwards, things seem like stylistic comments that would be undeserving
> of a Fixes: tag to begin with.
> Perhaps you'd be better off suggesting these changes in response to the
> original thread [2], so that it goes in "correctly" in the first place?
> Andy has to re-submit anyway as there are a few bugs that crept in in
> the most recent revision of his series.
>
> Thanks,
> Conor.
>
> 1 - https://git.kernel.org/pub/scm/linux/kernel/git/riscv/linux.git/log/?h=for-next
> 2 - https://lore.kernel.org/linux-riscv/20230509103033.11285-25-andy.chiu@sifive.com/
>
> > Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> > ---
> > Documentation/riscv/vector.rst | 4 ++--
> > 1 file changed, 2 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/riscv/vector.rst b/Documentation/riscv/vector.rst
> > index 178b3f3f452462..c7bd701c7963b6 100644
> > --- a/Documentation/riscv/vector.rst
> > +++ b/Documentation/riscv/vector.rst
> > @@ -13,7 +13,7 @@ order to support the use of the RISC-V Vector Extension.
> > Two new prctl() calls are added to allow programs to manage the enablement
> > status for the use of Vector in userspace:
> >
> > -prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
> > +* prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
> >
> > Sets the Vector enablement status of the calling thread, where the control
> > argument consists of two 2-bit enablement statuses and a bit for inheritance
> > @@ -89,7 +89,7 @@ prctl(PR_RISCV_V_SET_CONTROL, unsigned long arg)
> > * Every successful call overwrites a previous setting for the calling
> > thread.
> >
> > -prctl(PR_RISCV_V_SET_CONTROL)
> > +* prctl(PR_RISCV_V_SET_CONTROL)
> >
> > Gets the same Vector enablement status for the calling thread. Setting for
> > next execve() call and the inheritance bit are all OR-ed together.
> > --
> > An old man doll... just what I always wanted! - Clara
> >
Thanks for fixing the document. Do you mind if I merge them into my
patch and add you as a co-developer? I think merging those fixes into
the one original patch would be much cleaner than providing fix
patches afterward.
Thanks,
Andy
^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2023-05-16 14:28 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2023-05-14 9:04 [PATCH 0/5] riscv: Fixes for vector extension documentation Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 1/5] Documentation: riscv: vector: Separate SPDX license identifier and page title Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 2/5] Documentation: riscv: vector: Wrap control_argument struct definition in code block Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 3/5] Documentation: riscv: vector: Use bullet lists for prctl list Bagas Sanjaya
2023-05-14 9:49 ` Conor Dooley
2023-05-16 14:28 ` Andy Chiu
2023-05-14 9:04 ` [PATCH 4/5] Documentation: riscv: vector: Use bullet lists for prctl() return values Bagas Sanjaya
2023-05-14 9:04 ` [PATCH 5/5] Documentation: riscv: vector: Fix bullet list usage on sysctl section Bagas Sanjaya
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 read-only IMAP folder(s) and NNTP newsgroup(s).