[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