Hi,
Documentation for __fp16 seems to have drifted out of line with
compiler behaviour over time.
This patch tries to fix that up, documenting AArch64 support and
removing comments on restrictions on using the __fp16 type for arguments
and return types.
OK?
Thanks,
James
---
2016-11-30 James Greenhalgh <james.greenha...@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..cf16ec3 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 TS18661:3-2005
+(@xref{Floating Types}).
@node Decimal Float
@section Decimal Floating Types
