Remove request for preprocessor guards from header files. #321

CarolineConcatto · 2024-05-29T09:36:20Z

name: Pull request
about: Technical issues, document format problems, bugs in scripts or feature proposal.

Thank you for submitting a pull request!

If this PR is about a bugfix:

Please use the bugfix label and make sure to go through the checklist below.

If this PR is about a proposal:

We are looking forward to evaluate your proposal, and if possible to
make it part of the Arm C Language Extension (ACLE) specifications.

We would like to encourage you reading through the contribution
guidelines, in particular the section on submitting
a proposal.

Please use the proposal label.

As for any pull request, please make sure to go through the below
checklist.

Checklist: (mark with X those which apply)

If an issue reporting the bug exists, I have mentioned it in the
PR (do not bother creating the issue if all you want to do is
fixing the bug yourself).
I have added/updated the SPDX-FileCopyrightText lines on top
of any file I have edited. Format is SPDX-FileCopyrightText: Copyright {year} {entity or name} <{contact informations}>
(Please update existing copyright lines if applicable. You can
specify year ranges with hyphen , as in 2017-2019, and use
commas to separate gaps, as in 2018-2020, 2022).
I have updated the Copyright section of the sources of the
specification I have edited (this will show up in the text
rendered in the PDF and other output format supported). The
format is the same described in the previous item.
I have run the CI scripts (if applicable, as they might be
tricky to set up on non-*nix machines). The sequence can be
found in the contribution
guidelines. Don't
worry if you cannot run these scripts on your machine, your
patch will be automatically checked in the Actions of the pull
request.
I have added an item that describes the changes I have
introduced in this PR in the section Changes for next
release of the section Change Control/Document history
of the document. Create Changes for next release if it does
not exist. Notice that changes that are not modifying the
content and rendering of the specifications (both HTML and PDF)
do not need to be listed.
When modifying content and/or its rendering, I have checked the
correctness of the result in the PDF output (please refer to the
instructions on how to build the PDFs
locally).
The variable draftversion is set to true in the YAML header
of the sources of the specifications I have modified.
Please DO NOT add my GitHub profile to the list of contributors
in the README page of the project.

main/acle.md

…#95224) To enable function multi-versioning (FMV), current checks which rely on cmd line options or global macros to see if target feature is present need to be removed. This patch removes those for NEON and also implements changes to NEON header file as proposed in [ACLE](ARM-software/acle#321).

mgabka · 2024-07-03T09:49:22Z

main/acle.md

