[PATCH v2 0/4] arm64/fp: Documentation cleanups and clarifications

[PATCH v2 0/4] arm64/fp: Documentation cleanups and clarifications

[Mark Brown]

Edwin noticed some issues with the SVE and SME documentation which are
corrected by this series.

Signed-off-by: Mark Brown <broonie@kernel.org>
---
Changes in v2:
- Explicitly say which prtcl() configures the vector length.
- Link to v1: https://lore.kernel.org/r/20240122-arm64-sve-sme-doc-v1-0-3d492e45265b@kernel.org

---
Mark Brown (4):
      arm64/sve: Remove bitrotted comment about syscall behaviour
      arm64/sme: Fix cut'n'paste in ABI document
      arm64/fp: Clarify effect of setting an unsupported system VL
      arm64/sme: Remove spurious 'is' in SME documentation

 Documentation/arch/arm64/sme.rst | 11 +++++------
 Documentation/arch/arm64/sve.rst | 10 ++--------
 2 files changed, 7 insertions(+), 14 deletions(-)
---
base-commit: 6613476e225e090cc9aad49be7fa504e290dd33d
change-id: 20240110-arm64-sve-sme-doc-bc62ec1a2005

Best regards,
-- 
Mark Brown <broonie@kernel.org>

[PATCH v2 1/4] arm64/sve: Remove bitrotted comment about syscall behaviour

[Mark Brown]

When we documented that we always clear state not shared with FPSIMD we
didn't catch all of the places that mentioned that state might not be
cleared, remove a lingering reference.

Reported-by: Edmund Grimley-Evans <edmund.grimley-evans@arm.com>
Reviewed-by: Dave Martin <Dave.Martin@arm.com>
Signed-off-by: Mark Brown <broonie@kernel.org>
---
 Documentation/arch/arm64/sve.rst | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/Documentation/arch/arm64/sve.rst b/Documentation/arch/arm64/sve.rst
index 0d9a426e9f85..b45a2da19bf1 100644
--- a/Documentation/arch/arm64/sve.rst
+++ b/Documentation/arch/arm64/sve.rst
@@ -117,11 +117,6 @@ the SVE instruction set architecture.
 * The SVE registers are not used to pass arguments to or receive results from
   any syscall.
 
-* In practice the affected registers/bits will be preserved or will be replaced
-  with zeros on return from a syscall, but userspace should not make
-  assumptions about this.  The kernel behaviour may vary on a case-by-case
-  basis.
-
 * All other SVE state of a thread, including the currently configured vector
   length, the state of the PR_SVE_VL_INHERIT flag, and the deferred vector
   length (if any), is preserved across all syscalls, subject to the specific

-- 
2.30.2

[PATCH v2 2/4] arm64/sme: Fix cut'n'paste in ABI document

[Mark Brown]

The ABI for SME is very like that for SVE so bits of the ABI were copied
but not adequately search and replaced, fix that.

Reported-by: Edmund Grimley-Evans <edmund.grimley-evans@arm.com>
Signed-off-by: Mark Brown <broonie@kernel.org>
---
 Documentation/arch/arm64/sme.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/arch/arm64/sme.rst b/Documentation/arch/arm64/sme.rst
index 3d0e53ecac4f..3133d0e91b48 100644
--- a/Documentation/arch/arm64/sme.rst
+++ b/Documentation/arch/arm64/sme.rst
@@ -238,12 +238,12 @@ prctl(PR_SME_SET_VL, unsigned long arg)
       bits of Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become
       unspecified, including both streaming and non-streaming SVE state.
       Calling PR_SME_SET_VL with vl equal to the thread's current vector
-      length, or calling PR_SME_SET_VL with the PR_SVE_SET_VL_ONEXEC flag,
+      length, or calling PR_SME_SET_VL with the PR_SME_SET_VL_ONEXEC flag,
       does not constitute a change to the vector length for this purpose.
 
     * Changing the vector length causes PSTATE.ZA and PSTATE.SM to be cleared.
       Calling PR_SME_SET_VL with vl equal to the thread's current vector
-      length, or calling PR_SME_SET_VL with the PR_SVE_SET_VL_ONEXEC flag,
+      length, or calling PR_SME_SET_VL with the PR_SME_SET_VL_ONEXEC flag,
       does not constitute a change to the vector length for this purpose.
 
 

