From 3ffead7761acaf55a28654a8e97cee6f5c53d82d Mon Sep 17 00:00:00 2001
From: James Greenhalgh <james.greenhalgh@arm.com>
Date: Tue, 13 Dec 2016 10:43:02 +0000
Subject: [PATCH] [Patch Doc] Update documentation for __fp16 type

gcc/

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

From-SVN: r243602
---
 gcc/ChangeLog       |  5 +++++
 gcc/doc/extend.texi | 40 +++++++++++++++++++++-------------------
 2 files changed, 26 insertions(+), 19 deletions(-)

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 16c1ecad8eb..5fd41549487 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,8 @@
+2016-12-13  James Greenhalgh  <james.greenhalgh@arm.com>
+
+	* doc/extend.texi (Half-Precision): Update to document current
+	compiler behaviour.
+
 2016-12-13  James Greenhalgh  <james.greenhalgh@arm.com>
 
 	* doc/extend.texi (Floating Types): Document availability of
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index d82444978fa..5f7f676ccaa 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,11 @@ 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 portable code use the @code{_Float16} type defined
+by ISO/IEC TS 18661-3:2015 (@xref{Floating Types}).
 
 @node Decimal Float
 @section Decimal Floating Types
-- 
2.30.2