diff mbox

[Doc] Update documentation for __fp16 type

Message ID 1480590547-1844-1-git-send-email-james.greenhalgh@arm.com
State Accepted
Commit 3ffead7761acaf55a28654a8e97cee6f5c53d82d
Headers show

Commit Message

James Greenhalgh Dec. 1, 2016, 11:09 a.m. UTC
On Wed, Nov 30, 2016 at 05:58:13PM +0000, 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  <james.greenhalgh@arm.com>

	* doc/extend.texi (Half-Precision): Update to document current
	compiler behaviour.

Comments

James Greenhalgh Dec. 12, 2016, 11:16 a.m. UTC | #1
On Thu, Dec 01, 2016 at 11:09:07AM +0000, James Greenhalgh wrote:
> 

> On Wed, Nov 30, 2016 at 05:58:13PM +0000, 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  <james.greenhalgh@arm.com>

> 

> 	* 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{<arm_fp16.h>}, 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
Sandra Loosemore Dec. 12, 2016, 9:19 p.m. UTC | #2
On 12/12/2016 04:16 AM, James Greenhalgh wrote:
> On Thu, Dec 01, 2016 at 11:09:07AM +0000, James Greenhalgh wrote:

>>

>> On Wed, Nov 30, 2016 at 05:58:13PM +0000, 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
Andreas Schwab Dec. 15, 2016, 10:11 a.m. UTC | #3
On Dez 15 2016, Jakub Jelinek <jakub@redhat.com> wrote:

> --- gcc/doc/extend.texi.jj	2016-12-14 20:28:12.000000000 +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, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."
Jakub Jelinek Dec. 15, 2016, 10:15 a.m. UTC | #4
On Thu, Dec 15, 2016 at 11:11:37AM +0100, Andreas Schwab wrote:
> On Dez 15 2016, Jakub Jelinek <jakub@redhat.com> wrote:

> 

> > --- gcc/doc/extend.texi.jj	2016-12-14 20:28:12.000000000 +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
Andreas Schwab Dec. 15, 2016, 10:23 a.m. UTC | #5
On Dez 15 2016, Jakub Jelinek <jakub@redhat.com> wrote:

> So, shall we change also the first 3?


Yes, I'd think so.

Andreas.

-- 
Andreas Schwab, SUSE Labs, schwab@suse.de
GPG Key fingerprint = 0196 BAD8 1CE9 1970 F4BE  1748 E4D4 88E3 0EEA B9D7
"And now for something completely different."
Sandra Loosemore Dec. 15, 2016, 4:40 p.m. UTC | #6
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 <jakub@redhat.com> 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  <jakub@redhat.com>

>

> 	* doc/extend.texi: Clean up @xref{...} uses.

> 	* doc/invoke.texi: Likewise.

>

> --- gcc/doc/extend.texi.jj	2016-12-14 20:28:12.000000000 +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.000000000 +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
diff mbox

Patch

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{<arm_fp16.h>}, 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