mirrors/llvm-project
0
0
Fork 0
mirror of https://github.com/llvm/llvm-project.git synced 2025-04-27 14:56:06 +00:00
Code Issues Projects Releases Wiki Activity

[docs] Add section 'Half-Precision Floating Point'

Browse Source 
This documents the differences/interactions between _Float16 and __fp16
and is a companion change for the _Float16 type implementation (r312794).

Differential Revision:  https://reviews.llvm.org/D35295

llvm-svn: 317558
This commit is contained in:
Sjoerd Meijer 2017-11-07 10:09:45 +00:00
parent 365200295a
commit 167f2e34d5
1 changed files with 43 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
clang/docs/LanguageExtensions.rst
View File

@ -436,6 +436,49 @@ const_cast no no no no
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 an ARM C-Language Extension (ACLE), whereas ``_Float16`` is
defined by the C standards committee, so using ``_Float16`` will not prevent
code from being ported to architectures other than Arm. 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
=========================================================