[llvm] [LangRef] Clarify specification for float min/max operations (PR #172012)
Nikita Popov via llvm-commits
llvm-commits at lists.llvm.org
Fri Dec 12 07:35:32 PST 2025
https://github.com/nikic updated https://github.com/llvm/llvm-project/pull/172012
>From 0e5a0b31ac2d18b1f7b0fb1b26cf59b5fb777510 Mon Sep 17 00:00:00 2001
From: Nikita Popov <npopov at redhat.com>
Date: Fri, 12 Dec 2025 15:06:53 +0100
Subject: [PATCH 1/2] [LangRef] Clarify specification for float min/max
operations
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.
* Remove the semantics comparison section. I tried to adjust this,
but there's just so many caveats in here that it's hard to create
something that is both concise and correct.
---
llvm/docs/LangRef.rst | 218 +++++++++++++++---------------------------
1 file changed, 78 insertions(+), 140 deletions(-)
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 5fa3a4ebb2472..3ce5244a39b31 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -17288,96 +17288,6 @@ The returned value is completely identical to the input except for the sign bit;
in particular, if the input is a NaN, then the quiet/signaling bit and payload
are perfectly preserved.
-.. _i_fminmax_family:
-
-'``llvm.min.*``' Intrinsics Comparation
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Standard:
-"""""""""
-
-IEEE754 and ISO C define some min/max operations, and they have some differences
-on working with qNaN/sNaN and +0.0/-0.0. Here is the list:
-
-.. 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:
-""""""""""""""""""""
-
-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.
-
-.. 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)
-
.. _i_minnum:
'``llvm.minnum.*``' Intrinsic
@@ -17413,30 +17323,26 @@ 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.
-IEEE-754-2008 defines minNum, and it was removed in IEEE-754-2019. As the replacement, IEEE-754-2019
-defines :ref:`minimumNumber <i_minimumnum>`.
+If an operand is a signaling NaN, then the intrinsic will non-deterministically
+either:
-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.
+ * Return a :ref:`NaN <floatnan>`.
+ * Or treat the signaling NaN as a quiet NaN. In this case the intrinsic will
+ behave the same as ``llvm.minimumnum``.
-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.
+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.
-For existing libc implementations, the behaviors of fmin may be quite different on sNaN and signed zero behaviors,
-even in the same release of a single libm implementation.
+When used with the ``nsz`` flag, this intrinsics follows the semantics of
+``fmin`` in C.
.. _i_maxnum:
@@ -17473,30 +17379,26 @@ 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.
-IEEE-754-2008 defines maxNum, and it was removed in IEEE-754-2019. As the replacement, IEEE-754-2019
-defines :ref:`maximumNumber <i_maximumnum>`.
+If an operand is a signaling NaN, then the intrinsic will non-deterministically
+either:
-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.
+ * Return a :ref:`NaN <floatnan>`.
+ * Or treat the signaling NaN as a quiet NaN. In this case the intrinsic will
+ behave the same as ``llvm.maximumnum``.
-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.
+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.
-For existing libc implementations, the behaviors of fmin may be quite different on sNaN and signed zero behaviors,
-even in the same release of a single libm implementation.
+When used with the ``nsz`` flag, this intrinsics follows the semantics of
+``fmax`` in C.
.. _i_minimum:
@@ -17538,6 +17440,11 @@ 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 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:
'``llvm.maximum.*``' Intrinsic
@@ -17578,6 +17485,11 @@ 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 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:
'``llvm.minimumnum.*``' Intrinsic
@@ -17619,12 +17531,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.
+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.
+
Note that these are the semantics of minimumNumber specified in
IEEE-754-2019 with the usual :ref:`signaling NaN <floatnan>` exception.
-It has some differences 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 differs from ``llvm.minnum`` in that it is guaranteed to treat
+sNaN the same way as qNaN. ``llvm.minnum`` will instead non-deterministically
+either act like ``llvm.minimumnum`` or return a :ref:`NaN <floatnan>`.
.. _i_maximumnum:
@@ -17668,12 +17585,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.
+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.
+
Note that these are the semantics of maximumNumber specified in
IEEE-754-2019 with the usual :ref:`signaling NaN <floatnan>` exception.
-It has some differences 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 differs from ``llvm.maxnum`` in that it is guaranteed to treat
+sNaN the same way as qNaN. ``llvm.maxnum`` will instead non-deterministically
+either act like ``llvm.maximumnum`` or return a :ref:`NaN <floatnan>`.
.. _int_copysign:
@@ -20379,9 +20301,17 @@ 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.
+
+If the intrinsic call has the ``nnan`` fast-math flag, then the operation can
+assume that NaNs are not present in the input vector.
Arguments:
""""""""""
@@ -20408,9 +20338,17 @@ 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.
+
+If the intrinsic call has the ``nnan`` fast-math flag, then the operation can
+assume that NaNs are not present in the input vector.
Arguments:
""""""""""
>From 5b389dc616df27a3730f5099029b711931c2d193 Mon Sep 17 00:00:00 2001
From: Nikita Popov <npopov at redhat.com>
Date: Fri, 12 Dec 2025 16:35:07 +0100
Subject: [PATCH 2/2] Drop redundant nnan sentences
---
llvm/docs/LangRef.rst | 6 ------
1 file changed, 6 deletions(-)
diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 3ce5244a39b31..295914071531d 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -20310,9 +20310,6 @@ non-deterministically either:
* Return a :ref:`NaN <floatnan>`.
* Treat the signaling NaN as a quiet NaN.
-If the intrinsic call has the ``nnan`` fast-math flag, then the operation can
-assume that NaNs are not present in the input vector.
-
Arguments:
""""""""""
The argument to this intrinsic must be a vector of floating-point values.
@@ -20347,9 +20344,6 @@ non-deterministically either:
* Return a :ref:`NaN <floatnan>`.
* Treat the signaling NaN as a quiet NaN.
-If the intrinsic call has the ``nnan`` fast-math flag, then the operation can
-assume that NaNs are not present in the input vector.
-
Arguments:
""""""""""
The argument to this intrinsic must be a vector of floating-point values.
More information about the llvm-commits
mailing list