Improve documentation for VMLA/VMLS intrinsics for floats

[amilendra]

The clang and GCC implementations for the VMLA/VMLS intrinsics for floats are the same except for the -ffp-contract=on case where GCC: uses VMUL+VADD/VSUM
Clang: uses FMLA/FMLS (Fused MLA/MLS)

Non-float VMLA/VMLS intrinsics reduce to MLA/MLS in both implementations.

Previous ACLE releases (e.g. 2.1) made it clear that the VMLA/VMLS intrinsics for floats are implementation defined, but this information seem to have got lost in later releases.

So redocument the implementation-defined behaviour.

---

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.

[TamarChristinaArm]

I don't think this is correct, The VMLA intrinsics are implementation defined.

VMLA is defined by Armv7 which has two different instructions for FMA, one VMLA which is unfused https://developer.arm.com/documentation/ddi0406/c/Application-Level-Architecture/Instruction-Details/Alphabetical-list-of-instructions/VMLA--VMLS--floating-point- and VFMA which is the fused variant https://developer.arm.com/documentation/ddi0406/cb/Application-Level-Architecture/Instruction-Details/Alphabetical-list-of-instructions/VFMA--VFMS

When Armv8-A was added, for backwards compatibility the VMLA intrinsics were retained,

however since Armv8-a doesn't have an unfused variant the intrinsics was documented as an explicit operation

vadd(a[i], vmul(b[i], c[i])) for i = 0 to

rather than an instruction, to indicate that rounding shouldn't be done.
So the intrinsics shouldn't change based on -ffp-contraction because that would give you a different result on Armv8-a than Armv7-a.

So the clang behavior of fusing them is wrong (similar to GCC at some point). Clang was doing the right thing but changed at some point, and GCC was doing the wrong thing and we corrected it.

That's why I don't think this intrinsics is implementation defined, because it has a defined behavior for allowing porting of code from Armv7.

So -Ofast f.c -march=armv8-a needs to behave the same as -Ofast f.c -march=armv7-a because the intrinsics was meant to allow porting of code written for Armv7.

[paulwalker-arm]

Once you add -Ofast all bets are off. This is especially true when talking about cross architecture compatibility. In this instance we're talking about compiler optimisation flags that are beyond the control of the ACLE and I argue the ACLE has no mechanism to prevent contraction, regardless of the original intent.

[TamarChristinaArm]

Once you add -Ofast all bets are off. This is especially true when talking about cross architecture compatibility. In this instance we're talking about compiler optimisation flags that are beyond the control of the ACLE and I argue the ACLE has no mechanism to prevent contraction, regardless of the original intent.

That's not true at all, -Ofast can't affect an instruction that explicitly doesn't do fusion. The problem here is that ACLE has been interpreted incorrectly from the original intention.

As I said before, this instruction is supposed to return the exact same value on -Ofast f.c -march=armv8-a and -Ofast f.c -march=armv7-a.

[TamarChristinaArm]

Furthermore, LLVM's own documentation specifies that -ffp-contract is only allowed to do C and C++ standard fusions [1]
and as you yourself stated above, ACLE is not a C nor a C++ standard. and the ACLE standard had always intended that operation be unfused as it was to match the existing instruction semantics.

[1] https://clang.llvm.org/docs/UsersManual.html#cmdoption-ffp-contract

[paulwalker-arm]

The current documentation say's nothing about contraction. It says "This intrinsic compiles to the following instructions: RESULT[I] = a[i] + (b[i] * c[i])"? When I build this with -Ofast I get contraction.

