doc: Clarify FENV_ACCESS pragma semantics WRT `-ftrapping-math'

Our documentation indicates that it is the `-frounding-math' invocation 
option that controls whether we respect what the FENV_ACCESS pragma 
would imply, should we implement it, regarding the floating point 
environment.  It is only a part of the picture however, because the 
`-ftrapping-math' invocation option also affects how we handle said 
environment.  Clarify that in the description of both options then, as 
well as the FENV_ACCESS pragma itself.

	gcc/
	* doc/implement-c.texi (Floating point implementation): Mention
	`-fno-trapping-math' in the context of FENV_ACCESS pragma.
	* doc/invoke.texi (Optimize Options): Clarify FENV_ACCESS pragma
	implication in the descriptions of `-fno-trapping-math' and 
	`-frounding-math'.
---
Hi,

 Discovered in the course of investigating RISC-V unordered comparisons, 
c.f. <https://gcc.gnu.org/pipermail/gcc-patches/2022-July/597767.html>.

  Maciej
---
 gcc/doc/implement-c.texi |    3 ++-
 gcc/doc/invoke.texi      |    8 +++++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

gcc-doc-fenv-access-trapping.diff

On Tue, Jul 19, 2022 at 2:24 PM Maciej W. Rozycki <macro@embecosm.com> wrote:
>
> Our documentation indicates that it is the `-frounding-math' invocation
> option that controls whether we respect what the FENV_ACCESS pragma
> would imply, should we implement it, regarding the floating point
> environment.  It is only a part of the picture however, because the
> `-ftrapping-math' invocation option also affects how we handle said
> environment.  Clarify that in the description of both options then, as
> well as the FENV_ACCESS pragma itself.

I'll let Joseph comment on the patch since he wrote multiple times how
things should behave (I think it's OK).

We might want to split -ftrapping-math into -fieee-exceptions (whether
we care about the IEEE exception state) and -ftrapping-math (we
assume the user might have enabled the CPU to trap on IEEE
exceptions).  It might be also worth to document that any
inspection/modification of the FP state during asynchronous events
is not supported.

It was already mentioned that our default of -ftrapping-math -fno-rounding-math
doesn't make much sense given we don't really support inspecting the
IEEE exceptions state but -ftrapping-math makes us only careful about
CPU traps caused by IEEE exceptions which isn't the default behavior
anywhere (and should be discouraged in general).  Together with better
documentation I'd support trying to change the default of this for GCC 13.

>         gcc/
>         * doc/implement-c.texi (Floating point implementation): Mention
>         `-fno-trapping-math' in the context of FENV_ACCESS pragma.
>         * doc/invoke.texi (Optimize Options): Clarify FENV_ACCESS pragma
>         implication in the descriptions of `-fno-trapping-math' and
>         `-frounding-math'.
> ---
> Hi,
>
>  Discovered in the course of investigating RISC-V unordered comparisons,
> c.f. <https://gcc.gnu.org/pipermail/gcc-patches/2022-July/597767.html>.
>
>   Maciej
> ---
>  gcc/doc/implement-c.texi |    3 ++-
>  gcc/doc/invoke.texi      |    8 +++++++-
>  2 files changed, 9 insertions(+), 2 deletions(-)
>
> gcc-doc-fenv-access-trapping.diff
> Index: gcc/gcc/doc/implement-c.texi
> ===================================================================
> --- gcc.orig/gcc/doc/implement-c.texi
> +++ gcc/gcc/doc/implement-c.texi
> @@ -339,7 +339,8 @@ This is subject to change.
>  7.6.1).}
>
>  This pragma is not implemented, but the default is to ``off'' unless
> -@option{-frounding-math} is used in which case it is ``on''.
> +@option{-frounding-math} is used and @option{-fno-trapping-math} is not
> +in which case it is ``on''.
>
>  @item
>  @cite{Additional floating-point exceptions, rounding modes, environments,
> Index: gcc/gcc/doc/invoke.texi
> ===================================================================
> --- gcc.orig/gcc/doc/invoke.texi
> +++ gcc/gcc/doc/invoke.texi
> @@ -13513,6 +13513,11 @@ math functions.
>
>  The default is @option{-ftrapping-math}.
>
> +Future versions of GCC may provide finer control of this setting
> +using C99's @code{FENV_ACCESS} pragma.  This command-line option
> +will be used along with @option{-frounding-math} to specify the
> +default state for @code{FENV_ACCESS}.
> +
>  @item -frounding-math
>  @opindex frounding-math
>  Disable transformations and optimizations that assume default floating-point
> @@ -13531,7 +13536,8 @@ This option is experimental and does not
>  disable all GCC optimizations that are affected by rounding mode.
>  Future versions of GCC may provide finer control of this setting
>  using C99's @code{FENV_ACCESS} pragma.  This command-line option
> -will be used to specify the default state for @code{FENV_ACCESS}.
> +will be used along with @option{-ftrapping-math} to specify the
> +default state for @code{FENV_ACCESS}.
>
>  @item -fsignaling-nans
>  @opindex fsignaling-nans

On Tue, 19 Jul 2022, Maciej W. Rozycki wrote:

> Our documentation indicates that it is the `-frounding-math' invocation 
> option that controls whether we respect what the FENV_ACCESS pragma 
> would imply, should we implement it, regarding the floating point 
> environment.  It is only a part of the picture however, because the 
> `-ftrapping-math' invocation option also affects how we handle said 
> environment.  Clarify that in the description of both options then, as 
> well as the FENV_ACCESS pragma itself.
> 
> 	gcc/
> 	* doc/implement-c.texi (Floating point implementation): Mention
> 	`-fno-trapping-math' in the context of FENV_ACCESS pragma.
> 	* doc/invoke.texi (Optimize Options): Clarify FENV_ACCESS pragma
> 	implication in the descriptions of `-fno-trapping-math' and 
> 	`-frounding-math'.

OK.

On Wed, 27 Jul 2022, Joseph Myers wrote:

> > 	gcc/
> > 	* doc/implement-c.texi (Floating point implementation): Mention
> > 	`-fno-trapping-math' in the context of FENV_ACCESS pragma.
> > 	* doc/invoke.texi (Optimize Options): Clarify FENV_ACCESS pragma
> > 	implication in the descriptions of `-fno-trapping-math' and 
> > 	`-frounding-math'.
> 
> OK.

 I have committed this change, thank you for your review.

  Maciej