[PATCH] D67517: Create UsersManual section entitled 'Controlling Floating Point Behavior'

[John McCall via Phabricator via llvm-commits]

rjmccall added a comment.

Thanks!  Some wording suggestions.



================
Comment at: clang/docs/UsersManual.rst:1152
+
+  This option implies:
+
----------------
To be clear, fast math is not *equivalent* to just setting all of these separately, right?


================
Comment at: clang/docs/UsersManual.rst:1156
+
+   * ``-fno-honor-nan``
+
----------------
This isn't how these two options are spelled below.


================
Comment at: clang/docs/UsersManual.rst:1168
+
+   * ``-ffp-constract=fast``
+
----------------
Typo


================
Comment at: clang/docs/UsersManual.rst:1172
+
+   Select which denormal numbers the code is permitted to require.
+
----------------
I know this is existing text, but what does it mean to "require" a denormal number?  The values make it seem like this changes basic behavior, like a sort of rounding mode except for denormals.


================
Comment at: clang/docs/UsersManual.rst:1180
+
+   Defaults to ``ieee``.
+
----------------
mibintc wrote:
> I'm not certain this is correct description of the Default.  Previously in the documentation the default ws not described.  I looked at the code and in Target.h it is initialized to ieee but possibly other specializations would replace the initial value. 
If it's target-specific, that seems relevant to describe.


================
Comment at: clang/docs/UsersManual.rst:1188
+   With the 'no-strict' option, Clang attempts to match the overflowing behavior
+   of the target's native float-to-int conversion instructions.
+
----------------
"According to the C standard, when a floating-point value is converted to
integer type, the fractional component of the value is discarded, and if the
resulting integer is not expressible in the destination type, the conversion
has undefined behavior.  By default, Clang follows this rule strictly and does
not guarantee any particular result.  In non-strict mode, this behavior
becomes well-defined, and Clang uses the standard behavior for the target:
typically, the behavior of the target architecture's float-to-int conversion
instructions."

Ideally this would then specify that behavior for various targets.


================
Comment at: clang/docs/UsersManual.rst:1193
+   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."


================
Comment at: clang/docs/UsersManual.rst:1203
+
+   Form fused floating point operations (e.g. FMAs).  Valid values are:
+
----------------
"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.

Valid values for this option are:"

The second paragraph should probably describe how the pragma interacts with the option.


================
Comment at: clang/docs/UsersManual.rst:1213
+
+.. option:: -f[no-]honor-nans
+
----------------
cameron.mcinally wrote:
> mibintc wrote:
> > Both honor-nans and honor-infinities appear to have no effect at the moment, previously they were mapped to -menable-no-infs -menable-no-nans
> I believe others have the same problem too. All probably need to be reassessed. E.g. I think -f[no-]trapping-math isn't hooked up to anything in LLVM.
> 
> This may also get confusing when the -fp-model=/etc options are added, since they really do the same thing in different ways.
> 
> Is there a plan in place for how to handle this? Will the GCC options alias the Clang options?
If we accept these options, we should document them, even if just to say that they currently have no effect.  But I suspect that what this means is that they have no effect *separately* and we currently only enable NaN/Inf-unsafe optimizations given a more aggressive option like fast-math.


================
Comment at: clang/docs/UsersManual.rst:1229
+
+  Allow division operations to be reassociated.
+  Defaults to ``-fno-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."


Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D67517/new/

https://reviews.llvm.org/D67517