forked from OSchip/llvm-project
230 lines
9.1 KiB
HTML
230 lines
9.1 KiB
HTML
<html>
|
|
<head>
|
|
<title>Clang Language Extensions</title>
|
|
<link type="text/css" rel="stylesheet" href="../menu.css" />
|
|
<link type="text/css" rel="stylesheet" href="../content.css" />
|
|
<style type="text/css">
|
|
td {
|
|
vertical-align: top;
|
|
}
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<!--#include virtual="../menu.html.incl"-->
|
|
|
|
<div id="content">
|
|
|
|
<h1>Clang Language Extensions</h1>
|
|
|
|
<ul>
|
|
<li><a href="#intro">Introduction</a></li>
|
|
<li><a href="#vectors">Vectors and Extended Vectors</a></li>
|
|
<li><a href="#blocks">Blocks</a></li>
|
|
<li><a href="#overloading-in-c">Function Overloading in C</a></li>
|
|
<li><a href="#builtins">Builtin Functions</a>
|
|
<ul>
|
|
<li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
<!-- ======================================================================= -->
|
|
<h2 id="intro">Introduction</h2>
|
|
<!-- ======================================================================= -->
|
|
|
|
<p>This document describes the language extensions provided by Clang. In
|
|
addition to the langauge extensions listed here, Clang aims to support a broad
|
|
range of GCC extensions. Please see the <a
|
|
href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
|
|
more information on these extensions.</p>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h2 id="vectors">Vectors and Extended Vectors</h2>
|
|
<!-- ======================================================================= -->
|
|
|
|
<p>Supports the GCC vector extensions, plus some stuff like V[1]. ext_vector
|
|
with V.xyzw syntax and other tidbits. See also <a
|
|
href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h2 id="blocks">Blocks</h2>
|
|
<!-- ======================================================================= -->
|
|
|
|
<p>The syntax and high level language feature description is in <a
|
|
href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
|
|
details for the clang implementation are in <a
|
|
href="BlockImplementation.txt">BlockImplementation.txt</a>.</p>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h2 id="overloading-in-c">Function Overloading in C</h2>
|
|
<!-- ======================================================================= -->
|
|
|
|
<p>Clang provides support for C++ function overloading in C. Function
|
|
overloading in C is introduced using the <tt>overloadable</tt> attribute. For
|
|
example, one might provide several overloaded versions of a <tt>tgsin</tt>
|
|
function that invokes the appropriate standard function computing the sine of a
|
|
value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
|
|
precision:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
#include <math.h>
|
|
float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
|
|
double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
|
|
long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Given these declarations, one can call <tt>tgsin</tt> with a
|
|
<tt>float</tt> value to receive a <tt>float</tt> result, with a
|
|
<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
|
|
overloading in C follows the rules of C++ function overloading to pick
|
|
the best overload given the call arguments, with a few C-specific
|
|
semantics:</p>
|
|
<ul>
|
|
<li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
|
|
double</tt> is ranked as a floating-point promotion (per C99) rather
|
|
than as a floating-point conversion (as in C++).</li>
|
|
|
|
<li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
|
|
<tt>U*</tt> is considered a pointer conversion (with conversion
|
|
rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
|
|
|
|
<li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
|
|
is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
|
|
conversion is given "conversion" rank.</li>
|
|
</ul>
|
|
|
|
<p>The declaration of <tt>overloadable</tt> functions is restricted to
|
|
function declarations and definitions. Most importantly, if any
|
|
function with a given name is given the <tt>overloadable</tt>
|
|
attribute, then all function declarations and definitions with that
|
|
name (and in that scope) must have the <tt>overloadable</tt>
|
|
attribute. This rule even applies to redeclarations of functions whose original
|
|
declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
int f(int) __attribute__((overloadable));
|
|
float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
|
|
|
|
int g(int) __attribute__((overloadable));
|
|
int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Functions marked <tt>overloadable</tt> must have
|
|
prototypes. Therefore, the following code is ill-formed:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>However, <tt>overloadable</tt> functions are allowed to use a
|
|
ellipsis even if there are no named parameters (as is permitted in C++). This feature is particularly useful when combined with the <tt>unavailable</tt> attribute:</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>Functions declared with the <tt>overloadable</tt> attribute have
|
|
their names mangled according to the same rules as C++ function
|
|
names. For example, the three <tt>tgsin</tt> functions in our
|
|
motivating example get the mangled names <tt>_Z5tgsinf</tt>,
|
|
<tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
|
|
caveats to this use of name mangling:</p>
|
|
|
|
<ul>
|
|
|
|
<li>Future versions of Clang may change the name mangling of
|
|
functions overloaded in C, so you should not depend on an specific
|
|
mangling. To be completely safe, we strongly urge the use of
|
|
<tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
|
|
|
|
<li>The <tt>overloadable</tt> attribute has almost no meaning when
|
|
used in C++, because names will already be mangled and functions are
|
|
already overloadable. However, when an <tt>overloadable</tt>
|
|
function occurs within an <tt>extern "C"</tt> linkage specification,
|
|
it's name <i>will</i> be mangled in the same way as it would in
|
|
C.</li>
|
|
</ul>
|
|
|
|
<!-- ======================================================================= -->
|
|
<h2 id="builtins">Builtin Functions</h2>
|
|
<!-- ======================================================================= -->
|
|
|
|
<p>Clang supports a number of builtin library functions with the same syntax as
|
|
GCC, including things like <tt>__builtin_nan</tt>,
|
|
<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
|
|
<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
|
|
addition to the GCC builtins, Clang supports a number of builtins that GCC does
|
|
not, which are listed here.</p>
|
|
|
|
<p>Please note that Clang does not and will not support all of the GCC builtins
|
|
for vector operations. Instead of using builtins, you should use the functions
|
|
defined in target-specific header files like <tt><xmmintrin.h></tt>, which
|
|
define portable wrappers for these. Many of the Clang versions of these
|
|
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_shufflevector">__builtin_shufflevector</h3>
|
|
<!-- ======================================================================= -->
|
|
|
|
<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_shufflevector(vec1, vec2, index1, index2, ...)
|
|
</pre>
|
|
|
|
<p><b>Examples:</b></p>
|
|
|
|
<pre>
|
|
// 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 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>
|
|
</html>
|