Re: [PATCH, rs6000] Improve Documentation of Built-In Functions Part 1

[Segher Boessenkool]

Hi!

On Wed, Apr 25, 2018 at 11:28:44AM -0500, Kelvin Nilsen wrote:
> >>> 4. Remove descriptions of built-in function that do not belong in this
> >>> section because the
> >>>built-in functions are generic (not specific to PowerPC):
> >>> __builtin_fabsq,
> >>>__builtin_copysignq, __builtin_infq, __builtin_huge_valq, 
> >>> __builtin_nanq,
> >>>__builtin_nansq, __builtin_sqrtf128, __builtin_fmaf128.
> > 
> > Are these described in a generic place, then?  I don't see it?
> > 
> >> +@node Low-Level PowerPC Built-in Functions Available on all Targets
> >> +@subsubsection Low-Level PowerPC Built-in Functions Available on all 
> >> Targets
> 
> Regarding your question about "q functions", the existing gcc.pdf document
> is a bit confusing.  Here's what I can figure out.
> 
> The following are mentioned only in "Section 6.59.33: x86 Built-in Functions"
> 
>   __float128 __builtin_fabsq (__float128)
>   __float128 __builtin_copysignq (__float128, __float128)
>   __float128 __builtin_infq (void)
>   __float128 __builtin_huge_valq (void)
>   __float128 __builtin_nanq (void)
>   __float128 __builtin_nansq (void)
> 
> As far as I can tell, these should not be documented as specific to x86, but
> should be documented as generic across all platforms.  This is an issue 
> outside
> the realm of PowerPC maintenance.
> 
> If we want to preserve mention of these "q" functions, I would recommend
> changing the text that introduces them.  Currently, it says:
> 
>   "Previous versions of GCC supported some 'q' builtins for IEEE 128-bit
>floating point.  These functions are now mapped into the equivalent
>'f128' builtin functions."

I think that is a bit confusing, especially if you are not familiar with
those builtins already.

> If the description of these built-ins is not moved to a more generic context,
> I would prefer to replace this section with something like:
> 
> The following functions, which are also supported on x86 targets, are 
> supported
> if the -mfloat128 option is specified:
> 
>   __float128 __builtin_fabsq (__float128)
>   __float128 __builtin_copysignq (__float128, __float128)
>   __float128 __builtin_infq (void)
>   __float128 __builtin_huge_valq (void)
>   __float128 __builtin_nanq (void)
>   __float128 __builtin_nansq (void)

That looks fine.

> Regarding your question about f128 functions, these are "supposed to be"
> documented in "Section 6.58: Other Built-in Functions Provided by GCC".
> Search for the phrase "corresponding to the TS 18661-3 functions".  We
> should add "__builtin_sqrtf128 and builtin_fmaf128 to the list of functions
> described this way.  These may not be the only omissions.  Should we push
> for fixing this documentation in Section 6.58 instead of keeping it in
> the PowerPC section?

Well, are they supported on other targets?

> It is difficult to find the official TS 18661-3 document, and
> I'm not sure where to look for a list of which of the functions are
> currently implemented by gcc.  I found this "diff" document, which provides
> some hints.  Given that this standard is not easily accessible, perhaps the
> generic built-in documentation should provide a little more information?
> 
> See http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1945.pdf

That is the document I use.  See other mail for other resources :-)


Segher

Re: [PATCH, rs6000] Improve Documentation of Built-In Functions Part 1

[Segher Boessenkool]

Hi Kelvin,

On Tue, Apr 24, 2018 at 09:12:52AM -0500, Kelvin Nilsen wrote:
>     * doc/extend.texi: Tidy documentation of PowerPC built-in functions.

You should note the sections you renamed:
(PowerPC Built-in Functions): Rename to ...
(Low-Level PowerPC Built-in Functions): ... this.
(but see below).

> --- gcc/doc/extend.texi    (revision 259504)
> +++ gcc/doc/extend.texi    (working copy)
> @@ -15524,12 +15524,17 @@ implementing assertions.
> -@node PowerPC Built-in Functions
> -@subsection PowerPC Built-in Functions
> +@node Low-Level PowerPC Built-in Functions
> +@subsection Low-Level PowerPC Built-in Functions

