[LangRef] make it clear that FP instructions do not have side effects

[spatel]

Summary

There may still be some ambiguity about the output with undef and special constants, but I think we have consensus that the LLVM FP opcodes operate in an environment with no trapping, so let's make that explicit and fix the bogus example.

The existing text for the constrained intrinsics says:
"By default, LLVM optimization passes assume that the rounding mode is round-to-nearest and that floating point exceptions will not be monitored. Constrained FP intrinsics are used to support non-default rounding modes and accurately preserve exception behavior without compromising LLVM’s ability to optimize FP code when the default behavior is used."

[andrew.w.kaylor]

Thanks for taking the initiative on this!

docs/LangRef.rst

3047

I don't like the wording, "There is no possibility of trapping...." Strictly speaking, if the user code has unmasked FP exceptions (in spite of not telling us via FENV_ACCESS that they intended to) it is possible that these will trap. More to the point is that the optimizer assumes no trapping.

6401

Again, I'd suggest "can not trap or have any other side effects" -> "is assumed not to trap or have any other side effects"

[spatel]

Patch updated:
Improve/soften the wording - we make assumptions about the state of FP affairs.

[efriedma]

docs/LangRef.rst

3041

I would rather just rewrite this example so it doesn't use fdiv.

You can make the point this paragraph is trying to make much more clearly and unambiguously using integer sdiv rather than floating-point operations.

[spatel]

docs/LangRef.rst

3041

Yes, good point. Do you think there's value in also having the FP examples here to explicitly show the difference between int and FP, or are the additions to the opcode definitions enough?

[efriedma]

docs/LangRef.rst

3041

The additions to the opcode definitions are probably good enough.

6497

You might also want to mention we assume the default rounding mode, or maybe just the default floating-point environment. And maybe specifically call out that we assume the user won't read the floating-point exception state.

[spatel]

Patch updated:

1. Change the undef vs. UB example to use sdiv rather than fdiv.
2. Add more details about the assumed FP execution env and behavior of the FP instructions.

[lattner]

These changes look great, but I'd suggest explicitly mentioning that SNaN behavior somewhere, the relation of the instructions to the intrinsics etc. Perhaps a section before Fast Math Flags?

[spatel]

In D44216#1032251, @lattner wrote:

These changes look great, but I'd suggest explicitly mentioning that SNaN behavior somewhere, the relation of the instructions to the intrinsics etc. Perhaps a section before Fast Math Flags?

Sure, I'll follow-up. I'm intentionally making minimal patches because that makes it less likely that I'll veer into the unknown. Also, any help with the phraseology is appreciated; I've only played a lawyer on TV. :)

docs/LangRef.rst

 doesn't actually *have a live range*. Instead, the value is logically
 read from arbitrary registers that happen to be around when needed, so
 the value is not necessarily consistent over time. In fact, ``%A`` and
 ``%C`` need to have the same semantics or the core LLVM "replace all
 uses with" concept would not hold.
 
 .. code-block:: llvm
 
-      %A = fdiv undef, %X
+      %A = fadd undef, %X
       %B = fdiv %X, undef
     Safe:
-      %A = undef
-    b: unreachable
+      %A = NaN
+      %B = NaN
 
-These examples show the crucial difference between an *undefined value*
-and *undefined behavior*. An undefined value (like '``undef``') is
-allowed to have an arbitrary bit-pattern. This means that the ``%A``
-operation can be constant folded to '``undef``', because the '``undef``'
-could be an SNaN, and ``fdiv`` is not (currently) defined on SNaN's.
-However, in the second example, we can make a more aggressive
-assumption: because the ``undef`` is allowed to be an arbitrary value,
-we are allowed to assume that it could be zero. Since a divide by zero
-has *undefined behavior*, we are allowed to assume that the operation
-does not execute at all. This allows us to delete the divide and all
-code after it. Because the undefined operation "can't happen", the
-optimizer can assume that it occurs in dead code.
+By default, the optimizer does not model exceptions for floating-point 
+instructions (see constrained floating-point intrinsics for that 
+functionality), so we assume there are no side effects with these 
+instructions. Therefore, we return a NaN constant value in both cases. 
+This is because if the variable operand is a NaN, then no other output is
+possible.
 
 .. code-block:: text
 
     a:  store undef -> %X
     b:  store %X -> undef
     Safe:
     a: <deleted>
     b: unreachable

 The two arguments to the '``fadd``' instruction must be :ref:`floating
 point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
 Both arguments must have identical types.
 
 Semantics:
 """"""""""
 
 The value produced is the floating-point sum of the two operands.
+This instruction is assumed not to trap or have any other side effects.
 This instruction can also take any number of :ref:`fast-math
 flags <fastmath>`, which are optimization hints to enable otherwise
 unsafe floating-point optimizations:
 
 Example:
 """"""""
 
 .. code-block:: text

 The two arguments to the '``fsub``' instruction must be :ref:`floating
 point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
 Both arguments must have identical types.
 
 Semantics:
 """"""""""
 
 The value produced is the floating-point difference of the two operands.
+This instruction is assumed not to trap or have any other side effects.
 This instruction can also take any number of :ref:`fast-math
 flags <fastmath>`, which are optimization hints to enable otherwise
 unsafe floating-point optimizations:
 
 Example:
 """"""""
 
 .. code-block:: text

 The two arguments to the '``fmul``' instruction must be :ref:`floating
 point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
 Both arguments must have identical types.
 
 Semantics:
 """"""""""
 
 The value produced is the floating-point product of the two operands.
+This instruction is assumed not to trap or have any other side effects.
 This instruction can also take any number of :ref:`fast-math
 flags <fastmath>`, which are optimization hints to enable otherwise
 unsafe floating-point optimizations:
 
 Example:
 """"""""
 
 .. code-block:: text

 The two arguments to the '``fdiv``' instruction must be :ref:`floating
 point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
 Both arguments must have identical types.
 
 Semantics:
 """"""""""
 
 The value produced is the floating-point quotient of the two operands.
+This instruction is assumed not to trap or have any other side effects.
 This instruction can also take any number of :ref:`fast-math
 flags <fastmath>`, which are optimization hints to enable otherwise
 unsafe floating-point optimizations:
 
 Example:
 """"""""
 
 .. code-block:: text

 
 Semantics:
 """"""""""
 
 The value produced is the floating-point remainder of the two operands.
 This is the same output as a libm '``fmod``' function, but without any
 possibility of setting ``errno``. The remainder has the same sign as the 
 dividend.
+This instruction is assumed not to trap or have any other side effects.
 This instruction can also take any number of :ref:`fast-math
 flags <fastmath>`, which are optimization hints to enable otherwise
 unsafe floating-point optimizations:
 
 Example:
 """"""""
 
 .. code-block:: text