document __builtin_shufflevector
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@64485 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html
index e9f409a..1a8ff95 100644
--- a/docs/LanguageExtensions.html
+++ b/docs/LanguageExtensions.html
@@ -24,7 +24,6 @@
<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 @@
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><tgmath.h></tt>
-header file, but is intended to be usable for a broad variety of other similar
-situations, like the <tt><altivec.h></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><xmmintrin.h></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))
+ // 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)
</pre>
<p><b>Description:</b></p>
-<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>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 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>
-
-
-<!-- ======================================================================= -->
-<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
-<!-- ======================================================================= -->
-
-<p>todo describe me.</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>