<li><a href="#t_classifications">Type Classifications</a></li>
<li><a href="#t_primitive">Primitive Types</a>
<ol>
+ <li><a href="#t_integer">Integer Type</a></li>
<li><a href="#t_floating">Floating Point Types</a></li>
<li><a href="#t_void">Void Type</a></li>
<li><a href="#t_label">Label Type</a></li>
</li>
<li><a href="#t_derived">Derived Types</a>
<ol>
- <li><a href="#t_integer">Integer Type</a></li>
<li><a href="#t_array">Array Type</a></li>
<li><a href="#t_function">Function Type</a></li>
<li><a href="#t_pointer">Pointer Type</a></li>
<dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt>: </dt>
<dd>Similar to private, but the symbol is passed through the assembler and
- removed by the linker after evaluation.</dd>
+ removed by the linker after evaluation. Note that (unlike private
+ symbols) linker_private symbols are subject to coalescing by the linker:
+ weak symbols get merged and redefinitions are rejected. However, unlike
+ normal strong symbols, they are removed by the linker from the final
+ linked image (executable or dynamic library).</dd>
<dt><tt><b><a name="linkage_internal">internal</a></b></tt>: </dt>
<dd>Similar to private, but the value shows as a local symbol
translation unit that uses it. Unreferenced <tt>linkonce</tt> globals are
allowed to be discarded.</dd>
+ <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt>
+ <dd>"<tt>weak</tt>" linkage has the same merging semantics as
+ <tt>linkonce</tt> linkage, except that unreferenced globals with
+ <tt>weak</tt> linkage may not be discarded. This is used for globals that
+ are declared "weak" in C source code.</dd>
+
<dt><tt><b><a name="linkage_common">common</a></b></tt>: </dt>
- <dd>"<tt>common</tt>" linkage is exactly the same as <tt>linkonce</tt>
- linkage, except that unreferenced <tt>common</tt> globals may not be
- discarded. This is used for globals that may be emitted in multiple
- translation units, but that are not guaranteed to be emitted into every
- translation unit that uses them. One example of this is tentative
- definitions in C, such as "<tt>int X;</tt>" at global scope.</dd>
+ <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but
+ they are used for tentative definitions in C, such as "<tt>int X;</tt>" at
+ global scope.
+ Symbols with "<tt>common</tt>" linkage are merged in the same way as
+ <tt>weak symbols</tt>, and they may not be deleted if unreferenced.
+ <tt>common</tt> symbols may not have an explicit section,
+ must have a zero initializer, and may not be marked '<a
+ href="#globalvars"><tt>constant</tt></a>'. Functions and aliases may not
+ have common linkage.</dd>
- <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt>
- <dd>"<tt>weak</tt>" linkage is the same as <tt>common</tt> linkage, except
- that some targets may choose to emit different assembly sequences for them
- for target-dependent reasons. This is used for globals that are declared
- "weak" in C source code.</dd>
<dt><tt><b><a name="linkage_appending">appending</a></b></tt>: </dt>
<dd>"<tt>appending</tt>" linkage may only be applied to global variables of
function into callers whenever possible, ignoring any active inlining size
threshold for this caller.</dd>
+ <dt><tt>inlinehint</tt></dt>
+ <dd>This attribute indicates that the source code contained a hint that inlining
+ this function is desirable (such as the "inline" keyword in C/C++). It
+ is just a hint; it imposes no requirements on the inliner.</dd>
+
<dt><tt>noinline</tt></dt>
<dd>This attribute indicates that the inliner should never inline this
function in any situation. This attribute may not be used together with
<div class="doc_text">
-<p>Any memory access must be done though a pointer value associated
-with with address range of the memory access, otherwise the behavior
+<p>Any memory access must be done through a pointer value associated
+with an address range of the memory access, otherwise the behavior
is undefined. Pointer values are associated with address ranges
according to the following rules:</p>
<ul>
- <li>A pointer value formed from a <tt>getelementptr</tt> instruction is
- associated with the addresses associated with the first operand of
- the <tt>getelementptr</tt>.</li>
- <li>An addresses of a global variable is associated with the address
+ <li>A pointer value formed from a
+ <tt><a href="#i_getelementptr">getelementptr</a></tt> instruction
+ is associated with the addresses associated with the first operand
+ of the <tt>getelementptr</tt>.</li>
+ <li>An address of a global variable is associated with the address
range of the variable's storage.</li>
<li>The result value of an allocation instruction is associated with
the address range of the allocated storage.</li>
<li>A null pointer in the default address-space is associated with
- no addresses.</li>
- <li>A pointer value formed by an <tt>inttoptr</tt> is associated with
- all address ranges of all pointer values that contribute (directly
- or indirectly) to the computation of the pointer's value.</li>
- <li>The result value of a <tt>bitcast</tt> is associated with all
+ no address.</li>
+ <li>A pointer value formed by an
+ <tt><a href="#i_inttoptr">inttoptr</a></tt> is associated with all
+ address ranges of all pointer values that contribute (directly or
+ indirectly) to the computation of the pointer's value.</li>
+ <li>The result value of a
+ <tt><a href="#i_bitcast">bitcast</a></tt> is associated with all
addresses associated with the operand of the <tt>bitcast</tt>.</li>
<li>An integer constant other than zero or a pointer value returned
from a function not defined within LLVM may be associated with address
ranges allocated through mechanisms other than those provided by
- LLVM. Such ranges shall not overlap with any ranges of address
+ LLVM. Such ranges shall not overlap with any ranges of addresses
allocated by mechanisms provided by LLVM.</li>
</ul>
<p>LLVM IR does not associate types with memory. The result type of a
-<tt>load</tt> merely indicates the size and alignment of the memory from
-which to load, as well as the interpretation of the value. The first
-operand of a <tt>store</tt> similarly only indicates the size and
-alignment of the store.</p>
+<tt><a href="#i_load">load</a></tt> merely indicates the size and
+alignment of the memory from which to load, as well as the
+interpretation of the value. The first operand of a
+<tt><a href="#i_store">store</a></tt> similarly only indicates the size
+and alignment of the store.</p>
<p>Consequently, type-based alias analysis, aka TBAA, aka
<tt>-fstrict-aliasing</tt>, is not applicable to general unadorned
<p>The <a href="#t_firstclass">first class</a> types are perhaps the most
important. Values of these types are the only ones which can be produced by
- instructions, passed as arguments, or used as operands to instructions.</p>
+ instructions.</p>
</div>
</div>
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div>
+
+<div class="doc_text">
+
+<h5>Overview:</h5>
+<p>The integer type is a very simple type that simply specifies an arbitrary
+ bit width for the integer type desired. Any bit width from 1 bit to
+ 2<sup>23</sup>-1 (about 8 million) can be specified.</p>
+
+<h5>Syntax:</h5>
+<pre>
+ iN
+</pre>
+
+<p>The number of bits the integer will occupy is specified by the <tt>N</tt>
+ value.</p>
+
+<h5>Examples:</h5>
+<table class="layout">
+ <tr class="layout">
+ <td class="left"><tt>i1</tt></td>
+ <td class="left">a single-bit integer.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>i32</tt></td>
+ <td class="left">a 32-bit integer.</td>
+ </tr>
+ <tr class="layout">
+ <td class="left"><tt>i1942652</tt></td>
+ <td class="left">a really big integer of over 1 million bits.</td>
+ </tr>
+</table>
+
+<p>Note that the code generator does not yet support large integer types to be
+ used as function return types. The specific limit on how large a return type
+ the code generator can currently handle is target-dependent; currently it's
+ often 64 bits for 32-bit targets and 128 bits for 64-bit targets.</p>
+
+</div>
+
<!-- _______________________________________________________________________ -->
<div class="doc_subsubsection"> <a name="t_floating">Floating Point Types</a> </div>
<div class="doc_text">
<h5>Overview:</h5>
-<p>The metadata type represents embedded metadata. The only derived type that
- may contain metadata is <tt>metadata*</tt> or a function type that returns or
- takes metadata typed parameters, but not pointer to metadata types.</p>
+<p>The metadata type represents embedded metadata. No derived types may be
+ created from metadata except for <a href="#t_function">function</a>
+ arguments.
<h5>Syntax:</h5>
<pre>
<p>The real power in LLVM comes from the derived types in the system. This is
what allows a programmer to represent arrays, functions, pointers, and other
- useful types. Note that these derived types may be recursive: For example,
- it is possible to have a two dimensional array.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div>
-
-<div class="doc_text">
-
-<h5>Overview:</h5>
-<p>The integer type is a very simple derived type that simply specifies an
- arbitrary bit width for the integer type desired. Any bit width from 1 bit to
- 2^23-1 (about 8 million) can be specified.</p>
-
-<h5>Syntax:</h5>
-<pre>
- iN
-</pre>
-
-<p>The number of bits the integer will occupy is specified by the <tt>N</tt>
- value.</p>
-
-<h5>Examples:</h5>
-<table class="layout">
- <tr class="layout">
- <td class="left"><tt>i1</tt></td>
- <td class="left">a single-bit integer.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>i32</tt></td>
- <td class="left">a 32-bit integer.</td>
- </tr>
- <tr class="layout">
- <td class="left"><tt>i1942652</tt></td>
- <td class="left">a really big integer of over 1 million bits.</td>
- </tr>
-</table>
-
-<p>Note that the code generator does not yet support large integer types to be
- used as function return types. The specific limit on how large a return type
- the code generator can currently handle is target-dependent; currently it's
- often 64 bits for 32-bit targets and 128 bits for 64-bit targets.</p>
+ useful types. Each of these types contain one or more element types which
+ may be a primitive type, or another derived type. For example, it is
+ possible to have a two dimensional array, using an array as the element type
+ of another array.</p>
</div>
<h5>Syntax:</h5>
<pre>
- <returntype list> (<parameter list>)
+ <returntype> (<parameter list>)
</pre>
<p>...where '<tt><parameter list></tt>' is a comma-separated list of type
which indicates that the function takes a variable number of arguments.
Variable argument functions can access their arguments with
the <a href="#int_varargs">variable argument handling intrinsic</a>
- functions. '<tt><returntype list></tt>' is a comma-separated list of
- <a href="#t_firstclass">first class</a> type specifiers.</p>
+ functions. '<tt><returntype></tt>' is a any type except
+ <a href="#t_label">label</a>.</p>
<h5>Examples:</h5>
<table class="layout">
</td>
</tr><tr class="layout">
<td class="left"><tt>{i32, i32} (i32)</tt></td>
- <td class="left">A function taking an <tt>i32</tt>, returning two
- <tt>i32</tt> values as an aggregate of type <tt>{ i32, i32 }</tt>
+ <td class="left">A function taking an <tt>i32</tt>, returning a
+ <a href="#t_struct">structure</a> containing two <tt>i32</tt> values
</td>
</tr>
</table>
<dl>
<dt><b>Boolean constants</b></dt>
<dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
- constants of the <tt><a href="#t_primitive">i1</a></tt> type.</dd>
+ constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd>
<dt><b>Integer constants</b></dt>
<dd>Standard integers (such as '4') are constants of
<div class="doc_subsection"><a name="undefvalues">Undefined Values</a></div>
<div class="doc_text">
-<p>The string '<tt>undef</tt>' is recognized as a type-less constant that has no
- specific value. Undefined values may be of any type and be used anywhere a
- constant is permitted.</p>
+<p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and
+ indicates that the user of the value may recieve an unspecified bit-pattern.
+ Undefined values may be of any type (other than label or void) and be used
+ anywhere a constant is permitted.</p>
+
+<p>Undefined values are useful because they indicate to the compiler that the
+ program is well defined no matter what value is used. This gives the
+ compiler more freedom to optimize. Here are some examples of (potentially
+ surprising) transformations that are valid (in pseudo IR):</p>
-<p>Undefined values indicate to the compiler that the program is well defined no
- matter what value is used, giving the compiler more freedom to optimize.</p>
+
+<div class="doc_code">
+<pre>
+ %A = add %X, undef
+ %B = sub %X, undef
+ %C = xor %X, undef
+Safe:
+ %A = undef
+ %B = undef
+ %C = undef
+</pre>
+</div>
+
+<p>This is safe because all of the output bits are affected by the undef bits.
+Any output bit can have a zero or one depending on the input bits.</p>
+
+<div class="doc_code">
+<pre>
+ %A = or %X, undef
+ %B = and %X, undef
+Safe:
+ %A = -1
+ %B = 0
+Unsafe:
+ %A = undef
+ %B = undef
+</pre>
+</div>
+
+<p>These logical operations have bits that are not always affected by the input.
+For example, if "%X" has a zero bit, then the output of the 'and' operation will
+always be a zero, no matter what the corresponding bit from the undef is. As
+such, it is unsafe to optimize or assume that the result of the and is undef.
+However, it is safe to assume that all bits of the undef could be 0, and
+optimize the and to 0. Likewise, it is safe to assume that all the bits of
+the undef operand to the or could be set, allowing the or to be folded to
+-1.</p>
+
+<div class="doc_code">
+<pre>
+ %A = select undef, %X, %Y
+ %B = select undef, 42, %Y
+ %C = select %X, %Y, undef
+Safe:
+ %A = %X (or %Y)
+ %B = 42 (or %Y)
+ %C = %Y
+Unsafe:
+ %A = undef
+ %B = undef
+ %C = undef
+</pre>
+</div>
+
+<p>This set of examples show that undefined select (and conditional branch)
+conditions can go "either way" but they have to come from one of the two
+operands. In the %A example, if %X and %Y were both known to have a clear low
+bit, then %A would have to have a cleared low bit. However, in the %C example,
+the optimizer is allowed to assume that the undef operand could be the same as
+%Y, allowing the whole select to be eliminated.</p>
+
+
+<div class="doc_code">
+<pre>
+ %A = xor undef, undef
+
+ %B = undef
+ %C = xor %B, %B
+
+ %D = undef
+ %E = icmp lt %D, 4
+ %F = icmp gte %D, 4
+
+Safe:
+ %A = undef
+ %B = undef
+ %C = undef
+ %D = undef
+ %E = undef
+ %F = undef
+</pre>
+</div>
+
+<p>This example points out that two undef operands are not necessarily the same.
+This can be surprising to people (and also matches C semantics) where they
+assume that "X^X" is always zero, even if X is undef. This isn't true for a
+number of reasons, but the short answer is that an undef "variable" can
+arbitrarily change its value over its "live range". This is true because the
+"variable" doesn't actually <em>have a live range</em>. Instead, the value is
+logically read from arbitrary registers that happen to be around when needed,
+so the value is not neccesarily consistent over time. In fact, %A and %C need
+to have the same semantics or the core LLVM "replace all uses with" concept
+would not hold.</p>
+
+<div class="doc_code">
+<pre>
+ %A = fdiv undef, %X
+ %B = fdiv %X, undef
+Safe:
+ %A = undef
+b: unreachable
+</pre>
+</div>
+
+<p>These examples show the crucial difference between an <em>undefined
+value</em> and <em>undefined behavior</em>. An undefined value (like undef) is
+allowed to have an arbitrary bit-pattern. This means that the %A operation
+can be constant folded to undef because the undef could be an SNaN, and fdiv is
+not (currently) defined on SNaN's. However, in the second example, we can make
+a more aggressive assumption: because the undef is allowed to be an arbitrary
+value, we are allowed to assume that it could be zero. Since a divide by zero
+has <em>undefined behavior</em>, we are allowed to assume that the operation
+does not execute at all. This allows us to delete the divide and all code after
+it: since the undefined operation "can't happen", the optimizer can assume that
+it occurs in dead code.
+</p>
+
+<div class="doc_code">
+<pre>
+a: store undef -> %X
+b: store %X -> undef
+Safe:
+a: <deleted>
+b: unreachable
+</pre>
+</div>
+
+<p>These examples reiterate the fdiv example: a store "of" an undefined value
+can be assumed to not have any effect: we can assume that the value is
+overwritten with bits that happen to match what was already there. However, a
+store "to" an undefined location could clobber arbitrary memory, therefore, it
+has undefined behavior.</p>
</div>
instruction</a>.</dd>
<dt><b><tt>getelementptr ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
+ <dt><b><tt>getelementptr inbounds ( CSTPTR, IDX0, IDX1, ... )</tt></b></dt>
<dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
constants. As with the <a href="#i_getelementptr">getelementptr</a>
instruction, the index list may have zero or more indexes, which are
<h5>Syntax:</h5>
<pre>
<result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nsw add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw nsw add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = add nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = add nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = add nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
<result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nsw sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw nsw sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sub nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sub nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sub nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
<result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nsw mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = nuw nsw mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = mul nuw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = mul nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = mul nuw nsw <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
<result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
- <result> = exact sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sdiv exact <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
<h5>Syntax:</h5>
<pre>
<result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}*
+ <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}*
</pre>
<h5>Overview:</h5>
<h5>Arguments:</h5>
<p>The first argument is always a pointer, and forms the basis of the
- calculation. The remaining arguments are indices, that indicate which of the
+ calculation. The remaining arguments are indices that indicate which of the
elements of the aggregate object are indexed. The interpretation of each
index is dependent on the type being indexed into. The first index always
indexes the pointer value given as the first argument, the second index
calculation.</p>
<p>The type of each index argument depends on the type it is indexing into.
- When indexing into a (packed) structure, only <tt>i32</tt> integer
+ When indexing into a (optionally packed) structure, only <tt>i32</tt> integer
<b>constants</b> are allowed. When indexing into an array, pointer or
- vector, integers of any width are allowed (also non-constants).</p>
+ vector, integers of any width are allowed, and they are not required to be
+ constant.</p>
<p>For example, let's consider a C code fragment and how it gets compiled to
LLVM:</p>
}
</pre>
+<p>If the <tt>inbounds</tt> keyword is present, the result value of the
+ <tt>getelementptr</tt> is undefined if the base pointer is not an
+ <i>in bounds</i> address of an allocated object, or if any of the addresses
+ that would be formed by successive addition of the offsets implied by the
+ indices to the base address with infinitely precise arithmetic are not an
+ <i>in bounds</i> address of that allocated object.
+ The <i>in bounds</i> addresses for an allocated object are all the addresses
+ that point into the object, plus the address one byte past the end.</p>
+
+<p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to
+ the base address with silently-wrapping two's complement arithmetic, and
+ the result value of the <tt>getelementptr</tt> may be outside the object
+ pointed to by the base pointer. The result value may not necessarily be
+ used to access memory though, even if it happens to point into allocated
+ storage. See the <a href="#pointeraliasing">Pointer Aliasing Rules</a>
+ section for more information.</p>
+
<p>The getelementptr instruction is often confusing. For some more insight into
how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p>
<h5>Semantics:</h5>
<p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the
condition code given as <tt>cond</tt>. The comparison performed always yields
- either an <a href="#t_primitive"><tt>i1</tt></a> or vector of <tt>i1</tt>
+ either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt>
result, as follows:</p>
<ol>
values based on comparison of its operands.</p>
<p>If the operands are floating point scalars, then the result type is a boolean
-(<a href="#t_primitive"><tt>i1</tt></a>).</p>
+(<a href="#t_integer"><tt>i1</tt></a>).</p>
<p>If the operands are floating point vectors, then the result type is a vector
of boolean with the same number of elements as the operands being
<p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt>
according to the condition code given as <tt>cond</tt>. If the operands are
vectors, then the vectors are compared element by element. Each comparison
- performed always yields an <a href="#t_primitive">i1</a> result, as
+ performed always yields an <a href="#t_integer">i1</a> result, as
follows:</p>
<ol>
%ZZ = call zeroext i32 @bar() <i>; Return value is %zero extended</i>
</pre>
+<p>llvm treats calls to some functions with names and arguments that match the
+standard C99 library as being the C99 library functions, and may perform
+optimizations or generate code for them under that assumption. This is
+something we'd like to change in the future to provide better support for
+freestanding environments and non-C-based langauges.</p>
+
</div>
<!-- _______________________________________________________________________ -->
projects / oota-llvm.git / blobdiff