diff options
Diffstat (limited to 'docs/LanguageExtensions.rst')
-rw-r--r-- | docs/LanguageExtensions.rst | 80 |
1 files changed, 79 insertions, 1 deletions
diff --git a/docs/LanguageExtensions.rst b/docs/LanguageExtensions.rst index 78f987c4a8e8..9b407f31d973 100644 --- a/docs/LanguageExtensions.rst +++ b/docs/LanguageExtensions.rst @@ -139,6 +139,35 @@ and following ``__`` (double underscore) to avoid interference from a macro with the same name. For instance, ``gnu::__const__`` can be used instead of ``gnu::const``. +``__has_c_attribute`` +--------------------- + +This function-like macro takes a single argument that is the name of an +attribute exposed with the double square-bracket syntax in C mode. The argument +can either be a single identifier or a scoped identifier. If the attribute is +supported, a nonzero value is returned. If the attribute is not supported by the +current compilation target, this macro evaluates to 0. It can be used like this: + +.. code-block:: c + + #ifndef __has_c_attribute // Optional of course. + #define __has_c_attribute(x) 0 // Compatibility with non-clang compilers. + #endif + + ... + #if __has_c_attribute(fallthrough) + #define FALLTHROUGH [[fallthrough]] + #else + #define FALLTHROUGH + #endif + ... + +The attribute identifier (but not scope) can also be specified with a preceding +and following ``__`` (double underscore) to avoid interference from a macro with +the same name. For instance, ``gnu::__const__`` can be used instead of +``gnu::const``. + + ``__has_attribute`` ------------------- @@ -436,6 +465,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 ========================================================= @@ -1929,7 +2001,13 @@ provided, with values corresponding to the enumerators of C11's ``memory_order`` enumeration. (Note that Clang additionally provides GCC-compatible ``__atomic_*`` -builtins) +builtins and OpenCL 2.0 ``__opencl_atomic_*`` builtins. The OpenCL 2.0 +atomic builtins are an explicit form of the corresponding OpenCL 2.0 +builtin function, and are named with a ``__opencl_`` prefix. The macros +``__OPENCL_MEMORY_SCOPE_WORK_ITEM``, ``__OPENCL_MEMORY_SCOPE_WORK_GROUP``, +``__OPENCL_MEMORY_SCOPE_DEVICE``, ``__OPENCL_MEMORY_SCOPE_ALL_SVM_DEVICES``, +and ``__OPENCL_MEMORY_SCOPE_SUB_GROUP`` are provided, with values +corresponding to the enumerators of OpenCL's ``memory_scope`` enumeration.) Low-level ARM exclusive memory builtins --------------------------------------- |