Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / e2f6aa7ddbeade48c0e6dc554dbbe4e3374388d7 / . / docs / LanguageExtensions.html
blob: d73e3026b1f8e5f9a0f73cc6576b12e76b683eb8 [file] [log] [blame]
Chris Lattnerc4808bd2009-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 Gregor68b502a2009-02-13 00:57:04 +0000[diff] [blame]24<li><a href="#overloading-in-c">Function Overloading in C</a></li>
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]25<li><a href="#builtins">Builtin Functions</a>
26 <ul>
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]27 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
28 </ul>
29</li>
Chris Lattnere2f6aa72009-04-09 19:58:15 +0000[diff] [blame^]30<li><a href="#targetspecific">Target-Specific Extensions</a>
31 <ul>
32 <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
33 </ul>
34</li>
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]35</ul>
36
37
38<!-- ======================================================================= -->
39<h2 id="intro">Introduction</h2>
40<!-- ======================================================================= -->
41
42<p>This document describes the language extensions provided by Clang. In
43addition to the langauge extensions listed here, Clang aims to support a broad
44range of GCC extensions. Please see the <a
45href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
46more information on these extensions.</p>
47
48<!-- ======================================================================= -->
49<h2 id="vectors">Vectors and Extended Vectors</h2>
50<!-- ======================================================================= -->
51
52<p>Supports the GCC vector extensions, plus some stuff like V[1]. ext_vector
53with V.xyzw syntax and other tidbits. See also <a
54href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
55
56<!-- ======================================================================= -->
57<h2 id="blocks">Blocks</h2>
58<!-- ======================================================================= -->
59
Chris Lattner92bcf852009-03-09 07:03:22 +0000[diff] [blame]60<p>The syntax and high level language feature description is in <a
61href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
62details for the clang implementation are in <a
63href="BlockImplementation.txt">BlockImplementation.txt</a>.</p>
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]64
65<!-- ======================================================================= -->
Douglas Gregor68b502a2009-02-13 00:57:04 +0000[diff] [blame]66<h2 id="overloading-in-c">Function Overloading in C</h2>
67<!-- ======================================================================= -->
68
Chris Lattner6c6c34f2009-02-13 21:51:45 +0000[diff] [blame]69<p>Clang provides support for C++ function overloading in C. Function
70overloading in C is introduced using the <tt>overloadable</tt> attribute. For
71example, one might provide several overloaded versions of a <tt>tgsin</tt>
72function that invokes the appropriate standard function computing the sine of a
73value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
74precision:</p>
Douglas Gregor68b502a2009-02-13 00:57:04 +0000[diff] [blame]75
76<blockquote>
77<pre>
78#include &lt;math.h&gt;
79float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
80double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
81long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
82</pre>
83</blockquote>
84
85<p>Given these declarations, one can call <tt>tgsin</tt> with a
86<tt>float</tt> value to receive a <tt>float</tt> result, with a
87<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
88overloading in C follows the rules of C++ function overloading to pick
89the best overload given the call arguments, with a few C-specific
90semantics:</p>
91<ul>
92 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
93 double</tt> is ranked as a floating-point promotion (per C99) rather
94 than as a floating-point conversion (as in C++).</li>
95
96 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
97 <tt>U*</tt> is considered a pointer conversion (with conversion
98 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
99
100 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
101 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
102 conversion is given "conversion" rank.</li>
103</ul>
104
105<p>The declaration of <tt>overloadable</tt> functions is restricted to
106function declarations and definitions. Most importantly, if any
107function with a given name is given the <tt>overloadable</tt>
108attribute, then all function declarations and definitions with that
109name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattner6c6c34f2009-02-13 21:51:45 +0000[diff] [blame]110attribute. This rule even applies to redeclarations of functions whose original
111declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregor68b502a2009-02-13 00:57:04 +0000[diff] [blame]112
113<blockquote>
114<pre>
115int f(int) __attribute__((overloadable));
116float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
117
118int g(int) __attribute__((overloadable));
119int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
120</pre>
121</blockquote>
122
Douglas Gregor88a25f82009-02-18 07:07:28 +0000[diff] [blame]123<p>Functions marked <tt>overloadable</tt> must have
124prototypes. Therefore, the following code is ill-formed:</p>
125
126<blockquote>
127<pre>
128int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
129</pre>
130</blockquote>
131
132<p>However, <tt>overloadable</tt> functions are allowed to use a
133ellipsis 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>
134
135<blockquote>
136<pre>
Chris Lattner00c3f432009-02-18 22:27:46 +0000[diff] [blame]137void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor88a25f82009-02-18 07:07:28 +0000[diff] [blame]138</pre>
139</blockquote>
140
Douglas Gregor68b502a2009-02-13 00:57:04 +0000[diff] [blame]141<p>Functions declared with the <tt>overloadable</tt> attribute have
142their names mangled according to the same rules as C++ function
143names. For example, the three <tt>tgsin</tt> functions in our
144motivating example get the mangled names <tt>_Z5tgsinf</tt>,
145<tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
146caveats to this use of name mangling:</p>
147
148<ul>
149
150 <li>Future versions of Clang may change the name mangling of
151 functions overloaded in C, so you should not depend on an specific
152 mangling. To be completely safe, we strongly urge the use of
153 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
154
155 <li>The <tt>overloadable</tt> attribute has almost no meaning when
156 used in C++, because names will already be mangled and functions are
157 already overloadable. However, when an <tt>overloadable</tt>
158 function occurs within an <tt>extern "C"</tt> linkage specification,
159 it's name <i>will</i> be mangled in the same way as it would in
160 C.</li>
161</ul>
162
163<!-- ======================================================================= -->
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]164<h2 id="builtins">Builtin Functions</h2>
165<!-- ======================================================================= -->
166
167<p>Clang supports a number of builtin library functions with the same syntax as
168GCC, including things like <tt>__builtin_nan</tt>,
169<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
170<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
171addition to the GCC builtins, Clang supports a number of builtins that GCC does
172not, which are listed here.</p>
173
174<p>Please note that Clang does not and will not support all of the GCC builtins
175for vector operations. Instead of using builtins, you should use the functions
176defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
177define portable wrappers for these. Many of the Clang versions of these
178functions are implemented directly in terms of <a href="#vectors">extended
179vector support</a> instead of builtins, in order to reduce the number of
180builtins that we need to implement.</p>
181
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]182<!-- ======================================================================= -->
Chris Lattner1ffbcdc2009-02-13 20:00:20 +0000[diff] [blame]183<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]184<!-- ======================================================================= -->
185
Chris Lattner1ffbcdc2009-02-13 20:00:20 +0000[diff] [blame]186<p><tt>__builtin_shufflevector</tt> is used to expression generic vector
187permutation/shuffle/swizzle operations. This builtin is also very important for
188the implementation of various target-specific header files like
189<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]190</p>
191
192<p><b>Syntax:</b></p>
193
194<pre>
Chris Lattner1ffbcdc2009-02-13 20:00:20 +0000[diff] [blame]195__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]196</pre>
197
198<p><b>Examples:</b></p>
199
200<pre>
Chris Lattner1ffbcdc2009-02-13 20:00:20 +0000[diff] [blame]201 // Identity operation - return 4-element vector V1.
202 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
203
204 // "Splat" element 0 of V1 into a 4-element result.
205 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
206
207 // Reverse 4-element vector V1.
208 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
209
210 // Concatenate every other element of 4-element vectors V1 and V2.
211 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
212
213 // Concatenate every other element of 8-element vectors V1 and V2.
214 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]215</pre>
216
217<p><b>Description:</b></p>
218
Chris Lattner1ffbcdc2009-02-13 20:00:20 +0000[diff] [blame]219<p>The first two arguments to __builtin_shufflevector are vectors that have the
220same element type. The remaining arguments are a list of integers that specify
221the elements indices of the first two vectors that should be extracted and
222returned in a new vector. These element indices are numbered sequentially
223starting with the first vector, continuing into the second vector. Thus, if
224vec1 is a 4-element vector, index 5 would refer to the second element of vec2.
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]225</p>
226
Chris Lattner1ffbcdc2009-02-13 20:00:20 +0000[diff] [blame]227<p>The result of __builtin_shufflevector is a vector
228with the same element type as vec1/vec2 but that has an element count equal to
229the number of indices specified.
230</p>
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]231
Chris Lattnere2f6aa72009-04-09 19:58:15 +0000[diff] [blame^]232<!-- ======================================================================= -->
233<h2 id="targetspecific">Target-Specific Extensions</h2>
234<!-- ======================================================================= -->
235
236<p>Clang supports some language features conditionally on some targets.</p>
237
238<!-- ======================================================================= -->
239<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
240<!-- ======================================================================= -->
241
242<p>The X86 backend has these language extensions:</p>
243
244<!-- ======================================================================= -->
245<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
246<!-- ======================================================================= -->
247
248<p>Annotating a pointer with address space #256 causes it to be code generated
249relative to the X86 GS segment register.
250Note that this is a very very low-level feature that should only be used if you
251know what you're doing (for example in an OS kernel).</p>
252
253<p>Here is an example:</p>
254
255<pre>
256#define GS_RELATIVE __attribute__((address_space(256)))
257int foo(int GS_RELATIVE *P) {
258 return *P;
259}
260</pre>
261
262<p>Which compiles to (on X86-32):</p>
263
264<pre>
265_foo:
266 movl 4(%esp), %eax
267 movl %gs:(%eax), %eax
268 ret
269</pre>
270
Chris Lattnerc4808bd2009-02-09 08:46:11 +0000[diff] [blame]271</div>
272</body>
273</html>