[LangRef] describe the default FP environment

[spatel]

Summary

Follow-up for @lattner's suggestion in D44216: add a section and examples to describe the FP env.

I thought about mentioning IEEE-754 here, but I don't know how far we can or want to go in that direction.

[efriedma]

docs/LangRef.rst

2300

Using undef here is confusing, since it's not any specific value. If you want an SNaN, write an SNaN.

[spatel]

Patch updated:

1. Fix example to show SNaN explicitly.
2. Remove duplicate text from the opcode definitions. Now that we have a description of the environment, we can just point to it. Presumably, we'll do the same for non-constrained FP intrinsics, but I'll double-check those and make another patch.

[spatel]

Ping.

[scanon]

I'm OK with this.

[hfinkel]

In D44318#1043205, @scanon wrote:

I'm OK with this.

LGTM too.

I thought about mentioning IEEE-754 here, but I don't know how far we can or want to go in that direction.

I wouldn't mind doing this. We do, in fact, assume IEEE-754 representation (except for in special types) and we probably should document that.

[spatel]

In D44318#1043297, @hfinkel wrote:

I thought about mentioning IEEE-754 here, but I don't know how far we can or want to go in that direction.

I wouldn't mind doing this. We do, in fact, assume IEEE-754 representation (except for in special types) and we probably should document that.

Great - thanks for clarifying that. We'd be in big trouble with existing folds if that wasn't true. :)
I'll commit this as-is and enhance in follow-ups.

docs/LangRef.rst

 dependent if it *synchronizes with* and participates in the seq\_cst total
 orderings of other operations.
 
 Otherwise, an atomic operation that is not marked ``syncscope("singlethread")``
 or ``syncscope("<target-scope>")`` *synchronizes with* and participates in the
 seq\_cst total orderings of other operations that are not marked
 ``syncscope("singlethread")`` or ``syncscope("<target-scope>")``.
 
+.. _floatenv:
+
+Floating-Point Environment
+--------------------------
+
+The default LLVM floating-point environment assumes that floating-point
+instructions do not have side effects. No floating-point exception state is
+maintained in this environment. Results assume the round-to-nearest rounding
+mode. Therefore, there is no attempt to create or preserve invalid operation
+(SNaN) or division-by-zero exceptions in these examples:
+
+.. code-block:: llvm
+
+      %A = fdiv 0x7ff0000000000001, %X  ; 64-bit SNaN hex value 
+      %B = fdiv %X, 0.0
+    Safe:
+      %A = NaN
+      %B = NaN
+
+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.
+
+Code that requires different behavior than this should use the
+:ref:`Constrained Floating-Point Intrinsics <_constrainedfp>`.
+
 .. _fastmath:
 
 Fast-Math Flags
 ---------------
 
 LLVM IR floating-point operations (:ref:`fadd <i_fadd>`,
 :ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`,
 :ref:`frem <i_frem>`, :ref:`fcmp <i_fcmp>`) and :ref:`call <i_call>`

 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 is assumed to execute in the default :ref`floating-point
+environment <_floatenv>`. 
 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 is assumed to execute in the default :ref`floating-point
+environment <_floatenv>`. 
 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 is assumed to execute in the default :ref`floating-point
+environment <_floatenv>`. 
 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 is assumed to execute in the default :ref`floating-point
+environment <_floatenv>`. 
 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 is assumed to execute in the default :ref`floating-point
+environment <_floatenv>`. 
 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 pointer to the memory for which the ``invariant.group`` no longer holds.
 
 Semantics:
 """"""""""
 
 Returns another pointer that aliases its argument but which is considered different
 for the purposes of ``load``/``store`` ``invariant.group`` metadata.
 
+.. _constrainedfp:
+
 Constrained Floating Point Intrinsics
 -------------------------------------
 
 These intrinsics are used to provide special handling of floating point
 operations when specific rounding mode or floating point exception behavior is
 required.  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