If you change the name of a node you need to also change it wherever
it is referred to.  In this case, importantly the menu of per-target
built-in function documentation.  We probably should keep this
subsection's name, maybe do a subsubsection or such?

There is nothing particularly low-level about these builtins; maybe
call it "basic builtins" or similar?

Or we probably should start the "PowerPC Built-in Functions" node
with a menu of its subsubsections?  Like what FR-V has.

Sorry for the late review.


Segher

Re: [PATCH, rs6000] Improve Documentation of Built-In Functions Part 1

[Kelvin Nilsen]

Thank you for the prompt review and careful feedback.  I didn't notice
your message until this morning.  At this point, I'll wait a few days before
committing these changes as I understand we are still in the "RC phase of GCC 
8".


On 4/24/18 4:45 PM, Segher Boessenkool wrote:
> Hi!
> 
> On Tue, Apr 24, 2018 at 02:25:58PM -0500, Kelvin Nilsen wrote:
>>> 4. Remove descriptions of built-in function that do not belong in this
>>> section because the
>>>built-in functions are generic (not specific to PowerPC):
>>> __builtin_fabsq,
>>>__builtin_copysignq, __builtin_infq, __builtin_huge_valq, __builtin_nanq,
>>>__builtin_nansq, __builtin_sqrtf128, __builtin_fmaf128.
> 
> Are these described in a generic place, then?  I don't see it?
> 
>> +@node Low-Level PowerPC Built-in Functions Available on all Targets
>> +@subsubsection Low-Level PowerPC Built-in Functions Available on all Targets

Regarding your question about "q functions", the existing gcc.pdf document
is a bit confusing.  Here's what I can figure out.

The following are mentioned only in "Section 6.59.33: x86 Built-in Functions"

  __float128 __builtin_fabsq (__float128)
  __float128 __builtin_copysignq (__float128, __float128)
  __float128 __builtin_infq (void)
  __float128 __builtin_huge_valq (void)
  __float128 __builtin_nanq (void)
  __float128 __builtin_nansq (void)

As far as I can tell, these should not be documented as specific to x86, but
should be documented as generic across all platforms.  This is an issue outside
the realm of PowerPC maintenance.

If we want to preserve mention of these "q" functions, I would recommend
changing the text that introduces them.  Currently, it says:

  "Previous versions of GCC supported some 'q' builtins for IEEE 128-bit
   floating point.  These functions are now mapped into the equivalent
   'f128' builtin functions."

If the description of these built-ins is not moved to a more generic context,
I would prefer to replace this section with something like:

The following functions, which are also supported on x86 targets, are supported
if the -mfloat128 option is specified:

  __float128 __builtin_fabsq (__float128)
  __float128 __builtin_copysignq (__float128, __float128)
  __float128 __builtin_infq (void)
  __float128 __builtin_huge_valq (void)
  __float128 __builtin_nanq (void)
  __float128 __builtin_nansq (void)

Regarding your question about f128 functions, these are "supposed to be"
documented in "Section 6.58: Other Built-in Functions Provided by GCC".
Search for the phrase "corresponding to the TS 18661-3 functions".  We
should add "__builtin_sqrtf128 and builtin_fmaf128 to the list of functions
described this way.  These may not be the only omissions.  Should we push
for fixing this documentation in Section 6.58 instead of keeping it in
the PowerPC section?

It is difficult to find the official TS 18661-3 document, and
I'm not sure where to look for a list of which of the functions are
currently implemented by gcc.  I found this "diff" document, which provides
some hints.  Given that this standard is not easily accessible, perhaps the
generic built-in documentation should provide a little more information?

See http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1945.pdf

Re: [PATCH, rs6000] Improve Documentation of Built-In Functions Part 1

[Segher Boessenkool]

Hi!

