diff options
| author | ed <ed@FreeBSD.org> | 2009-06-02 17:58:47 +0000 |
|---|---|---|
| committer | ed <ed@FreeBSD.org> | 2009-06-02 17:58:47 +0000 |
| commit | f27e5a09a0d815b8a4814152954ff87dadfdefc0 (patch) | |
| tree | ce7d964cbb5e39695b71481698f10cb099c23d4a /docs/LanguageExtensions.html | |
| download | FreeBSD-src-f27e5a09a0d815b8a4814152954ff87dadfdefc0.zip FreeBSD-src-f27e5a09a0d815b8a4814152954ff87dadfdefc0.tar.gz | |
Import Clang, at r72732.
Diffstat (limited to 'docs/LanguageExtensions.html')
| -rw-r--r-- | docs/LanguageExtensions.html | 327 |
1 files changed, 327 insertions, 0 deletions
diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html new file mode 100644 index 0000000..c486562 --- /dev/null +++ b/docs/LanguageExtensions.html @@ -0,0 +1,327 @@ +<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="#builtinmacros">Builtin Macros</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> +<li><a href="#targetspecific">Target-Specific Extensions</a> + <ul> + <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li> + </ul> +</li> +<li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a> + <ul> + <li><a href="#analyzerattributes">Analyzer Attributes</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="builtinmacros">Builtin Macros</h2> +<!-- ======================================================================= --> + +<p>__BASE_FILE__, __INCLUDE_LEVEL__, __TIMESTAMP__, __COUNTER__</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> + +<!-- ======================================================================= --> +<h2 id="targetspecific">Target-Specific Extensions</h2> +<!-- ======================================================================= --> + +<p>Clang supports some language features conditionally on some targets.</p> + +<!-- ======================================================================= --> +<h3 id="x86-specific">X86/X86-64 Language Extensions</h3> +<!-- ======================================================================= --> + +<p>The X86 backend has these language extensions:</p> + +<!-- ======================================================================= --> +<h4 id="x86-gs-segment">Memory references off the GS segment</h4> +<!-- ======================================================================= --> + +<p>Annotating a pointer with address space #256 causes it to be code generated +relative to the X86 GS segment register, and address space #257 causes it to be +relative to the X86 FS segment. Note that this is a very very low-level +feature that should only be used if you know what you're doing (for example in +an OS kernel).</p> + +<p>Here is an example:</p> + +<pre> +#define GS_RELATIVE __attribute__((address_space(256))) +int foo(int GS_RELATIVE *P) { + return *P; +} +</pre> + +<p>Which compiles to (on X86-32):</p> + +<pre> +_foo: + movl 4(%esp), %eax + movl %gs:(%eax), %eax + ret +</pre> + +<!-- ======================================================================= --> +<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2> +<!-- ======================================================================= --> + +<p>Clang supports additional attributes that are useful for documenting program +invariants and rules for static analysis tools. The extensions documented here +are used by the <a +href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer +engine</a> that is part of Clang's Analysis library.</p> + +<!-- ======================================================================= --> +<h3 id="analyzerattributes">Analyzer Attributes</h3> +<!-- ======================================================================= --> + +<h4 id="attr_analyzer_noreturn"><tt>analyzer_noreturn</tt></h4> + +<p>Clang's static analysis engine understands the standard <tt>noreturn</tt> +attribute. This attribute, which is typically affixed to a function prototype, +indicates that a call to a given function never returns. Function prototypes for +common functions like <tt>exit</tt> are typically annotated with this attribute, +as well as a variety of common assertion handlers. Users can educate the static +analyzer about their own custom assertion handles (thus cutting down on false +positives due to false paths) by marking their own "panic" functions +with this attribute.</p> + +<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes +there are special functions that for all intensive purposes should be considered +panic functions (i.e., they are only called when an internal program error +occurs) but may actually return so that the program can fail gracefully. The +<tt>analyzer_noreturn</tt> attribute allows one to annotate such functions as +being interpreted as "no return" functions by the analyzer (thus +pruning bogus paths) but will not affect compilation (as in the case of +<tt>noreturn</tt>).</p> + +<p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the +same places where the <tt>noreturn</tt> attribute can be placed. It is commonly +placed at the end of function prototypes:</p> + +<pre> + void foo() <b>__attribute__((analyzer_noreturn))</b>; +</p> + +</div> +</body> +</html> |