The specification has been poorly worded, with a difference in implementation being the result. We can either capture this, ideally in a way that suggests ways to avoid such issues (i.e. don't use flags whose behaviour is not guaranteed to be consistent across architectures), or we can continue to leave readers to work it out for themselves.

[TamarChristinaArm]

The current documentation say's nothing about contraction. It says "This intrinsic compiles to the following instructions: RESULT[I] = a[i] + (b[i] * c[i])"? When I build this with -Ofast I get contraction.

Yes, this was a bad specification, and it happened because when Armv8-a was added, the decision was made to switch all the "instructions" in the standard to use Arvm8-a instructions. This of course doesn't work when Armv8-a didn't have a matching instruction.

But note how the vfma one explicitly said it's a fused operation. I think they missed adding unfused to the vmla one because they didn't keep in mind fp-contract when the example was written.

This compatibility with Armv7 however is the reason why many duplicate intrinsics exist, e.g. that's why we have both vdup_n_s8 and vmov_n_s8.

The specification has been poorly worded, with a difference in implementation being the result. We can either capture this, ideally in a way that suggests ways to avoid such issues (i.e. don't use flags whose behaviour is not guaranteed to be consistent across architectures), or we can continue to leave readers to work it out for themselves.

I'm not saying that the documentation doesn't need updating. But I don't agree in updating it to be "implementation defined" because that was never the intention of it. But things got lost during the way.

Note that GCC had this fused behavior before GCC 12. We explicitly took the decision to fix it due to complaints of people porting code. https://godbolt.org/z/WcfzTdf3E so this changed.

We did so because of two clauses in the ACLE manual https://arm-software.github.io/acle/main/acle.html#undefined-behavior and https://arm-software.github.io/acle/main/acle.html#specification-of-advanced-simd-intrinsics where in this case the semantics comes from Armv7/Armv6 and prior.

The confusion comes from instructions that don't exist in Armv8 but intrinsic were still added to aid porting of older code.

[paulwalker-arm]

I'm not saying that the documentation doesn't need updating. But I don't agree in updating it to be "implementation defined" because that was never the intention of it. But things got lost during the way.

Yep. I prefer we drop that part as well. For me the key bit is showing explicit calls to vaddq and vmulq.

[amilendra]

The current documentation say's nothing about contraction. It says "This intrinsic compiles to the following instructions: RESULT[I] = a[i] + (b[i] * c[i])"? When I build this with -Ofast I get contraction.

Yes, this was a bad specification, and it happened because when Armv8-a was added, the decision was made to switch all the "instructions" in the standard to use Arvm8-a instructions. This of course doesn't work when Armv8-a didn't have a matching instruction.

But note how the vfma one explicitly said it's a fused operation. I think they missed adding unfused to the vmla one because they didn't keep in mind fp-contract when the example was written.

This compatibility with Armv7 however is the reason why many duplicate intrinsics exist, e.g. that's why we have both vdup_n_s8 and vmov_n_s8.

The specification has been poorly worded, with a difference in implementation being the result. We can either capture this, ideally in a way that suggests ways to avoid such issues (i.e. don't use flags whose behaviour is not guaranteed to be consistent across architectures), or we can continue to leave readers to work it out for themselves.

I'm not saying that the documentation doesn't need updating. But I don't agree in updating it to be "implementation defined" because that was never the intention of it. But things got lost during the way.

Note that GCC had this fused behavior before GCC 12. We explicitly took the decision to fix it due to complaints of people porting code. https://godbolt.org/z/WcfzTdf3E so this changed.

We did so because of two clauses in the ACLE manual https://arm-software.github.io/acle/main/acle.html#undefined-behavior and https://arm-software.github.io/acle/main/acle.html#specification-of-advanced-simd-intrinsics where in this case the semantics comes from Armv7/Armv6 and prior.

The confusion comes from instructions that don't exist in Armv8 but intrinsic were still added to aid porting of older code.

@TamarChristinaArm
Clearly this needs some more expertise than what I have and the clang implementation should be changed to match the gcc implementation which should be based on the spec changed. Would you mind taking this over and improving the specification?

[paulwalker-arm]

There are no plans to change the clang implementation. It is my understanding that if the Final instruction sequence is implementation defined phrasing is removed then the original objection is resolved?

[amilendra]

There are no plans to change the clang implementation. It is my understanding that if the Final instruction sequence is implementation defined phrasing is removed then the original objection is resolved?

I see. Thanks. I've removed that part.