From fc50eb143befe21b947612e06a7c8e49848ffcb6 Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Wed, 29 May 2024 09:20:28 +0000 Subject: [PATCH 01/14] Remove request for preprocessor guards from header files. --- main/acle.md | 46 ++++++---------------------------------------- 1 file changed, 6 insertions(+), 40 deletions(-) diff --git a/main/acle.md b/main/acle.md index 89166c57..e71be689 100644 --- a/main/acle.md +++ b/main/acle.md @@ -904,7 +904,6 @@ correctly: ``` c #include - // UINT64_C not defined here since we did not set __STDC_FORMAT_MACROS ... #include ``` @@ -914,9 +913,7 @@ and: ``` c #include ... - #define __STDC_FORMAT_MACROS #include - // ... UINT64_C is now defined ``` ### `` @@ -925,13 +922,10 @@ and: to the more specific header files below. These intrinsics are in the C implementation namespace and begin with double underscores. It is unspecified whether they are available without the header being -included. The `__ARM_ACLE` macro should be tested before including the -header: +included. ``` c - #ifdef __ARM_ACLE #include - #endif /* __ARM_ACLE */ ``` ### `` @@ -939,13 +933,10 @@ header: `` is provided to define the scalar 16-bit floating point arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is -included. The `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` feature macro -should be tested before including the header: +included. ``` c - #ifdef __ARM_FEATURE_FP16_SCALAR_ARITHMETIC #include - #endif /* __ARM_FEATURE_FP16_SCALAR_ARITHMETIC */ ``` ### `` @@ -953,13 +944,10 @@ should be tested before including the header: `` is provided to define the 16-bit brain floating point arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is -included. The `__ARM_FEATURE_BF16` feature macro -should be tested before including the header: +included. ``` c - #ifdef __ARM_FEATURE_BF16 #include - #endif /* __ARM_FEATURE_BF16 */ ``` When `__ARM_BF16_FORMAT_ALTERNATIVE` is defined to `1` the only scalar @@ -975,13 +963,10 @@ instructions available are conversion intrinsics between `bfloat16_t` and intrinsics](#advanced-simd-neon-intrinsics) and associated [data types](#vector-data-types). As these intrinsics and data types are in the user namespace, an implementation would not normally define them -until the header is included. The `__ARM_NEON` macro should be tested -before including the header: +until the header is included. ``` c - #ifdef __ARM_NEON #include - #endif /* __ARM_NEON */ ``` Including `` will also cause the following header files @@ -999,13 +984,9 @@ following it. --> `` defines data types and intrinsics for SVE and its extensions; see [SVE language extensions and intrinsics](#sve-language-extensions-and-intrinsics) for details. -You should test the `__ARM_FEATURE_SVE` macro before including the -header: ``` c - #ifdef __ARM_FEATURE_SVE #include - #endif /* __ARM_FEATURE_SVE */ ``` Including `` also includes the following header files: @@ -1019,13 +1000,10 @@ Including `` also includes the following header files: `` defines intrinsics for moving data between Neon and SVE vector types; see [NEON-SVE Bridge](#neon-sve-bridge) -for details. The `__ARM_NEON_SVE_BRIDGE` macro should be tested -before including the header: +for details. ``` c - #ifdef __ARM_NEON_SVE_BRIDGE #include - #endif /* __ARM_NEON_SVE_BRIDGE */ ``` Including `` will also include @@ -1040,17 +1018,8 @@ intrinsics occupy both the user namespace and the `__arm_` namespace; defining `__ARM_MVE_PRESERVE_USER_NAMESPACE` will hide the definition of the user namespace variants. -The `__ARM_FEATURE_MVE` macro should be tested before including the -header: - ``` c - #if (__ARM_FEATURE_MVE & 3) == 3 - #include - /* MVE integer and floating point intrinsics are now available to use. */ - #elif __ARM_FEATURE_MVE & 1 #include - /* MVE integer intrinsics are now available to use. */ - #endif ``` ### `` @@ -1061,13 +1030,10 @@ change or be extended in the future. `` declares functions and defines intrinsics for SME and its extensions; see [SME language extensions and intrinsics](#sme-language-extensions-and-intrinsics) -for details. The `__ARM_FEATURE_SME` macro should be tested before -including the header: +for details. ``` c - #ifdef __ARM_FEATURE_SME #include - #endif ``` Including `` also includes [``](#arm_sve.h). From 994aec62002c3d4f9ea362c727f692939abe8532 Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Thu, 30 May 2024 09:22:47 +0000 Subject: [PATCH 02/14] Re-add the need for __STDC_FORMAT_MACROS --- main/acle.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/main/acle.md b/main/acle.md index e71be689..526fd43d 100644 --- a/main/acle.md +++ b/main/acle.md @@ -904,6 +904,7 @@ correctly: ``` c #include + // UINT64_C not defined here since we did not set __STDC_FORMAT_MACROS ... #include ``` @@ -912,8 +913,10 @@ and: ``` c #include + #define __STDC_FORMAT_MACROS ... #include + // ... UINT64_C is now defined ``` ### `` From 12709321227c85743e9a67f7b5d3f2d4bc4f925e Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Thu, 30 May 2024 09:41:12 +0000 Subject: [PATCH 03/14] Fix unwanted change --- main/acle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/main/acle.md b/main/acle.md index 526fd43d..c1b0e118 100644 --- a/main/acle.md +++ b/main/acle.md @@ -913,8 +913,8 @@ and: ``` c #include - #define __STDC_FORMAT_MACROS ... + #define __STDC_FORMAT_MACROS #include // ... UINT64_C is now defined ``` From 6e3991a63d3ff6db4dbecfaf608e5ba11c52272b Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Thu, 30 May 2024 11:03:21 +0000 Subject: [PATCH 04/14] Re-add __ARM_NEON_SVE_BRIDGE it is related to compiler support --- main/acle.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/main/acle.md b/main/acle.md index c1b0e118..b8ecdd34 100644 --- a/main/acle.md +++ b/main/acle.md @@ -1006,7 +1006,9 @@ Neon and SVE vector types; see [NEON-SVE Bridge](#neon-sve-bridge) for details. ``` c + #ifdef __ARM_NEON_SVE_BRIDGE #include + #endif /* __ARM_NEON_SVE_BRIDGE */ ``` Including `` will also include From 907987539ba9726a951369f61d04e9f4db511f53 Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Thu, 30 May 2024 11:10:50 +0000 Subject: [PATCH 05/14] Adde missing sentence for __ARM_NEON_SVE_BRIDGE --- main/acle.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/main/acle.md b/main/acle.md index b8ecdd34..d0850d71 100644 --- a/main/acle.md +++ b/main/acle.md @@ -1003,7 +1003,8 @@ Including `` also includes the following header files: `` defines intrinsics for moving data between Neon and SVE vector types; see [NEON-SVE Bridge](#neon-sve-bridge) -for details. +for details. The `__ARM_NEON_SVE_BRIDGE` macro should be tested +-before including the header: ``` c #ifdef __ARM_NEON_SVE_BRIDGE From ae42458994e78bbc8163b264c7274015ddec8cc0 Mon Sep 17 00:00:00 2001 From: CarolineConcatto Date: Thu, 30 May 2024 12:14:32 +0100 Subject: [PATCH 06/14] Update acle.md --- main/acle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/main/acle.md b/main/acle.md index d0850d71..f1a73a40 100644 --- a/main/acle.md +++ b/main/acle.md @@ -1004,7 +1004,7 @@ Including `` also includes the following header files: `` defines intrinsics for moving data between Neon and SVE vector types; see [NEON-SVE Bridge](#neon-sve-bridge) for details. The `__ARM_NEON_SVE_BRIDGE` macro should be tested --before including the header: +before including the header: ``` c #ifdef __ARM_NEON_SVE_BRIDGE From 92e5b8caa7105393b3004a9a8a4ab8b520b37803 Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Tue, 2 Jul 2024 14:30:21 +0000 Subject: [PATCH 07/14] Add more information about the macro headers --- main/acle.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 62 insertions(+), 5 deletions(-) diff --git a/main/acle.md b/main/acle.md index f1a73a40..d4040246 100644 --- a/main/acle.md +++ b/main/acle.md @@ -925,10 +925,13 @@ and: to the more specific header files below. These intrinsics are in the C implementation namespace and begin with double underscores. It is unspecified whether they are available without the header being -included. +included. The `__ARM_ACLE` macro can be tested before including the +header, but this might limit function multi-versioning capabilities: ``` c + #ifdef __ARM_ACLE #include + #endif /* __ARM_ACLE */ ``` ### `` @@ -936,10 +939,14 @@ included. `` is provided to define the scalar 16-bit floating point arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is -included. +included. The `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` macro can be +tested before including the header, but this might limit function +multi-versioning capabilities: ``` c + #ifdef __ARM_FEATURE_FP16_SCALAR_ARITHMETIC #include + #endif /* __ARM_FEATURE_FP16_SCALAR_ARITHMETIC */ ``` ### `` @@ -947,10 +954,13 @@ included. `` is provided to define the 16-bit brain floating point arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is -included. +included. The `__ARM_FEATURE_BF16` macro can be tested before including +the header, but this might limit function multi-versioning capabilities: ``` c + #ifdef __ARM_FEATURE_BF16 #include + #endif /* __ARM_FEATURE_BF16 */ ``` When `__ARM_BF16_FORMAT_ALTERNATIVE` is defined to `1` the only scalar @@ -966,10 +976,14 @@ instructions available are conversion intrinsics between `bfloat16_t` and intrinsics](#advanced-simd-neon-intrinsics) and associated [data types](#vector-data-types). As these intrinsics and data types are in the user namespace, an implementation would not normally define them -until the header is included. +until the header is included. The `__ARM_NEON` macro can be tested before +including the header, but this might limit function multi-versioning +capabilities: ``` c + #ifdef __ARM_NEON #include + #endif /* __ARM_NEON */ ``` Including `` will also cause the following header files @@ -987,9 +1001,13 @@ following it. --> `` defines data types and intrinsics for SVE and its extensions; see [SVE language extensions and intrinsics](#sve-language-extensions-and-intrinsics) for details. +The `__ARM_FEATURE_SVE` macro can be tested before including the header, +but this might limit function multi-versioning capabilities: ``` c + #ifdef __ARM_FEATURE_SVE #include + #endif /* __ARM_FEATURE_SVE */ ``` Including `` also includes the following header files: @@ -1024,8 +1042,17 @@ intrinsics occupy both the user namespace and the `__arm_` namespace; defining `__ARM_MVE_PRESERVE_USER_NAMESPACE` will hide the definition of the user namespace variants. +The `__ARM_FEATURE_MVE` macro should be tested before including the +header: + ``` c + #if (__ARM_FEATURE_MVE & 3) == 3 + #include + /* MVE integer and floating point intrinsics are now available to use. */ + #elif __ARM_FEATURE_MVE & 1 #include + /* MVE integer intrinsics are now available to use. */ + #endif ``` ### `` @@ -1036,14 +1063,44 @@ change or be extended in the future. `` declares functions and defines intrinsics for SME and its extensions; see [SME language extensions and intrinsics](#sme-language-extensions-and-intrinsics) -for details. +for details. The `__ARM_FEATURE_SME` macro can be tested before including the +header, but this might limit function multi-versioning capabilities: ``` c + #ifdef __ARM_FEATURE_SME #include + #endif ``` Including `` also includes [``](#arm_sve.h). +These macro features: +`__ARM_ACLE`, `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC`, `__ARM_FEATURE_BF16`, +`__ARM_NEON`, `__ARM_FEATURE_SVE` and ` __ARM_FEATURE_SME` +represent a compiler's ability to use the instructions associated +with the feature via ACLE documented builtins and within inline assembly. +They may also be influenced by source code mechanisms like `#pragma` or +`attribute`, but users should not rely on this. They are defined for user +convenience. + +For example: + +``` c + #ifdef __ARM_FEATURE_SME + #include + #endif + void foo(svbool_t pg, void *ptr, uint32_t slice_base) { + svst1_hor_za8(0, slice_base, pg, ptr); + } +``` + +`foo` uses `__ARM_FEATURE_SME` to have available SME intriniscs, +like `svst1_hor_za8`. However it has the compilation error: +`builtin can only be called from a streaming function` +for the command line: +`armclang -O3 -target aarch64-linux-gnu -march=armv8-a+sme` +that defines `__ARM_FEATURE_SME` to one. + ## Attributes GCC-style attributes are provided to annotate types, objects and From fb4b4f8e5aeab9daefb4ec8b3d93a926b360fe33 Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Mon, 8 Jul 2024 16:46:39 +0000 Subject: [PATCH 08/14] Add a section in headers to explain headers and macros --- main/acle.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/main/acle.md b/main/acle.md index d4040246..032a30f5 100644 --- a/main/acle.md +++ b/main/acle.md @@ -1074,24 +1074,23 @@ header, but this might limit function multi-versioning capabilities: Including `` also includes [``](#arm_sve.h). -These macro features: -`__ARM_ACLE`, `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC`, `__ARM_FEATURE_BF16`, -`__ARM_NEON`, `__ARM_FEATURE_SVE` and ` __ARM_FEATURE_SME` -represent a compiler's ability to use the instructions associated -with the feature via ACLE documented builtins and within inline assembly. -They may also be influenced by source code mechanisms like `#pragma` or -`attribute`, but users should not rely on this. They are defined for user -convenience. +### Predefined Macros and Headers + +The macros can represent a compiler's ability to use the instructions +associated with the feature via ACLE documented intrinsics and within inline +assembly. However users should not rely solely on macro definition, because +there are intrinsics that may be influenced by mechanisms like `#pragma` or +`attribute`. The macros are defined only for user convenience. For example: ``` c #ifdef __ARM_FEATURE_SME #include + void foo(svbool_t pg, void *ptr, uint32_t slice_base) { + svst1_hor_za8(0, slice_base, pg, ptr); + } #endif - void foo(svbool_t pg, void *ptr, uint32_t slice_base) { - svst1_hor_za8(0, slice_base, pg, ptr); - } ``` `foo` uses `__ARM_FEATURE_SME` to have available SME intriniscs, From 15bd06391d6ade048189e9a8877e0774fc0ea550 Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Fri, 2 Aug 2024 14:53:34 +0000 Subject: [PATCH 09/14] Re-write section with Predefined macros and header files --- main/acle.md | 72 +++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 32 deletions(-) diff --git a/main/acle.md b/main/acle.md index 032a30f5..0da51f01 100644 --- a/main/acle.md +++ b/main/acle.md @@ -925,8 +925,9 @@ and: to the more specific header files below. These intrinsics are in the C implementation namespace and begin with double underscores. It is unspecified whether they are available without the header being -included. The `__ARM_ACLE` macro can be tested before including the -header, but this might limit function multi-versioning capabilities: +included. The `__ARM_ACLE` macro can be tested before including the header. +However, this is not recommended for cases where target feature selection is +overridden within code, for example, when using #function-multi-versioning. ``` c #ifdef __ARM_ACLE @@ -939,9 +940,10 @@ header, but this might limit function multi-versioning capabilities: `` is provided to define the scalar 16-bit floating point arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is -included. The `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` macro can be -tested before including the header, but this might limit function -multi-versioning capabilities: +included. The `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` macro can be tested before +including the header. However, this is not recommended for cases where target +feature selection is overridden within code, for example, when using +#function-multi-versioning. ``` c #ifdef __ARM_FEATURE_FP16_SCALAR_ARITHMETIC @@ -954,8 +956,10 @@ multi-versioning capabilities: `` is provided to define the 16-bit brain floating point arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is -included. The `__ARM_FEATURE_BF16` macro can be tested before including -the header, but this might limit function multi-versioning capabilities: +included. The `__ARM_FEATURE_BF16` macro can be tested before including the +header. However, this is not recommended for cases where target feature +selection is overridden within code, for example, when using +function-multi-versioning. ``` c #ifdef __ARM_FEATURE_BF16 @@ -977,8 +981,10 @@ intrinsics](#advanced-simd-neon-intrinsics) and associated [data types](#vector-data-types). As these intrinsics and data types are in the user namespace, an implementation would not normally define them until the header is included. The `__ARM_NEON` macro can be tested before -including the header, but this might limit function multi-versioning -capabilities: +including the header. However, this is not recommended for cases where target +feature selection is overridden within code, for example, when using +#function-multi-versioning. + ``` c #ifdef __ARM_NEON @@ -1001,8 +1007,9 @@ following it. --> `` defines data types and intrinsics for SVE and its extensions; see [SVE language extensions and intrinsics](#sve-language-extensions-and-intrinsics) for details. -The `__ARM_FEATURE_SVE` macro can be tested before including the header, -but this might limit function multi-versioning capabilities: +The `__ARM_FEATURE_SVE` macro can be tested before including the header. +However, this is not recommended for cases where target feature selection is +overridden within code, for example, when using #function-multi-versioning. ``` c #ifdef __ARM_FEATURE_SVE @@ -1064,7 +1071,9 @@ change or be extended in the future. `` declares functions and defines intrinsics for SME and its extensions; see [SME language extensions and intrinsics](#sme-language-extensions-and-intrinsics) for details. The `__ARM_FEATURE_SME` macro can be tested before including the -header, but this might limit function multi-versioning capabilities: +header. However, this is not recommended for cases where target feature +selection is overridden within code, for example, when using +#function-multi-versioning. ``` c #ifdef __ARM_FEATURE_SME @@ -1074,31 +1083,30 @@ header, but this might limit function multi-versioning capabilities: Including `` also includes [``](#arm_sve.h). -### Predefined Macros and Headers - -The macros can represent a compiler's ability to use the instructions -associated with the feature via ACLE documented intrinsics and within inline -assembly. However users should not rely solely on macro definition, because -there are intrinsics that may be influenced by mechanisms like `#pragma` or -`attribute`. The macros are defined only for user convenience. +### Predefined feature macros and header files -For example: +Testing a feature macro returns the compiler's availability for the feature via ACLE +documented intrinsics and inline assembly. This property can be independent of +where the test is performed, meaning a feature macro does not guarantee the +validity of using the feature at the point it is tested. For example: ``` c - #ifdef __ARM_FEATURE_SME - #include - void foo(svbool_t pg, void *ptr, uint32_t slice_base) { - svst1_hor_za8(0, slice_base, pg, ptr); - } - #endif + #include + + void foo(svbool_t pg, void *ptr, uint32_t slice_base) { + #ifdef __ARM_FEATURE_SME + svst1_hor_za8(0, slice_base, pg, ptr); + #endif + } ``` -`foo` uses `__ARM_FEATURE_SME` to have available SME intriniscs, -like `svst1_hor_za8`. However it has the compilation error: -`builtin can only be called from a streaming function` -for the command line: -`armclang -O3 -target aarch64-linux-gnu -march=armv8-a+sme` -that defines `__ARM_FEATURE_SME` to one. +Whilst testing `__ARM_FEATURE_SME` ensures the compiler has available the SME +intrinsic `svst1_hor_za8`, `foo` will fail to compile because it has not been +decorated with the necessary keywords to guarantee the function will be +executed in streaming mode. + +Not all such issues can be caught during compilation and may instead result in +runtime failures. ## Attributes From 4fafea95615dff65982c38061fbc8f1b26d74fe9 Mon Sep 17 00:00:00 2001 From: CarolineConcatto Date: Tue, 6 Aug 2024 11:17:24 +0100 Subject: [PATCH 10/14] Apply suggestions from code review Co-authored-by: rsandifo-arm --- main/acle.md | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/main/acle.md b/main/acle.md index 0da51f01..ce3aa6a3 100644 --- a/main/acle.md +++ b/main/acle.md @@ -1085,10 +1085,14 @@ Including `` also includes [``](#arm_sve.h). ### Predefined feature macros and header files -Testing a feature macro returns the compiler's availability for the feature via ACLE -documented intrinsics and inline assembly. This property can be independent of -where the test is performed, meaning a feature macro does not guarantee the -validity of using the feature at the point it is tested. For example: +Feature macros indicate whether that feature's intrinsics and inline assembly instructions +are available in normal unannotated functions. In some implementations, the macro definitions +are invariant throughout a translation unit, while in other implementations, the macro +definitions can vary with pragmas. + +The macro definitions are otherwise independent of where the test is performed, +meaning that a feature macro does not guarantee that the feature can be used at the +point that it is tested. For example: ``` c #include @@ -1100,10 +1104,9 @@ validity of using the feature at the point it is tested. For example: } ``` -Whilst testing `__ARM_FEATURE_SME` ensures the compiler has available the SME -intrinsic `svst1_hor_za8`, `foo` will fail to compile because it has not been -decorated with the necessary keywords to guarantee the function will be -executed in streaming mode. +While testing `__ARM_FEATURE_SME` ensures that the SME intrinsic `svst1_hor_za8` +is available, `foo` will fail to compile because the call does not occur in a +[streaming statement](#streaming-statement). Not all such issues can be caught during compilation and may instead result in runtime failures. From 50f5670e384005c8275625de8a7e9d1a597eafda Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Tue, 6 Aug 2024 15:49:09 +0000 Subject: [PATCH 11/14] Re-write predefined feature macros and header files section --- main/acle.md | 52 +++++++++++++++++++--------------------------------- 1 file changed, 19 insertions(+), 33 deletions(-) diff --git a/main/acle.md b/main/acle.md index ce3aa6a3..e6ae6429 100644 --- a/main/acle.md +++ b/main/acle.md @@ -925,9 +925,8 @@ and: to the more specific header files below. These intrinsics are in the C implementation namespace and begin with double underscores. It is unspecified whether they are available without the header being -included. The `__ARM_ACLE` macro can be tested before including the header. -However, this is not recommended for cases where target feature selection is -overridden within code, for example, when using #function-multi-versioning. +included. When `__ARM_ACLE` is defined to `1`, the header file is +guaranteed to be available. ``` c #ifdef __ARM_ACLE @@ -940,10 +939,8 @@ overridden within code, for example, when using #function-multi-versioning. `` is provided to define the scalar 16-bit floating point arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is -included. The `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` macro can be tested before -including the header. However, this is not recommended for cases where target -feature selection is overridden within code, for example, when using -#function-multi-versioning. +included. When `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` is defined to `1`, +the header file is available in a normal unannotated function. ``` c #ifdef __ARM_FEATURE_FP16_SCALAR_ARITHMETIC @@ -956,10 +953,8 @@ feature selection is overridden within code, for example, when using `` is provided to define the 16-bit brain floating point arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is -included. The `__ARM_FEATURE_BF16` macro can be tested before including the -header. However, this is not recommended for cases where target feature -selection is overridden within code, for example, when using -function-multi-versioning. +included. The `__ARM_FEATURE_BF16` is defined to `1`, the header file is +available in a normal unannotated function. ``` c #ifdef __ARM_FEATURE_BF16 @@ -980,10 +975,8 @@ instructions available are conversion intrinsics between `bfloat16_t` and intrinsics](#advanced-simd-neon-intrinsics) and associated [data types](#vector-data-types). As these intrinsics and data types are in the user namespace, an implementation would not normally define them -until the header is included. The `__ARM_NEON` macro can be tested before -including the header. However, this is not recommended for cases where target -feature selection is overridden within code, for example, when using -#function-multi-versioning. +until the header is included. The `__ARM_NEON` is defined to `1`, +the header file is available in a normal unannotated function. ``` c @@ -1007,9 +1000,8 @@ following it. --> `` defines data types and intrinsics for SVE and its extensions; see [SVE language extensions and intrinsics](#sve-language-extensions-and-intrinsics) for details. -The `__ARM_FEATURE_SVE` macro can be tested before including the header. -However, this is not recommended for cases where target feature selection is -overridden within code, for example, when using #function-multi-versioning. +The `__ARM_FEATURE_SVE` is defined to `1`, the header file is available +in a normal unannotated function. ``` c #ifdef __ARM_FEATURE_SVE @@ -1070,10 +1062,8 @@ change or be extended in the future. `` declares functions and defines intrinsics for SME and its extensions; see [SME language extensions and intrinsics](#sme-language-extensions-and-intrinsics) -for details. The `__ARM_FEATURE_SME` macro can be tested before including the -header. However, this is not recommended for cases where target feature -selection is overridden within code, for example, when using -#function-multi-versioning. +for details. The `__ARM_FEATURE_SME` is defined to `1`, +the header file is available in a normal unannotated function. ``` c #ifdef __ARM_FEATURE_SME @@ -1085,18 +1075,17 @@ Including `` also includes [``](#arm_sve.h). ### Predefined feature macros and header files -Feature macros indicate whether that feature's intrinsics and inline assembly instructions -are available in normal unannotated functions. In some implementations, the macro definitions -are invariant throughout a translation unit, while in other implementations, the macro -definitions can vary with pragmas. +Testing a feature macro returns the compiler's availability for the feature +via ACLE documented intrinsics and inline assembly. This property can be +independent of where the test is performed. There should be no assumption on +the order or context in wich the preprocessor macros are evaluated. -The macro definitions are otherwise independent of where the test is performed, -meaning that a feature macro does not guarantee that the feature can be used at the -point that it is tested. For example: +The compiler may add additional restrictions to the intrinsics beyond what is +captured by the ACLE macros depending on the context in which the intrinsics +are used. For example: ``` c #include - void foo(svbool_t pg, void *ptr, uint32_t slice_base) { #ifdef __ARM_FEATURE_SME svst1_hor_za8(0, slice_base, pg, ptr); @@ -1108,9 +1097,6 @@ While testing `__ARM_FEATURE_SME` ensures that the SME intrinsic `svst1_hor_za8` is available, `foo` will fail to compile because the call does not occur in a [streaming statement](#streaming-statement). -Not all such issues can be caught during compilation and may instead result in -runtime failures. - ## Attributes GCC-style attributes are provided to annotate types, objects and From 9d357be24f4c5e0cd3973657cc6bd0b645552a89 Mon Sep 17 00:00:00 2001 From: CarolineConcatto Date: Wed, 7 Aug 2024 14:32:37 +0100 Subject: [PATCH 12/14] Apply suggestions from code review Co-authored-by: Sander de Smalen --- main/acle.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/main/acle.md b/main/acle.md index e6ae6429..afc49cc2 100644 --- a/main/acle.md +++ b/main/acle.md @@ -1075,10 +1075,9 @@ Including `` also includes [``](#arm_sve.h). ### Predefined feature macros and header files -Testing a feature macro returns the compiler's availability for the feature -via ACLE documented intrinsics and inline assembly. This property can be -independent of where the test is performed. There should be no assumption on -the order or context in wich the preprocessor macros are evaluated. +Evaluating a feature macro returns the availability of intrinsics and inline +assembly for that feature, but no assumptions should be made on the order or +context in which the preprocessor macros are evaluated. The compiler may add additional restrictions to the intrinsics beyond what is captured by the ACLE macros depending on the context in which the intrinsics @@ -1093,8 +1092,8 @@ are used. For example: } ``` -While testing `__ARM_FEATURE_SME` ensures that the SME intrinsic `svst1_hor_za8` -is available, `foo` will fail to compile because the call does not occur in a +If `__ARM_FEATURE_SME` evaluates to `true` the SME intrinsic `svst1_hor_za8` +is available, but `foo` may still fail to compile because the call does not occur in a [streaming statement](#streaming-statement). ## Attributes From cd750bf5d73d4eefb79b42f57b7bc1b67876b911 Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Wed, 7 Aug 2024 14:00:12 +0000 Subject: [PATCH 13/14] Address review comments --- main/acle.md | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/main/acle.md b/main/acle.md index afc49cc2..b29663ce 100644 --- a/main/acle.md +++ b/main/acle.md @@ -940,7 +940,7 @@ guaranteed to be available. arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is included. When `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` is defined to `1`, -the header file is available in a normal unannotated function. +the header file is guaranteed to be available. ``` c #ifdef __ARM_FEATURE_FP16_SCALAR_ARITHMETIC @@ -954,7 +954,7 @@ the header file is available in a normal unannotated function. arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is included. The `__ARM_FEATURE_BF16` is defined to `1`, the header file is -available in a normal unannotated function. +guaranteed to be available in a normal unannotated function. ``` c #ifdef __ARM_FEATURE_BF16 @@ -976,7 +976,7 @@ intrinsics](#advanced-simd-neon-intrinsics) and associated [data types](#vector-data-types). As these intrinsics and data types are in the user namespace, an implementation would not normally define them until the header is included. The `__ARM_NEON` is defined to `1`, -the header file is available in a normal unannotated function. +the header file is guaranteed to be available in a normal unannotated function. ``` c @@ -1000,8 +1000,8 @@ following it. --> `` defines data types and intrinsics for SVE and its extensions; see [SVE language extensions and intrinsics](#sve-language-extensions-and-intrinsics) for details. -The `__ARM_FEATURE_SVE` is defined to `1`, the header file is available -in a normal unannotated function. +The `__ARM_FEATURE_SVE` is defined to `1`, the header file is guaranteed to be +available in a normal unannotated function. ``` c #ifdef __ARM_FEATURE_SVE @@ -1063,7 +1063,7 @@ change or be extended in the future. `` declares functions and defines intrinsics for SME and its extensions; see [SME language extensions and intrinsics](#sme-language-extensions-and-intrinsics) for details. The `__ARM_FEATURE_SME` is defined to `1`, -the header file is available in a normal unannotated function. +the header file is guaranteed to be available in a normal unannotated function. ``` c #ifdef __ARM_FEATURE_SME @@ -1077,7 +1077,17 @@ Including `` also includes [``](#arm_sve.h). Evaluating a feature macro returns the availability of intrinsics and inline assembly for that feature, but no assumptions should be made on the order or -context in which the preprocessor macros are evaluated. +context in which the preprocessor macros are evaluated. For example: + +``` c + __attribute__((target("+sve"))) + void foo() { + #ifdef __ARM_FEATURE_SVE + // The user should make no assumptions that the target attribute + // has enabled the __ARM_FEATURE_SVE macro. + #endif +} +``` The compiler may add additional restrictions to the intrinsics beyond what is captured by the ACLE macros depending on the context in which the intrinsics @@ -1093,8 +1103,8 @@ are used. For example: ``` If `__ARM_FEATURE_SME` evaluates to `true` the SME intrinsic `svst1_hor_za8` -is available, but `foo` may still fail to compile because the call does not occur in a -[streaming statement](#streaming-statement). +is available, but `foo` may still fail to compile because the call does not +occur in a [streaming statement](#streaming-statement). ## Attributes From 7b3ee3409a48fdfe8c07200e5b888dde99061862 Mon Sep 17 00:00:00 2001 From: Caroline Concatto Date: Wed, 7 Aug 2024 14:12:53 +0000 Subject: [PATCH 14/14] Re-write sentence about the header availability --- main/acle.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/main/acle.md b/main/acle.md index b29663ce..81da3dab 100644 --- a/main/acle.md +++ b/main/acle.md @@ -940,7 +940,8 @@ guaranteed to be available. arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is included. When `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` is defined to `1`, -the header file is guaranteed to be available. +the header file is available regardless of the context in which the macro +is evaluated. ``` c #ifdef __ARM_FEATURE_FP16_SCALAR_ARITHMETIC @@ -953,8 +954,9 @@ the header file is guaranteed to be available. `` is provided to define the 16-bit brain floating point arithmetic intrinsics. As these intrinsics are in the user namespace, an implementation would not normally define them until the header is -included. The `__ARM_FEATURE_BF16` is defined to `1`, the header file is -guaranteed to be available in a normal unannotated function. +included. When `__ARM_FEATURE_BF16` is defined to `1`, the header file is +guaranteed to be available regardless of the context in which the macro +is evaluated. ``` c #ifdef __ARM_FEATURE_BF16 @@ -975,8 +977,9 @@ instructions available are conversion intrinsics between `bfloat16_t` and intrinsics](#advanced-simd-neon-intrinsics) and associated [data types](#vector-data-types). As these intrinsics and data types are in the user namespace, an implementation would not normally define them -until the header is included. The `__ARM_NEON` is defined to `1`, -the header file is guaranteed to be available in a normal unannotated function. +until the header is included. When `__ARM_NEON` is defined to `1`, +the header file is available regardless of the context in which the macro is +evaluated. ``` c @@ -1000,8 +1003,8 @@ following it. --> `` defines data types and intrinsics for SVE and its extensions; see [SVE language extensions and intrinsics](#sve-language-extensions-and-intrinsics) for details. -The `__ARM_FEATURE_SVE` is defined to `1`, the header file is guaranteed to be -available in a normal unannotated function. +When `__ARM_FEATURE_SVE` is defined to `1`, the header file is available +regardless of the context in which the macro is evaluated. ``` c #ifdef __ARM_FEATURE_SVE @@ -1062,8 +1065,8 @@ change or be extended in the future. `` declares functions and defines intrinsics for SME and its extensions; see [SME language extensions and intrinsics](#sme-language-extensions-and-intrinsics) -for details. The `__ARM_FEATURE_SME` is defined to `1`, -the header file is guaranteed to be available in a normal unannotated function. +for details. When `__ARM_FEATURE_SME` is defined to `1`, the header file is +available regardless of the context in which the macro is evaluated. ``` c #ifdef __ARM_FEATURE_SME