+`__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.


I think it is better to use "documented intrinsics", the fact that they are implemented as builtins is an implantation detail.

mgabka · 2024-07-03T09:58:34Z

main/acle.md

@@ -1072,6 +1074,33 @@ including the header:

 Including `<arm_sme.h>` also includes [`<arm_sve.h>`](#arm_sve.h).

+These macro features:


This paragraph is added in a strange place, to me looks like it will fall int the section about arm_sme, while this is not strictly related to sme, maybe better to move it to the beginning, I mean the paragraphs about "Header files"?
IMO you can be more general and do not have to list all of the feature macros.

mgabka · 2024-07-03T10:00:30Z

main/acle.md

+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


this is badly phrased. Do you mean here that users should not rely on #pragma or attribute or the feature.
macros?

If it is about the macros, I think we need to phrase it differently and explain that the presence of the macro does not guarantee that the architecture feature is always present at various stages of compilation or execution.

Hi Maciej,
I re-wrote this paragraph and added a section at the end of HEADER to explain headers + macros.
Just in case the ACLE has a section: Feature test macros. It is generic, it is about all predefined macros.
The point here is that the ACLE/I want to explain that headers protected by macro does not imply we can always use intrinsics.

main/acle.md

…llvm#95224) To enable function multi-versioning (FMV), current checks which rely on cmd line options or global macros to see if target feature is present need to be removed. This patch removes those for NEON and also implements changes to NEON header file as proposed in [ACLE](ARM-software/acle#321).

paulwalker-arm · 2024-07-24T14:28:43Z

main/acle.md

+included. The `__ARM_ACLE` macro can be tested before including the
+header, but this might limit function multi-versioning capabilities:


Ignore me if this format has already been agreed but if not can I recommend:

The `XYZ` 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.

paulwalker-arm · 2024-07-24T16:17:48Z

main/acle.md

+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<arm_sme.h>
+     void foo(svbool_t pg, void *ptr, uint32_t slice_base) {
+        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.
+


How about?

Testing a feature macro returns the compiler's support 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:

#include <arm_sme.h> void foo(svbool_t pg, void *ptr, uint32_t slice_base) { #ifdef __ARM_FEATURE_SME svst1_hor_za8(0, slice_base, pg, ptr); #endif }

Whilst testing `__ARM_FEATURE_SME` ensures the compiler supports 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.

Testing a feature macro returns the compiler's support for the feature via ACLE documented intrinsics and inline assembly.

Not sure if it is just me, the key is how we define "support".
For me compiler supports ACLE when the given ACLE is implemented. While the feature macro is only defined when appropriate features are enabled in the cmd line option only. Maybe worth to change it to sth like:

"Testing a feature macro allows to check if the compiler can make use of the architecture feature via ACLE documented intrinsics and inline assembly assuming the provided compilation flags."

What do you think?

This distinction is not relevant because there is no assumption about compilation flags. The macro alone is sufficient to detect at the source level whether the compiler (in the mode it's in when compiling the input) can support a specific feature. By support we effectively mean "is able to compile the input when it is correctly formed".

The provided example shows something that is not "correctly formed" where the compiler will report an error that must be fixed before the code will compile. There are many other examples but I don't see a reason to document them all here.

Note I say "compile" and not "compile to a working binary" because the more typical result is the compiler correctly building the input which then generates a SIGILL when executed. This is covered by the "Not all such issues..." sentence. Personally I don't think it's worth going into anymore detail than this.

Sure, I get the difference between "compile" and not "compile to a working binary".

For me it was just the meaning of word support, as in my mind feature could be supported (as implemented) by a tool but not available when given set of options it provided. It has this small difference from the user point of view as if feature is not implemented they can not do anything, while if it is not enabled they can change options.
But I am not against your version either.

I think that's because you are considering this from the point of view of a human asking whether the compiler can support a feature. Whereas the feature macros are source code actions and thus the context is the point the source code is being compiled, at which point the compiler has already been "configured" (for want of a better word) by the user.

Perhaps the point you are raising is the document does not detail what actions the user should take in order to control the definitions of the feature flags, which is intentional because we cannot dictate that.

I agree it would be good to be a bit more precise about what “support” means though. At one level, GCC 14 “supports” SME2, and the word is often used in that sense. So if we just say “support”, users might expect GCC 14 to define __ARM_FEATURE_SME2 unconditionally.

Instead, for compatibility, we have to define the macro only if the intrinsics are “available” in functions that have no target annotations (not precise wording either). What users need to do to achieve that for a given compiler is outside the scope of the ACLE, but I think the result is within scope.

IMO, the example of using SME intrinsics in non-streaming functions is an example of an intrinsics being available, but being used incorrectly. It's somewhat like passing an out-of-range value to a constant argument, except that the error is contextual, rather than contained within the call. (I still think it's a good example though.)

I did changed to what @paulwalker-arm requested, but instead of using support I wrote available, as suggested by @rsandifo-arm.
I hope it is correct.

mgabka · 2024-07-25T08:57:42Z

main/acle.md

@@ -1072,6 +1074,32 @@ including the header:

 Including `<arm_sme.h>` also includes [`<arm_sve.h>`](#arm_sve.h).

+### Predefined Macros and Headers


should this be changed to : "### predefined feature macros and header files" ?

CarolineConcatto · 2024-08-02T14:57:28Z

Thank you @paulwalker-arm, @mgabka and @rsandifo-arm for your inputs.
I have made the changes asked.
Carol

DanielKristofKiss

LGTM

vhscampos · 2024-08-05T14:05:22Z

Let's wait until the end of this week for additional feedback

main/acle.md

sdesmalen-arm · 2024-08-05T13:40:11Z

main/acle.md

+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.


Suggested change

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.

When the compiler sets the preprocessor macro to 1, that indicates that it supports the ACLE for the specified feature and that the corresponding header file and intrinsics and types are available. The inverse is not necessarily true, i.e. when the compiler does not define the macro, that doesn't mean that the header file and corresponding intrinsics/types are not available. Compilers that support the target attribute may (and probably should) make it possible to include these header files and make the intrinsics/types available, even when the macro is not set.

However, when a user doesn't test for the macro, it could still be that the header file is not available and the compiler will fail to build the file. For example, if the compiler is too old to recognise <arm_some_feature.h>.

It is probably sufficient to say that the header is guaranteed to be available if the macro is set. (same comment for all the similar cases below)

Agreed, but also: __ARM_ACLE is a special case in that, like __ARM_NEON_SVE_BRIDGE, it describes the presence of a header file rather than a specific architecture feature. So I think the original text was ok too (and so is your suggestion).

For the feature macros, maybe “is available in a normal unannotated function” would be more specific than “is available”.

So this was suggested by @paulwalker-arm

The XYZ 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.
From another previous asked change.

I have no preference, but would be nice to agree in what to write here, before I change again. The sentence you see here is a mix of previous interaction that we agree we should replace taking into account FMV.

I'm not sure that wording is appropriate for __ARM_ACLE though (specifically that macro, not others). There is no change in features that would affect whether the compiler provides <arm_acle.h>. Intrinsics within <arm_acle.h> that depend on features have their own __ARM_FEATURE_* macro.

rsandifo-arm · 2024-08-05T16:16:47Z

main/acle.md

+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.


Agreed, but also: __ARM_ACLE is a special case in that, like __ARM_NEON_SVE_BRIDGE, it describes the presence of a header file rather than a specific architecture feature. So I think the original text was ok too (and so is your suggestion).

For the feature macros, maybe “is available in a normal unannotated function” would be more specific than “is available”.

main/acle.md

Co-authored-by: rsandifo-arm <[email protected]>

main/acle.md

sdesmalen-arm · 2024-08-06T16:08:05Z

main/acle.md

+    #include <arm_sme.h>
+
+    void foo(svbool_t pg, void *ptr, uint32_t slice_base) {
+    #ifdef __ARM_FEATURE_SME
+      svst1_hor_za8(0, slice_base, pg, ptr);
+    #endif


I thought the paragraph above is more about the evaluation context/order of the macro to express that a user can't rely on the macro being set/unset when used with the ACLE keyword attributes, e.g.

__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 current example is more about showing that the compiler can add additional restrictions to the use of an intrinsic beyond what is captured by the ACLE macro. If that is the intent of the example, I think it would be helpful if that can be added as an separate paragraph, e.g. something like "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".

Thank you @sdesmalen-arm for the suggestions.
I made some changes according to your comments.

sdesmalen-arm · 2024-08-07T13:04:32Z

main/acle.md

+included. When `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` is defined to `1`,
+the header file is available in a normal unannotated function.


The macro is also available outside of function scope. The scope in which it is used shouldn't matter, because it is a preprocessor macro.

I wrote again this sentence to:
When __ARM_xxx is defined to 1, the header file is available
regardless of the context in which the macro is evaluated.

main/acle.md

Co-authored-by: Sander de Smalen <[email protected]>

sdesmalen-arm

I'm content with the phrasing now. Please address the nits though.

sdesmalen-arm · 2024-08-07T14:28:30Z

main/acle.md

@@ -1019,7 +1023,7 @@ Including `<arm_sve.h>` also includes the following header files:

 `<arm_neon_sve_bridge.h>` 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
+for details. The `__ARM_NEON_SVE_BRIDGE` macro should be tested


nit: unnecessary change.

sdesmalen-arm · 2024-08-07T14:29:07Z

main/acle.md

+      // The user should make no assumptions that the target attribute
+     // has enabled the __ARM_FEATURE_SVE macro.


nit: whitespace

Suggested change

// The user should make no assumptions that the target attribute

// has enabled the __ARM_FEATURE_SVE macro.

// The user should make no assumptions that the target attribute

// has enabled the __ARM_FEATURE_SVE macro.

sdesmalen-arm · 2024-08-07T14:33:00Z

main/acle.md

+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:


I'm still not convinced this is worth pointing out, because the compiler may also enforce requirements on the range of immediate arguments, and we never bothered to document that either. That said though, I don't see any harm in adding this either.

vhscampos · 2024-08-14T09:32:44Z

Since this PR got approval with minor nits, I'm merging it. @CarolineConcatto please address the remaining nits in a following PR. Thanks

sallyarmneale · 2024-09-25T09:22:18Z

main/acle.md

+}
+```
+
+The compiler may add additional restrictions to the intrinsics beyond what is


