Re: [PATCH, rs6000] Improved Documentation of Built-in Functions Part 2

2018-05-14 Thread Segher Boessenkool 
Hi Kelvin,

On Mon, May 14, 2018 at 09:59:25AM -0500, Kelvin Nilsen wrote:
> 2018-05-14  Kelvin Nilsen  
> 
>   * doc/extend.texi (Basic PowerPC Built-in Functions): Rename this
>   subsection to be "PowerPC Built-in Functions".
>   (PowerPC Altivec/VSX Built-in Functions): Change this
>   subsection to subsubsection and rename as "PowerPC Altivec
>   Built-in Functions Available on ISA 2.05".
>   (PowerPC Built-in Functions Available on ISA 2.06): New
>   subsubsection.
>   (PowerPC Built-in Functions Available on ISA 2.07): Likewise.
>   (PowerPC Built-in Functions Available on ISA 3.0): Likewise.
>   (PowerPC Hardware Transactional Memory Built-in Functions): Split
>   this subsection into two subsubsections named "Basic PowerPC
>   Hardware Transactional Memory Built-in Functions" and "PowerPC
>   Hardware Transactional Memory Built-in Functions".  Move the basic
>   subsubsection forward to be next to other basic subsubsections.
>   (PowerPC Atomic Memory Operation Functions): Change this
>   subsection to subsubsection.

I don't think basic is such a great name.  Essentially all builtins are
"basic".  It's not immediately clear what basic means.  Maybe describe
the things defined by the header files in (subsub)sections named after
those header files?

The patch is okay for trunk, thanks!


Segher

[PATCH, rs6000] Improved Documentation of Built-in Functions Part 2

2018-05-14 Thread Kelvin Nilsen 
The focus of this patch is to restructure the section headers within the PowerPC
portion of the extend.texi documentation file.  Restructuring section headers 
prepares
the foundation for subsequent documentation improvements which will be 
delivered in
follow-on patches.

I have bootstrapped and regression tested without regressions on
powerpc64le-unknown-linux (P8).  I have also confirmed that this patch builds
on powerpc-linux (P7 bing-endian, both -m32 and -m64 target options).

I have also built and reviewed the gcc.pdf file.

Is this ok for the trunk?

gcc/ChangeLog:

2018-05-14  Kelvin Nilsen  

* doc/extend.texi (Basic PowerPC Built-in Functions): Rename this
subsection to be "PowerPC Built-in Functions".
(PowerPC Altivec/VSX Built-in Functions): Change this
subsection to subsubsection and rename as "PowerPC Altivec
Built-in Functions Available on ISA 2.05".
(PowerPC Built-in Functions Available on ISA 2.06): New
subsubsection.
(PowerPC Built-in Functions Available on ISA 2.07): Likewise.
(PowerPC Built-in Functions Available on ISA 3.0): Likewise.
(PowerPC Hardware Transactional Memory Built-in Functions): Split
this subsection into two subsubsections named "Basic PowerPC
Hardware Transactional Memory Built-in Functions" and "PowerPC
Hardware Transactional Memory Built-in Functions".  Move the basic
subsubsection forward to be next to other basic subsubsections.
(PowerPC Atomic Memory Operation Functions): Change this
subsection to subsubsection.

Index: gcc/doc/extend.texi
===
--- gcc/doc/extend.texi (revision 260182)
+++ gcc/doc/extend.texi (working copy)
@@ -12477,10 +12477,7 @@ instructions, but allow the compiler to schedule t
 * MSP430 Built-in Functions::
 * NDS32 Built-in Functions::
 * picoChip Built-in Functions::
-* Basic PowerPC Built-in Functions::
-* PowerPC AltiVec/VSX Built-in Functions::
-* PowerPC Hardware Transactional Memory Built-in Functions::
-* PowerPC Atomic Memory Operation Functions::
+* PowerPC Built-in Functions::
 * RX Built-in Functions::
 * S/390 System z Built-in Functions::
 * SH Built-in Functions::
@@ -15536,25 +15533,35 @@ implementing assertions.
 
 @end table
 
-@node Basic PowerPC Built-in Functions
-@subsection Basic PowerPC Built-in Functions
+@node PowerPC Built-in Functions
+@subsection PowerPC Built-in Functions
 
+This section describes built-in functions that are supported for
+various configurations of the PowerPC processor.
+
 @menu
 * Basic PowerPC Built-in Functions Available on all Configurations::
 * Basic PowerPC Built-in Functions Available on ISA 2.05::
 * Basic PowerPC Built-in Functions Available on ISA 2.06::
 * Basic PowerPC Built-in Functions Available on ISA 2.07::
+* Basic PowerPC Hardware Transactional Memory Built-in Functions::
 * Basic PowerPC Built-in Functions Available on ISA 3.0::
+* PowerPC AltiVec Built-in Functions Available on ISA 2.05::
+* PowerPC AltiVec Built-in Functions Available on ISA 2.06::
+* PowerPC AltiVec Built-in Functions Available on ISA 2.07::
+* PowerPC AltiVec Built-in Functions Available on ISA 3.0::
+* PowerPC Hardware Transactional Memory Built-in Functions::
+* PowerPC Atomic Memory Operation Functions::
 @end menu
 
-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 Basic PowerPC Built-in Functions Available on all Configurations
 @subsubsection Basic PowerPC Built-in Functions Available on all Configurations
 
+This section describes PowerPC built-in functions that are supported
+on all configurations and do not require
+the inclusion of any special header files to declare prototypes or
+provide macro definitions.
+
 @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.
@@ -15889,6 +15896,150 @@ addition to the @option{-mpower8-fusion}, @option{
 
 This section intentionally empty.
 
+@node Basic PowerPC Hardware Transactional Memory Built-in Functions
+@subsubsection Basic PowerPC Hardware Transactional Memory Built-in Functions
+
+The following basic built-in functions are available with
+@option{-mhtm} or @option{-mcpu=CPU} where CPU is `power8' or later.
+They all generate the machine instruction that is part of the name.
+
+The Hardware Transactional Memory (HTM) builtins (with the exception
+of @code{__builtin_tbegin}) return 
+the full 4-bit condition register value set by their associated hardware
+instruction.  The header file @code{htmintrin.h} defines some macros that can
+be used to decipher the return value.  The @code{__builtin_tbegin} builtin