[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

3058

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.

6407

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

3040–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

3040–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

3040–3041

The additions to the opcode definitions are probably good enough.

6505

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
-      %B = fdiv %X, undef
+      %A = sdiv undef, %X
+      %B = sdiv %X, undef
     Safe:
-      %A = undef
+      %A = 0
     b: unreachable
 
 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.
+operation can be constant folded to '``0``', because the '``undef``'
+could be zero, and zero divided by any value is zero.
 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.
 
 .. 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 to execute in the default floating-point
+environment. It has no side effects. Users can not assume that any 
+floating-point exception state is updated by this instruction.
 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 to execute in the default floating-point
+environment. It has no side effects. Users can not assume that any 
+floating-point exception state is updated by this instruction.
 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 to execute in the default floating-point
+environment. It has no side effects. Users can not assume that any 
+floating-point exception state is updated by this instruction.
 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 to execute in the default floating-point
+environment. It has no side effects. Users can not assume that any 
+floating-point exception state is updated by this instruction.
 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 to execute in the default floating-point
+environment. It has no side effects. Users can not assume that any 
+floating-point exception state is updated by this instruction.
 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