Skip to content

Commit 91f5076

Browse files
committed
clarify which part is the payload and which operations are not affected; add list of known-broken cases
1 parent ad615db commit 91f5076

File tree

1 file changed

+52
-19
lines changed

1 file changed

+52
-19
lines changed

llvm/docs/LangRef.rst

+52-19
Original file line numberDiff line numberDiff line change
@@ -3398,25 +3398,44 @@ round-to-nearest rounding mode, and subnormals are assumed to be preserved.
33983398
Running default LLVM code in an environment where these assumptions are not met
33993399
can lead to undefined behavior.
34003400

3401-
The representation bits of a floating-point value do not mutate arbitrarily; if
3402-
there is no floating-point operation being performed, the NaN payload (if any)
3403-
is preserved.
3401+
Code that requires different behavior than this should use the
3402+
:ref:`Constrained Floating-Point Intrinsics <constrainedfp>`.
3403+
3404+
.. _floatnan:
3405+
3406+
Behavior of Floating-Point NaN values
3407+
-------------------------------------
3408+
3409+
A floating-point NaN value consists of a sign bit, a quiet/signaling bit, and a
3410+
payload (which makes up the rest of the mantissa except for the quiet/signaling
3411+
bit). LLVM assumes that the quiet/signaling bit being set to ``1`` indicates a
3412+
quiet NaN (QNan), and a value of ``0`` indicates a signaling NaN (SNaN). In the
3413+
following we will hence just call it the "quiet bit"
3414+
3415+
The representation bits of a floating-point value do not mutate arbitrarily; in
3416+
particular, if there is no floating-point operation being performed, NaN signs,
3417+
quiet bits, and payloads are preserved.
3418+
3419+
For the purpose of this section, ``bitcast`` as well as the following operations
3420+
are not "floating-point math operations": ``fneg``, ``llvm.fabs``, and
3421+
``llvm.copysign``. They act directly on the underlying bit representation and
3422+
never change anything except for the sign bit.
34043423

34053424
When a floating-point math operation produces a NaN value, the result has a
3406-
non-deterministic sign. The payload is non-deterministically chosen from the
3407-
following set:
3408-
3409-
- The payload that is all-zero except that the ``quiet`` bit is set.
3410-
("Preferred NaN" case)
3411-
- The payload of any input operand that is a NaN, bit-wise ORed with a payload that has
3412-
the ``quiet`` bit set. ("Quieting NaN propagation" case)
3413-
- The payload of any input operand that is a NaN. ("Unchanged NaN propagation" case)
3414-
- A target-specific set of further NaN payloads, that definitely all have their
3415-
``quiet`` bit set. The set can depend on the payloads of the input NaNs.
3416-
This set is empty on x86 and ARM, but can be non-empty on other architectures.
3417-
(For instance, on wasm, if any input NaN is not the preferred NaN, then
3418-
this set contains all quiet NaNs; otherwise, it is empty.
3419-
On SPARC, this set consists of the all-one payload.)
3425+
non-deterministic sign. The quiet bit and payload are non-deterministically
3426+
chosen from the following set of options:
3427+
3428+
- The quiet bit is set and the payload is all-zero. ("Preferred NaN" case)
3429+
- The quiet bit is set and the payload is copied from any input operand that is
3430+
a NaN. ("Quieting NaN propagation" case)
3431+
- The quiet bit and payload are copied from any input operand that is a NaN.
3432+
("Unchanged NaN propagation" case)
3433+
- The quiet bit is set and the payload is picked from a target-specific set of
3434+
further possible NaN payloads. The set can depend on the payloads of the input
3435+
NaNs. This set is empty on x86 and ARM, but can be non-empty on other
3436+
architectures. (For instance, on wasm, if any input NaN does not have the
3437+
preferred all-zero payload, then this set contains all possible payloads;
3438+
otherwise, it is empty. On SPARC, this set consists of the all-one payload.)
34203439

34213440
In particular, if all input NaNs are quiet, then the output NaN is definitely
34223441
quiet. Signaling NaN outputs can only occur if they are provided as an input
@@ -3427,8 +3446,22 @@ quiet NaNs. For example, "pow(1.0, SNaN)" may be simplified to 1.0.
34273446

34283447
Code that requires different behavior than this should use the
34293448
:ref:`Constrained Floating-Point Intrinsics <constrainedfp>`.
3430-
In particular, constrained intrinsics rule out the "Unchanged NaN propagation" case;
3431-
they are guaranteed to return a QNaN.
3449+
In particular, constrained intrinsics rule out the "Unchanged NaN propagation"
3450+
case; they are guaranteed to return a QNaN.
3451+
3452+
Unfortunately, due to hard-or-impossible-to-fix issues, LLVM violates its own
3453+
specification on some architectures:
3454+
- x86-32 without SSE2 enabled may convert floating-point values to x86_fp80 and
3455+
back when performing floating-point math operations; this can lead to results
3456+
with different precision than expected and it can alter NaN values. Since
3457+
optimizations can make contradiction assumptions, this can lead to arbitrary
3458+
miscompilations. See `issue #44218
3459+
<https://github.com/llvm/llvm-project/issues/44218>`_.
3460+
- x86-32 (even with SSE2 enabled) may implicitly perform such a conversion on
3461+
values returned from a function.
3462+
- Older MIPS versions use the opposite polarity for the quiet/signaling bit, and
3463+
LLVM does not correctly represent this. See `issue #60796
3464+
<https://github.com/llvm/llvm-project/issues/60796>`_.
34323465

34333466
.. _fastmath:
34343467

0 commit comments

Comments
 (0)