From 9631dfd1c19b6b0ee53cf256aef68e9002b65f93 Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Fri, 13 Feb 2009 20:00:20 +0000 Subject: [PATCH] document __builtin_shufflevector llvm-svn: 64485 --- clang/docs/LanguageExtensions.html | 81 +++++++++++------------------- 1 file changed, 30 insertions(+), 51 deletions(-) diff --git a/clang/docs/LanguageExtensions.html b/clang/docs/LanguageExtensions.html index e9f409ace9cd..1a8ff953adf9 100644 --- a/clang/docs/LanguageExtensions.html +++ b/clang/docs/LanguageExtensions.html @@ -24,7 +24,6 @@ td {
  • Function Overloading in C
  • Builtin Functions
    • @@ -148,75 +147,55 @@ functions are implemented directly in terms of extended vector support instead of builtins, in order to reduce the number of builtins that we need to implement.

    - -

    __builtin_overload

    +

    __builtin_shufflevector

    -

    __builtin_overload is used to implement type-generic "overloaded" -functions in C. This builtin is used to implement the <tgmath.h> -header file, but is intended to be usable for a broad variety of other similar -situations, like the <altivec.h> header. -In the future, we intend to eliminate __builtin_overload in favor of function overloading in C, which provides a better solution for type-generic "overloaded" functions. +

    __builtin_shufflevector is used to expression generic vector +permutation/shuffle/swizzle operations. This builtin is also very important for +the implementation of various target-specific header files like +<xmmintrin.h>.

    Syntax:

    -__builtin_overload(FnNameStr, PromotionRuleStr, NumArgs, arg1, arg2, ...
-                   overloadcandidate1, overloadcandidate2, ...)
+__builtin_shufflevector(vec1, vec2, index1, index2, ...)

    Examples:

    -#define sin(x) \
-  (__builtin_overload("sin", "tgmath", 1, x, sinf, sin, sinl,
-                      csinf, csin, csinl)(x))
-#define fma(x,y,z) \
-  (__builtin_overload("fma", "tgmath", 3, x, y, z, fmaf, fma, fmal)(x,y,z))
-#define ldexp(x, y) \
-  (__builtin_overload("ldexp", "tgmath1", 2, x, 0, ldexpf, ldexp, ldexpl)(x,y))
+  // Identity operation - return 4-element vector V1.
+  __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
+
+  // "Splat" element 0 of V1 into a 4-element result.
+  __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
+
+  // Reverse 4-element vector V1.
+  __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
+
+  // Concatenate every other element of 4-element vectors V1 and V2.
+  __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
+
+  // Concatenate every other element of 8-element vectors V1 and V2.
+  __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)

    Description:

    -

    The first argument to __builtin_overload is a string that is the name of the -"function" being implemented. This is used to produce diagnostics that make -sense to the user. For example, if you accidentally pass a pointer argument to -"sin" in GCC, it emits 6 errors about incompatible types. This name allows -Clang to diagnose the error in a way the user can understand. +

    The first two arguments to __builtin_shufflevector are vectors that have the +same element type. The remaining arguments are a list of integers that specify +the elements indices of the first two vectors that should be extracted and +returned in a new vector. These element indices are numbered sequentially +starting with the first vector, continuing into the second vector. Thus, if +vec1 is a 4-element vector, index 5 would refer to the second element of vec2.

    -

    The second argument is a string that indicates a set of promotion rules to -apply to the arguments before prototype matching occurs. The currently -supported rules are:

    - -
    -
    tgmath
    -
    Follow the rules of C99 7.22 to determine a single common type, and use it - for every argument.
    -
    tgmath1
    -
    Follow the rules of C99 7.22 to determine a single common type of just the - first argument (e.g. treat ints as doubles).
    -
    - -

    The third argument is an integer that specifies the arity of the function - being overloaded. After this are N expression arguments which are promoted - according to the rules specified by the promotion rule string.

    - -

    The final arguments are functions or function pointers with different - signatures. __builtin_overload will match and evaluate to the first function - pointer whose signature is compatible and does not cause value truncation of - any arguments to the function.

    - - - -

    __builtin_shufflevector

    - - -

    todo describe me.

    - +

    The result of __builtin_shufflevector is a vector +with the same element type as vec1/vec2 but that has an element count equal to +the number of indices specified. +