Skip to content
Permalink
Browse files

Revert "Create UsersManual section entitled 'Controlling Floating Point"

This reverts commit a08d5a4.

llvm-svn: 372185
  • Loading branch information
erichkeane committed Sep 17, 2019
1 parent 5c62152 commit f478c8bf92652151a73008ebc5c01b210e184ce7
Showing with 30 additions and 159 deletions.
  1. +30 −159 clang/docs/UsersManual.rst
@@ -1128,165 +1128,6 @@ number of cases where the compilation environment is tightly controlled
and the precompiled header cannot be generated after headers have been
installed.

.. _controlling-fp-behavior:

Controlling Floating Point Behavior
-----------------------------------

Clang provides a number of ways to control floating point behavior. The options
are listed below.

.. option:: -ffast-math

Enable fast-math mode. This option lets the
compiler make aggressive, potentially-lossy assumptions about
floating-point math. These include:

* Floating-point math obeys regular algebraic rules for real numbers (e.g.
``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and
``(a + b) * c == a * c + b * c``),
* Operands to floating-point operations are not equal to ``NaN`` and
``Inf``, and
* ``+0`` and ``-0`` are interchangeable.

``-ffast-math`` also defines the ``__FAST_MATH__`` preprocessor
macro. Some math libraries recognize this macro and change their behavior.
With the exception of ``-ffp-contract=fast``, using any of the options
below to disable any of the individual optimizations in ``-ffast-math``
will cause ``__FAST_MATH__`` to no longer be set.

This option implies:

* ``-fno-honor-infinities``

* ``-fno-honor-nans``

* ``-fno-math-errno``

* ``-ffinite-math``

* ``-fassociative-math``

* ``-freciprocal-math``

* ``-fno-signed-zeros``

* ``-fno-trapping-math``

* ``-ffp-contract=fast``

.. option:: -fdenormal-fp-math=<value>

Select which denormal numbers the code is permitted to require.

Valid values are:

* ``ieee`` - IEEE 754 denormal numbers
* ``preserve-sign`` - the sign of a flushed-to-zero number is preserved in the sign of 0
* ``positive-zero`` - denormals are flushed to positive zero

Defaults to ``ieee``.

.. option:: -f[no-]strict-float-cast-overflow

When a floating-point value is not representable in a destination integer
type, the code has undefined behavior according to the language standard.
By default, Clang will not guarantee any particular result in that case.
With the 'no-strict' option, Clang attempts to match the overflowing behavior
of the target's native float-to-int conversion instructions.

.. option:: -f[no-]math-errno

Require math functions to indicate errors by setting errno.
The default varies by ToolChain. ``-fno-math-errno`` allows optimizations
that might cause standard C math functions to not set ``errno``.
For example, on some systems, the math function ``sqrt`` is specified
as setting ``errno`` to ``EDOM`` when the input is negative. On these
systems, the compiler cannot normally optimize a call to ``sqrt`` to use
inline code (e.g. the x86 ``sqrtsd`` instruction) without additional
checking to ensure that ``errno`` is set appropriately.
``-fno-math-errno`` permits these transformations.

On some targets, math library functions never set ``errno``, and so
``-fno-math-errno`` is the default. This includes most BSD-derived
systems, including Darwin.

.. option:: -f[no-]trapping-math

``-fno-trapping-math`` allows optimizations that assume that
floating point operations cannot generate traps such as divide-by-zero,
overflow and underflow. Defaults to ``-ftrapping-math``.
Currently this option has no effect.

.. option:: -ffp-contract=<value>

Specify when the compiler is permitted to form fused floating-point
operations, such as fused multiply-add (FMA). Fused operations are
permitted to produce more precise results than performing the same
operations separately.

The C standard permits intermediate floating-point results within an
expression to be computed with more precision than their type would
normally allow. This permits operation fusing, and Clang takes advantage
of this by default. This behavior can be controlled with the
``FP_CONTRACT`` pragma. Please refer to the pragma documentation for a
description of how the pragma interacts with this option.

Valid values are:

* ``fast`` (everywhere)
* ``on`` (according to FP_CONTRACT pragma, default)
* ``off`` (never fuse)

.. option:: -f[no-]honor-infinities

If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
has the same effect as specifying ``-ffinite-math``.

.. option:: -f[no-]honor-nans

If both ``-fno-honor-infinities`` and ``-fno-honor-nans`` are used,
has the same effect as specifying ``-ffinite-math``.

.. option:: -f[no-]signed-zeros

Allow optimizations that ignore the sign of floating point zeros.
Defaults to ``-fno-signed-zeros``.

.. option:: -f[no-]associative-math

Allow floating point operations to be reassociated.
Defaults to ``-fno-associative-math``.

.. option:: -f[no-]reciprocal-math

Allow division operations to be transformed into multiplication by a
reciprocal. This can be significantly faster than an ordinary division
but can also have significantly less precision. Defaults to
``-fno-reciprocal-math``.

.. option:: -f[no-]unsafe-math-optimizations

Allow unsafe floating-point optimizations. Also implies:

* ``-fassociative-math``
* ``-freciprocal-math``
* ``-fno-signed-zeroes``
* ``-fno-trapping-math``.

Defaults to ``-fno-unsafe-math-optimizations``.

.. option:: -f[no-]finite-math

Allow floating-point optimizations that assume arguments and results are
not NaNs or +-Inf. This defines the ``__FINITE_MATH_ONLY__`` preprocessor macro.
Also implies:

* ``-fno-honor-infinities``
* ``-fno-honor-nans``

Defaults to ``-fno-finite-math``.

.. _controlling-code-generation:

Controlling Code Generation
@@ -1425,6 +1266,36 @@ are listed below.
This enables better devirtualization. Turned off by default, because it is
still experimental.

.. option:: -ffast-math

Enable fast-math mode. This defines the ``__FAST_MATH__`` preprocessor
macro, and lets the compiler make aggressive, potentially-lossy assumptions
about floating-point math. These include:

* Floating-point math obeys regular algebraic rules for real numbers (e.g.
``+`` and ``*`` are associative, ``x/y == x * (1/y)``, and
``(a + b) * c == a * c + b * c``),
* operands to floating-point operations are not equal to ``NaN`` and
``Inf``, and
* ``+0`` and ``-0`` are interchangeable.

.. option:: -fdenormal-fp-math=[values]

Select which denormal numbers the code is permitted to require.

Valid values are: ``ieee``, ``preserve-sign``, and ``positive-zero``,
which correspond to IEEE 754 denormal numbers, the sign of a
flushed-to-zero number is preserved in the sign of 0, denormals are
flushed to positive zero, respectively.

.. option:: -f[no-]strict-float-cast-overflow

When a floating-point value is not representable in a destination integer
type, the code has undefined behavior according to the language standard.
By default, Clang will not guarantee any particular result in that case.
With the 'no-strict' option, Clang attempts to match the overflowing behavior
of the target's native float-to-int conversion instructions.

.. option:: -fwhole-program-vtables

Enable whole-program vtable optimizations, such as single-implementation

0 comments on commit f478c8b

Please sign in to comment.
You can’t perform that action at this time.