[Clang][doc] -ffp-contract options and standard compliance #127621
Conversation
|
@llvm/pr-subscribers-clang Author: Sjoerd Meijer (sjoerdmeijer) ChangesWe had an internal discussion about -ffp-contract, how it compared to GCC which defaults to fast, and standard compliance. Looking at our docs, I think most information is there, but also thought it could be a little bit more explicit about when it is and isn't standard compliant. Let me know if you think this is an improvement or not; happy to abandon this if you think it is not helping much. Full diff: https://github.com/llvm/llvm-project/pull/127621.diff 1 Files Affected:
diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst
index d977868b8a2c6..8809632479a00 100644
--- a/clang/docs/UsersManual.rst
+++ b/clang/docs/UsersManual.rst
@@ -1681,19 +1681,25 @@ for more details.
permitted to produce more precise results than performing the same
operations separately.
- The C standard permits intermediate floating-point results within an
+ The C/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``
- and ``clang fp contract`` pragmas. Please refer to the pragma documentation
- for a description of how the pragmas interact with this option.
+ of this by default (``on``). Fusion across statements is non-C/C++ standard
+ compliant behavior and can be enabled (``fast``).
+
+ Fusion can be controlled with the ``FP_CONTRACT`` and ``clang fp contract``
+ pragmas. Please refer to the pragma documentation for a description of how
+ the pragmas interact with this option.
Valid values are:
- * ``fast`` (fuse across statements disregarding pragmas, default for CUDA)
- * ``on`` (fuse in the same statement unless dictated by pragmas, default for languages other than CUDA/HIP)
- * ``off`` (never fuse)
- * ``fast-honor-pragmas`` (fuse across statements unless dictated by pragmas, default for HIP)
+ * ``fast``: enable non-C/C++ standard compliant behavior and fusion across
+ statements disregarding pragmas (default for CUDA)
+ * ``on``: enable C/C++ standard complaint fusion in the same statement unless
+ dictated by pragmas (default for languages other than CUDA/HIP)
+ * ``off``: disable fusion
+ * ``fast-honor-pragmas``: fuse across statements unless dictated by pragmas
+ (default for HIP)
.. option:: -f[no-]honor-infinities
|
clang/docs/UsersManual.rst
Outdated
| and ``clang fp contract`` pragmas. Please refer to the pragma documentation | ||
| for a description of how the pragmas interact with this option. | ||
| of this by default (``on``). Fusion across statements is non-C/C++ standard | ||
| compliant behavior and can be enabled (``fast``). |
There was a problem hiding this comment.
This last sentence is a bit unclear. I would suggest " Fusion across statements is not compliant with the C/C++ standard but can be enabled using -ffp-contract=fast."
BTW, the C standard allows contraction of "expressions" saying that "a floating expression may be contracted" but the language gets imprecise if we start talking about "contraction across expressions" or "contractions across statements." I think saying "contractions across statements" is not allowed is more accurate, because we always have sub-expressions within what we're contracting. On the other hand, there are cases where we will not contract even within a statement. For example, an explicit cast in the middle of a statement prevents contraction (e.g. x = c + (float)(a * b) when a, b, and c are double). @AaronBallman can you suggest more precise wording?
clang/docs/UsersManual.rst
Outdated
| * ``off`` (never fuse) | ||
| * ``fast-honor-pragmas`` (fuse across statements unless dictated by pragmas, default for HIP) | ||
| * ``fast``: enable non-C/C++ standard compliant behavior and fusion across | ||
| statements disregarding pragmas (default for CUDA) |
There was a problem hiding this comment.
I would change the order here. Fusion across expressions is the important point for most people. Perhaps "enable fusion across expressions, breaking compliance with the C/C++ standard (default for CUDA)"?
There was a problem hiding this comment.
Done.
I did notice you're using "expressions", but I've kept "statements".
sjoerdmeijer
force-pushed
the
docs-fp-contract
branch
from
fd2cb4b to
d7483fc
Compare
clang/docs/UsersManual.rst
Outdated
| * ``off`` (never fuse) | ||
| * ``fast-honor-pragmas`` (fuse across statements unless dictated by pragmas, default for HIP) | ||
| * ``fast``: enable non-C/C++ standard compliant behavior and fusion across | ||
| statements disregarding pragmas (default for CUDA) |
There was a problem hiding this comment.
Done.
I did notice you're using "expressions", but I've kept "statements".
clang/docs/UsersManual.rst
Outdated
| @@ -1681,19 +1681,27 @@ for more details. | |||
| permitted to produce more precise results than performing the same | |||
| operations separately. | |||
|
|
|||
| The C standard permits intermediate floating-point results within an | |||
| The C/C++ standard permits intermediate floating-point results within an | |||
There was a problem hiding this comment.
| The C/C++ standard permits intermediate floating-point results within an | |
| The C/C++ standards permit intermediate floating-point results within an |
There was a problem hiding this comment.
I'd prefer C and C++ standards. Same elsewhere in the changes. :-)
clang/docs/UsersManual.rst
Outdated
| @@ -1681,19 +1681,27 @@ for more details. | |||
| permitted to produce more precise results than performing the same | |||
| operations separately. | |||
|
|
|||
| The C standard permits intermediate floating-point results within an | |||
| The C/C++ standard permits intermediate floating-point results within an | |||
There was a problem hiding this comment.
I'd prefer C and C++ standards. Same elsewhere in the changes. :-)
|
Thanks for your reviews! I will make those changes before merging this. |
We had an internal discussion about -ffp-contract, how it compared to GCC which defaults to fast, and standard compliance. Looking at our docs, I think most information is there, but also thought it could be a little bit more explicit about when it is and isn't standard compliant. Let me know if you think this is an improvement or not; happy to abandon this if you think it is not helping much.
sjoerdmeijer
force-pushed
the
docs-fp-contract
branch
from
d7483fc to
a9c669c
Compare
We had an internal discussion about -ffp-contract, how it compared to GCC which defaults to fast, and standard compliance. Looking at our docs, I think most information is there, but also thought it could be a little bit more explicit about when it is and isn't standard compliant. Let me know if you think this is an improvement or not; happy to abandon this if you think it is not helping much.