-- 
2.30.2

Re: [PATCH v2 2/4] arm64/sme: Fix cut'n'paste in ABI document

[Dave Martin]

On Wed, Jan 24, 2024 at 06:12:36PM +0000, Mark Brown wrote:
> The ABI for SME is very like that for SVE so bits of the ABI were copied
> but not adequately search and replaced, fix that.
> 
> Reported-by: Edmund Grimley-Evans <edmund.grimley-evans@arm.com>
> Signed-off-by: Mark Brown <broonie@kernel.org>
> ---
>  Documentation/arch/arm64/sme.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/arch/arm64/sme.rst b/Documentation/arch/arm64/sme.rst
> index 3d0e53ecac4f..3133d0e91b48 100644
> --- a/Documentation/arch/arm64/sme.rst
> +++ b/Documentation/arch/arm64/sme.rst
> @@ -238,12 +238,12 @@ prctl(PR_SME_SET_VL, unsigned long arg)
>        bits of Z0..Z31 except for Z0 bits [127:0] .. Z31 bits [127:0] to become
>        unspecified, including both streaming and non-streaming SVE state.
>        Calling PR_SME_SET_VL with vl equal to the thread's current vector
> -      length, or calling PR_SME_SET_VL with the PR_SVE_SET_VL_ONEXEC flag,
> +      length, or calling PR_SME_SET_VL with the PR_SME_SET_VL_ONEXEC flag,
>        does not constitute a change to the vector length for this purpose.
>  
>      * Changing the vector length causes PSTATE.ZA and PSTATE.SM to be cleared.
>        Calling PR_SME_SET_VL with vl equal to the thread's current vector
> -      length, or calling PR_SME_SET_VL with the PR_SVE_SET_VL_ONEXEC flag,
> +      length, or calling PR_SME_SET_VL with the PR_SME_SET_VL_ONEXEC flag,
>        does not constitute a change to the vector length for this purpose.

Reviewed-by: Dave Martin <Dave.Martin@arm.com>

[PATCH v2 3/4] arm64/fp: Clarify effect of setting an unsupported system VL

[Mark Brown]

The documentation for system vector length configuration does not cover all
cases where unsupported values are written, tighten it up.

Reported-by: Edmund Grimley-Evans <edmund.grimley-evans@arm.com>
Signed-off-by: Mark Brown <broonie@kernel.org>
---
 Documentation/arch/arm64/sme.rst | 5 ++---
 Documentation/arch/arm64/sve.rst | 5 ++---
 2 files changed, 4 insertions(+), 6 deletions(-)

diff --git a/Documentation/arch/arm64/sme.rst b/Documentation/arch/arm64/sme.rst
index 3133d0e91b48..f4376c06f447 100644
--- a/Documentation/arch/arm64/sme.rst
+++ b/Documentation/arch/arm64/sme.rst
@@ -379,9 +379,8 @@ The regset data starts with struct user_za_header, containing:
 /proc/sys/abi/sme_default_vector_length
 
     Writing the text representation of an integer to this file sets the system
-    default vector length to the specified value, unless the value is greater
-    than the maximum vector length supported by the system in which case the
-    default vector length is set to that maximum.
+    default vector length to the specified value rounded to a supported value
+    using the same rules as for setting vector length via PR_SME_SET_VL.
 
     The result can be determined by reopening the file and reading its
     contents.
diff --git a/Documentation/arch/arm64/sve.rst b/Documentation/arch/arm64/sve.rst
index b45a2da19bf1..8d8837fc39ec 100644
--- a/Documentation/arch/arm64/sve.rst
+++ b/Documentation/arch/arm64/sve.rst
@@ -423,9 +423,8 @@ The regset data starts with struct user_sve_header, containing:
 /proc/sys/abi/sve_default_vector_length
 
     Writing the text representation of an integer to this file sets the system
-    default vector length to the specified value, unless the value is greater
-    than the maximum vector length supported by the system in which case the
-    default vector length is set to that maximum.
+    default vector length to the specified value rounded to a supported value
+    using the same rules as for setting vector length via PR_SVE_SET_VL.
 
     The result can be determined by reopening the file and reading its
     contents.

-- 
2.30.2

Re: [PATCH v2 3/4] arm64/fp: Clarify effect of setting an unsupported system VL

[Dave Martin]

