diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index b17e3c828ed3d..38f0a019cab5d 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -2405,6 +2405,8 @@ example: function which has an ``ssp`` or ``sspstrong`` attribute, the calling function's attribute will be upgraded to ``sspreq``. +.. _strictfp: + ``strictfp`` This attribute indicates that the function was called from a scope that requires strict floating-point semantics. LLVM will not attempt any @@ -3582,11 +3584,12 @@ status flags are not observable. Therefore, floating-point math operations do not have side effects and may be speculated freely. Results assume the round-to-nearest rounding mode, and subnormals are assumed to be preserved. -Running LLVM code in an environment where these assumptions are not met can lead -to undefined behavior. The ``strictfp`` and ``denormal-fp-math`` attributes as -well as :ref:`Constrained Floating-Point Intrinsics ` can be used -to weaken LLVM's assumptions and ensure defined behavior in non-default -floating-point environments; see their respective documentation for details. +Running LLVM code in an environment where these assumptions are not met +typically leads to undefined behavior. The ``strictfp`` and ``denormal-fp-math`` +attributes as well as :ref:`Constrained Floating-Point Intrinsics +` can be used to weaken LLVM's assumptions and ensure defined +behavior in non-default floating-point environments; see their respective +documentation for details. .. _floatnan: @@ -3608,10 +3611,11 @@ are not "floating-point math operations": ``fneg``, ``llvm.fabs``, and ``llvm.copysign``. These operations act directly on the underlying bit representation and never change anything except possibly for the sign bit. -For floating-point math operations, unless specified otherwise, the following -rules apply when a NaN value is returned: the result has a non-deterministic -sign; the quiet bit and payload are non-deterministically chosen from the -following set of options: +Floating-point math operations that return a NaN are an exception from the +general principle that LLVM implements IEEE-754 semantics. Unless specified +otherwise, the following rules apply whenever the IEEE-754 semantics say that a +NaN value is returned: the result has a non-deterministic sign; the quiet bit +and payload are non-deterministically chosen from the following set of options: - The quiet bit is set and the payload is all-zero. ("Preferred NaN" case) - The quiet bit is set and the payload is copied from any input operand that is @@ -3657,6 +3661,40 @@ specification on some architectures: LLVM does not correctly represent this. See `issue #60796 `_. +.. _floatsem: + +Floating-Point Semantics +------------------------ + +This section defines the semantics for core floating-point operations on types +that use a format specified by IEEE-745. These types are: ``half``, ``float``, +``double``, and ``fp128``, which correspond to the binary16, binary32, binary64, +and binary128 formats, respectively. The "core" operations are those defined in +section 5 of IEEE-745, which all have corresponding LLVM operations. + +The value returned by those operations matches that of the corresponding +IEEE-754 operation executed in the :ref:`default LLVM floating-point environment +`, except that the behavior of NaN results is instead :ref:`as +specified here `. In particular, such a floating-point instruction +returning a non-NaN value is guaranteed to always return the same bit-identical +result on all machines and optimization levels. + +This means that optimizations and backends may not change the observed bitwise +result of these operations in any way (unless NaNs are returned), and frontends +can rely on these operations providing correctly rounded results as described in +the standard. + +(Note that this is only about the value returned by these operations; see the +:ref:`floating-point environment section ` regarding flags and +exceptions.) + +Various flags, attributes, and metadata can alter the behavior of these +operations and thus make them not bit-identical across machines and optimization +levels any more: most notably, the :ref:`fast-math flags ` as well as +the :ref:`strictfp ` and :ref:`denormal-fp-math ` +attributes and :ref:`!fpmath metadata `. See their +corresponding documentation for details. + .. _fastmath: Fast-Math Flags @@ -3943,7 +3981,7 @@ Floating-Point Types - Description * - ``half`` - - 16-bit floating-point value + - 16-bit floating-point value (IEEE-754 binary16) * - ``bfloat`` - 16-bit "brain" floating-point value (7-bit significand). Provides the @@ -3952,13 +3990,13 @@ Floating-Point Types extensions and Arm's ARMv8.6-A extensions, among others. * - ``float`` - - 32-bit floating-point value + - 32-bit floating-point value (IEEE-754 binary32) * - ``double`` - - 64-bit floating-point value + - 64-bit floating-point value (IEEE-754 binary64) * - ``fp128`` - - 128-bit floating-point value (113-bit significand) + - 128-bit floating-point value (IEEE-754 binary128) * - ``x86_fp80`` - 80-bit floating-point value (X87) @@ -3966,10 +4004,6 @@ Floating-Point Types * - ``ppc_fp128`` - 128-bit floating-point value (two 64-bits) -The binary format of half, float, double, and fp128 correspond to the -IEEE-754-2008 specifications for binary16, binary32, binary64, and binary128 -respectively. - X86_amx Type """""""""""" @@ -6925,6 +6959,8 @@ For example, %2 = load float, ptr %c, align 4, !alias.scope !6 store float %0, ptr %arrayidx.i, align 4, !noalias !7 +.. _fpmath-metadata: + '``fpmath``' Metadata ^^^^^^^^^^^^^^^^^^^^^