* [PATCH] Improve __LONG_DOUBLE_USES_FLOAT128 commentary
@ 2020-02-14 22:54 Paul E. Murphy
2020-02-17 16:14 ` Paul Clarke
2020-03-24 23:35 ` Joseph Myers
0 siblings, 2 replies; 3+ messages in thread
From: Paul E. Murphy @ 2020-02-14 22:54 UTC (permalink / raw)
To: libc-alpha
Per the feedback from Joseph [1]. Good comments and a more
self-explanatory macro name will be very helpful when this
macro or its successor are able to assume a non-zero value.
[1] <https://sourceware.org/ml/libc-alpha/2020-02/msg00687.html>
---8<---
As noted, this is not the most ideal name for the conditional
used to determine whether long double ABI should be redirected
to _Float128 ABI. Once the development effort settles down, I
will rename it.
Improve the commentary to aid future developers who will stumble
upon this novel, yet not always perfect, mechanism to support
alternative formats for long double.
---
bits/long-double.h | 15 ++++++++++++
.../ldbl-128ibm-compat/bits/long-double.h | 24 +++++++++++++++----
2 files changed, 35 insertions(+), 4 deletions(-)
diff --git a/bits/long-double.h b/bits/long-double.h
index 6e16447e65..29ba2506a2 100644
--- a/bits/long-double.h
+++ b/bits/long-double.h
@@ -37,4 +37,19 @@
#ifndef __NO_LONG_DOUBLE_MATH
# define __NO_LONG_DOUBLE_MATH 1
#endif
+
+/* The macro __LONG_DOUBLE_USES_FLOAT128 is used to determine the
+ choice of the underlying ABI of long double during a single compilation.
+
+ If the value is non-zero, any API which is parameterized by the long
+ double type (i.e the scanf/printf family of functions or the explicitly
+ parameterized math.h functions) will be redirected to a compatible
+ implementation using _Float128 ABI via symbols suffixed with ieee128.
+
+ These redirections usually take the form of an "ASM Label" as called out
+ int Chapter 6.47.4 in the GCC 9 manual. And in very rare cases, a
+ macro. They do not alter or otherwise change the ABI stability of glibc.
+
+ The mechanism this macro uses to acquire it's value is specific both a
+ function of architecture, and options used to invoke compilation. */
#define __LONG_DOUBLE_USES_FLOAT128 0
diff --git a/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h b/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h
index 91dddbdc8b..6bec7d82a3 100644
--- a/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h
+++ b/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h
@@ -22,8 +22,24 @@
# define __NO_LONG_DOUBLE_MATH 1
# endif
#endif
-/* On platforms that reuse the _Float128 implementation for IEEE long
- double, access to the correct long double functions is selected based
- on the long double mode being used during the compilation. On
- powerpc64le, this is true when -mabi=ieeelongdouble is in use. */
+
+/* The macro __LONG_DOUBLE_USES_FLOAT128 is used to determine the
+ choice of the underlying ABI of long double during a single compilation.
+
+ If the value is non-zero, any API which is parameterized by the long
+ double type (i.e the scanf/printf family of functions or the explicitly
+ parameterized math.h functions) will be redirected to a compatible
+ implementation using _Float128 ABI via symbols suffixed with ieee128.
+
+ These redirections usually take the form of an "ASM Label" as called out
+ int Chapter 6.47.4 in the GCC 9 manual. And in very rare cases, a
+ macro. They do not alter or otherwise change the ABI stability of glibc.
+
+ The mechanism this macro uses to acquire it's value is specific both a
+ function of architecture, and options used to invoke compilation.
+
+ On powerpc64le, the GCC >=7 compiler option -mabi=ieeelongdouble will
+ change the underlying format of long double to IEEE 128 binary floating
+ point. We enable the redirects based how many mantissa digits GCC
+ reports for long double. For older GCC and non-IEEE, this is 106. */
#define __LONG_DOUBLE_USES_FLOAT128 (__LDBL_MANT_DIG__ == 113)
--
2.21.1
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] Improve __LONG_DOUBLE_USES_FLOAT128 commentary
2020-02-14 22:54 [PATCH] Improve __LONG_DOUBLE_USES_FLOAT128 commentary Paul E. Murphy
@ 2020-02-17 16:14 ` Paul Clarke
2020-03-24 23:35 ` Joseph Myers
1 sibling, 0 replies; 3+ messages in thread
From: Paul Clarke @ 2020-02-17 16:14 UTC (permalink / raw)
To: Paul E. Murphy, libc-alpha
On 2/14/20 4:54 PM, Paul E. Murphy wrote:
> Per the feedback from Joseph [1]. Good comments and a more
> self-explanatory macro name will be very helpful when this
> macro or its successor are able to assume a non-zero value.
>
>
> [1] <https://sourceware.org/ml/libc-alpha/2020-02/msg00687.html>
>
> ---8<---
>
> As noted, this is not the most ideal name for the conditional
> used to determine whether long double ABI should be redirected
> to _Float128 ABI. Once the development effort settles down, I
> will rename it.
>
> Improve the commentary to aid future developers who will stumble
> upon this novel, yet not always perfect, mechanism to support
> alternative formats for long double.
> ---
> bits/long-double.h | 15 ++++++++++++
> .../ldbl-128ibm-compat/bits/long-double.h | 24 +++++++++++++++----
> 2 files changed, 35 insertions(+), 4 deletions(-)
>
> diff --git a/bits/long-double.h b/bits/long-double.h
> index 6e16447e65..29ba2506a2 100644
> --- a/bits/long-double.h
> +++ b/bits/long-double.h
> @@ -37,4 +37,19 @@
> #ifndef __NO_LONG_DOUBLE_MATH
> # define __NO_LONG_DOUBLE_MATH 1
> #endif
> +
> +/* The macro __LONG_DOUBLE_USES_FLOAT128 is used to determine the
> + choice of the underlying ABI of long double during a single compilation.
I'm not sure you need "during a single compilation".
> +
> + If the value is non-zero, any API which is parameterized by the long
> + double type (i.e the scanf/printf family of functions or the explicitly
> + parameterized math.h functions) will be redirected to a compatible
> + implementation using _Float128 ABI via symbols suffixed with ieee128.
> +
> + These redirections usually take the form of an "ASM Label" as called out
> + int Chapter 6.47.4 in the GCC 9 manual. And in very rare cases, a
I don't see "ASM Label" in that section, although the page is called "Asm-Labels.html". hmm
> + macro. They do not alter or otherwise change the ABI stability of glibc.
I presume "They" refers to "redirections" and not "macro". I wonder if the "And..." fragment should be joined with the sentence before it? "GCC 9 manual, and..."
> +
> + The mechanism this macro uses to acquire it's value is specific both a
> + function of architecture, and options used to invoke compilation. */
s/it's/its/
"value is specific both a function of architecture, and options used to invoke compilation" doesn't read well.
"value is a function of architecture and compilation options", perhaps?
> #define __LONG_DOUBLE_USES_FLOAT128 0
> diff --git a/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h b/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h
> index 91dddbdc8b..6bec7d82a3 100644
> --- a/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h
> +++ b/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h
> @@ -22,8 +22,24 @@
> # define __NO_LONG_DOUBLE_MATH 1
> # endif
> #endif
> -/* On platforms that reuse the _Float128 implementation for IEEE long
> - double, access to the correct long double functions is selected based
> - on the long double mode being used during the compilation. On
> - powerpc64le, this is true when -mabi=ieeelongdouble is in use. */
> +
> +/* The macro __LONG_DOUBLE_USES_FLOAT128 is used to determine the
> + choice of the underlying ABI of long double during a single compilation.
> +
> + If the value is non-zero, any API which is parameterized by the long
> + double type (i.e the scanf/printf family of functions or the explicitly
> + parameterized math.h functions) will be redirected to a compatible
> + implementation using _Float128 ABI via symbols suffixed with ieee128.
> +
> + These redirections usually take the form of an "ASM Label" as called out
> + int Chapter 6.47.4 in the GCC 9 manual. And in very rare cases, a
> + macro. They do not alter or otherwise change the ABI stability of glibc.
> +
> + The mechanism this macro uses to acquire it's value is specific both a
> + function of architecture, and options used to invoke compilation.
> +
> + On powerpc64le, the GCC >=7 compiler option -mabi=ieeelongdouble will
> + change the underlying format of long double to IEEE 128 binary floating
> + point. We enable the redirects based how many mantissa digits GCC
> + reports for long double. For older GCC and non-IEEE, this is 106. */
> #define __LONG_DOUBLE_USES_FLOAT128 (__LDBL_MANT_DIG__ == 113)
>
PC
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] Improve __LONG_DOUBLE_USES_FLOAT128 commentary
2020-02-14 22:54 [PATCH] Improve __LONG_DOUBLE_USES_FLOAT128 commentary Paul E. Murphy
2020-02-17 16:14 ` Paul Clarke
@ 2020-03-24 23:35 ` Joseph Myers
1 sibling, 0 replies; 3+ messages in thread
From: Joseph Myers @ 2020-03-24 23:35 UTC (permalink / raw)
To: Paul E. Murphy; +Cc: libc-alpha
On Fri, 14 Feb 2020, Paul E. Murphy wrote:
> +/* The macro __LONG_DOUBLE_USES_FLOAT128 is used to determine the
> + choice of the underlying ABI of long double during a single compilation.
> +
> + If the value is non-zero, any API which is parameterized by the long
> + double type (i.e the scanf/printf family of functions or the explicitly
> + parameterized math.h functions) will be redirected to a compatible
> + implementation using _Float128 ABI via symbols suffixed with ieee128.
> +
> + These redirections usually take the form of an "ASM Label" as called out
> + int Chapter 6.47.4 in the GCC 9 manual. And in very rare cases, a
> + macro. They do not alter or otherwise change the ABI stability of glibc.
I don't think this paragraph about how the redirections are implemented
should be present at all; it's simply a description of how the redirection
macros work, which belongs with the implementation of those macros if
anywhere. (And referencing particular section numbers in the GCC manual
is a bad idea; section names may be somewhat stable, numbers are very
unstable.)
> diff --git a/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h b/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h
I think it's best for the detailed comment defining the semantics of the
macro to be only in the default bits/long-double.h file, with
architecture-specific files having comments that only discuss the
architecture-specific details for that architecture. That avoids having
multiple places that need updating with any improvement to the
documentation.
--
Joseph S. Myers
joseph@codesourcery.com
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-03-24 23:35 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-02-14 22:54 [PATCH] Improve __LONG_DOUBLE_USES_FLOAT128 commentary Paul E. Murphy
2020-02-17 16:14 ` Paul Clarke
2020-03-24 23:35 ` Joseph Myers
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).