On Wed, Jan 24, 2024 at 06:12:37PM +0000, Mark Brown wrote:
> The documentation for system vector length configuration does not cover all
> cases where unsupported values are written, tighten it up.
> 
> Reported-by: Edmund Grimley-Evans <edmund.grimley-evans@arm.com>
> Signed-off-by: Mark Brown <broonie@kernel.org>
> ---
>  Documentation/arch/arm64/sme.rst | 5 ++---
>  Documentation/arch/arm64/sve.rst | 5 ++---
>  2 files changed, 4 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/arch/arm64/sme.rst b/Documentation/arch/arm64/sme.rst
> index 3133d0e91b48..f4376c06f447 100644
> --- a/Documentation/arch/arm64/sme.rst
> +++ b/Documentation/arch/arm64/sme.rst
> @@ -379,9 +379,8 @@ The regset data starts with struct user_za_header, containing:
>  /proc/sys/abi/sme_default_vector_length
>  
>      Writing the text representation of an integer to this file sets the system
> -    default vector length to the specified value, unless the value is greater
> -    than the maximum vector length supported by the system in which case the
> -    default vector length is set to that maximum.
> +    default vector length to the specified value rounded to a supported value
> +    using the same rules as for setting vector length via PR_SME_SET_VL.
>  
>      The result can be determined by reopening the file and reading its
>      contents.
> diff --git a/Documentation/arch/arm64/sve.rst b/Documentation/arch/arm64/sve.rst
> index b45a2da19bf1..8d8837fc39ec 100644
> --- a/Documentation/arch/arm64/sve.rst
> +++ b/Documentation/arch/arm64/sve.rst
> @@ -423,9 +423,8 @@ The regset data starts with struct user_sve_header, containing:
>  /proc/sys/abi/sve_default_vector_length
>  
>      Writing the text representation of an integer to this file sets the system
> -    default vector length to the specified value, unless the value is greater
> -    than the maximum vector length supported by the system in which case the
> -    default vector length is set to that maximum.
> +    default vector length to the specified value rounded to a supported value
> +    using the same rules as for setting vector length via PR_SVE_SET_VL.
>  
>      The result can be determined by reopening the file and reading its
>      contents.

Since you picked up my suggestion, I guess I owe you a

Reviewed-by: Dave Martin <Dave.Martin@arm.com>

Cheers
---Dave

[PATCH v2 4/4] arm64/sme: Remove spurious 'is' in SME documentation

[Mark Brown]

Just a typographical error.

Reported-by: Edmund Grimley-Evans <edmund.grimley-evans@arm.com>
Reviewed-by: Dave Martin <Dave.Martin@arm.com>
Signed-off-by: Mark Brown <broonie@kernel.org>
---
 Documentation/arch/arm64/sme.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/arch/arm64/sme.rst b/Documentation/arch/arm64/sme.rst
index f4376c06f447..be317d457417 100644
--- a/Documentation/arch/arm64/sme.rst
+++ b/Documentation/arch/arm64/sme.rst
@@ -75,7 +75,7 @@ model features for SME is included in Appendix A.
 2.  Vector lengths
 ------------------
 
-SME defines a second vector length similar to the SVE vector length which is
+SME defines a second vector length similar to the SVE vector length which
 controls the size of the streaming mode SVE vectors and the ZA matrix array.
 The ZA matrix is square with each side having as many bytes as a streaming
 mode SVE vector.

-- 
2.30.2

Re: [PATCH v2 0/4] arm64/fp: Documentation cleanups and clarifications

[Catalin Marinas]

On Wed, 24 Jan 2024 18:12:34 +0000, Mark Brown wrote:
> Edwin noticed some issues with the SVE and SME documentation which are
> corrected by this series.
> 
> 

Applied to arm64 (for-next/documentation), thanks!

[1/4] arm64/sve: Remove bitrotted comment about syscall behaviour
      https://git.kernel.org/arm64/c/b4725d3e4603
[2/4] arm64/sme: Fix cut'n'paste in ABI document
      https://git.kernel.org/arm64/c/ae35792764bc
[3/4] arm64/fp: Clarify effect of setting an unsupported system VL
      https://git.kernel.org/arm64/c/3fd97cf3234c
[4/4] arm64/sme: Remove spurious 'is' in SME documentation
      https://git.kernel.org/arm64/c/e47c18c3b25e

-- 
Catalin