[v2] arm64/sve: Document that __SVE_VQ_MAX is much larger than needed

Message ID 20240209-arm64-sve-vl-max-comment-v2-1-111b283469ee@kernel.org
State New
Headers
Series [v2] arm64/sve: Document that __SVE_VQ_MAX is much larger than needed |

Commit Message

Mark Brown Feb. 9, 2024, 4:53 p.m. UTC
  __SVE_VQ_MAX is defined without comment as 512 but the actual
architectural maximum is 16, a substantial difference which might not
be obvious to readers especially given the several different units used
for specifying vector sizes in various contexts and the fact that it's
often used via macros.  In an effort to minimise surprises for users who
might assume the value is the architectural maximum and use it to do
things like size allocations add a comment noting the difference, and
add a note for SVE_VQ_MAX to aid discoverability.

Signed-off-by: Mark Brown <broonie@kernel.org>
---
Changes in v2:
- Use new wording mostly provided by Dave Martin.
- Reference __SVE_VQ_MAX comment near SVE_VQ_MAX define.
- Link to v1: https://lore.kernel.org/r/20240206-arm64-sve-vl-max-comment-v1-1-dddf16414412@kernel.org
---
 arch/arm64/include/uapi/asm/sve_context.h | 11 +++++++++++
 1 file changed, 11 insertions(+)


---
base-commit: 54be6c6c5ae8e0d93a6c4641cb7528eb0b6ba478
change-id: 20240206-arm64-sve-vl-max-comment-64efa3f03625

Best regards,
  

Comments

Dave Martin Feb. 12, 2024, 4:54 p.m. UTC | #1
On Fri, Feb 09, 2024 at 04:53:36PM +0000, Mark Brown wrote:
> __SVE_VQ_MAX is defined without comment as 512 but the actual
> architectural maximum is 16, a substantial difference which might not
> be obvious to readers especially given the several different units used
> for specifying vector sizes in various contexts and the fact that it's
> often used via macros.  In an effort to minimise surprises for users who
> might assume the value is the architectural maximum and use it to do
> things like size allocations add a comment noting the difference, and
> add a note for SVE_VQ_MAX to aid discoverability.
> 
> Signed-off-by: Mark Brown <broonie@kernel.org>
> ---
> Changes in v2:
> - Use new wording mostly provided by Dave Martin.
> - Reference __SVE_VQ_MAX comment near SVE_VQ_MAX define.
> - Link to v1: https://lore.kernel.org/r/20240206-arm64-sve-vl-max-comment-v1-1-dddf16414412@kernel.org
> ---
>  arch/arm64/include/uapi/asm/sve_context.h | 11 +++++++++++
>  1 file changed, 11 insertions(+)
> 
> diff --git a/arch/arm64/include/uapi/asm/sve_context.h b/arch/arm64/include/uapi/asm/sve_context.h
> index 754ab751b523..72aefc081061 100644
> --- a/arch/arm64/include/uapi/asm/sve_context.h
> +++ b/arch/arm64/include/uapi/asm/sve_context.h
> @@ -13,6 +13,17 @@
>  
>  #define __SVE_VQ_BYTES		16	/* number of bytes per quadword */
>  
> +/*
> + * Yes, __SVE_VQ_MAX is 512 QUADWORDS.
> + *
> + * To help ensure forward portability, this is much larger than the
> + * current maximum value defined by the SVE architecture.  While arrays
> + * or static allocations can be sized based on this value, watch out!
> + * It will waste a surprisingly large amount of memory.
> + *
> + * Dynamic sizing based on the actual runtime vector length is likely to
> + * be preferable for most purposes.
> + */
>  #define __SVE_VQ_MIN		1
>  #define __SVE_VQ_MAX		512

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

[...]
  
Catalin Marinas Feb. 22, 2024, 10:05 p.m. UTC | #2
On Fri, 09 Feb 2024 16:53:36 +0000, Mark Brown wrote:
> __SVE_VQ_MAX is defined without comment as 512 but the actual
> architectural maximum is 16, a substantial difference which might not
> be obvious to readers especially given the several different units used
> for specifying vector sizes in various contexts and the fact that it's
> often used via macros.  In an effort to minimise surprises for users who
> might assume the value is the architectural maximum and use it to do
> things like size allocations add a comment noting the difference, and
> add a note for SVE_VQ_MAX to aid discoverability.
> 
> [...]

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

[1/1] arm64/sve: Document that __SVE_VQ_MAX is much larger than needed
      https://git.kernel.org/arm64/c/21eb468e9fc1
  

Patch

diff --git a/arch/arm64/include/uapi/asm/sve_context.h b/arch/arm64/include/uapi/asm/sve_context.h
index 754ab751b523..72aefc081061 100644
--- a/arch/arm64/include/uapi/asm/sve_context.h
+++ b/arch/arm64/include/uapi/asm/sve_context.h
@@ -13,6 +13,17 @@ 
 
 #define __SVE_VQ_BYTES		16	/* number of bytes per quadword */
 
+/*
+ * Yes, __SVE_VQ_MAX is 512 QUADWORDS.
+ *
+ * To help ensure forward portability, this is much larger than the
+ * current maximum value defined by the SVE architecture.  While arrays
+ * or static allocations can be sized based on this value, watch out!
+ * It will waste a surprisingly large amount of memory.
+ *
+ * Dynamic sizing based on the actual runtime vector length is likely to
+ * be preferable for most purposes.
+ */
 #define __SVE_VQ_MIN		1
 #define __SVE_VQ_MAX		512