[LangRef] Adjust the documentation of some fast-math flags. #99557
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The first change is the clarification of rewrite-based semantics, and the fact that when doing the rewrite, all of the instructions involved need to have the rewrite. This is not a change in semantics: there is wide agreement that this behavior is true for most flags. But it is necessary to clarify this, and also clarify that there is a fundamental difference between a flag like `nnan` and a flag like `contract`. Note that several InstCombine transforms do not correctly check this behavior at the moment. The second change is a specific clarification of the rewrites performed by arcp. These rewrites capture what is necessary to enable the transformations that currently require just arcp, none of which are using the flag incorrectly right now.
|
@llvm/pr-subscribers-llvm-ir Author: Joshua Cranmer (jcranmer-intel) ChangesThe first change is the clarification of rewrite-based semantics, and the fact that when doing the rewrite, all of the instructions involved need to have the rewrite. This is not a change in semantics: there is wide agreement that this behavior is true for most flags. But it is necessary to clarify this, and also clarify that there is a fundamental difference between a flag like The second change is a specific clarification of the rewrites performed by arcp. These rewrites capture what is necessary to enable the transformations that currently require just arcp, none of which are using the flag incorrectly right now. Full diff: https://github.com/llvm/llvm-project/pull/99557.diff 1 Files Affected:
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index cd86156ec816f..af852782741c7 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3669,6 +3669,10 @@ LLVM IR floating-point operations (:ref:`fneg <i_fneg>`, :ref:`fadd <i_fadd>`,
may use the following flags to enable otherwise unsafe
floating-point transformations.
+``fast``
+ This flag is a shorthand for specifying all fast-math flags at once, and
+ imparts no additional semantics from using all of them.
+
``nnan``
No NaNs - Allow optimizations to assume the arguments and result are not
NaN. If an argument is a nan, or the result would be a nan, it produces
@@ -3684,9 +3688,51 @@ floating-point transformations.
argument or zero result as insignificant. This does not imply that -0.0
is poison and/or guaranteed to not exist in the operation.
+Rewrite-based flags
+^^^^^^^^^^^^^^^^^^^
+
+The following flags have rewrite-based semantics. These flags allow expressions,
+potentially containing multiple non-consecutive instructions, to be rewritten
+into alternative instructions. When multiple instructions are involved in an
+expression, it is necessary that all of the instructions have the necessary
+rewrite-based flag present on them, and the rewritten instructions will
+generally have the intersection of the flags present on the input instruction.
+
+In the following example, the floating-point expression in the body of ``@orig``
+has ``contract`` and ``reassoc`` in common, and thus if it is rewritten into the
+expression in the body of ``@target``, all of the new instructions get those two
+flags and only those flags as a result. Since the ``arcp`` is present on only
+one of the instructions in the expression, it is not present in the transformed
+expression. Furthermore, this reassociation here is only legal because both the
+instructions had the ``reassoc`` flag; if only one had it, it would not be legal
+to make the transformation.
+
+.. code-block:: llvm
+
+ define double @orig(double %a, double %b, double %c) {
+ %t1 = fmul contract reassoc double %a, %b
+ %val = fmul contract reassoc arcp double %t1, %c
+ ret double %val
+ }
+
+ define double @target(double %a, double %b, double %c) {
+ %t1 = fmul contract reassoc double %b, %c
+ %val = fmul contract reassoc double %a, %t1
+ ret double %val
+ }
+
+These rules do not apply to the other fast-math flags. Whether or not a flag
+like ``nnan`` is present on any or all of the rewritten instructions is based
+on whether or not it is possible for said instruction to have a NaN input or
+output, given the original flags.
+
``arcp``
- Allow Reciprocal - Allow optimizations to use the reciprocal of an
- argument rather than perform division.
+ Allows division to be treated as a multiplication by a reciprocal.
+ Specifically, this permits ``a / b`` to be considered equivalent to
+ ``a * (1.0 / b)`` (which may subsequently be susceptible to code motion),
+ and it also permits ``a / (b / c)`` to be considered equivalent to
+ ``a * (c / b)``. Both of these rewrites can be applied in either direction:
+ ``a * (c / b)`` can be rewritten into ``a / (b / c)``.
``contract``
Allow floating-point contraction (e.g. fusing a multiply followed by an
@@ -3705,9 +3751,6 @@ floating-point transformations.
Allow reassociation transformations for floating-point instructions.
This may dramatically change results in floating-point.
-``fast``
- This flag implies all of the others.
-
.. _uselistorder:
Use-list Order Directives
|
|
This change also subsumes the #89442 change. |
arsenm
approved these changes
Jul 19, 2024
|
LLVM Buildbot has detected a new failure on builder Full details are available at: https://lab.llvm.org/buildbot/#/builders/35/builds/1608 Here is the relevant piece of the build log for the reference: |
banach-space
pushed a commit
to banach-space/llvm-project
that referenced
this pull request
Aug 7, 2024
The first change is the clarification of rewrite-based semantics, and the fact that when doing the rewrite, all of the instructions involved need to have the rewrite. This is not a change in semantics: there is wide agreement that this behavior is true for most flags. But it is necessary to clarify this, and also clarify that there is a fundamental difference between a flag like `nnan` and a flag like `contract`. Note that several InstCombine transforms do not correctly check this behavior at the moment. The second change is a specific clarification of the rewrites performed by arcp. These rewrites capture what is necessary to enable the transformations that currently require just arcp, none of which are using the flag incorrectly right now.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The first change is the clarification of rewrite-based semantics, and the fact that when doing the rewrite, all of the instructions involved need to have the rewrite. This is not a change in semantics: there is wide agreement that this behavior is true for most flags. But it is necessary to clarify this, and also clarify that there is a fundamental difference between a flag like
nnanand a flag likecontract. Note that several InstCombine transforms do not correctly check this behavior at the moment.The second change is a specific clarification of the rewrites performed by arcp. These rewrites capture what is necessary to enable the transformations that currently require just arcp, none of which are using the flag incorrectly right now.