[PATCH] D35295: [docs] Add section 'Half-Precision Floating Point'

[Sjoerd Meijer via Phabricator via cfe-commits]

SjoerdMeijer updated this revision to Diff 121003.
SjoerdMeijer added a comment.

Addressed the comments about portability, and added a note that Float16 is available in both C and C++ mode.


https://reviews.llvm.org/D35295

Files:
  docs/LanguageExtensions.rst


Index: docs/LanguageExtensions.rst
===================================================================
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -436,6 +436,48 @@
 
 See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`.
 
+Half-Precision Floating Point
+=============================
+
+Clang supports two half-precision (16-bit) floating point types: ``__fp16`` and
+``_Float16``. ``__fp16`` is defined in the ARM C Language Extensions (`ACLE
+<http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053d/IHI0053D_acle_2_1.pdf>`_
+and ``_Float16`` in ISO/IEC TS 18661-3:2015.
+
+``__fp16`` is a storage and interchange format only. This means that values of
+``__fp16`` promote to (at least) float when used in arithmetic operations.
+There are two ``__fp16`` formats. Clang supports the IEEE 754-2008 format and
+not the ARM alternative format.
+
+ISO/IEC TS 18661-3:2015 defines C support for additional floating point types.
+``_FloatN`` is defined as a binary floating type, where the N suffix denotes
+the number of bits and is 16, 32, 64, or greater and equal to 128 and a
+multiple of 32. Clang supports ``_Float16``. The difference from ``__fp16`` is
+that arithmetic on ``_Float16`` is performed in half-precision, thus it is not
+a storage-only format. ``_Float16`` is available as a source language type in
+both C and C++ mode.
+
+It is recommended that portable code use the ``_Float16`` type because
+``__fp16`` is a ARM C-Language Extension (ACLE) and ``_Float16`` is defined by
+the C standards committee, which should help portability between entire
+architectures. Also, ``_Float16`` arithmetic and operations will directly map
+on half-precision instructions when they are available (e.g. Armv8.2-A),
+avoiding conversions to/from single-precision, and thus will result in more
+performant code. If half-precision instructions are unavailable, values will be
+promoted to single-precision, similar to the semantics of ``__fp16`` except
+that the results will be stored in single-precision.
+
+In an arithmetic operation where one operand is of ``__fp16`` type and the
+other is of ``_Float16`` type, the ``_Float16`` type is first converted to
+``__fp16`` type and then the operation is completed as if both operands were of
+``__fp16`` type.
+
+To define a ``_Float16`` literal, suffix ``f16`` can be appended to the compile-time
+constant declaration. There is no default argument promotion for ``_Float16``; this
+applies to the standard floating types only. As a consequence, for example, an
+explicit cast is required for printing a ``_Float16`` value (there is no string
+format specifier for ``_Float16``).
+
 Messages on ``deprecated`` and ``unavailable`` Attributes
 =========================================================
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D35295.121003.patch
Type: text/x-patch
Size: 2814 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20171031/dafe895b/attachment.bin>