[LangRef] Adjust the documentation of some fast-math flags. (#99557)

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.

Author: jcranmer-intel

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