On Tue, Apr 24, 2018 at 02:25:58PM -0500, Kelvin Nilsen wrote:
> > 4. Remove descriptions of built-in function that do not belong in this
> > section because the
> >    built-in functions are generic (not specific to PowerPC):
> > __builtin_fabsq,
> >    __builtin_copysignq, __builtin_infq, __builtin_huge_valq, __builtin_nanq,
> >    __builtin_nansq, __builtin_sqrtf128, __builtin_fmaf128.

Are these described in a generic place, then?  I don't see it?

> +@node Low-Level PowerPC Built-in Functions Available on all Targets
> +@subsubsection Low-Level PowerPC Built-in Functions Available on all Targets

"Targets" is not such a great name.  "Configurations", maybe?

>  CPU supports the Embedded ISA category.
>  @item cellbe
>  CPU has a CELL broadband engine.
> +@item darn
> +CPU supports the darn (deliver a random number) instruction.

"the @code{darn}" etc.

>  CPU has hardware transaction memory instructions.
>  @item htm-nosc
>  Kernel aborts hardware transactions when a syscall is made.
> +@item htm-no-suspend
> +CPU supports hardware transaction memory but does not support the
> +tsuspend. instruction.

"@code{tsuspend.} instruction"

> +The following functions require (@option{-mhard-float}),
> +(@option{-mpowerpc-gfxopt}), and (@option{-mpopcntb}) options.

Why the parentheses?  The text within parens is not an explanation of
something that came before, it's just part of the main sentence.

Similar in many places.

> +The @code{__builtin_darn} and @code{__builtin_darn_raw}
> +functions require a
> +64-bit environment supporting ISA 3.0 or later.
> +The @code{__builtin_darn} function provides a 64-bit conditioned
> +random number.  The @code{__builtin_darn_raw} function provides a
> +64-bit raw random number.  The @code{__builtin_darn_32} function
> +provides a 32-bit random number.

