intel/llvm
1
0
Fork 0
mirror of https://github.com/intel/llvm.git synced 2026-02-03 10:39:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

document __builtin_shufflevector

Browse Source 
llvm-svn: 64485
This commit is contained in:
Chris Lattner
2009-02-13 20:00:20 +00:00
parent 52d9c49d88
commit 9631dfd1c1
1 changed files with 30 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
clang/docs/LanguageExtensions.html
View File

@@ -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))
// 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>