may -> might
See https://confluence.arm.com/display/TCOM/Concise+and+clear+words+and+phrases

sallyarmneale · 2024-09-25T09:22:39Z

main/acle.md

+```
+
+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


may -> might
https://confluence.arm.com/display/TCOM/Concise+and+clear+words+and+phrases

sallyarmneale

Two minor changes

Remove request for preprocessor guards from header files.

fc50eb1

CarolineConcatto requested a review from rsandifo-arm May 29, 2024 09:39

vhscampos self-requested a review May 30, 2024 09:13

CarolineConcatto added 2 commits May 30, 2024 09:22

Re-add the need for __STDC_FORMAT_MACROS

994aec6

Fix unwanted change

1270932

paulwalker-arm reviewed May 30, 2024

View reviewed changes

main/acle.md Outdated Show resolved Hide resolved

CarolineConcatto added 3 commits May 30, 2024 11:03

Re-add __ARM_NEON_SVE_BRIDGE it is related to compiler support

6e3991a

Adde missing sentence for __ARM_NEON_SVE_BRIDGE

9079875

Update acle.md

ae42458

This was referenced Jun 11, 2024

[Clang] Remove preprocessor guards and global feature checks for NEON llvm/llvm-project#95102

Closed

[Clang] Remove preprocessor guards and global feature checks for NEON llvm/llvm-project#95224

Merged

Add more information about the macro headers

92e5b8c

mgabka reviewed Jul 3, 2024

View reviewed changes

Add a section in headers to explain headers and macros

fb4b4f8

paulwalker-arm reviewed Jul 24, 2024

View reviewed changes

mgabka reviewed Jul 25, 2024

View reviewed changes

Re-write section with Predefined macros and header files

15bd063

vhscampos added the proposal label Aug 5, 2024

DanielKristofKiss approved these changes Aug 5, 2024

View reviewed changes

sdesmalen-arm suggested changes Aug 5, 2024

View reviewed changes

rsandifo-arm reviewed Aug 5, 2024

View reviewed changes

Apply suggestions from code review

4fafea9

Co-authored-by: rsandifo-arm <[email protected]>

sdesmalen-arm reviewed Aug 6, 2024

View reviewed changes

Re-write predefined feature macros and header files section

50f5670

sdesmalen-arm reviewed Aug 7, 2024

View reviewed changes

CarolineConcatto and others added 3 commits August 7, 2024 14:32

Apply suggestions from code review

9d357be

Co-authored-by: Sander de Smalen <[email protected]>

Address review comments

cd750bf

Re-write sentence about the header availability

7b3ee34

sdesmalen-arm approved these changes Aug 7, 2024

View reviewed changes

vhscampos merged commit ede4598 into ARM-software:main Aug 14, 2024
4 checks passed

vhscampos mentioned this pull request Aug 14, 2024

[BUG] Follow up on #321 #340

Closed

vhscampos linked an issue Aug 14, 2024 that may be closed by this pull request

[BUG] Follow up on #321 #340

Closed

Lukacma added a commit to Lukacma/acle that referenced this pull request Aug 16, 2024

Fix formatting error from ARM-software#321

aa32228

vhscampos pushed a commit that referenced this pull request Sep 3, 2024

Fix formatting error from #321 (#341)

ddfc048

sallyarmneale reviewed Sep 25, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Remove request for preprocessor guards from header files. #321

Remove request for preprocessor guards from header files. #321

CarolineConcatto commented May 29, 2024

mgabka Jul 3, 2024

mgabka Jul 3, 2024

mgabka Jul 3, 2024

CarolineConcatto Jul 9, 2024

paulwalker-arm Jul 24, 2024

paulwalker-arm Jul 24, 2024

mgabka Jul 25, 2024

paulwalker-arm Jul 25, 2024

mgabka Jul 25, 2024

paulwalker-arm Jul 25, 2024

rsandifo-arm Jul 29, 2024

CarolineConcatto Aug 5, 2024

mgabka Jul 25, 2024

CarolineConcatto commented Aug 2, 2024

DanielKristofKiss left a comment

vhscampos commented Aug 5, 2024

sdesmalen-arm Aug 5, 2024

rsandifo-arm Aug 5, 2024

CarolineConcatto Aug 6, 2024

rsandifo-arm Aug 6, 2024

rsandifo-arm Aug 5, 2024

sdesmalen-arm Aug 6, 2024

CarolineConcatto Aug 7, 2024

sdesmalen-arm Aug 7, 2024

CarolineConcatto Aug 7, 2024

sdesmalen-arm left a comment

sdesmalen-arm Aug 7, 2024

sdesmalen-arm Aug 7, 2024

sdesmalen-arm Aug 7, 2024

vhscampos commented Aug 14, 2024

sallyarmneale Sep 25, 2024

sallyarmneale Sep 25, 2024

sallyarmneale left a comment

		@@ -1072,6 +1074,33 @@ including the header:

		Including `<arm_sme.h>` also includes [`<arm_sve.h>`](#arm_sve.h).

		These macro features:

		included. The `__ARM_ACLE` macro can be tested before including the
		header, but this might limit function multi-versioning capabilities:

		@@ -1072,6 +1074,32 @@ including the header:

		Including `<arm_sme.h>` also includes [`<arm_sve.h>`](#arm_sve.h).

		### Predefined Macros and Headers

		included. When `__ARM_FEATURE_FP16_SCALAR_ARITHMETIC` is defined to `1`,
		the header file is available in a normal unannotated function.

		// The user should make no assumptions that the target attribute
		// has enabled the __ARM_FEATURE_SVE macro.

Remove request for preprocessor guards from header files. #321

Remove request for preprocessor guards from header files. #321

Conversation

CarolineConcatto commented May 29, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CarolineConcatto commented Aug 2, 2024

DanielKristofKiss left a comment

Choose a reason for hiding this comment

vhscampos commented Aug 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sdesmalen-arm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vhscampos commented Aug 14, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sallyarmneale left a comment

Choose a reason for hiding this comment