Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / f161d4155f51328da08d4a28233d5ca9ce5b998a / . / docs / LanguageExtensions.html
blob: dfffd2f5d68b9cd550a250791d9bd4892ecd540b [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
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame^]61<p>Clang provides support for C++ function overloading in C. Function
62overloading in C is introduced using the <tt>overloadable</tt> attribute. For
63example, one might provide several overloaded versions of a <tt>tgsin</tt>
64function that invokes the appropriate standard function computing the sine of a
65value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
66precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]67
68<blockquote>
69<pre>
70#include &lt;math.h&gt;
71float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
72double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
73long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
74</pre>
75</blockquote>
76
77<p>Given these declarations, one can call <tt>tgsin</tt> with a
78<tt>float</tt> value to receive a <tt>float</tt> result, with a
79<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
80overloading in C follows the rules of C++ function overloading to pick
81the best overload given the call arguments, with a few C-specific
82semantics:</p>
83<ul>
84 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
85 double</tt> is ranked as a floating-point promotion (per C99) rather
86 than as a floating-point conversion (as in C++).</li>
87
88 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
89 <tt>U*</tt> is considered a pointer conversion (with conversion
90 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
91
92 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
93 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
94 conversion is given "conversion" rank.</li>
95</ul>
96
97<p>The declaration of <tt>overloadable</tt> functions is restricted to
98function declarations and definitions. Most importantly, if any
99function with a given name is given the <tt>overloadable</tt>
100attribute, then all function declarations and definitions with that
101name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame^]102attribute. This rule even applies to redeclarations of functions whose original
103declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]104
105<blockquote>
106<pre>
107int f(int) __attribute__((overloadable));
108float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
109
110int g(int) __attribute__((overloadable));
111int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
112</pre>
113</blockquote>
114
115<p>Functions declared with the <tt>overloadable</tt> attribute have
116their names mangled according to the same rules as C++ function
117names. For example, the three <tt>tgsin</tt> functions in our
118motivating example get the mangled names <tt>_Z5tgsinf</tt>,
119<tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
120caveats to this use of name mangling:</p>
121
122<ul>
123
124 <li>Future versions of Clang may change the name mangling of
125 functions overloaded in C, so you should not depend on an specific
126 mangling. To be completely safe, we strongly urge the use of
127 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
128
129 <li>The <tt>overloadable</tt> attribute has almost no meaning when
130 used in C++, because names will already be mangled and functions are
131 already overloadable. However, when an <tt>overloadable</tt>
132 function occurs within an <tt>extern "C"</tt> linkage specification,
133 it's name <i>will</i> be mangled in the same way as it would in
134 C.</li>
135</ul>
136
137<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]138<h2 id="builtins">Builtin Functions</h2>
139<!-- ======================================================================= -->
140
141<p>Clang supports a number of builtin library functions with the same syntax as
142GCC, including things like <tt>__builtin_nan</tt>,
143<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
144<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
145addition to the GCC builtins, Clang supports a number of builtins that GCC does
146not, which are listed here.</p>
147
148<p>Please note that Clang does not and will not support all of the GCC builtins
149for vector operations. Instead of using builtins, you should use the functions
150defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
151define portable wrappers for these. Many of the Clang versions of these
152functions are implemented directly in terms of <a href="#vectors">extended
153vector support</a> instead of builtins, in order to reduce the number of
154builtins that we need to implement.</p>
155
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]156<!-- ======================================================================= -->
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]157<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]158<!-- ======================================================================= -->
159
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]160<p><tt>__builtin_shufflevector</tt> is used to expression generic vector
161permutation/shuffle/swizzle operations. This builtin is also very important for
162the implementation of various target-specific header files like
163<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]164</p>
165
166<p><b>Syntax:</b></p>
167
168<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]169__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]170</pre>
171
172<p><b>Examples:</b></p>
173
174<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]175 // Identity operation - return 4-element vector V1.
176 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
177
178 // "Splat" element 0 of V1 into a 4-element result.
179 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
180
181 // Reverse 4-element vector V1.
182 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
183
184 // Concatenate every other element of 4-element vectors V1 and V2.
185 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
186
187 // Concatenate every other element of 8-element vectors V1 and V2.
188 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]189</pre>
190
191<p><b>Description:</b></p>
192
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]193<p>The first two arguments to __builtin_shufflevector are vectors that have the
194same element type. The remaining arguments are a list of integers that specify
195the elements indices of the first two vectors that should be extracted and
196returned in a new vector. These element indices are numbered sequentially
197starting with the first vector, continuing into the second vector. Thus, if
198vec1 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]199</p>
200
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]201<p>The result of __builtin_shufflevector is a vector
202with the same element type as vec1/vec2 but that has an element count equal to
203the number of indices specified.
204</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]205
206</div>
207</body>
208</html>