Author: Nikita Popov Date: 2026-01-23T14:35:32+01:00 New Revision: 6bae2a98b4c757da73611afe0f28b5ca5287d8c1
URL: https://github.com/llvm/llvm-project/commit/6bae2a98b4c757da73611afe0f28b5ca5287d8c1 DIFF: https://github.com/llvm/llvm-project/commit/6bae2a98b4c757da73611afe0f28b5ca5287d8c1.diff LOG: [LangRef] Clarify specification for float min/max operations (#172012) This implements some clarifications for the specification of floating point min/max operations based on the discussion in https://discourse.llvm.org/t/rfc-a-consistent-set-of-semantics-for-the-floating-point-minimum-and-maximum-operations/89006. The key changes are: * Explicitly specify minnum and maxnum with an sNaN operand as non-deterministically either returning NaN or treating sNaN as qNaN. This was implied by our general NaN semantics, but is important to call out here due to the special behavior of sNaN. * Explicitly specify the same non-determinism for the minnum/maxnum based vector reductions as well. * Explicitly specify the meaning of nsz on float min/max ops. In particular, clarify that unlike normal nsz semantics, it does not allow introducing a zero with a different sign out of thin air. * Simplify the semantics comparison section. This now focuses only on NaN and signed zero behavior, but omits information about exceptions that is not relevant for these non-constrained intrinsics. Added: Modified: clang/docs/LanguageExtensions.rst llvm/docs/LangRef.rst Removed: ################################################################################ diff --git a/clang/docs/LanguageExtensions.rst b/clang/docs/LanguageExtensions.rst index 7363b237d8885..2f9be164ad0bb 100644 --- a/clang/docs/LanguageExtensions.rst +++ b/clang/docs/LanguageExtensions.rst @@ -842,20 +842,20 @@ of diff erent sizes and signs is forbidden in binary and ternary builtins. T __builtin_elementwise_max(T x, T y) return x or y, whichever is larger integer and floating point types For floating point types, follows semantics of maxNum in IEEE 754-2008. See `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. T __builtin_elementwise_min(T x, T y) return x or y, whichever is smaller integer and floating point types For floating point types, follows semantics of minNum in IEEE 754-2008. See `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. T __builtin_elementwise_maxnum(T x, T y) return x or y, whichever is larger. Follows IEEE 754-2008 floating point types semantics (maxNum) with +0.0>-0.0. See `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. T __builtin_elementwise_minnum(T x, T y) return x or y, whichever is smaller. Follows IEEE 754-2008 floating point types semantics (minNum) with +0.0>-0.0. See `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. T __builtin_elementwise_add_sat(T x, T y) return the sum of x and y, clamped to the range of integer types representable values for the signed/unsigned integer type. @@ -863,19 +863,19 @@ of diff erent sizes and signs is forbidden in binary and ternary builtins. representable values for the signed/unsigned integer type. T __builtin_elementwise_maximum(T x, T y) return x or y, whichever is larger. Follows IEEE 754-2019 floating point types semantics, see `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. T __builtin_elementwise_minimum(T x, T y) return x or y, whichever is smaller. Follows IEEE 754-2019 floating point types semantics, see `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. T __builtin_elementwise_maximumnum(T x, T y) return x or y, whichever is larger. Follows IEEE 754-2019 floating point types semantics, see `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. T __builtin_elementwise_minimumnum(T x, T y) return x or y, whichever is smaller. Follows IEEE 754-2019 floating point types semantics, see `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. T __builtin_elementwise_fshl(T x, T y, T z) perform a funnel shift left. Concatenate x and y (x is the most integer types significant bits of the wide value), the combined value is shifted @@ -940,11 +940,11 @@ Let ``VT`` be a vector type and ``ET`` the element type of ``VT``. ET __builtin_reduce_xor(VT a) ^ integer types ET __builtin_reduce_maximum(VT a) return the largest element of the vector. Follows IEEE 754-2019 floating point types semantics, see `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. ET __builtin_reduce_minimum(VT a) return the smallest element of the vector. Follows IEEE 754-2019 floating point types semantics, see `LangRef - <http://llvm.org/docs/LangRef.html#llvm-min-intrinsics-comparation>`_ + <http://llvm.org/docs/LangRef.html#i-fminmax-family>`_ for the comparison. ======================================= ====================================================================== ================================== diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst index 103058d161f86..6cb5c568347aa 100644 --- a/llvm/docs/LangRef.rst +++ b/llvm/docs/LangRef.rst @@ -17556,93 +17556,45 @@ are perfectly preserved. .. _i_fminmax_family: -'``llvm.min.*``' Intrinsics Comparation -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Floating-point min/max intrinsics comparison +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Standard: -""""""""" +LLVM supports three pairs of floating-point min/max intrinsics, which diff er +in their handling of :ref:`NaN values <floatnan>`: -IEEE754 and ISO C define some min/max operations, and they have some diff erences -on working with qNaN/sNaN and +0.0/-0.0. Here is the list: + * ``llvm.minimum`` and ``llvm.maximum``: Return NaN if one the arguments is + NaN. + * ``llvm.minimumnum`` and ``llvm.maximumnum``: Return the other argument if + one of the arguments is NaN. + * ``llvm.minnum`` and ``llvm.maxnum``: For quiet NaNs behaves like + minimumnum/maximumnum. For signaling NaNs, non-deterministically returns + NaN or the other operand. -.. list-table:: - :header-rows: 2 - - * - ``ISO C`` - - fmin/fmax - - fmininum/fmaximum - - fminimum_num/fmaximum_num - - * - ``IEEE754`` - - minNum/maxNum (2008) - - minimum/maximum (2019) - - minimumNumber/maximumNumber (2019) - - * - ``+0.0 vs -0.0`` - - either one - - +0.0 > -0.0 - - +0.0 > -0.0 - - * - ``NUM vs sNaN`` - - qNaN, invalid exception - - qNaN, invalid exception - - NUM, invalid exception - - * - ``qNaN vs sNaN`` - - qNaN, invalid exception - - qNaN, invalid exception - - qNaN, invalid exception - - * - ``NUM vs qNaN`` - - NUM, no exception - - qNaN, no exception - - NUM, no exception - -LLVM Implementation: -"""""""""""""""""""" +Additionally, each of these intrinsics supports two behaviors for signed zeros. +By default, -0.0 is considered smaller than +0.0. If the ``nsz`` flag is +specified, the order is non-deterministic: If the two inputs are zeros with +opposite sign, either input may be returned. -LLVM implements all ISO C flavors as listed in this table, except in the -default floating-point environment exceptions are ignored. The constrained -versions of the intrinsics respect the exception behavior. +The mapping between the LLVM intrinsics, C functions and IEEE 754 functions is +as follows (up to divergences permitted by the usual `NaN rules <floatnan>`): .. list-table:: :header-rows: 1 - :widths: 16 28 28 28 - - * - Operation - - minnum/maxnum - - minimum/maximum - - minimumnum/maximumnum - - * - ``NUM vs qNaN`` - - NUM, no exception - - qNaN, no exception - - NUM, no exception - - * - ``NUM vs sNaN`` - - qNaN, invalid exception - - qNaN, invalid exception - - NUM, invalid exception - - * - ``qNaN vs sNaN`` - - qNaN, invalid exception - - qNaN, invalid exception - - qNaN, invalid exception - - * - ``sNaN vs sNaN`` - - qNaN, invalid exception - - qNaN, invalid exception - - qNaN, invalid exception - - * - ``+0.0 vs -0.0`` - - +0.0(max)/-0.0(min) - - +0.0(max)/-0.0(min) - - +0.0(max)/-0.0(min) - - * - ``NUM vs NUM`` - - larger(max)/smaller(min) - - larger(max)/smaller(min) - - larger(max)/smaller(min) + + * - LLVM intrinsic + - llvm.minnum with nsz flag + - llvm.minimum + - llvm.minimumnum + + * - C function + - fmin + - fminimum + - fminimum_num + + * - IEEE 754 function + - minNum (2008) + - minimum (2019) + - minimumNumber (2019) .. _i_minnum: @@ -17679,30 +17631,36 @@ type. Semantics: """""""""" -Follows the semantics of minNum in IEEE-754-2008, except that -0.0 < +0.0 for the purposes -of this intrinsic. As for signaling NaNs, per the minNum semantics, if either operand is sNaN, -the result is qNaN. This matches the recommended behavior for the libm -function ``fmin``, although not all implementations have implemented these recommended behaviors. -If either operand is a qNaN, returns the other non-NaN operand. Returns NaN only if both operands are -NaN or if either operand is sNaN. Note that arithmetic on an sNaN doesn't consistently produce a qNaN, -so arithmetic feeding into a minnum can produce inconsistent results. For example, -``minnum(fadd(sNaN, -0.0), 1.0)`` can produce qNaN or 1.0 depending on whether ``fadd`` is folded. +If both operands are qNaNs, returns a :ref:`NaN <floatnan>`. If one operand is +qNaN and another operand is a number, returns the number. If both operands are +numbers, returns the lesser of the two arguments. -0.0 is considered to be less +than +0.0 for this intrinsic. + +If an operand is a signaling NaN, then the intrinsic will non-deterministically +either: -IEEE-754-2008 defines minNum, and it was removed in IEEE-754-2019. As the replacement, IEEE-754-2019 -defines :ref:`minimumNumber <i_minimumnum>`. + * Return a :ref:`NaN <floatnan>`. + * Or treat the signaling NaN as a quiet NaN. -If the intrinsic is marked with the nsz attribute, then the effect is as in the definition in C -and IEEE-754-2008: the result of ``minnum(-0.0, +0.0)`` may be either -0.0 or +0.0. +If the ``nsz`` flag is specified, ``llvm.minnum`` with one +0.0 and one +-0.0 operand may non-deterministically return either operand. Contrary to normal +``nsz`` semantics, if both operands have the same sign, the result must also +have the same sign. -Some architectures, such as ARMv8 (FMINNM), LoongArch (fmin), MIPSr6 (min.fmt), PowerPC/VSX (xsmindp), -have instructions that match these semantics exactly; thus it is quite simple for these architectures. -Some architectures have similar ones while they are not exact equivalent. Such as x86 implements ``MINPS``, -which implements the semantics of C code ``a<b?a:b``: NUM vs qNaN always return qNaN. ``MINPS`` can be used -if ``nsz`` and ``nnan`` are given. +When used with the ``nsz`` flag, this intrinsic follows the semantics of +``fmin`` in C and ``minNum`` in IEEE 754-2008, except for signaling NaN inputs, +which follow :ref:`LLVM's usual signaling NaN behavior <floatnan>` instead. -For existing libc implementations, the behaviors of fmin may be quite diff erent on sNaN and signed zero behaviors, -even in the same release of a single libm implementation. +The ``llvm.minnum`` intrinsic can be refined into ``llvm.minimumnum``, as the +latter exhibits a subset of behaviors of the former. + +.. warning:: + + If the intrinsic is used without nsz, not all backends currently respect the + specified signed zero ordering. Do not rely on it until this warning has + been removed. See `issue #174730 + <https://github.com/llvm/llvm-project/issues/174730>`_. .. _i_maxnum: @@ -17739,30 +17697,36 @@ type. Semantics: """""""""" -Follows the semantics of maxNum in IEEE-754-2008, except that -0.0 < +0.0 for the purposes -of this intrinsic. As for signaling NaNs, per the maxNum semantics, if either operand is sNaN, -the result is qNaN. This matches the recommended behavior for the libm -function ``fmax``, although not all implementations have implemented these recommended behaviors. -If either operand is a qNaN, returns the other non-NaN operand. Returns NaN only if both operands are -NaN or if either operand is sNaN. Note that arithmetic on an sNaN doesn't consistently produce a qNaN, -so arithmetic feeding into a maxnum can produce inconsistent results. For example, -``maxnum(fadd(sNaN, -0.0), 1.0)`` can produce qNaN or 1.0 depending on whether ``fadd`` is folded. +If both operands are qNaNs, returns a :ref:`NaN <floatnan>`. If one operand is +qNaN and another operand is a number, returns the number. If both operands are +numbers, returns the greater of the two arguments. -0.0 is considered to be +less than +0.0 for this intrinsic. + +If an operand is a signaling NaN, then the intrinsic will non-deterministically +either: -IEEE-754-2008 defines maxNum, and it was removed in IEEE-754-2019. As the replacement, IEEE-754-2019 -defines :ref:`maximumNumber <i_maximumnum>`. + * Return a :ref:`NaN <floatnan>`. + * Or treat the signaling NaN as a quiet NaN. -If the intrinsic is marked with the nsz attribute, then the effect is as in the definition in C -and IEEE-754-2008: the result of maxnum(-0.0, +0.0) may be either -0.0 or +0.0. +If the ``nsz`` flag is specified, ``llvm.maxnum`` with one +0.0 and one +-0.0 operand may non-deterministically return either operand. Contrary to normal +``nsz`` semantics, if both operands have the same sign, the result must also +have the same sign. -Some architectures, such as ARMv8 (FMAXNM), LoongArch (fmax), MIPSr6 (max.fmt), PowerPC/VSX (xsmaxdp), -have instructions that match these semantics exactly; thus it is quite simple for these architectures. -Some architectures have similar ones while they are not exact equivalent. Such as x86 implements ``MAXPS``, -which implements the semantics of C code ``a>b?a:b``: NUM vs qNaN always return qNaN. ``MAXPS`` can be used -if ``nsz`` and ``nnan`` are given. +When used with the ``nsz`` flag, this intrinsic follows the semantics of +``fmax`` in C and ``maxNum`` in IEEE 754-2008, except for signaling NaN inputs, +which follow :ref:`LLVM's usual signaling NaN behavior <floatnan>` instead. -For existing libc implementations, the behaviors of fmin may be quite diff erent on sNaN and signed zero behaviors, -even in the same release of a single libm implementation. +The ``llvm.maxnum`` intrinsic can be refined into ``llvm.maximumnum``, as the +latter exhibits a subset of behaviors of the former. + +.. warning:: + + If the intrinsic is used without nsz, not all backends currently respect the + specified signed zero ordering. Do not rely on it until this warning has + been removed. See `issue #174730 + <https://github.com/llvm/llvm-project/issues/174730>`_. .. _i_minimum: @@ -17799,10 +17763,18 @@ type. Semantics: """""""""" -If either operand is a NaN, returns NaN. Otherwise returns the lesser -of the two arguments. -0.0 is considered to be less than +0.0 for this -intrinsic. Note that these are the semantics specified in the draft of -IEEE 754-2019. +If either operand is a NaN, returns a :ref:`NaN <floatnan>`. Otherwise returns +the lesser of the two arguments. -0.0 is considered to be less than +0.0 for +this intrinsic. + +This intrinsic follows the semantics of ``fminimum`` in C23 and ``minimum`` in +IEEE 754-2019, except for signaling NaN inputs, which follow +:ref:`LLVM's usual signaling NaN behavior <floatnan>` instead. + +If the ``nsz`` flag is specified, ``llvm.maximum`` with one +0.0 and one +-0.0 operand may non-deterministically return either operand. Contrary to normal +``nsz`` semantics, if both operands have the same sign, the result must also +have the same sign. .. _i_maximum: @@ -17839,10 +17811,18 @@ type. Semantics: """""""""" -If either operand is a NaN, returns NaN. Otherwise returns the greater -of the two arguments. -0.0 is considered to be less than +0.0 for this -intrinsic. Note that these are the semantics specified in the draft of -IEEE 754-2019. +If either operand is a NaN, returns a :ref:`NaN <floatnan>`. Otherwise returns +the greater of the two arguments. -0.0 is considered to be less than +0.0 for +this intrinsic. + +This intrinsic follows the semantics of ``fmaximum`` in C23 and ``maximum`` in +IEEE 754-2019, except for signaling NaN inputs, which follow +:ref:`LLVM's usual signaling NaN behavior <floatnan>` instead. + +If the ``nsz`` flag is specified, ``llvm.maximum`` with one +0.0 and one +-0.0 operand may non-deterministically return either operand. Contrary to normal +``nsz`` semantics, if both operands have the same sign, the result must also +have the same sign. .. _i_minimumnum: @@ -17885,12 +17865,17 @@ one operand is NaN (including sNaN) and another operand is a number, return the number. Otherwise returns the lesser of the two arguments. -0.0 is considered to be less than +0.0 for this intrinsic. -Note that these are the semantics of minimumNumber specified in -IEEE-754-2019 with the usual :ref:`signaling NaN <floatnan>` exception. +If the ``nsz`` flag is specified, ``llvm.minimumnum`` with one +0.0 and one +-0.0 operand may non-deterministically return either operand. Contrary to normal +``nsz`` semantics, if both operands have the same sign, the result must also +have the same sign. -It has some diff erences with '``llvm.minnum.*``': -1)'``llvm.minnum.*``' will return qNaN if either operand is sNaN. -2)'``llvm.minnum*``' may return either one if we compare +0.0 vs -0.0. +This intrinsic follows the semantics of ``fminimum_num`` in C23 and +``minimumNumber`` in IEEE 754-2019, except for signaling NaN inputs, which +follow :ref:`LLVM's usual signaling NaN behavior <floatnan>` instead. + +This intrinsic behaves the same as ``llvm.minnum`` other than its treatment of +sNaN inputs. .. _i_maximumnum: @@ -17934,12 +17919,17 @@ another operand is a number, return the number. Otherwise returns the greater of the two arguments. -0.0 is considered to be less than +0.0 for this intrinsic. -Note that these are the semantics of maximumNumber specified in -IEEE-754-2019 with the usual :ref:`signaling NaN <floatnan>` exception. +If the ``nsz`` flag is specified, ``llvm.maximumnum`` with one +0.0 and one +-0.0 operand may non-deterministically return either operand. Contrary to normal +``nsz`` semantics, if both operands have the same sign, the result must also +have the same sign. + +This intrinsic follows the semantics of ``fmaximum_num`` in C23 and +``maximumNumber`` in IEEE 754-2019, except for signaling NaN inputs, which +follow :ref:`LLVM's usual signaling NaN behavior <floatnan>` instead. -It has some diff erences with '``llvm.maxnum.*``': -1)'``llvm.maxnum.*``' will return qNaN if either operand is sNaN. -2)'``llvm.maxnum*``' may return either one if we compare +0.0 vs -0.0. +This intrinsic behaves the same as ``llvm.maxnum`` other than its treatment of +sNaN inputs. .. _int_copysign: @@ -20694,9 +20684,14 @@ The '``llvm.vector.reduce.fmax.*``' intrinsics do a floating-point ``MAX`` reduction of a vector, returning the result as a scalar. The return type matches the element-type of the vector input. -This instruction has the same comparison semantics as the '``llvm.maxnum.*``' -intrinsic. If the intrinsic call has the ``nnan`` fast-math flag, then the -operation can assume that NaNs are not present in the input vector. +This instruction has the same comparison and ``nsz`` semantics as the +'``llvm.maxnum.*``' intrinsic. + +If any of the vector elements is a signaling NaN, the intrinsic will +non-deterministically either: + + * Return a :ref:`NaN <floatnan>`. + * Treat the signaling NaN as a quiet NaN. Arguments: """""""""" @@ -20723,9 +20718,14 @@ The '``llvm.vector.reduce.fmin.*``' intrinsics do a floating-point ``MIN`` reduction of a vector, returning the result as a scalar. The return type matches the element-type of the vector input. -This instruction has the same comparison semantics as the '``llvm.minnum.*``' -intrinsic. If the intrinsic call has the ``nnan`` fast-math flag, then the -operation can assume that NaNs are not present in the input vector. +This instruction has the same comparison and ``nsz`` semantics as the +'``llvm.minnum.*``' intrinsic. + +If any of the vector elements is a signaling NaN, the intrinsic will +non-deterministically either: + + * Return a :ref:`NaN <floatnan>`. + * Treat the signaling NaN as a quiet NaN. Arguments: """""""""" _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