Is darn_32 conditioned or raw?  (I realise you didn't change this text :-) )

The rest looks great, thanks!  If you fix those details, and probably not
delete the q/f128 things yet, it is okay for trunk.

Cheers,


Segher

Re: [PATCH, rs6000] Improve Documentation of Built-In Functions Part 1

[Kelvin Nilsen]

I'm updating this patch to make two improvements to what was submitted
earlier today:

1. Correct the description of the htm-no-suspend CPU feature.

2. Add a comment to clarify that the builtin_divde and builtin_divdeu
   built-in functions require 64-bit targets.

Everything else is the same as submitted previously.

On 4/24/18 9:12 AM, Kelvin Nilsen wrote:
> This is the first of several patches to address shortcomings in existing
> documentation of
> PowerPC built-in functions.  The focus of this particular patch is to
> improve documentation
> of low-level built-in functions that do not require special include headers.
> 
> A summary of this patch follows:
> 
> 1. Change the name of the first PowerPC built-in section from "PowerPC
> Built-in Functions"
>    to "Low-Level PowerPC Built-in Functions".  This section has never
> described all PowerPC
>    built-in functions.
> 
> 2. Introduce subsubsections within this section to independently
> describe built-in functions
>    that target particular ISA levels.  Sort function descriptions into
> appropriate
>    subsubsections.
> 
> 3. Add descriptions of three new features that can be tested with the
> __builtin_cpu_supports
>    function: darn, htm-no-suspend, and scv.
> 
> 4. Remove descriptions of built-in function that do not belong in this
> section because the
>    built-in functions are generic (not specific to PowerPC):
> __builtin_fabsq,
>    __builtin_copysignq, __builtin_infq, __builtin_huge_valq, __builtin_nanq,
>    __builtin_nansq, __builtin_sqrtf128, __builtin_fmaf128.
> 
> 5. Corrected the spellings of several built-in functions:
> __builtin_fmaf128_round_to_odd,
>    __builtin_addg6s, __builtin_cbctdt, __builtin_cdtbcd.
> 
> This patch is limited in scope in order to manage complexity of the
> diffs.  Subsequent patches
> will address different sections of the documentation.  Subsequent
> patches will also add
> new function descriptions into these sections.
> 
> This patch affects only extend.texi.  The gcc.pdf file has been built
> and reviewed.
> 
> Is this ok for the trunk?
gcc/ChangeLog:

2018-04-24  Kelvin Nilsen  

* doc/extend.texi: Tidy documentation of PowerPC built-in functions.

Index: gcc/doc/extend.texi
===
--- gcc/doc/extend.texi (revision 259504)
+++ gcc/doc/extend.texi (working copy)
@@ -15524,12 +15524,17 @@ implementing assertions.
 
 @end table
 
-@node PowerPC Built-in Functions
-@subsection PowerPC Built-in Functions
+@node Low-Level PowerPC Built-in Functions
+@subsection Low-Level PowerPC Built-in Functions
 
-The following built-in functions are always available and can be used to
-check the PowerPC target platform type:
+This section describes PowerPC built-in functions that do not require
+the inclusion of any special header files to declare prototypes or
+provide macro definitions.  The sections that follow describe
+additional PowerPC built-in functions.
 
+@node Low-Level PowerPC Built-in Functions Available on all Targets
+@subsubsection Low-Level PowerPC Built-in Functions Available on all Targets
+
 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
 This function is a @code{nop} on the PowerPC platform and is included solely
 to maintain API compatibility with the x86 builtins.
@@ -15633,6 +15638,8 @@ CPU supports the set of compatible performance mon
 CPU supports the Embedded ISA category.
 @item cellbe
 CPU has a CELL broadband engine.
+@item darn
+CPU supports the darn (deliver a random number) instruction.
 @item dfp
 CPU has a decimal floating point unit.
 @item dscr
@@ -15649,6 +15656,9 @@ CPU has a floating point unit.
 CPU has hardware transaction memory instructions.
 @item htm-nosc
 Kernel aborts hardware transactions when a syscall is made.
+@item htm-no-suspend
+CPU supports hardware transaction memory but does not support the
+tsuspend. instruction.
 @item ic_snoop
 CPU supports icache snooping capabilities.
 @item ieee128
@@ -15677,6 +15687,8 @@ CPU supports the old POWER ISA (eg, 601)
 CPU supports 64-bit mode execution.
 @item ppcle
 CPU supports a little-endian mode that uses address swizzling.
+@item scv
+Kernel supports system call vectored.
 @item smt
 CPU support simultaneous multi-threading.
 @item spe
@@ -15708,19 +15720,81 @@ Here is an example:
 @end smallexample
 @end deftypefn
 
-These built-in functions are available for the PowerPC family of
+The following built-in functions are also available on all PowerPC
 processors:
 @smallexample
-float __builtin_recipdivf (float, float);
-float __builtin_rsqrtf (float);
-double __builtin_recipdiv (double, double);
-double __builtin_rsqrt (double);
 uint64_t __builtin_ppc_get_timebase ();
 unsigned long __builtin_ppc_mftb ();
-double __builtin_unpack_longdouble (long double, int);
-long double __builtin_pack_longdouble (double, double);
 @end smallexample
 
+The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}

[PATCH, rs6000] Improve Documentation of Built-In Functions Part 1

[Kelvin Nilsen]

This is the first of several patches to address shortcomings in existing
documentation of
PowerPC built-in functions.  The focus of this particular patch is to
improve documentation
of low-level built-in functions that do not require special include headers.

A summary of this patch follows:

1. Change the name of the first PowerPC built-in section from "PowerPC
Built-in Functions"
   to "Low-Level PowerPC Built-in Functions".  This section has never
described all PowerPC
   built-in functions.

2. Introduce subsubsections within this section to independently
describe built-in functions
   that target particular ISA levels.  Sort function descriptions into
appropriate
   subsubsections.

3. Add descriptions of three new features that can be tested with the
__builtin_cpu_supports
   function: darn, htm-no-suspend, and scv.

4. Remove descriptions of built-in function that do not belong in this
section because the
   built-in functions are generic (not specific to PowerPC):
