[llvm] 4c34086 - [LangRef] improve documentation of SNaN in the default FP environment

[Sanjay Patel via llvm-commits]

Author: Sanjay Patel
Date: 2023-02-15T08:58:07-05:00
New Revision: 4c3408697b73fd7c6d58658eeb5b7743cb9fab6c

URL: https://github.com/llvm/llvm-project/commit/4c3408697b73fd7c6d58658eeb5b7743cb9fab6c
DIFF: https://github.com/llvm/llvm-project/commit/4c3408697b73fd7c6d58658eeb5b7743cb9fab6c.diff

LOG: [LangRef] improve documentation of SNaN in the default FP environment

Make it explicit that SNaN is not handled differently than
QNaN in the LLVM default floating-point environment.

Note that an IEEE-754-compliant model disallows transforms
like "X * 1.0 -> X". That is because math operations are
expected to convert SNaN to QNaN (set the signaling bit).

But LLVM has had those kinds of transforms from the beginning:
https://alive2.llvm.org/ce/z/igb55y

We should be IEEE-754-compliant under strict-FP (the logic is
implemented with a helper named canIgnoreSNaN()), but I don't
think there is any demand to do that with default optimization.

See issue #43070 for earlier draft/discussion about this change.

Differential Revision: https://reviews.llvm.org/D143074

Added: 
    

Modified: 
    llvm/docs/LangRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index cd51a42de24fe..1762bdb537d8f 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -3284,15 +3284,17 @@ seq\_cst total orderings of other operations that are not marked
 Floating-Point Environment
 --------------------------
 
-The default LLVM floating-point environment assumes that floating-point
-instructions do not have side effects. Results assume the round-to-nearest
-rounding mode. No floating-point exception state is maintained in this
-environment. Therefore, there is no attempt to create or preserve invalid
-operation (SNaN) or division-by-zero exceptions.
-
-The benefit of this exception-free assumption is that floating-point
-operations may be speculated freely without any other fast-math relaxations
-to the floating-point model.
+The default LLVM floating-point environment assumes that traps are disabled and
+status flags are not observable. Therefore, floating-point math operations do
+not have side effects and may be speculated freely. Results assume the
+round-to-nearest rounding mode.
+
+Floating-point math operations are allowed to treat all NaNs as if they were
+quiet NaNs. For example, "pow(1.0, SNaN)" may be simplified to 1.0. This also
+means that SNaN may be passed through a math operation without quieting. For
+example, "fmul SNaN, 1.0" may be simplified to SNaN rather than QNaN. However,
+SNaN values are never created by math operations. They may only occur when
+provided as a program input value.
 
 Code that requires 
diff erent behavior than this should use the
 :ref:`Constrained Floating-Point Intrinsics <constrainedfp>`.