[RFC][doc] Document that RISC-V's __fp16 has different behavior

[kito-cheng]

Summary

RISC-V has a draft extension for half-precision proposed last year[1],
so we think adding a new type for that would be great to make this
easier to use that extension.

We found there is _Float16 and __fp16 types are supported on GCC and
Clang, but _Float16 has C++ supporting issue on GCC site, so we think
support both type is a reasonable choice to us.

However we would like have slight different behavior for __fp16 other
than ACLE: The evaluation format of __fp16 set same as _Float16,
which means no promotion are performed if there is no hardware half-precision
supported.

The only concern to us is it's defined differnt with clang's document,
so we would put this RFC patch here, to make sure it's OK for make
__fp16 has differnt behavior between differnt targets.

This patch contain document change only, implementation would be in
another patches.

[1] https://github.com/riscv/riscv-isa-manual/pull/496
[2] https://github.com/riscv/riscv-elf-psabi-doc/pull/172

Co-authored-by: Evandro Menezes <[e-mail]>

[SjoerdMeijer]

However we would like have slight different behavior for fp16 other than ACLE: The evaluation format of fp16 set same as _Float16, which means no promotion are performed if there is no hardware half-precision supported.

Well, this is really problematic, because you're giving __fp16 a different semantics, you're defining it to behave as _Float16.
Redefining an existing type, let it differentiate from other targets can never be a good thing.
I don't see how this is going to help anyone.

[kito-cheng]

RISC-V using _Float16 as official half-precision type.

clang/docs/LanguageExtensions.rst

 ``__fp16`` is supported on every target, as it is purely a storage format; see below.
 ``_Float16`` is currently only supported on the following targets, with further
 targets pending ABI standardization:
 
 * 32-bit ARM
 * 64-bit ARM (AArch64)
 * AMDGPU
 * SPIR
+* RISC-V
 
 ``_Float16`` will be supported on more targets as they define ABIs for it.
 
 ``__bf16`` is purely a storage format; it is currently only supported on the following targets:
 * 32-bit ARM
 * 64-bit ARM (AArch64)
 
 The ``__bf16`` type is only available when supported in hardware.
 
-``__fp16`` is a storage and interchange format only.  This means that values of
+``__fp16`` is a storage and interchange format only on most targets.  This means that values of
 ``__fp16`` are immediately promoted to (at least) ``float`` when used in arithmetic
 operations, so that e.g. the result of adding two ``__fp16`` values has type ``float``.
 The behavior of ``__fp16`` is specified by the ARM C Language Extensions (`ACLE <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053d/IHI0053D_acle_2_1.pdf>`_).
 Clang uses the ``binary16`` format from IEEE 754-2008 for ``__fp16``, not the ARM
 alternative format.
 
+On RISC-V, the evaluation format of ``__fp16`` will depend on the presence of
+the ``Zfh``  (half-precision) extension. ``__fp16`` will perform arithmetic
+without promotion when the Zfh extension is enabled, and promoted to float
+otherwise.
+
 ``_Float16`` is an interchange floating-point type.  This means that, just like arithmetic on
 ``float`` or ``double``, arithmetic on ``_Float16`` operands is formally performed in the
 ``_Float16`` type, so that e.g. the result of adding two ``_Float16`` values has type
 ``_Float16``.  The behavior of ``_Float16`` is specified by ISO/IEC TS 18661-3:2015
 ("Floating-point extensions for C").  As with ``__fp16``, Clang uses the ``binary16``
 format from IEEE 754-2008 for ``_Float16``.
 
 ``_Float16`` arithmetic will be performed using native half-precision support