@@ -3398,25 +3398,44 @@ round-to-nearest rounding mode, and subnormals are assumed to be preserved.
3398
3398
Running default LLVM code in an environment where these assumptions are not met
3399
3399
can lead to undefined behavior.
3400
3400
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.
3404
3423
3405
3424
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.)
3420
3439
3421
3440
In particular, if all input NaNs are quiet, then the output NaN is definitely
3422
3441
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.
3427
3446
3428
3447
Code that requires different behavior than this should use the
3429
3448
: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>`_.
3432
3465
3433
3466
.. _fastmath:
3434
3467
0 commit comments