[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 undef, %X
+      %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 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