Skip to content

[LangRef] Clarify specification for float min/max operations #172012

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
nikic wants to merge 2 commits into
base: main
Choose a base branch
from
Open

[LangRef] Clarify specification for float min/max operations #172012

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0e5a0b3
[LangRef] Clarify specification for float min/max operations
nikic Dec 12, 2025
5b389dc
Drop redundant nnan sentences
nikic Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 72 additions & 140 deletions llvm/docs/LangRef.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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``.
Copy link
Member

@jyknight jyknight Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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."

Copy link
Contributor Author

@nikic nikic Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@jyknight jyknight Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@nikic nikic Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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.
Copy link
Contributor

@jcranmer-intel jcranmer-intel Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).


.. _i_maxnum:

Expand Down Expand Up @@ -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.
Copy link
Contributor

@RalfJung RalfJung Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth mentioning IEEE-754 maxnum? With the nsz flag, it matches that, modulo the SNaN exception.


.. _i_minimum:

Expand Down Expand Up @@ -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.
Comment on lines 17440 to 17441
Copy link
Contributor

@jcranmer-intel jcranmer-intel Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove "the draft of" here; it's been released for a while.


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
Expand Down Expand Up @@ -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.
Comment on lines 17485 to 17486
Copy link
Contributor

@RalfJung RalfJung Dec 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)


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
Expand Down Expand Up @@ -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
Copy link
Member

@jyknight jyknight Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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."

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:

Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -20379,9 +20301,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:
""""""""""
Expand All @@ -20408,9 +20335,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:
""""""""""
Expand Down
Loading