document __builtin_shufflevector

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@64485 91177308-0d34-0410-b5e6-96231b3b80d8

docs/LanguageExtensions.html

@@ -24,7 +24,6 @@ td {
 <li><a href="#overloading-in-c">Function Overloading in C</a></li>
 <li><a href="#builtins">Builtin Functions</a>
   <ul>
-  <li><a href="#__builtin_overload">__builtin_overload</a></li>
   <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
   </ul>
 </li>
@@ -148,75 +147,55 @@ functions are implemented directly in terms of <a href="#vectors">extended
 vector support</a> instead of builtins, in order to reduce the number of
 builtins that we need to implement.</p>
 
-
 <!-- ======================================================================= -->
-<h3 id="__builtin_overload">__builtin_overload</h3>
+<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
 <!-- ======================================================================= -->
 
-<p><tt>__builtin_overload</tt> is used to implement type-generic "overloaded"
-functions in C.  This builtin is used to implement the <tt>&lt;tgmath.h&gt;</tt>
-header file, but is intended to be usable for a broad variety of other similar
-situations, like the <tt>&lt;altivec.h&gt;</tt> header.
-<b>In the future, we intend to eliminate <tt>__builtin_overload</tt> in favor of <a href="#overloading-in-c">function overloading in C</a>, which provides a better solution for type-generic "overloaded" functions.</b>
+<p><tt>__builtin_shufflevector</tt> 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
+<tt>&lt;xmmintrin.h&gt;</tt>.
 </p>
 
 <p><b>Syntax:</b></p>
 
 <pre>
-__builtin_overload(FnNameStr, PromotionRuleStr, NumArgs, arg1, arg2, ...
-                   overloadcandidate1, overloadcandidate2, ...)
+__builtin_shufflevector(vec1, vec2, index1, index2, ...)
 </pre>
 
 <p><b>Examples:</b></p>
 
 <pre>
-#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))
-</pre>
+  // Identity operation - return 4-element vector V1.
+  __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
 
-<p><b>Description:</b></p>
+  // "Splat" element 0 of V1 into a 4-element result.
+  __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
 
-<p>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.
-</p>
+  // Reverse 4-element vector V1.
+  __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
 
-<p>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:</p>
-
-<dl>
-  <dt>tgmath</dt>
-  <dd>Follow the rules of C99 7.22 to determine a single common type, and use it
-      for every argument.</dd>
-  <dt>tgmath1</dt>
-  <dd>Follow the rules of C99 7.22 to determine a single common type of just the
-      first argument (e.g. treat ints as doubles).</dd>
-</dl>
-
-<p>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.</p>
-   
-<p>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.</p>
+  // 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)
+</pre>
 
-<!-- ======================================================================= -->
-<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
-<!-- ======================================================================= -->
+<p><b>Description:</b></p>
 
-<p>todo describe me.</p>
+<p>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.
+</p>
 
+<p>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.
+</p>
 
 </div>
 </body>