Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 73241dfeb5c498255b662984cca369fd28ec3147 / . / docs / LanguageExtensions.html
blob: 1a8ff953adf907cc33483f2d56aec297a23b99a9 [file] [log] [blame]
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1<html>
2<head>
3<title>Clang Language Extensions</title>
4<link type="text/css" rel="stylesheet" href="../menu.css" />
5<link type="text/css" rel="stylesheet" href="../content.css" />
6<style type="text/css">
7td {
8 vertical-align: top;
9}
10</style>
11</head>
12<body>
13
14<!--#include virtual="../menu.html.incl"-->
15
16<div id="content">
17
18<h1>Clang Language Extensions</h1>
19
20<ul>
21<li><a href="#intro">Introduction</a></li>
22<li><a href="#vectors">Vectors and Extended Vectors</a></li>
23<li><a href="#blocks">Blocks</a></li>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]24<li><a href="#overloading-in-c">Function Overloading in C</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]25<li><a href="#builtins">Builtin Functions</a>
26 <ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]27 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
28 </ul>
29</li>
30</ul>
31
32
33<!-- ======================================================================= -->
34<h2 id="intro">Introduction</h2>
35<!-- ======================================================================= -->
36
37<p>This document describes the language extensions provided by Clang. In
38addition to the langauge extensions listed here, Clang aims to support a broad
39range of GCC extensions. Please see the <a
40href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
41more information on these extensions.</p>
42
43<!-- ======================================================================= -->
44<h2 id="vectors">Vectors and Extended Vectors</h2>
45<!-- ======================================================================= -->
46
47<p>Supports the GCC vector extensions, plus some stuff like V[1]. ext_vector
48with V.xyzw syntax and other tidbits. See also <a
49href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
50
51<!-- ======================================================================= -->
52<h2 id="blocks">Blocks</h2>
53<!-- ======================================================================= -->
54
55<p>The idea, syntax, and semantics.</p>
56
57<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]58<h2 id="overloading-in-c">Function Overloading in C</h2>
59<!-- ======================================================================= -->
60
61<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>
62
63<blockquote>
64<pre>
65#include &lt;math.h&gt;
66float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
67double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
68long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
69</pre>
70</blockquote>
71
72<p>Given these declarations, one can call <tt>tgsin</tt> with a
73<tt>float</tt> value to receive a <tt>float</tt> result, with a
74<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
75overloading in C follows the rules of C++ function overloading to pick
76the best overload given the call arguments, with a few C-specific
77semantics:</p>
78<ul>
79 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
80 double</tt> is ranked as a floating-point promotion (per C99) rather
81 than as a floating-point conversion (as in C++).</li>
82
83 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
84 <tt>U*</tt> is considered a pointer conversion (with conversion
85 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
86
87 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
88 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
89 conversion is given "conversion" rank.</li>
90</ul>
91
92<p>The declaration of <tt>overloadable</tt> functions is restricted to
93function declarations and definitions. Most importantly, if any
94function with a given name is given the <tt>overloadable</tt>
95attribute, then all function declarations and definitions with that
96name (and in that scope) must have the <tt>overloadable</tt>
97attribute. This rule even applies to redeclarations of functions whose original declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
98
99<blockquote>
100<pre>
101int f(int) __attribute__((overloadable));
102float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
103
104int g(int) __attribute__((overloadable));
105int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
106</pre>
107</blockquote>
108
109<p>Functions declared with the <tt>overloadable</tt> attribute have
110their names mangled according to the same rules as C++ function
111names. For example, the three <tt>tgsin</tt> functions in our
112motivating example get the mangled names <tt>_Z5tgsinf</tt>,
113<tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
114caveats to this use of name mangling:</p>
115
116<ul>
117
118 <li>Future versions of Clang may change the name mangling of
119 functions overloaded in C, so you should not depend on an specific
120 mangling. To be completely safe, we strongly urge the use of
121 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
122
123 <li>The <tt>overloadable</tt> attribute has almost no meaning when
124 used in C++, because names will already be mangled and functions are
125 already overloadable. However, when an <tt>overloadable</tt>
126 function occurs within an <tt>extern "C"</tt> linkage specification,
127 it's name <i>will</i> be mangled in the same way as it would in
128 C.</li>
129</ul>
130
131<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]132<h2 id="builtins">Builtin Functions</h2>
133<!-- ======================================================================= -->
134
135<p>Clang supports a number of builtin library functions with the same syntax as
136GCC, including things like <tt>__builtin_nan</tt>,
137<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
138<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
139addition to the GCC builtins, Clang supports a number of builtins that GCC does
140not, which are listed here.</p>
141
142<p>Please note that Clang does not and will not support all of the GCC builtins
143for vector operations. Instead of using builtins, you should use the functions
144defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
145define portable wrappers for these. Many of the Clang versions of these
146functions are implemented directly in terms of <a href="#vectors">extended
147vector support</a> instead of builtins, in order to reduce the number of
148builtins that we need to implement.</p>
149
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]150<!-- ======================================================================= -->
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]151<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]152<!-- ======================================================================= -->
153
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]154<p><tt>__builtin_shufflevector</tt> is used to expression generic vector
155permutation/shuffle/swizzle operations. This builtin is also very important for
156the implementation of various target-specific header files like
157<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]158</p>
159
160<p><b>Syntax:</b></p>
161
162<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]163__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]164</pre>
165
166<p><b>Examples:</b></p>
167
168<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]169 // Identity operation - return 4-element vector V1.
170 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
171
172 // "Splat" element 0 of V1 into a 4-element result.
173 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
174
175 // Reverse 4-element vector V1.
176 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
177
178 // Concatenate every other element of 4-element vectors V1 and V2.
179 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
180
181 // Concatenate every other element of 8-element vectors V1 and V2.
182 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]183</pre>
184
185<p><b>Description:</b></p>
186
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]187<p>The first two arguments to __builtin_shufflevector are vectors that have the
188same element type. The remaining arguments are a list of integers that specify
189the elements indices of the first two vectors that should be extracted and
190returned in a new vector. These element indices are numbered sequentially
191starting with the first vector, continuing into the second vector. Thus, if
192vec1 is a 4-element vector, index 5 would refer to the second element of vec2.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]193</p>
194
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]195<p>The result of __builtin_shufflevector is a vector
196with the same element type as vec1/vec2 but that has an element count equal to
197the number of indices specified.
198</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]199
200</div>
201</body>
202</html>