[Docs] Clarify that reassoc isn't just for reassociation

[llvm-beanz]

The reassoc fast-math flag allows a much wider array of algebraic transformations than just strictly reassociations. In some cases it does commutations, distributions, and folds away redundant inverse operations...

While it might make sense to fix the flag naming at some point, in the meantime we should at least have the docs be accurate to avoid confusion.

[llvmbot]

@llvm/pr-subscribers-llvm-ir

Author: Chris B (llvm-beanz)

Changes

The reassoc fast-math flag allows a much wider array of algebraic transformations than just strictly reassociations. In some cases it does commutations, or distributions.

While it might make sense to fix the flag naming at some point, in the meantime we should at least have the docs be accurate to avoid confusion.

---

Full diff: https://github.com/llvm/llvm-project/pull/133168.diff

1 Files Affected:

• (modified) llvm/docs/LangRef.rst (+3-2)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 655ec4389456c..c505aff34da31 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3971,8 +3971,9 @@ output, given the original flags.
    for places where this can apply to LLVM's intrinsic math functions.
 
 ``reassoc``
-   Allow reassociation transformations for floating-point instructions.
-   This may dramatically change results in floating-point.
+   Allow algebraically equivalent transformations for floating-point
+   instructions such as reassociation transformations. This may dramatically
+   change results in floating-point.
 
 .. _uselistorder:
 

[llvm-beanz]

As a note, the language I'm proposing here is based on the language from the LLVM 5 language reference:

Fast - Allow algebraically equivalent transformations that may dramatically change results in floating point (e.g. reassociate). This flag implies all the others.

(see: https://releases.llvm.org/5.0.0/docs/LangRef.html#fast-math-flags)

The modern reassoc flag is really inherited from the unsafe algebra behaviors that came with the fast flag from older LLVM.

[llvm-ci]

LLVM Buildbot has detected a new failure on builder ml-opt-devrel-x86-64 running on ml-opt-devrel-x86-64-b1 while building llvm at step 6 "test-build-unified-tree-check-all".

Full details are available at: https://lab.llvm.org/buildbot/#/builders/175/builds/16169

Here is the relevant piece of the build log for the reference

Step 6 (test-build-unified-tree-check-all) failure: test (failure)
******************** TEST 'LLVM-Unit :: Transforms/Vectorize/./VectorizeTests/18/27' FAILED ********************
Script(shard):
--
GTEST_OUTPUT=json:/b/ml-opt-devrel-x86-64-b1/build/unittests/Transforms/Vectorize/./VectorizeTests-LLVM-Unit-48532-18-27.json GTEST_SHUFFLE=0 GTEST_TOTAL_SHARDS=27 GTEST_SHARD_INDEX=18 /b/ml-opt-devrel-x86-64-b1/build/unittests/Transforms/Vectorize/./VectorizeTests
--

Note: This is test shard 19 of 27.
[==========] Running 2 tests from 2 test suites.
[----------] Global test environment set-up.
[----------] 1 test from VPRecipeTest
[ RUN      ] VPRecipeTest.CastVPInterleaveRecipeToVPUser
Stack dump without symbol names (ensure you have llvm-symbolizer in your PATH or set the environment var `LLVM_SYMBOLIZER_PATH` to point to it):
0  VectorizeTests  0x00005651c2dcae08
1  VectorizeTests  0x00005651c2dc8705
2  libpthread.so.0 0x00007f62420ff140
3  VectorizeTests  0x00005651c29bdee4
4  VectorizeTests  0x00005651c2dde32f
5  VectorizeTests  0x00005651c2de6082
6  VectorizeTests  0x00005651c2de6667
7  VectorizeTests  0x00005651c2df3666
8  VectorizeTests  0x00005651c2ddd89c
9  VectorizeTests  0x00005651c2991dd6
10 libc.so.6       0x00007f6241bebd7a __libc_start_main + 234
11 VectorizeTests  0x00005651c299755a

--
exit: -11
--
shard JSON output does not exist: /b/ml-opt-devrel-x86-64-b1/build/unittests/Transforms/Vectorize/./VectorizeTests-LLVM-Unit-48532-18-27.json
********************