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

[SjoerdMeijer]

Summary

This documents the differences and interactions between _Float16 and __fp16.

This is a companion change for the _Float16 type implementation in D33719.

[simon_tatham]

docs/LanguageExtensions.rst

448 ↗

(On Diff #106154)

typo: artimethic -> arithmetic

454 ↗

(On Diff #106154)

typo: egual -> equal

455 ↗

(On Diff #106154)

Wording nit: "The difference with __fp16 is that ..." suggests that you're about to describe how __fp16 does things. Or at least it could be read as suggesting that.

Using "from" instead of "with" clarifies that you're saying how something is unlike fp16. I think I would also clarify by restating the type name in the subclause, along the lines of

The difference from ``__fp16`` is that arithmetic on ``_Float16`` is performed in half-precision, ...

[SjoerdMeijer]

Thanks for review! Feedback addressed.

[simon_tatham]

docs/LanguageExtensions.rst

457 ↗

(On Diff #106167)

I think the use of "portable" here doesn't really give enough detail.

From an ARM-specific perspective, source code using _Float16 will be compiled into code that uses the hardware FP instructions for arithmetic on 16-bit FP values which were introduced in ARMv8.2, whereas __fp16 will be compiled into code that only uses the instructions to convert 16-bit to and from 32-bit, from a much earlier architecture revision. So from that perspective, using _Float16 will reduce portability, because it will make your code run (or at least run at full hardware-FP speed) on a smaller set of CPUs.

On the other hand, from a source language perspective, __fp16 is defined in an ARM-specific language extension, whereas _Float16 is defined by the C standards committee. So if your portability concern is between entire architectures, rather than between versions of the ARM architecture, then using _Float16 probably does help.

So I think it would probably be better to make some of this explicit – don't just say one or the other type is "more portable", but say something more specific about the circumstances in which each one can be expected to work.

[SjoerdMeijer]

Good points. I am thinking about how to write this down.
I am not yet sure that _Float16 can reduce portability. I think the behaviour will depend on FLT_EVAL_METHOD. I.e., if your architecture supports half-precision instructions, you would like to set FLT_EVAL_METHOD = 16, which would avoid evaluation in float and thus promotions/truncations. If your architecture does not support half-precision arithmetic, this will be FLT_EVAL_METHOD = 0 so that _Float16 is evaluated in float. So, from that point of view _Float16 can achieve the same things as '__fp16`, and it is more efficient when the hardware supports it and is indeed also more portable between entire architectures.

[SjoerdMeijer]

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

[simon_tatham]

docs/LanguageExtensions.rst

462 ↗

(On Diff #121003)

Sorry to nitpick a second time, but I think the phrase "entire architectures" is a bit strange here. I know it's the same phrase I actually *wrote* in my last review comment, but I was being a bit informal, and also explicitly contrasting with "versions of the Arm architecture" in the same sentence, to distinguish (say) "port between Arm and x86" from "port between ArmThis and ArmThat". Out of context it doesn't seem quite idiomatic or quite clear to me, so sorry to have accidentally suggested it!

How about something like this as alternative wording:

``__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.

[SjoerdMeijer]

Many thanks for the reviews and suggestions! Comments addressed.

[simon_tatham]

LGTM now, thanks! (But other reviewers may still want to comment.)

cfe/trunk/docs/LanguageExtensions.rst

 C-style cast                     yes     yes     yes     no
 reinterpret_cast                 yes     no      yes     no
 static_cast                      yes     no      yes     no
 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
 =========================================================
 
 An optional string message can be added to the ``deprecated`` and
 ``unavailable`` attributes.  For example:
 
 .. code-block:: c++