[llvm] LangRef: state explicitly that floats generally behave according to IEEE-754 (PR #102140)

[Joshua Cranmer via llvm-commits]

================
@@ -3572,6 +3572,29 @@ 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>")``.
 
+.. _floatsem:
+
+Floating-Point Semantics
+------------------------
+
+LLVM floating-point types fall into two categories:
+
+- half, float, double, and fp128, which correspond to the binary16, binary32,
+  binary64, and binary128 formats described in the IEEE-754 specification.
+- The remaining types, which do not directly correspond to a standard IEEE
+  format.
+
+For types that do correspond to an IEEE format, LLVM IR float operations behave
+like the corresponding operations in IEEE-754, with two exceptions: LLVM makes
+:ref:`specific assumptions about the state of the floating-point environment
+<floatenv>` and it implements :ref:`different rules for operations that return
+NaN values <floatnan>`.
----------------
jcranmer-intel wrote:

I'm struggling to come up with good wordsmithing here. It's not the case that there are two exceptions to IEEE-754 here. As @arsenm notes, we don't necessarily agree with IEEE 754 on denormal values. Also, we (rather explicitly) don't guarantee the side-effect on flags or exceptions of IEEE 754 semantics. The more we try to fine-tune the text to make "it's exactly IEEE 754 BUT", the more I think we obscure what the actual thing we're trying to state is.

This is a quick attempt I have of a direction that makes more sense to me:
> Unless otherwise specified, floating-point instructions return the same value [i.e., we make no implication about flags or exceptions here, although this may be subtle] that the corresponding IEEE 754 operation for their type when executing in the default floating-point environment [link], except that the behavior of NaN values is instead as specified here [link]. In particular, a floating-point instruction lacking fast-math flags operating on normal floating-point values is guaranteed to always return the same bit-identical result on all machines. When executing in the non-default floating-point environment, the result is typically undefined behavior unless constrained intrinsics [link] are used.

(This still doesn't cover denormal behavior, because that's non-default floating-point environment, but I'm not sure I have a firm grip on what the denormal guarantees we want to make in the first place are!)

https://github.com/llvm/llvm-project/pull/102140