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

[Simon Tatham via Phabricator via cfe-commits]

simon_tatham accepted this revision.
simon_tatham added a comment.
This revision is now accepted and ready to land.

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


https://reviews.llvm.org/D35295



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[Sjoerd Meijer via Phabricator via cfe-commits]

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

Many thanks for the reviews and suggestions! Comments addressed.


https://reviews.llvm.org/D35295

Files:
  docs/LanguageExtensions.rst


Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -436,6 +436,49 @@
 
 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
+`_)
+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
 =
 


Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -436,6 +436,49 @@
 
 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
+`_)
+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 

[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
+`_
+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
 =
 


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
+`_
+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 

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

[Sjoerd Meijer via Phabricator via cfe-commits]

SjoerdMeijer added a comment.

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.


https://reviews.llvm.org/D35295



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[Simon Tatham via Phabricator via cfe-commits]

simon_tatham added inline comments.



Comment at: docs/LanguageExtensions.rst:457
+that arithmetic on ``_Float16`` is performed in half-precision, thus it is not
+a storage-only format. It is recommended that portable code use the
+``_Float16`` type.

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.


https://reviews.llvm.org/D35295



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[Sjoerd Meijer via Phabricator via cfe-commits]

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

Thanks for review! Feedback addressed.


https://reviews.llvm.org/D35295

Files:
  docs/LanguageExtensions.rst


Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -436,6 +436,38 @@
 
 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
+`_
+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. It is recommended that portable code use the
+``_Float16`` type.
+
+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
 =
 


Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -436,6 +436,38 @@
 
 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
+`_
+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. It is recommended that portable code use the
+``_Float16`` type.
+
+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
 =
 
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[Simon Tatham via Phabricator via cfe-commits]

simon_tatham added inline comments.



Comment at: docs/LanguageExtensions.rst:448
+``__fp16`` is a storage and interchange format only. This means that values of
+``__fp16`` promote to (at least) float when used in artimethic operations. 
There are
+two ``__fp16`` formats. Clang supports the IEEE 754-2008 format and not the

typo: artimethic -> arithmetic



Comment at: docs/LanguageExtensions.rst:454
+``_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 egual to 128 and a
+multiple of 32. Clang supports ``_Float16``.  The difference with ``__fp16`` is

typo: egual -> equal



Comment at: docs/LanguageExtensions.rst:455
+the number of bits and is 16, 32, 64, or greater and egual to 128 and a
+multiple of 32. Clang supports ``_Float16``.  The difference with ``__fp16`` is
+that arithmetic is performed in half-precision, thus it is not a storage-only

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, ...


https://reviews.llvm.org/D35295



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

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

[Sjoerd Meijer via Phabricator via cfe-commits]

SjoerdMeijer created this revision.

This documents the differences and interactions between _Float16 and __fp16.


https://reviews.llvm.org/D35295

Files:
  docs/LanguageExtensions.rst


Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -436,6 +436,37 @@
 
 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
+`_
+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 artimethic 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 egual to 128 and a
+multiple of 32. Clang supports ``_Float16``.  The difference with ``__fp16`` is
+that arithmetic is performed in half-precision, thus it is not a storage-only
+format. It is recommended that portable code use the ``_Float16`` type.
+
+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
 =
 


Index: docs/LanguageExtensions.rst
===
--- docs/LanguageExtensions.rst
+++ docs/LanguageExtensions.rst
@@ -436,6 +436,37 @@
 
 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
+`_
+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 artimethic 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 egual to 128 and a
+multiple of 32. Clang supports ``_Float16``.  The difference with ``__fp16`` is
+that arithmetic is performed in half-precision, thus it is not a storage-only
+format. It is recommended that portable code use the ``_Float16`` type.
+
+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
 =
 
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits