[PATCH] D146188: [Clang][DOC] Add documentation in for __builtin_flt_rounds and __builtin_set_flt_rounds

[John McCall via Phabricator via cfe-commits]

rjmccall added inline comments.


================
Comment at: clang/docs/LanguageExtensions.rst:3288
+This builtin is restrcted to work on x86 and arm targets currently. When support
+for the builtin is added for new targets, the manual should be updated accordingly.
+
----------------
This meta-commentary about when to update the manual should not go into the manual.

I'm going to insist that we talk about ``#pragma STDC FENV_ACCESS`` here.  It would be inappropriate not to, given that it's undefined behavior to use this without also using the pragma or one of those flags.  We should not be documenting features with non-obvious UB without warning.

How about:

```
By default, these builtins may not be used.  The floating point rounding mode is part of the floating point environment, and it is undefined behavior to read or modify the floating point environment, or to run code under a non-default floating point environment, unless that code is compiled under a special mode.  Clang supports three well-defined ways to control the rounding mode of floating point operations:

- The standard pragma ``#pragma STDC FENV_ROUND <mode>`` can change the rounding mode to a specific value for the operations covered by the pragma.  This does not permit dynamic access to the rounding mode, but in many cases it is sufficient to achieve the desired effect, and it is more optimizable than the alternatives below.

- The standard pragma ``#pragma STDC FENV_ROUND FE_DYNAMIC`` allows dynamic access to the floating point rounding mode (including by these builtins) in code covered by the pragma.  The command line option ``-frounding-math`` behaves as if the translation unit began with this pragma.  This pragma does not allow changes to the floating point exceptions mode and so may be more optimizable than the next alternative.

- The standard pragma ``#pragma STDC FENV_ACCESS ON`` allows dynamic access to the entire floating point environment (including by these builtins) in code covered by the pragma.  The command line option ``-ffp-model=strict`` behaves as if the translation unit began with this pragma.

Code that modifies the floating point rounding mode dynamically must take care to reset it to the default mode before returning control to code that is not compiled under one of these last two pragmas.  See the C standard for more information about these pragmas.
```

Serge, please fact-check all that.


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

https://reviews.llvm.org/D146188