[llvm] [LangRef] Clarify the semantics of fast-math flags (PR #89442)

[Andy Kaylor via llvm-commits]

https://github.com/andykaylor created https://github.com/llvm/llvm-project/pull/89442

This change clarifies the semantics of the fast-math flags when a
transformation enabled by fast-math flags involves more than one
instruction.

This was discussed at https://discourse.llvm.org/t/rfc-fast-math-optimizations-with-mixed-fast-math-flags/78320


>From e203c73d870610ad1d855efe4d6e4d4e613c9ecd Mon Sep 17 00:00:00 2001
From: Andy Kaylor <andrew.kaylor at intel.com>
Date: Fri, 19 Apr 2024 12:12:33 -0700
Subject: [PATCH] [LangRef] Clarify the semantics of fast-math flags

This change clarifies the semantics of the fast-math flags when a
transformation enabled by fast-math flags involves more than one
instruction.

This was discussed at https://discourse.llvm.org/t/rfc-fast-math-optimizations-with-mixed-fast-math-flags/78320
---
 llvm/docs/LangRef.rst | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 9592929d79feb4..dcb21330fa8156 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3656,6 +3656,45 @@ floating-point transformations.
 ``fast``
    This flag implies all of the others.
 
+When performing a transformation that involves more that one instruction, the
+flags required to enable the transformation must be set on all instructions
+involved in the transformation, and any new instructions created by the
+transformation should have only those flags set which were set on all the
+original instructions that are being transformed.
+
+For example
+
+::
+
+%mul1 = fmul float %x, %y
+%mul2 = fmul fast float %mul1, %z
+
+cannot be transformed to
+
+::
+
+%mul1 = fmul float %x, %z
+%mul2 = fmul fast float %mul1, %y
+
+because the %mul1 instruction does not have the 'reassoc' flag set.
+
+Similarly, if applying reassociation to
+
+::
+
+%mul1 = fmul reassoc float %x, %y
+%mul2 = fmul fast float %mul1, %z
+
+the result must be
+
+::
+
+%mul1 = fmul reassoc float %x, %z
+%mul2 = fmul reassoc float %mul1, %y
+
+because only the reassoc flag is set on both original instructions.
+
+
 .. _uselistorder:
 
 Use-list Order Directives