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

[Segher Boessenkool]

Hi!

On Wed, May 09, 2018 at 12:42:11PM -0500, Kelvin Nilsen wrote:
> 1. Change the name of the first PowerPC built-in section from 
>"PowerPC Built-in Functions" to "Basic PowerPC Built-in Functions".
>This section has never described all PowerPC built-in functions.

After the patch it looks like this:

* 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::
* RX Built-in Functions::
* S/390 System z Built-in Functions::

I think it is nicer to just have a single "PowerPC Built-in Functions"
node, with then everything else hanging from a menu in there (as you have
for "Basic PowerPC Built-in Functions" now; so just rename that and put
the V*X, TM, atomic nodes in that menu too; probably need to make those
subsubsections or such).

> 2018-05-09  Kelvin Nilsen  
> 
>   * doc/extend.texi (PowerPC Built-in Functions): Rename this
>   subsection.
>   (Basic PowerPC Built-in Functions): The new name of the
>   subsection previously known as "PowerPC Built-in Functions".
>   (Basic PowerPC Built-in Functions Available on all Configurations):
>   New subsubsection.
>   (Basic PowerPC Built-in Functions Available on ISA 2.05): Likewise.
>   (Basic PowerPC Built-in Functions Available on ISA 2.06): Likewise.
>   (Basic PowerPC Built-in Functions Available on ISA 2.07): Likewise.
>   (Basic PowerPC Built-in Functions Available on ISA 3.0): Likewise.

But please commit this now, it's a nice improvement already.  Thanks!


Segher

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

[Kelvin Nilsen]

This is the first of several planned patches to address shortcomings in
existing documentation of PowerPC built-in functions.  The focus of this
particular patch is to improve documentation of basic built-in functions
that do not require inclusion of special header files.

A summary of this patch follows:

1. Change the name of the first PowerPC built-in section from 
   "PowerPC Built-in Functions" to "Basic 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. 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 differs from the previous draft patch in the following regards:

1. This patch adds back in documentation of the __builtin_fabsq,
   __builtin_copysignq, __builtin_infq, __builtin_huge_valq, __builtin_nanq,
   __builtin_nansq, __builtin_sqrtf128, and __builtin_fmaf128 functions.

2. Consistently, changed subsubsection names from
   "Low-Level PowerPC Built-in ... " to "Basic PowerPC Built-in ... "

3. Changed subsubsection name from "... Available on All Targets" to
   "... Available on All Configurations".

4. Used @code{} font for darn and tsuspend. instruction names.

5. Removed unnecessary parentheses around many option descriptions.

6. Clarified that the result returned from the __builtin_darn_32 function is
   conditioned.

7. Enhanced the ChangeLog to call out each of the subsection names
   (within extend.texi) that is affected by this patch.

8. Changed the menu reference to the newly named "Basic PowerPC Built-in
   Functions"

9. Added a new sub-menu to identify the subsubsections of the "Basic PowerPC
   Built-in Functions" section.

I have bootstrapped and regression tested without regressions on both
powerpc64le-unknown-linux (P8) and on powerpc-linux (P8 big-endian,
with both -m32 and -m64 target options).  I have built and reviewed the
gcc.pdf on the little-endian test platform.  I did not build the gcc.pdf 
file on my big-endian test platform because it is missing relevant fonts.

Is this ok for the trunk?

2018-05-09  Kelvin Nilsen  

* doc/extend.texi (PowerPC Built-in Functions): Rename this
subsection.
(Basic PowerPC Built-in Functions): The new name of the
subsection previously known as "PowerPC Built-in Functions".
(Basic PowerPC Built-in Functions Available on all Configurations):
New subsubsection.
(Basic PowerPC Built-in Functions Available on ISA 2.05): Likewise.
(Basic PowerPC Built-in Functions Available on ISA 2.06): Likewise.
(Basic PowerPC Built-in Functions Available on ISA 2.07): Likewise.
(Basic PowerPC Built-in Functions Available on ISA 3.0): Likewise.

Index: gcc/doc/extend.texi
===
--- gcc/doc/extend.texi (revision 260073)
+++ gcc/doc/extend.texi (working copy)
@@ -12475,7 +12475,7 @@
 * MSP430 Built-in Functions::
 * NDS32 Built-in Functions::
 * picoChip Built-in Functions::
-* PowerPC 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::
@@ -15534,12 +15534,25 @@
 
 @end table
 
-@node PowerPC Built-in Functions
-@subsection PowerPC Built-in Functions
+@node Basic PowerPC Built-in Functions
+@subsection Basic PowerPC Built-in Functions
 
-The following built-in functions are always available and can be used to
-check the PowerPC target platform type:
+@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 Built-in Functions Available on ISA 3.0::
+@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
+
 @deftypefn {Built-in Function} void __builtin_cpu_init (void)
 This