[LangRef] Clarify specification for float min/max operations #172012
+72
−140
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.
Member
|
@llvm/pr-subscribers-llvm-ir Author: Nikita Popov (nikic) ChangesThis 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:
Full diff: https://github.com/llvm/llvm-project/pull/172012.diff 1 Files Affected:
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:
""""""""""
|
RalfJung
reviewed
Dec 12, 2025
llvm/docs/LangRef.rst
Outdated
| * 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. |
Contributor
There was a problem hiding this comment.
If the assumption is violated, then ... UB? poison? undef?
Contributor
Author
There was a problem hiding this comment.
This is a pre-existing sentence, just moved slightly. I went ahead and just deleted them entirely, because this is just standard nnan semantics and does not require explicit mention.
RalfJung
reviewed
Dec 12, 2025
Comment on lines
17485
to
17486
| intrinsic. Note that these are the semantics specified in the draft of | ||
| IEEE 754-2019. |
Contributor
There was a problem hiding this comment.
Suggested change
| intrinsic. Note that these are the semantics specified in the draft of | |
| IEEE 754-2019. | |
| intrinsic. Note that these are the semantics of maximum specified in | |
| IEEE-754-2019 with the usual :ref:`signaling NaN <floatnan>` exception. |
For consistency with maximumNumber.
(same suggestion for minimum)
RalfJung
reviewed
Dec 12, 2025
| 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. |
Contributor
There was a problem hiding this comment.
Is it worth mentioning IEEE-754 maxnum? With the nsz flag, it matches that, modulo the SNaN exception.
Contributor
|
This sounds good to me! I don't have a strong opinion on whether |
jyknight
reviewed
Dec 12, 2025
| 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``. |
Member
There was a problem hiding this comment.
Documenting how this differs from minimumnum is a good idea, but having it in this bullet point seems confusing. I suggest to move it out, maybe to the top paragraph, saying something like "This behaves identically to llvm.minimumnum other than its treatment of sNaN inputs."
Contributor
Author
There was a problem hiding this comment.
What I was trying to highlight here is that minnum non-deterministically chooses between two behaviors, and one of those behaviors is equivalent to minimumnum. This is what makes it legal to refine minnum to minimumnum.
Member
There was a problem hiding this comment.
Embedding the comment within "If an operand is a signaling NaN [...]" doesn't clearly communicate that minnum is equivalent to minimumnum for everything other than sNaN.
Contributor
Author
There was a problem hiding this comment.
Ah yes, I see what you mean. I guess I can just explicitly say that minnum can be refined to minimumnum and save people the inference.
Member
There was a problem hiding this comment.
Nit: "returns a :ref:`NaN <floatnan>`" for consistency with other locations.
| 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 |
Member
There was a problem hiding this comment.
Doesn't need to re-explain what the semantics of minnum. I suggest to use the same sentence I suggested for minnum, and similarly place it in the top paragraph, "This behaves identically to llvm.minnum other than its treatment of sNaN inputs."
Contributor
jcranmer-intel
left a comment
There was a problem hiding this comment.
I do somewhat miss having the table that organizes all of the different flavors of min/max operations to help identify which ones are in use.
That said, I've long been considering the need to have a dedicated docs page on floating-point semantics for LLVM IR and what different stakeholders need to understand about those semantics (like the existing atomics page), and the table would definitely fit there better. This entire saga is upping work on that document in my priority list, but nothing's going to happen before the end of the calendar year.
| 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. |
Contributor
There was a problem hiding this comment.
I would mention the equivalence to IEEE 754-2008's minNum here, I think.
(IEEE 754-2008 minNum has the same semantics as C's fmin with respect to sNaN (if supported) and indifference as to which value is returned for -0/+0--I'm not entirely clear how many people in the discussion are aware of this equivalency, so it's better to just spell it out).
Comment on lines
17440
to
17441
| intrinsic. Note that these are the semantics specified in the draft of | ||
| IEEE 754-2019. |
Contributor
There was a problem hiding this comment.
Remove "the draft of" here; it's been released for a while.
arsenm
reviewed
Dec 12, 2025
Contributor
arsenm
left a comment
There was a problem hiding this comment.
So if it's nondeterministic, what do we constant fold to for a signaling nan?
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
6 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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: