diff --git a/clang/docs/LanguageExtensions.rst b/clang/docs/LanguageExtensions.rst --- a/clang/docs/LanguageExtensions.rst +++ b/clang/docs/LanguageExtensions.rst @@ -506,6 +506,82 @@ If it's an extension (OpenCL) vector, it's only available in C and OpenCL C. And it selects base on signedness of the condition operands (OpenCL v1.1 s6.3.9). +Vector Builtins +--------------- + +**Note: The implementation of vector builtins is work-in-progress and incomplete.** + +In addition to the operators mentioned above, Clang provides a set of builtins +to perform additional operations on certain scalar and vector types. + +Let ``T`` be one of the following types: + +* an integer type (as in C2x 6.2.5p19), but excluding enumerated types and _Bool +* the standard floating types float or double +* a half-precision floating point type, if one is supported on the target +* a vector type. + +For scalar types, consider the operation applied to a vector with a single element. + +*Elementwise Builtins* + +Each builtin returns a vector equivalent to applying the specified operation +elementwise to the input. + +Unless specified otherwise operation(±0) = ±0 and operation(±infinity) = ±infinity + +========================================= ================================================================ ========================================= + Name Operation Supported element types +========================================= ================================================================ ========================================= + T __builtin_elementwise_abs(T x) return the absolute value of a number x signed integer and floating point types + T __builtin_elementwise_ceil(T x) return the smallest integral value greater than or equal to x floating point types + T __builtin_elementwise_floor(T x) return the largest integral value less than or equal to x floating point types + T __builtin_elementwise_roundeven(T x) round x to the nearest integer value in floating point format, floating point types + rounding halfway cases to even (that is, to the nearest value + that is an even integer), regardless of the current rounding + direction. + T__builtin_elementwise_trunc(T x) return the integral value nearest to but no larger in floating point types + magnitude than x + T __builtin_elementwise_max(T x, T y) return x or y, whichever is larger integer and floating point types + T __builtin_elementwise_min(T x, T y) return x or y, whichever is smaller integer and floating point types +========================================= ================================================================ ========================================= + + +*Reduction Builtins* + +Each builtin returns a scalar equivalent to applying the specified +operation(x, y) as recursive even-odd pairwise reduction to all vector +elements. ``operation(x, y)`` is repeatedly applied to each non-overlapping +even-odd element pair with indices ``i * 2`` and ``i * 2 + 1`` with +``i in [0, Number of elements / 2)``. If the numbers of elements is not a +power of 2, the vector is widened with neutral elements for the reduction +at the end to the next power of 2. + +Example: + +.. code-block:: c++ + + __builtin_reduce_fadd([e3, e2, e1, e0]) = __builtin_reduced_fadd([e3 + e2, e1 + e0]) + = (e3 + e2) + (e1 + e0) + + +Let ``VT`` be a vector type and ``ET`` the element type of ``VT``. + +======================================= ================================================================ ================================== + Name Operation Supported element types +======================================= ================================================================ ================================== + ET __builtin_reduce_max(VT a) return x or y, whichever is larger; If exactly one argument is integer and floating point types + a NaN, return the other argument. If both arguments are NaNs, + fmax() return a NaN. + ET __builtin_reduce_min(VT a) return x or y, whichever is smaller; If exactly one argument integer and floating point types + is a NaN, return the other argument. If both arguments are + NaNs, fmax() return a NaN. + ET __builtin_reduce_add(VT a) \+ integer and floating point types + ET __builtin_reduce_and(VT a) & integer types + ET __builtin_reduce_or(VT a) \| integer types + ET __builtin_reduce_xor(VT a) ^ integer types +======================================= ================================================================ ================================== + Matrix Types ============