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

[Serge Pavlov via Phabricator via cfe-commits]

sepavloff 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.
+
----------------
xiongji90 wrote:
> rjmccall wrote:
> > 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.
> > 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.
> 
> Hi, @sepavloff 
> Could you provide your insight here?
> Thanks very much.
Such note is useful for any function that operates floating-point environment. It makes sense to put such functions to a separate section, like `Floating-point environment access` or something similar. Now only `__builtin_flt_rounds` and `__builtin_set_flt_rounds` are here but other builtins like `fesetmode`, `fesetenv` and similar can appear later on. At the beginning of this section the explanation about FP environment is quite useful.

```
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 latest standard draft (https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3088.pdf) says (7.6.1p2):
```
The FENV_ACCESS pragma provides a means to inform the implementation when a program might
access the floating-point environment to test floating-point status flags or run under non-default
floating-point control modes.
```
So, reading FP environment (made by `__builtin_flt_rounds`) does not require special arrangements. It however is worth mentioning that in this case the compiler may assume default values instead of reading them from hardware.

```
- 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.
```
Here `dynamic access` may be confusing. Maybe describe it more verbose, like:
```
This does not permit changing rounding mode by other means, including call of `__builtin_set_flt_rounds` or `fesetround`.
```

```
- 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.
```
According to the standard draft (7.6.2p4):
```
...If no FENV_ROUND pragma is in effect, or the specified constant rounding mode is FE_DYNAMIC,
rounding is according to the mode specified by the dynamic floating-point environment, which is the
dynamic rounding mode that was established either at thread creation or by a call to fesetround,
fesetmode, fesetenv, or feupdateenv. If the FE_DYNAMIC mode is specified and FENV_ACCESS is
“off”, the translator may assume that the default rounding mode is in effect.
```
This pragma does not set rounding mode (in contrast to the first variant), it must be set by other means, and `__builtin_set_flt_rounds` may be used for that.

```- 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.
```
Again, `dynamic access` may be unclear here, maybe we can use `any access`? 


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188