__builtin_fabsq,
   __builtin_copysignq, __builtin_infq, __builtin_huge_valq, __builtin_nanq,
   __builtin_nansq, __builtin_sqrtf128, __builtin_fmaf128.

5. Corrected the spellings of several built-in functions:
__builtin_fmaf128_round_to_odd,
   __builtin_addg6s, __builtin_cbctdt, __builtin_cdtbcd.

This patch is limited in scope in order to manage complexity of the
diffs.  Subsequent patches
will address different sections of the documentation.  Subsequent
patches will also add
new function descriptions into these sections.

This patch affects only extend.texi.  The gcc.pdf file has been built
and reviewed.

Is this ok for the trunk?

gcc/ChangeLog:

2018-04-24  Kelvin Nilsen  

    * doc/extend.texi: Tidy documentation of PowerPC built-in functions.

Index: gcc/doc/extend.texi
===
--- gcc/doc/extend.texi    (revision 259504)
+++ gcc/doc/extend.texi    (working copy)
@@ -15524,12 +15524,17 @@ implementing assertions.
 
 @end table
 
-@node PowerPC Built-in Functions
-@subsection PowerPC Built-in Functions
+@node Low-Level PowerPC Built-in Functions
+@subsection Low-Level PowerPC Built-in Functions
 
-The following built-in functions are always available and can be used to
-check the PowerPC target platform type:
+This section describes PowerPC built-in functions that do not require
+the inclusion of any special header files to declare prototypes or
+provide macro definitions.  The sections that follow describe
+additional PowerPC built-in functions.
 
+@node Low-Level PowerPC Built-in Functions Available on all Targets
+@subsubsection Low-Level PowerPC Built-in Functions Available on all
Targets
+
 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
 This function is a @code{nop} on the PowerPC platform and is included
solely
 to maintain API compatibility with the x86 builtins.
@@ -15633,6 +15638,8 @@ CPU supports the set of compatible performance mon
 CPU supports the Embedded ISA category.
 @item cellbe
 CPU has a CELL broadband engine.
+@item darn
+CPU supports the darn (deliver a random number) instruction.
 @item dfp
 CPU has a decimal floating point unit.
 @item dscr
@@ -15649,6 +15656,8 @@ CPU has a floating point unit.
 CPU has hardware transaction memory instructions.
 @item htm-nosc
 Kernel aborts hardware transactions when a syscall is made.
+@item htm-no-suspend
+Kernel aborts hardware transactions when the thread is suspended.
 @item ic_snoop
 CPU supports icache snooping capabilities.
 @item ieee128
@@ -15677,6 +15686,8 @@ CPU supports the old POWER ISA (eg, 601)
 CPU supports 64-bit mode execution.
 @item ppcle
 CPU supports a little-endian mode that uses address swizzling.
+@item scv
+Kernel supports system call vectored.
 @item smt
 CPU support simultaneous multi-threading.
 @item spe
@@ -15708,19 +15719,81 @@ Here is an example:
 @end smallexample
 @end deftypefn
 
-These built-in functions are available for the PowerPC family of
+The following built-in functions are also available on all PowerPC
 processors:
 @smallexample
-float __builtin_recipdivf (float, float);
-float __builtin_rsqrtf (float);
-double __builtin_recipdiv (double, double);
-double __builtin_rsqrt (double);
 uint64_t __builtin_ppc_get_timebase ();
 unsigned long __builtin_ppc_mftb ();
-double __builtin_unpack_longdouble (long double, int);
-long double __builtin_pack_longdouble (double, double);
 @end smallexample
 
+The @code{__builtin_ppc_get_timebase} and @code{__builtin_ppc_mftb}
+functions generate instructions to read the Time Base Register.  The
+@code{__builtin_ppc_get_timebase} function may generate multiple
+instructions and always returns the 64 bits of the Time Base Register.
+The @code{__builtin_ppc_mftb} function always generates one instruction and
+returns the Time Base Register value as an unsigned long, throwing away
+the most significant word on 32-bit environments.
+
+@node Low-Level PowerPC Built-in Functions Available on ISA 2.05