Skip to content

[IR] LangRef: state explicitly that floats generally behave according to IEEE-754 #102140

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

Merged
merged 7 commits into from
Oct 11, 2024
Merged

[IR] LangRef: state explicitly that floats generally behave according to IEEE-754 #102140

Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
d643f2c
LangRef: state explicitly that floats generally behave according to I…
RalfJung Aug 6, 2024
648d3ce
Floating-Point Types: move comment about IEEE formats into the table
RalfJung Aug 21, 2024
d107aa0
spell out more clearly which part of IEEE-754 we are importing
RalfJung Aug 21, 2024
cd80e84
de-duplicate paragraph about running code in non-default floatenv
RalfJung Aug 21, 2024
7d4deb8
move floatsem section after the more generally applicable floatenv an…
RalfJung Aug 27, 2024
29f5c14
also mention fpmath metadata, and add more links
RalfJung Oct 11, 2024
f909f35
correctness is perfection
RalfJung Oct 11, 2024
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
65 changes: 48 additions & 17 deletions llvm/docs/LangRef.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3582,11 +3582,12 @@ status flags are not observable. Therefore, floating-point math operations do
not have side effects and may be speculated freely. Results assume the
round-to-nearest rounding mode, and subnormals are assumed to be preserved.

Copy link
Contributor

Choose a reason for hiding this comment

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

Also the denormal exception

Copy link
Contributor Author

@RalfJung RalfJung Aug 13, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

What is the denormal exception? Is this about what happens when denormal-fp-math is set, but the default is to be IEEE-compatible?

Given that IEEE says that denormals are not flushed and LLVM assumes the same by default, I don't think this is an exception from "IR float ops behave according to IEEE".

Running LLVM code in an environment where these assumptions are not met can lead
to undefined behavior. The ``strictfp`` and ``denormal-fp-math`` attributes as
well as :ref:`Constrained Floating-Point Intrinsics <constrainedfp>` can be used
to weaken LLVM's assumptions and ensure defined behavior in non-default
floating-point environments; see their respective documentation for details.
Running LLVM code in an environment where these assumptions are not met
typically leads to undefined behavior. The ``strictfp`` and ``denormal-fp-math``
attributes as well as :ref:`Constrained Floating-Point Intrinsics
<constrainedfp>` can be used to weaken LLVM's assumptions and ensure defined
behavior in non-default floating-point environments; see their respective
documentation for details.

.. _floatnan:

Expand All @@ -3608,10 +3609,11 @@ are not "floating-point math operations": ``fneg``, ``llvm.fabs``, and
``llvm.copysign``. These operations act directly on the underlying bit
representation and never change anything except possibly for the sign bit.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This paragraph is basically an exact duplicate of the second paragraph in the floatenv section, so I am inclined to remove it... but your draft did include such a sentence.

The way I view it, the floatsem section is just about the IEEE float formats. This paragraph is true for all formats so it should be in the floatenv section.

For floating-point math operations, unless specified otherwise, the following
rules apply when a NaN value is returned: the result has a non-deterministic
sign; the quiet bit and payload are non-deterministically chosen from the
following set of options:
Floating-point math operations that return a NaN are an exception from the
general principle that LLVM implements IEEE-754 semantics. Unless specified
otherwise, the following rules apply whenever the IEEE-754 semantics say that a
NaN value is returned: the result has a non-deterministic sign; the quiet bit
and payload are non-deterministically chosen from the following set of options:

- The quiet bit is set and the payload is all-zero. ("Preferred NaN" case)
- The quiet bit is set and the payload is copied from any input operand that is
Expand Down Expand Up @@ -3657,6 +3659,39 @@ specification on some architectures:
LLVM does not correctly represent this. See `issue #60796
<https://github.com/llvm/llvm-project/issues/60796>`_.

.. _floatsem:

Floating-Point Semantics
------------------------

This section defines the semantics for core floating-point operations on types
that use a format specified by IEEE-745. These types are: ``half``, ``float``,
``double``, and ``fp128``, which correspond to the binary16, binary32, binary64,
and binary128 formats, respectively. The "core" operations are those defined in
section 5 of IEEE-745, which all have corresponding LLVM operations.

The value returned by those operations matches that of the corresponding
IEEE-754 operation executed in the :ref:`default LLVM floating-point environment
<floatenv>`, except that the behavior of NaN results is instead :ref:`as
specified here <floatnan>`. In particular, such a floating-point instruction
returning a non-NaN value is guaranteed to always return the same bit-identical
result on all machines and optimization levels.

This means that optimizations and backends may not change the observed bitwise
result of these operations in any way (unless NaNs are returned), and frontends
can rely on these operations providing perfectly rounded results as described in
the standard.

Copy link
Contributor

Choose a reason for hiding this comment

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

Term is usually "correctly rounded" not "perfectly rounded"

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ah, fair. It should be clear from context who is in charge of defining "correct" here (namely, IEEE-754).

I am adding these edits as new commits so it's easy to see what changed; I can squash them later or now if you prefer.

(Note that this is only about the value returned by these operations; see the
:ref:`floating-point environment section <floatenv>` regarding flags and
exceptions.)

Various flags and attributes can alter the behavior of these operations and thus
Copy link
Contributor

Choose a reason for hiding this comment

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

and metadata (e.g. !fpmath)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ah, I didn't know about that one, thanks. I added a mention, and also used the opportunity to add links for strictfp and denormal-fp-math.

make them not bit-identical across machines and optimization levels any more:
most notably, the :ref:`fast-math flags <fastmath>` as well as the ``strictfp``
and ``denormal-fp-math`` attributes. See their corresponding documentation for
details.

.. _fastmath:

Fast-Math Flags
Expand Down Expand Up @@ -3943,7 +3978,7 @@ Floating-Point Types
- Description

* - ``half``
- 16-bit floating-point value
- 16-bit floating-point value (IEEE-754 binary16)

* - ``bfloat``
- 16-bit "brain" floating-point value (7-bit significand). Provides the
Expand All @@ -3952,24 +3987,20 @@ Floating-Point Types
extensions and Arm's ARMv8.6-A extensions, among others.

* - ``float``
- 32-bit floating-point value
- 32-bit floating-point value (IEEE-754 binary32)

* - ``double``
- 64-bit floating-point value
- 64-bit floating-point value (IEEE-754 binary64)

* - ``fp128``
- 128-bit floating-point value (113-bit significand)
- 128-bit floating-point value (IEEE-754 binary128)

* - ``x86_fp80``
- 80-bit floating-point value (X87)

* - ``ppc_fp128``
- 128-bit floating-point value (two 64-bits)

The binary format of half, float, double, and fp128 correspond to the
IEEE-754-2008 specifications for binary16, binary32, binary64, and binary128
respectively.

X86_amx Type
""""""""""""

Expand Down
Loading