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

[xiongji90 via Phabricator via cfe-commits]

This revision was automatically updated to reflect the committed changes.
xiongji90 marked an inline comment as done.
Closed by commit rG2ed77846a916: This patch adds doc for __builtin_flt_rounds 
and __builtin_set_flt_rounds (authored by xiongji90).

Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

Files:
  clang/docs/LanguageExtensions.rst
  clang/docs/UsersManual.rst


Index: clang/docs/UsersManual.rst
===
--- clang/docs/UsersManual.rst
+++ clang/docs/UsersManual.rst
@@ -1787,6 +1787,48 @@
* ``16`` - Forces ``_Float16`` operations to be emitted without using excess
  precision arithmetic.
 
+.. _floating-point-environment:
+
+Accessing the floating point environment
+
+Many targets allow floating point operations to be configured to control things
+such as how inexact results should be rounded and how exceptional conditions
+should be handled. This configuration is called the floating point environment.
+C and C++ restrict access to the floating point environment by default, and the
+compiler is allowed to assume that all operations are performed in the default
+environment. When code is compiled in this default mode, operations that depend
+on the environment (such as floating-point arithmetic and `FLT_ROUNDS`) may 
have
+undefined behavior if the dynamic environment is not the default environment; 
for
+example, `FLT_ROUNDS` may or may not simply return its default value for the 
target
+instead of reading the dynamic environment, and floating-point operations may 
be
+optimized as if the dynamic environment were the default.  Similarly, it is 
undefined
+behavior to change the floating point environment in this default mode, for 
example
+by calling the `fesetround` function.
+C provides two pragmas to allow code to dynamically modify the floating point 
environment:
+
+- ``#pragma STDC FENV_ACCESS ON`` allows dynamic changes to the entire floating
+  point environment.
+
+- ``#pragma STDC FENV_ROUND FE_DYNAMIC`` allows dynamic changes to just the 
floating
+  point rounding mode.  This may be more optimizable than ``FENV_ACCESS ON`` 
because
+  the compiler can still ignore the possibility of floating-point exceptions 
by default.
+
+Both of these can be used either at the start of a block scope, in which case
+they cover all code in that scope (unless they're turned off in a child scope),
+or at the top level in a file, in which case they cover all subsequent function
+bodies until they're turned off.  Note that it is undefined behavior to enter
+code that is *not* covered by one of these pragmas from code that *is* covered
+by one of these pragmas unless the floating point environment has been restored
+to its default state.  See the C standard for more information about these 
pragmas.
+
+The command line option ``-frounding-math`` behaves as if the translation unit
+began with ``#pragma STDC FENV_ROUND FE_DYNAMIC``. The command line option
+``-ffp-model=strict`` behaves as if the translation unit began with ``#pragma 
STDC FENV_ACCESS ON``.
+
+Code that just wants to use a specific rounding mode for specific floating 
point
+operations can avoid most of the hazards of the dynamic floating point 
environment
+by using ``#pragma STDC FENV_ROUND`` with a value other than ``FE_DYNAMIC``.
+
 .. _crtfastmath.o:
 
 A note about ``crtfastmath.o``
Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3324,7 +3324,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3332,6 +3332,28 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds`` and ``__builtin_set_flt_rounds``
+-
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+   void __builtin_set_flt_rounds(int);
+
+Returns and sets current floating point rounding mode. The encoding of returned
+values and input parameters is same as the result of FLT_ROUNDS, specified by C
+standard:
+- ``0``  - toward zero
+- ``1``  - to nearest, ties to even
+- ``2``  - toward positive infinity
+- ``3``  - toward negative infinity
+- ``4``  - to nearest, ties away from zero
+The effect of passing some other value to ``__builtin_flt_rounds`` is
+implementation-defined. ``__builtin_set_flt_rounds`` is currently only 
supported
+to work on x86, x86_64, Arm and AArch64 targets. These builtins read and modify
+the 

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

[John McCall via Phabricator via cfe-commits]

rjmccall accepted this revision.
rjmccall added a comment.
This revision is now accepted and ready to land.

Thanks!


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 marked an inline comment as done.
xiongji90 added a comment.

Hi, @rjmccall 
I updated the patch to address your previous comments, could you help review 
again?
Thanks very much.




Comment at: clang/docs/LanguageExtensions.rst:3272
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+The effect of passing some other value to ``__builtin_flt_rounds`` is

rjmccall wrote:
> I suspect this won't end up being formatted as a list; you should do 
> something like:
> 
> ```
> - ``0`` - toward zero
> - ``1`` - to nearest, ties to even
> ...
> ```
Done.
Thanks very much.


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 updated this revision to Diff 520288.
xiongji90 added a comment.

Address previous comments


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

Files:
  clang/docs/LanguageExtensions.rst
  clang/docs/UsersManual.rst


Index: clang/docs/UsersManual.rst
===
--- clang/docs/UsersManual.rst
+++ clang/docs/UsersManual.rst
@@ -1787,6 +1787,48 @@
* ``16`` - Forces ``_Float16`` operations to be emitted without using excess
  precision arithmetic.
 
+.. _floating-point-environment:
+
+Accessing the floating point environment
+
+Many targets allow floating point operations to be configured to control things
+such as how inexact results should be rounded and how exceptional conditions
+should be handled. This configuration is called the floating point environment.
+C and C++ restrict access to the floating point environment by default, and the
+compiler is allowed to assume that all operations are performed in the default
+environment. When code is compiled in this default mode, operations that depend
+on the environment (such as floating-point arithmetic and `FLT_ROUNDS`) may 
have
+undefined behavior if the dynamic environment is not the default environment; 
for
+example, `FLT_ROUNDS` may or may not simply return its default value for the 
target
+instead of reading the dynamic environment, and floating-point operations may 
be
+optimized as if the dynamic environment were the default.  Similarly, it is 
undefined
+behavior to change the floating point environment in this default mode, for 
example
+by calling the `fesetround` function.
+C provides two pragmas to allow code to dynamically modify the floating point 
environment:
+
+- ``#pragma STDC FENV_ACCESS ON`` allows dynamic changes to the entire floating
+  point environment.
+
+- ``#pragma STDC FENV_ROUND FE_DYNAMIC`` allows dynamic changes to just the 
floating
+  point rounding mode.  This may be more optimizable than ``FENV_ACCESS ON`` 
because
+  the compiler can still ignore the possibility of floating-point exceptions 
by default.
+
+Both of these can be used either at the start of a block scope, in which case
+they cover all code in that scope (unless they're turned off in a child scope),
+or at the top level in a file, in which case they cover all subsequent function
+bodies until they're turned off.  Note that it is undefined behavior to enter
+code that is *not* covered by one of these pragmas from code that *is* covered
+by one of these pragmas unless the floating point environment has been restored
+to its default state.  See the C standard for more information about these 
pragmas.
+
+The command line option ``-frounding-math`` behaves as if the translation unit
+began with ``#pragma STDC FENV_ROUND FE_DYNAMIC``. The command line option
+``-ffp-model=strict`` behaves as if the translation unit began with ``#pragma 
STDC FENV_ACCESS ON``.
+
+Code that just wants to use a specific rounding mode for specific floating 
point
+operations can avoid most of the hazards of the dynamic floating point 
environment
+by using ``#pragma STDC FENV_ROUND`` with a value other than ``FE_DYNAMIC``.
+
 .. _crtfastmath.o:
 
 A note about ``crtfastmath.o``
Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3289,7 +3289,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3297,6 +3297,28 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds`` and ``__builtin_set_flt_rounds``
+-
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+   void __builtin_set_flt_rounds(int);
+
+Returns and sets current floating point rounding mode. The encoding of returned
+values and input parameters is same as the result of FLT_ROUNDS, specified by C
+standard:
+- ``0``  - toward zero
+- ``1``  - to nearest, ties to even
+- ``2``  - toward positive infinity
+- ``3``  - toward negative infinity
+- ``4``  - to nearest, ties away from zero
+The effect of passing some other value to ``__builtin_flt_rounds`` is
+implementation-defined. ``__builtin_set_flt_rounds`` is currently only 
supported
+to work on x86, x86_64, Arm and AArch64 targets. These builtins read and modify
+the floating-point environment, which is not always allowed and may have 
unexpected
+behavior. Please see the section on `Accessing the floating point 

[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:3272
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+The effect of passing some other value to ``__builtin_flt_rounds`` is

I suspect this won't end up being formatted as a list; you should do something 
like:

```
- ``0`` - toward zero
- ``1`` - to nearest, ties to even
...
```



Comment at: clang/docs/UsersManual.rst:1388
+by calling the `fesetround` function.
+
 Clang provides a number of ways to control floating point behavior, including

This isn't quite the right place for this.  Please put this new subsection 
after the described flags but before the "A note about..." subsections.

This file is RST, so you need to use double-backticks to format text in 
monospace.

This paragraph is just talking about the default mode which restricts access to 
the floating-point environment; let's add some text after it on how to get out 
of that default mode:

```
C provides two pragmas to allow code to dynamically modify the floating point 
environment:

- ``#pragma STDC FENV_ACCESS ON`` allows dynamic changes to the entire floating 
point environment.

- ``#pragma STDC FENV_ROUND FE_DYNAMIC`` allows dynamic changes to just the 
floating point rounding mode.  This may be more optimizable than ``FENV_ACCESS 
ON`` because the compiler can still ignore the possibility of floating-point 
exceptions by default.

Both of these can be used either at the start of a block scope, in which case 
they cover all code in that scope (unless they're turned off in a child scope), 
or at the top level in a file, in which case they cover all subsequent function 
bodies until they're turned off.  Note that it is undefined behavior to enter 
code that is *not* covered by one of these pragmas from code that *is* covered 
by one of these pragmas unless the floating point environment has been restored 
to its default state.  See the C standard for more information about these 
pragmas.

The command line option ``-frounding-math`` behaves as if the translation unit 
began with ``#pragma STDC FENV_ROUND FE_DYNAMIC``.  The command line option 
``-ffp-model=strict`` behaves as if the translation unit began with ``#pragma 
STDC FENV_ACCESS ON``.

Code that just wants to use a specific rounding mode for specific floating 
point operations can avoid most of the hazards of the dynamic floating point 
environment by using ``#pragma STDC FENV_ROUND`` with a value other than 
``FE_DYNAMIC``.
```


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 added a comment.

In D146188#4224902 , @rjmccall wrote:

> In D146188#4223249 , @xiongji90 
> wrote:
>
>> Hi, @rjmccall and @sepavloff 
>> In UserManual, we include a section `Controlling Floating Point Behavior`: 
>> https://github.com/llvm/llvm-project/blob/main/clang/docs/UsersManual.rst#controlling-floating-point-behavior
>>  , now we need to add a new section for floating-point environment, do we 
>> need to add the new section in parallel with `Controlling Floating Point 
>> Behavior` section or just put the section under `Controlling Floating Point 
>> Behavior`? And current `Controlling Floating Point Behavior` includes 
>> following description:
>> `Clang provides a number of ways to control floating point behavior, 
>> including with command line options and source pragmas.`
>> So, we need to update it to `Clang provides a number of ways to control 
>> floating point behavior, including with command line options, source pragmas 
>> and builtins.` and mention __builtin_flt_rounds, __builtin_set_flt_rounds in 
>> this section. Does this meet your expectation?
>
> I think you should add a subsection to Controlling Floating Point Behavior 
> about the floating-point environment.  You should not mention these builtins 
> there specifically — if you want an example function that reads or modifies 
> the environment, you should use one of the standard APIs like the 
> `FLT_ROUNDS` macro or the `fesetround` function.  You should also add the 
> documentation for these builtins where you've currently got it, and that 
> documentation can cross-reference to Controlling Floating Point Behavior.  
> Does that make sense?

Hi, @rjmccall 
I created floating point environment section, does it meet your expectation?
Thanks very much.


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 updated this revision to Diff 508925.
xiongji90 added a comment.

Add floating point environment section in UserManual.rst


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

Files:
  clang/docs/LanguageExtensions.rst
  clang/docs/UsersManual.rst


Index: clang/docs/UsersManual.rst
===
--- clang/docs/UsersManual.rst
+++ clang/docs/UsersManual.rst
@@ -1368,6 +1368,24 @@
 Controlling Floating Point Behavior
 ---
 
+.. _floating-point-environment:
+
+Accessing the floating point environment
+
+Many targets allow floating point operations to be configured to control things
+such as how inexact results should be rounded and how exceptional conditions
+should be handled. This configuration is called the floating point environment.
+C and C++ restrict access to the floating point environment by default, and the
+compiler is allowed to assume that all operations are performed in the default
+environment. When code is compiled in this default mode, operations that depend
+on the environment (such as floating-point arithmetic and `FLT_ROUNDS`) may 
have
+undefined behavior if the dynamic environment is not the default environment; 
for
+example, `FLT_ROUNDS` may or may not simply return its default value for the 
target
+instead of reading the dynamic environment, and floating-point operations may 
be
+optimized as if the dynamic environment were the default.  Similarly, it is 
undefined
+behavior to change the floating point environment in this default mode, for 
example
+by calling the `fesetround` function.
+
 Clang provides a number of ways to control floating point behavior, including
 with command line options and source pragmas. This section
 describes the various floating point semantic modes and the corresponding 
options.
Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3246,7 +3246,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3254,6 +3254,28 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds`` and ``__builtin_set_flt_rounds``
+-
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+   void __builtin_set_flt_rounds(int);
+
+Returns and sets current floating point rounding mode. The encoding of returned
+values and input parameters is same as the result of FLT_ROUNDS, specified by C
+standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+The effect of passing some other value to ``__builtin_flt_rounds`` is
+implementation-defined. ``__builtin_set_flt_rounds`` is currently only 
supported
+to work on x86, x86_64, Arm and AArch64 targets. These builtins read and modify
+the floating-point environment, which is not always allowed and may have 
unexpected
+behavior. Please see the section on `Accessing the floating point environment 
`_
 for more information.
+
 String builtins
 ---
 


Index: clang/docs/UsersManual.rst
===
--- clang/docs/UsersManual.rst
+++ clang/docs/UsersManual.rst
@@ -1368,6 +1368,24 @@
 Controlling Floating Point Behavior
 ---
 
+.. _floating-point-environment:
+
+Accessing the floating point environment
+
+Many targets allow floating point operations to be configured to control things
+such as how inexact results should be rounded and how exceptional conditions
+should be handled. This configuration is called the floating point environment.
+C and C++ restrict access to the floating point environment by default, and the
+compiler is allowed to assume that all operations are performed in the default
+environment. When code is compiled in this default mode, operations that depend
+on the environment (such as floating-point arithmetic and `FLT_ROUNDS`) may have
+undefined behavior if the dynamic environment is not the default environment; for
+example, `FLT_ROUNDS` may or may not simply return its default value for the target
+instead of reading the dynamic environment, and floating-point operations may be
+optimized as if the dynamic environment were the 

[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 a comment.

In D146188#4223249 , @xiongji90 wrote:

> Hi, @rjmccall and @sepavloff 
> In UserManual, we include a section `Controlling Floating Point Behavior`: 
> https://github.com/llvm/llvm-project/blob/main/clang/docs/UsersManual.rst#controlling-floating-point-behavior
>  , now we need to add a new section for floating-point environment, do we 
> need to add the new section in parallel with `Controlling Floating Point 
> Behavior` section or just put the section under `Controlling Floating Point 
> Behavior`? And current `Controlling Floating Point Behavior` includes 
> following description:
> `Clang provides a number of ways to control floating point behavior, 
> including with command line options and source pragmas.`
> So, we need to update it to `Clang provides a number of ways to control 
> floating point behavior, including with command line options, source pragmas 
> and builtins.` and mention __builtin_flt_rounds, __builtin_set_flt_rounds in 
> this section. Does this meet your expectation?

I think you should add a subsection to Controlling Floating Point Behavior 
about the floating-point environment.  You should not mention these builtins 
there specifically — if you want an example function that reads or modifies the 
environment, you should use one of the standard APIs like the `FLT_ROUNDS` 
macro or the `fesetround` function.  You should also add the documentation for 
these builtins where you've currently got it, and that documentation can 
cross-reference to Controlling Floating Point Behavior.  Does that make sense?


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 added a comment.

Hi, @rjmccall and @sepavloff 
In UserManual, we include a section `Controlling Floating Point Behavior`: 
https://github.com/llvm/llvm-project/blob/main/clang/docs/UsersManual.rst#controlling-floating-point-behavior
 , now we need to add a new section for floating-point environment, do we need 
to add the new section in parallel with `Controlling Floating Point Behavior` 
section or just put the section under `Controlling Floating Point Behavior`? 
And current `Controlling Floating Point Behavior` includes following 
description:
`Clang provides a number of ways to control floating point behavior, including 
with command line options and source pragmas.`
So, we need to update it to `Clang provides a number of ways to control 
floating point behavior, including with command line options, source pragmas 
and builtins.` and mention __builtin_flt_rounds, __builtin_set_flt_rounds in 
this section. Does this meet your expectation?
Thanks very much.


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[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 a comment.

Okay.  I was looking at a version of the standard that makes reading the 
environment UB.  If that's been relaxed, then I agree that it would be much 
more natural to talk about *changing* the environment than just *accessing* it.

And yeah, I agree it would make sense to break this out into a separate section 
under "Controlling floating-point behavior".  We can cross-reference to that 
section from the Language Extensions document with something like:

  These builtins read and modify the floating-point environment, which is not 
always allowed and may have unexpected behavior.  Please see the section on 
`accessing the floating point environment 
`_.

And then you just need to set up the corresponding anchor in the user's manual:

  .. _floating-point-environment:
  
  Accessing the floating point environment
  --
  
  Many targets allow floating point operations to be configured to control 
things such as how inexact results should be rounded and how exceptional 
conditions should be handled.  This configuration is called the floating point 
environment.  C and C++ restrict access to the floating point environment by 
default, and the compiler is allowed to assume that all operations are 
performed in the default environment.  When code is compiled in this default 
mode, operations that depend on the environment (such as floating-point 
arithmetic and `FLT_ROUNDS`) may have undefined behavior if the dynamic 
environment is not the default environment; for example, `FLT_ROUNDS` may or 
may not simply return its default value for the target instead of reading the 
dynamic environment, and floating-point operations may be optimized as if the 
dynamic environment were the default.  Similarly, it is undefined behavior to 
change the floating point environment in this default mode, for example by 
calling the `fesetround` function.
  
  Clang supports three ways to change how floating point operations behave:
  ...


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[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 `` 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 `` 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, 

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 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.
+

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 `` 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 `` 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.


Repository:
  rG LLVM Github Monorepo

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

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 updated this revision to Diff 506475.

Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

Files:
  clang/docs/LanguageExtensions.rst
  clang/docs/ReleaseNotes.rst


Index: clang/docs/ReleaseNotes.rst
===
--- clang/docs/ReleaseNotes.rst
+++ clang/docs/ReleaseNotes.rst
@@ -272,6 +272,7 @@
 - Add ``__builtin_elementwise_log2`` builtin for floating point types only.
 - Add ``__builtin_elementwise_exp`` builtin for floating point types only.
 - Add ``__builtin_elementwise_exp2`` builtin for floating point types only.
+- Add ``__builtin_set_flt_rounds`` builtin for X86, x86_64, Arm and AArch64 
only.
 
 AST Matchers
 
Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3246,7 +3246,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3254,6 +3254,26 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds`` and ``__builtin_set_flt_rounds``
+-
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+   void __builtin_set_flt_rounds(int);
+
+Returns and sets current floating point rounding mode. The encoding of returned
+values and input parameters is same as the result of FLT_ROUNDS, specified by C
+standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+The effect of passing some other value to ``__builtin_flt_rounds`` is
+implementation-defined. ``__builtin_set_flt_rounds`` is currently only 
supported to
+work on x86, x86_64, Arm and AArch64 targets currently.
+
 String builtins
 ---
 


Index: clang/docs/ReleaseNotes.rst
===
--- clang/docs/ReleaseNotes.rst
+++ clang/docs/ReleaseNotes.rst
@@ -272,6 +272,7 @@
 - Add ``__builtin_elementwise_log2`` builtin for floating point types only.
 - Add ``__builtin_elementwise_exp`` builtin for floating point types only.
 - Add ``__builtin_elementwise_exp2`` builtin for floating point types only.
+- Add ``__builtin_set_flt_rounds`` builtin for X86, x86_64, Arm and AArch64 only.
 
 AST Matchers
 
Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3246,7 +3246,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3254,6 +3254,26 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds`` and ``__builtin_set_flt_rounds``
+-
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+   void __builtin_set_flt_rounds(int);
+
+Returns and sets current floating point rounding mode. The encoding of returned
+values and input parameters is same as the result of FLT_ROUNDS, specified by C
+standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+The effect of passing some other value to ``__builtin_flt_rounds`` is
+implementation-defined. ``__builtin_set_flt_rounds`` is currently only supported to
+work on x86, x86_64, Arm and AArch64 targets currently.
+
 String builtins
 ---
 
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 updated this revision to Diff 506472.
xiongji90 added a comment.

Combine description of __builtin_flt_rounds and __builtin_set_flt_rounds


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

Files:
  clang/docs/LanguageExtensions.rst
  clang/docs/ReleaseNotes.rst


Index: clang/docs/ReleaseNotes.rst
===
--- clang/docs/ReleaseNotes.rst
+++ clang/docs/ReleaseNotes.rst
@@ -272,6 +272,7 @@
 - Add ``__builtin_elementwise_log2`` builtin for floating point types only.
 - Add ``__builtin_elementwise_exp`` builtin for floating point types only.
 - Add ``__builtin_elementwise_exp2`` builtin for floating point types only.
+- Add ``__builtin_set_flt_rounds`` builtin for X86, x86_64, Arm and AArch64 
only.
 
 AST Matchers
 
Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3246,7 +3246,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3254,6 +3254,25 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds`` and ``__builtin_set_flt_rounds``
+-
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+   void __builtin_set_flt_rounds(int);
+
+Returns and sets current rounding mode. Encoding of the returned values and
+input parameter is same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+The effect of passing some other value to ``__builtin_flt_rounds`` is
+implementation-defined. ``__builtin_set_flt_rounds`` is restricted to work on
+X86 and Arm targets currently.
+
 String builtins
 ---
 


Index: clang/docs/ReleaseNotes.rst
===
--- clang/docs/ReleaseNotes.rst
+++ clang/docs/ReleaseNotes.rst
@@ -272,6 +272,7 @@
 - Add ``__builtin_elementwise_log2`` builtin for floating point types only.
 - Add ``__builtin_elementwise_exp`` builtin for floating point types only.
 - Add ``__builtin_elementwise_exp2`` builtin for floating point types only.
+- Add ``__builtin_set_flt_rounds`` builtin for X86, x86_64, Arm and AArch64 only.
 
 AST Matchers
 
Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3246,7 +3246,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3254,6 +3254,25 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds`` and ``__builtin_set_flt_rounds``
+-
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+   void __builtin_set_flt_rounds(int);
+
+Returns and sets current rounding mode. Encoding of the returned values and
+input parameter is same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+The effect of passing some other value to ``__builtin_flt_rounds`` is
+implementation-defined. ``__builtin_set_flt_rounds`` is restricted to work on
+X86 and Arm targets currently.
+
 String builtins
 ---
 
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[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 `` 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

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[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:3271
+4  - to nearest, ties away from zero
+The effect of passing some other value to this builtin is 
implementation-defined.
+

This comment belongs with the other builtin.  I would suggest just combining 
these two into one section, though, like:

```
``__builtin_flt_rounds`` and ``__builtin_set_flt_rounds``
-
```

That way you don't have to describe the options twice.

Make sure you clarify that the target restrictions only applies to 
`__builtin_set_flt_rounds`.



Comment at: clang/docs/LanguageExtensions.rst:3280
+
+Sets the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:





Comment at: clang/docs/LanguageExtensions.rst:3287
+4  - to nearest, ties away from zero
+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.




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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 added inline comments.



Comment at: clang/docs/LanguageExtensions.rst:3295
+support this builtin. Since this builtin changes default floating-point
+environment, ``#pragma STDC FENV_ACCESS ON`` is required.
+

rjmccall wrote:
> sepavloff wrote:
> > Not necessary. Options `-ffp-model=strict` or `-frounding-math` also can be 
> > used. I would remove this statement.
> It is appropriate to at least say that not all modes permit changing the 
> default floating-point environment and cross-reference the appropriate place 
> in the Clang documentation where we talk about that in more detail.  If we 
> don't have such a place already, this is the time to add it.
Hi, @rjmccall and @sepavloff 
I removed the statement that requiring to add "#pragma stdc fenv access", I 
checked the doc that there has not been any description about default fp 
environment, do you mean we need to add such description first and 
cross-reference it here?
Thanks very much.


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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 updated this revision to Diff 506460.

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

https://reviews.llvm.org/D146188

Files:
  clang/docs/LanguageExtensions.rst


Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3246,7 +3246,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3254,6 +3254,39 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds``
+--
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+
+Returns the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+The effect of passing some other value to this builtin is 
implementation-defined.
+
+``__builtin_set_flt_rounds``
+--
+
+.. code-block:: c
+
+   void __builtin_set_flt_rounds(int);
+
+Sets the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+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.
+
 String builtins
 ---
 


Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3246,7 +3246,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3254,6 +3254,39 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds``
+--
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+
+Returns the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+The effect of passing some other value to this builtin is implementation-defined.
+
+``__builtin_set_flt_rounds``
+--
+
+.. code-block:: c
+
+   void __builtin_set_flt_rounds(int);
+
+Sets the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+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.
+
 String builtins
 ---
 
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[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:3283
+Sets the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero

"Sets the current floating-point rounding mode.  The parameter uses the same 
values specified for ``FLT_ROUNDS`` by the C standard:
...
The effect of passing some other value to this builtin is 
implementation-defined."



Comment at: clang/docs/LanguageExtensions.rst:3293
+This builtin is converted to llvm.set.rounding intrinsic in LLVM IR level
+and not all targets support this intrinsic, so only x86 and arm targets
+support this builtin. Since this builtin changes default floating-point

sepavloff wrote:
> If some other target start supporting `llvm.set_rounding` this statement 
> becomes wrong. Maybe just 'some targets'?
The manual should document when a specific builtin is restricted to specific 
targets.  If someone adds support for the builtin on new targets, they should 
update the manual.  Think about it from a user's perspective: they should be 
able to check what targets support this builtin without having to figure out 
that the builtin turns into a specific intrinsic and then crawl around in the 
LLVM source code to figure out which targets implement that intrinsic.

With that said, please do not refer to LLVM-level details in the Clang 
documentation.  Users shouldn't have to care that the builtin is lowered to 
such-and-such LLVM intrinsic.  Even if they did, that's not a hard guarantee we 
want to make anyway — we document high-level semantics, not the fine details of 
the intermediate representation coming out of the frontend.

Also, please do not cross-reference the LLVM documentation.  The Clang 
documentation is user-facing and has a much, much wider potential audience than 
the LLVM documentation, which is focused on implementors.  People should be 
able to use the compiler without worrying about backend details.  If we have to 
repeat some information between the two places, that's fine.



Comment at: clang/docs/LanguageExtensions.rst:3295
+support this builtin. Since this builtin changes default floating-point
+environment, ``#pragma STDC FENV_ACCESS ON`` is required.
+

sepavloff wrote:
> Not necessary. Options `-ffp-model=strict` or `-frounding-math` also can be 
> used. I would remove this statement.
It is appropriate to at least say that not all modes permit changing the 
default floating-point environment and cross-reference the appropriate place in 
the Clang documentation where we talk about that in more detail.  If we don't 
have such a place already, this is the time to add it.


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[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:3293
+This builtin is converted to llvm.set.rounding intrinsic in LLVM IR level
+and not all targets support this intrinsic, so only x86 and arm targets
+support this builtin. Since this builtin changes default floating-point

If some other target start supporting `llvm.set_rounding` this statement 
becomes wrong. Maybe just 'some targets'?



Comment at: clang/docs/LanguageExtensions.rst:3295
+support this builtin. Since this builtin changes default floating-point
+environment, ``#pragma STDC FENV_ACCESS ON`` is required.
+

Not necessary. Options `-ffp-model=strict` or `-frounding-math` also can be 
used. I would remove this statement.


Repository:
  rG LLVM Github Monorepo

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

https://reviews.llvm.org/D146188

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[xiongji90 via Phabricator via cfe-commits]

xiongji90 created this revision.
xiongji90 added reviewers: rjmccall, sepavloff, aaron.ballman, andrew.w.kaylor.
Herald added a project: All.
xiongji90 requested review of this revision.
Herald added a project: clang.
Herald added a subscriber: cfe-commits.

This patch aims to add necessary description for __builtin_flt_rounds and 
__builtins_set_flt_rounds in LanguageExtensions.rst


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D146188

Files:
  clang/docs/LanguageExtensions.rst


Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3246,7 +3246,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3254,6 +3254,46 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds``
+--
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+
+Returns the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+See `llvm.get.rounding
+`_ for
+more information on the semantics.
+
+``__builtin_set_flt_rounds``
+--
+
+.. code-block:: c
+
+   void __builtin_set_flt_rounds(int);
+
+Sets the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+See `llvm.set.rounding
+`_ for
+more information on the semantics.
+This builtin is converted to llvm.set.rounding intrinsic in LLVM IR level
+and not all targets support this intrinsic, so only x86 and arm targets
+support this builtin. Since this builtin changes default floating-point
+environment, ``#pragma STDC FENV_ACCESS ON`` is required.
+
 String builtins
 ---
 


Index: clang/docs/LanguageExtensions.rst
===
--- clang/docs/LanguageExtensions.rst
+++ clang/docs/LanguageExtensions.rst
@@ -3246,7 +3246,7 @@
 
double __builtin_canonicalize(double);
float __builtin_canonicalizef(float);
-   long double__builtin_canonicalizel(long double);
+   long double __builtin_canonicalizel(long double);
 
 Returns the platform specific canonical encoding of a floating point
 number. This canonicalization is useful for implementing certain
@@ -3254,6 +3254,46 @@
 `_ for
 more information on the semantics.
 
+``__builtin_flt_rounds``
+--
+
+.. code-block:: c
+
+   int __builtin_flt_rounds();
+
+Returns the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+See `llvm.get.rounding
+`_ for
+more information on the semantics.
+
+``__builtin_set_flt_rounds``
+--
+
+.. code-block:: c
+
+   void __builtin_set_flt_rounds(int);
+
+Sets the current rounding mode. Encoding of the returned values is
+same as the result of FLT_ROUNDS, specified by C standard:
+0  - toward zero
+1  - to nearest, ties to even
+2  - toward positive infinity
+3  - toward negative infinity
+4  - to nearest, ties away from zero
+See `llvm.set.rounding
+`_ for
+more information on the semantics.
+This builtin is converted to llvm.set.rounding intrinsic in LLVM IR level
+and not all targets support this intrinsic, so only x86 and arm targets
+support this builtin. Since this builtin changes default floating-point
+environment, ``#pragma STDC FENV_ACCESS ON`` is required.
+
 String builtins
 ---
 
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits