Re: [Patch Doc] Update documentation for __fp16 type
On 12/15/2016 03:27 AM, Jakub Jelinek wrote:
On Thu, Dec 15, 2016 at 11:23:14AM +0100, Andreas Schwab wrote:
On Dez 15 2016, Jakub Jelinek wrote:
So, shall we change also the first 3?
Yes, I'd think so.
So here is it in patch form. Is this ok for trunk?
2016-12-15 Jakub Jelinek
* doc/extend.texi: Clean up @xref{...} uses.
* doc/invoke.texi: Likewise.
--- gcc/doc/extend.texi.jj 2016-12-14 20:28:12.0 +0100
+++ gcc/doc/extend.texi 2016-12-15 11:26:07.867736292 +0100
@@ -1057,7 +1057,7 @@ implements conversions between @code{__f
calls.
It is recommended that portable code use the @code{_Float16} type defined
-by ISO/IEC TS 18661-3:2015 (@xref{Floating Types}).
+by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
@node Decimal Float
@section Decimal Floating Types
@@ -2089,7 +2089,7 @@ union foo f = @{ .d = 4 @};
converts 4 to a @code{double} to store it in the union using
the second element. By contrast, casting 4 to type @code{union foo}
stores it into the union as the integer @code{i}, since it is
-an integer. (@xref{Cast to Union}.)
+an integer. @xref{Cast to Union}.
You can combine this technique of naming elements with ordinary C
initialization of successive elements. Each initializer element that
@@ -2181,7 +2181,7 @@ specified is a union type. You can spec
@code{union} keyword or with a @code{typedef} name that refers to
a union. A cast to a union actually creates a compound literal and
yields an lvalue, not an rvalue like true casts do.
-(@xref{Compound Literals}.)
+@xref{Compound Literals}.
The types that may be cast to the union type are those of the members
of the union. Thus, given the following union and variables:
--- gcc/doc/invoke.texi.jj 2016-12-15 10:26:15.0 +0100
+++ gcc/doc/invoke.texi 2016-12-15 11:25:19.226386092 +0100
@@ -7262,8 +7262,8 @@ release to an another.
@opindex fno-keep-inline-dllexport
This is a more fine-grained version of @option{-fkeep-inline-functions},
which applies only to functions that are declared using the @code{dllexport}
-attribute or declspec (@xref{Function Attributes,,Declaring Attributes of
-Functions}.)
+attribute or declspec. @xref{Function Attributes,,Declaring Attributes of
+Functions}.
@item -fkeep-inline-functions
@opindex fkeep-inline-functions
This is OK, but FYI it would have been simpler just to do
s/@xref/@pxref/
in the one instance that was causing an diagnostic. Sorry I missed that
in the original patch review. :-(
-Sandra
Re: [Patch Doc] Update documentation for __fp16 type
On Thu, Dec 15, 2016 at 11:23:14AM +0100, Andreas Schwab wrote:
> On Dez 15 2016, Jakub Jelinek wrote:
>
> > So, shall we change also the first 3?
>
> Yes, I'd think so.
So here is it in patch form. Is this ok for trunk?
2016-12-15 Jakub Jelinek
* doc/extend.texi: Clean up @xref{...} uses.
* doc/invoke.texi: Likewise.
--- gcc/doc/extend.texi.jj 2016-12-14 20:28:12.0 +0100
+++ gcc/doc/extend.texi 2016-12-15 11:26:07.867736292 +0100
@@ -1057,7 +1057,7 @@ implements conversions between @code{__f
calls.
It is recommended that portable code use the @code{_Float16} type defined
-by ISO/IEC TS 18661-3:2015 (@xref{Floating Types}).
+by ISO/IEC TS 18661-3:2015. @xref{Floating Types}.
@node Decimal Float
@section Decimal Floating Types
@@ -2089,7 +2089,7 @@ union foo f = @{ .d = 4 @};
converts 4 to a @code{double} to store it in the union using
the second element. By contrast, casting 4 to type @code{union foo}
stores it into the union as the integer @code{i}, since it is
-an integer. (@xref{Cast to Union}.)
+an integer. @xref{Cast to Union}.
You can combine this technique of naming elements with ordinary C
initialization of successive elements. Each initializer element that
@@ -2181,7 +2181,7 @@ specified is a union type. You can spec
@code{union} keyword or with a @code{typedef} name that refers to
a union. A cast to a union actually creates a compound literal and
yields an lvalue, not an rvalue like true casts do.
-(@xref{Compound Literals}.)
+@xref{Compound Literals}.
The types that may be cast to the union type are those of the members
of the union. Thus, given the following union and variables:
--- gcc/doc/invoke.texi.jj 2016-12-15 10:26:15.0 +0100
+++ gcc/doc/invoke.texi 2016-12-15 11:25:19.226386092 +0100
@@ -7262,8 +7262,8 @@ release to an another.
@opindex fno-keep-inline-dllexport
This is a more fine-grained version of @option{-fkeep-inline-functions},
which applies only to functions that are declared using the @code{dllexport}
-attribute or declspec (@xref{Function Attributes,,Declaring Attributes of
-Functions}.)
+attribute or declspec. @xref{Function Attributes,,Declaring Attributes of
+Functions}.
@item -fkeep-inline-functions
@opindex fkeep-inline-functions
Jakub
Re: [Patch Doc] Update documentation for __fp16 type
On Dez 15 2016, Jakub Jelinek wrote: > So, shall we change also the first 3? Yes, I'd think so. Andreas. -- Andreas Schwab, SUSE Labs, sch...@suse.de GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE 1748 E4D4 88E3 0EEA B9D7 "And now for something completely different."
Re: [Patch Doc] Update documentation for __fp16 type
On Thu, Dec 15, 2016 at 11:11:37AM +0100, Andreas Schwab wrote:
> On Dez 15 2016, Jakub Jelinek wrote:
>
> > --- gcc/doc/extend.texi.jj 2016-12-14 20:28:12.0 +0100
> > +++ gcc/doc/extend.texi 2016-12-15 10:56:14.470702563 +0100
> > @@ -1057,7 +1057,7 @@ implements conversions between @code{__f
> > calls.
> >
> > It is recommended that portable code use the @code{_Float16} type defined
> > -by ISO/IEC TS 18661-3:2015 (@xref{Floating Types}).
> > +by ISO/IEC TS 18661-3:2015. (@xref{Floating Types}.)
>
> I think the parens should be removed.
We have it in other spots:
extend.texi-stores it into the union as the integer @code{i}, since it is
extend.texi:an integer. (@xref{Cast to Union}.)
extend.texi-
extend.texi-yields an lvalue, not an rvalue like true casts do.
extend.texi:(@xref{Compound Literals}.)
extend.texi-
invoke.texi-which applies only to functions that are declared using the
@code{dllexport}
invoke.texi:attribute or declspec (@xref{Function Attributes,,Declaring
Attributes of
invoke.texi-Functions}.)
invoke.texi-needs for some languages.
invoke.texi:(@xref{Interface,,Interfacing to GCC Output,gccint,GNU Compiler
invoke.texi-Collection (GCC) Internals},
invoke.texi-for more discussion of @file{libgcc.a}.)
The last one looks correct to me, the third one looks weird (the dot inside
of (), but no dot before (.
So, shall we change also the first 3?
Jakub
Re: [Patch Doc] Update documentation for __fp16 type
On Dez 15 2016, Jakub Jelinek wrote:
> --- gcc/doc/extend.texi.jj2016-12-14 20:28:12.0 +0100
> +++ gcc/doc/extend.texi 2016-12-15 10:56:14.470702563 +0100
> @@ -1057,7 +1057,7 @@ implements conversions between @code{__f
> calls.
>
> It is recommended that portable code use the @code{_Float16} type defined
> -by ISO/IEC TS 18661-3:2015 (@xref{Floating Types}).
> +by ISO/IEC TS 18661-3:2015. (@xref{Floating Types}.)
I think the parens should be removed.
Andreas.
--
Andreas Schwab, SUSE Labs, sch...@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE 1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."
Re: [Patch Doc] Update documentation for __fp16 type
On Mon, Dec 12, 2016 at 02:19:47PM -0700, Sandra Loosemore wrote:
> One small grammar nit at the end:
>
> > > +It is recommended that code which is intended to be portable use the
> > > +@code{_Float16} type defined by ISO/IEC TS 18661-3:2015
> > > +(@xref{Floating Types}).
>
> Either s/which/that/ or rewrite the beginning of the sentence as "It is
> recommended that portable code use..."
>
> The patch is OK to commit with that fixed.
I've noticed
../../gcc/doc/extend.texi:1060: warning: `.' or `,' must follow @xref, not )
warning with this. The following patch adjusts it similarly how other
(@xref{...}.) look like. @xref actually emits
See Section 6.11 [Floating Types], page 415
in pdf or
*Note Floating Types::
in info.
Tested with building gcc.info and gcc.pdf and checking what is in there.
Ok for trunk?
2016-12-15 Jakub Jelinek
* doc/extend.texi: Add a dot after @xref{...}.
--- gcc/doc/extend.texi.jj 2016-12-14 20:28:12.0 +0100
+++ gcc/doc/extend.texi 2016-12-15 10:56:14.470702563 +0100
@@ -1057,7 +1057,7 @@ implements conversions between @code{__f
calls.
It is recommended that portable code use the @code{_Float16} type defined
-by ISO/IEC TS 18661-3:2015 (@xref{Floating Types}).
+by ISO/IEC TS 18661-3:2015. (@xref{Floating Types}.)
@node Decimal Float
@section Decimal Floating Types
Jakub
Re: [Patch Doc] Update documentation for __fp16 type
On 12/12/2016 04:16 AM, James Greenhalgh wrote:
On Thu, Dec 01, 2016 at 11:09:07AM +, James Greenhalgh wrote:
On Wed, Nov 30, 2016 at 05:58:13PM +, Joseph Myers wrote:
On Wed, 30 Nov 2016, James Greenhalgh wrote:
+@code{_Float16} type defined by ISO/IEC TS18661:3-2005
Add a space after "TS", and it's -3:2015 not :3-2005.
You would think that after 2 months of having the specification sitting
on my desk I'd have got that right... Fixed in this revision.
*ping*
One small grammar nit at the end:
+It is recommended that code which is intended to be portable use the
+@code{_Float16} type defined by ISO/IEC TS 18661-3:2015
+(@xref{Floating Types}).
Either s/which/that/ or rewrite the beginning of the sentence as "It is
recommended that portable code use..."
The patch is OK to commit with that fixed.
-Sandra
Re: [Patch Doc] Update documentation for __fp16 type
On Thu, Dec 01, 2016 at 11:09:07AM +, James Greenhalgh wrote:
>
> On Wed, Nov 30, 2016 at 05:58:13PM +, Joseph Myers wrote:
> > On Wed, 30 Nov 2016, James Greenhalgh wrote:
> >
> > > +@code{_Float16} type defined by ISO/IEC TS18661:3-2005
> >
> > Add a space after "TS", and it's -3:2015 not :3-2005.
>
> You would think that after 2 months of having the specification sitting
> on my desk I'd have got that right... Fixed in this revision.
*ping*
Thanks,
James
>
> > I think the -mfp16-format documentation in invoke.texi should also be
> > updated to reflect that it affects availability of _Float16.
>
> I'm working on something larger for -mfp16-format, I'll update invoke.texi
> at that point (or otherwise before GCC 7 releases).
>
> Thanks,
> James
>
> ---
>
> 2016-12-01 James Greenhalgh
>
> * doc/extend.texi (Half-Precision): Update to document current
> compiler behaviour.
>
> diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
> index 7d3d17a..23d03bd 100644
> --- a/gcc/doc/extend.texi
> +++ b/gcc/doc/extend.texi
> @@ -1012,11 +1012,12 @@ that handle conversions if/when long double is
> changed to be IEEE
> @cindex half-precision floating point
> @cindex @code{__fp16} data type
>
> -On ARM targets, GCC supports half-precision (16-bit) floating point via
> -the @code{__fp16} type. You must enable this type explicitly
> -with the @option{-mfp16-format} command-line option in order to use it.
> +On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
> +point via the @code{__fp16} type defined in the ARM C Language Extensions.
> +On ARM systems, you must enable this type explicitly with the
> +@option{-mfp16-format} command-line option in order to use it.
>
> -ARM supports two incompatible representations for half-precision
> +ARM targets support two incompatible representations for half-precision
> floating-point values. You must choose one of the representations and
> use it consistently in your program.
>
> @@ -1031,22 +1032,20 @@ format, but does not support infinities or NaNs.
> Instead, the range
> of exponents is extended, so that this format can represent normalized
> values in the range of @math{2^{-14}} to 131008.
>
> -The @code{__fp16} type is a storage format only. For purposes
> -of arithmetic and other operations, @code{__fp16} values in C or C++
> -expressions are automatically promoted to @code{float}. In addition,
> -you cannot declare a function with a return value or parameters
> -of type @code{__fp16}.
> +The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
> +not require use of the @option{-mfp16-format} command-line option.
>
> -Note that conversions from @code{double} to @code{__fp16}
> -involve an intermediate conversion to @code{float}. Because
> -of rounding, this can sometimes produce a different result than a
> -direct conversion.
> +The @code{__fp16} type may only be used as an argument to intrinsics defined
> +in @code{}, or as a storage format. For purposes of
> +arithmetic and other operations, @code{__fp16} values in C or C++
> +expressions are automatically promoted to @code{float}.
>
> -ARM provides hardware support for conversions between
> +The ARM target provides hardware support for conversions between
> @code{__fp16} and @code{float} values
> -as an extension to VFP and NEON (Advanced SIMD). GCC generates
> -code using these hardware instructions if you compile with
> -options to select an FPU that provides them;
> +as an extension to VFP and NEON (Advanced SIMD), and from ARMv8 provides
> +hardware support for conversions between @code{__fp16} and @code{double}
> +values. GCC generates code using these hardware instructions if you
> +compile with options to select an FPU that provides them;
> for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
> in addition to the @option{-mfp16-format} option to select
> a half-precision format.
> @@ -1054,8 +1053,12 @@ a half-precision format.
> Language-level support for the @code{__fp16} data type is
> independent of whether GCC generates code using hardware floating-point
> instructions. In cases where hardware support is not specified, GCC
> -implements conversions between @code{__fp16} and @code{float} values
> -as library calls.
> +implements conversions between @code{__fp16} and other types as library
> +calls.
> +
> +It is recommended that code which is intended to be portable use the
> +@code{_Float16} type defined by ISO/IEC TS 18661-3:2015
> +(@xref{Floating Types}).
>
> @node Decimal Float
> @section Decimal Floating Types
Re: [Patch Doc] Update documentation for __fp16 type
On Wed, Nov 30, 2016 at 05:58:13PM +, Joseph Myers wrote:
> On Wed, 30 Nov 2016, James Greenhalgh wrote:
>
> > +@code{_Float16} type defined by ISO/IEC TS18661:3-2005
>
> Add a space after "TS", and it's -3:2015 not :3-2005.
You would think that after 2 months of having the specification sitting
on my desk I'd have got that right... Fixed in this revision.
> I think the -mfp16-format documentation in invoke.texi should also be
> updated to reflect that it affects availability of _Float16.
I'm working on something larger for -mfp16-format, I'll update invoke.texi
at that point (or otherwise before GCC 7 releases).
Thanks,
James
---
2016-12-01 James Greenhalgh
* doc/extend.texi (Half-Precision): Update to document current
compiler behaviour.
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index 7d3d17a..23d03bd 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -1012,11 +1012,12 @@ that handle conversions if/when long double is changed to be IEEE
@cindex half-precision floating point
@cindex @code{__fp16} data type
-On ARM targets, GCC supports half-precision (16-bit) floating point via
-the @code{__fp16} type. You must enable this type explicitly
-with the @option{-mfp16-format} command-line option in order to use it.
+On ARM and AArch64 targets, GCC supports half-precision (16-bit) floating
+point via the @code{__fp16} type defined in the ARM C Language Extensions.
+On ARM systems, you must enable this type explicitly with the
+@option{-mfp16-format} command-line option in order to use it.
-ARM supports two incompatible representations for half-precision
+ARM targets support two incompatible representations for half-precision
floating-point values. You must choose one of the representations and
use it consistently in your program.
@@ -1031,22 +1032,20 @@ format, but does not support infinities or NaNs. Instead, the range
of exponents is extended, so that this format can represent normalized
values in the range of @math{2^{-14}} to 131008.
-The @code{__fp16} type is a storage format only. For purposes
-of arithmetic and other operations, @code{__fp16} values in C or C++
-expressions are automatically promoted to @code{float}. In addition,
-you cannot declare a function with a return value or parameters
-of type @code{__fp16}.
+The GCC port for AArch64 only supports the IEEE 754-2008 format, and does
+not require use of the @option{-mfp16-format} command-line option.
-Note that conversions from @code{double} to @code{__fp16}
-involve an intermediate conversion to @code{float}. Because
-of rounding, this can sometimes produce a different result than a
-direct conversion.
+The @code{__fp16} type may only be used as an argument to intrinsics defined
+in @code{}, or as a storage format. For purposes of
+arithmetic and other operations, @code{__fp16} values in C or C++
+expressions are automatically promoted to @code{float}.
-ARM provides hardware support for conversions between
+The ARM target provides hardware support for conversions between
@code{__fp16} and @code{float} values
-as an extension to VFP and NEON (Advanced SIMD). GCC generates
-code using these hardware instructions if you compile with
-options to select an FPU that provides them;
+as an extension to VFP and NEON (Advanced SIMD), and from ARMv8 provides
+hardware support for conversions between @code{__fp16} and @code{double}
+values. GCC generates code using these hardware instructions if you
+compile with options to select an FPU that provides them;
for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp},
in addition to the @option{-mfp16-format} option to select
a half-precision format.
@@ -1054,8 +1053,12 @@ a half-precision format.
Language-level support for the @code{__fp16} data type is
independent of whether GCC generates code using hardware floating-point
instructions. In cases where hardware support is not specified, GCC
-implements conversions between @code{__fp16} and @code{float} values
-as library calls.
+implements conversions between @code{__fp16} and other types as library
+calls.
+
+It is recommended that code which is intended to be portable use the
+@code{_Float16} type defined by ISO/IEC TS 18661-3:2015
+(@xref{Floating Types}).
@node Decimal Float
@section Decimal Floating Types
Re: [Patch Doc] Update documentation for __fp16 type
On Wed, 30 Nov 2016, James Greenhalgh wrote:
> +@code{_Float16} type defined by ISO/IEC TS18661:3-2005
Add a space after "TS", and it's -3:2015 not :3-2005.
I think the -mfp16-format documentation in invoke.texi should also be
updated to reflect that it affects availability of _Float16.
--
Joseph S. Myers
jos...@codesourcery.com
