<li><a href="#modulestructure">Module Structure</a></li>
<li><a href="#linkage">Linkage Types</a>
<ol>
- <li><a href="#linkage_private">private</a></li>
- <li><a href="#linkage_linker_private">linker_private</a></li>
- <li><a href="#linkage_internal">internal</a></li>
- <li><a href="#linkage_available_externally">available_externally</a></li>
- <li><a href="#linkage_linkonce">linkonce</a></li>
- <li><a href="#linkage_common">common</a></li>
- <li><a href="#linkage_weak">weak</a></li>
- <li><a href="#linkage_appending">appending</a></li>
- <li><a href="#linkage_externweak">extern_weak</a></li>
- <li><a href="#linkage_linkonce">linkonce_odr</a></li>
- <li><a href="#linkage_weak">weak_odr</a></li>
- <li><a href="#linkage_external">externally visible</a></li>
- <li><a href="#linkage_dllimport">dllimport</a></li>
- <li><a href="#linkage_dllexport">dllexport</a></li>
+ <li><a href="#linkage_private">'<tt>private</tt>' Linkage</a></li>
+ <li><a href="#linkage_linker_private">'<tt>linker_private</tt>' Linkage</a></li>
+ <li><a href="#linkage_internal">'<tt>internal</tt>' Linkage</a></li>
+ <li><a href="#linkage_available_externally">'<tt>available_externally</tt>' Linkage</a></li>
+ <li><a href="#linkage_linkonce">'<tt>linkonce</tt>' Linkage</a></li>
+ <li><a href="#linkage_common">'<tt>common</tt>' Linkage</a></li>
+ <li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li>
+ <li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li>
+ <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li>
+ <li><a href="#linkage_linkonce">'<tt>linkonce_odr</tt>' Linkage</a></li>
+ <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li>
+ <li><a href="#linkage_external">'<tt>externally visible</tt>' Linkage</a></li>
+ <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li>
+ <li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li>
</ol>
</li>
<li><a href="#callingconv">Calling Conventions</a></li>
<li><a href="#gc">Garbage Collector Names</a></li>
<li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
<li><a href="#datalayout">Data Layout</a></li>
+ <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li>
</ol>
</li>
<li><a href="#typesystem">Type System</a>
<li><a href="#inlineasm">Inline Assembler Expressions</a></li>
</ol>
</li>
+ <li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
+ <ol>
+ <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li>
+ <li><a href="#intg_compiler_used">The '<tt>llvm.compiler.used</tt>'
+ Global Variable</a></li>
+ <li><a href="#intg_global_ctors">The '<tt>llvm.global_ctors</tt>'
+ Global Variable</a></li>
+ <li><a href="#intg_global_dtors">The '<tt>llvm.global_dtors</tt>'
+ Global Variable</a></li>
+ </ol>
+ </li>
<li><a href="#instref">Instruction Reference</a>
<ol>
<li><a href="#terminators">Terminator Instructions</a>
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
</div>
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="pointeraliasing">Pointer Aliasing Rules</a>
+</div>
+
+<div class="doc_text">
+
+<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><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 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 addresses
+ allocated by mechanisms provided by LLVM.</li>
+ </ul>
+
+<p>LLVM IR does not associate types with memory. The result type of a
+<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
+LLVM IR. <a href="#metadata">Metadata</a> may be used to encode
+additional information which specialized optimization passes may use
+to implement type-based alias analysis.</p>
+
+</div>
+
<!-- *********************************************************************** -->
<div class="doc_section"> <a name="typesystem">Type System</a> </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
</div>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="intrinsic_globals">Intrinsic Global Variables</a>
+</div>
+<!-- *********************************************************************** -->
+
+<p>LLVM has a number of "magic" global variables that contain data that affect
+code generation or other IR semantics. These are documented here. All globals
+of this sort should have a section specified as "<tt>llvm.metadata</tt>". This
+section and all globals that start with "<tt>llvm.</tt>" are reserved for use
+by LLVM.</p>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+<a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a>
+</div>
+
+<div class="doc_text">
+
+<p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a
+href="#linkage_appending">appending linkage</a>. This array contains a list of
+pointers to global variables and functions which may optionally have a pointer
+cast formed of bitcast or getelementptr. For example, a legal use of it is:</p>
+
+<pre>
+ @X = global i8 4
+ @Y = global i32 123
+
+ @llvm.used = appending global [2 x i8*] [
+ i8* @X,
+ i8* bitcast (i32* @Y to i8*)
+ ], section "llvm.metadata"
+</pre>
+
+<p>If a global variable appears in the <tt>@llvm.used</tt> list, then the
+compiler, assembler, and linker are required to treat the symbol as if there is
+a reference to the global that it cannot see. For example, if a variable has
+internal linkage and no references other than that from the <tt>@llvm.used</tt>
+list, it cannot be deleted. This is commonly used to represent references from
+inline asms and other things the compiler cannot "see", and corresponds to
+"attribute((used))" in GNU C.</p>
+
+<p>On some targets, the code generator must emit a directive to the assembler or
+object file to prevent the assembler and linker from molesting the symbol.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+<a name="intg_compiler_used">The '<tt>llvm.compiler.used</tt>' Global Variable</a>
+</div>
+
+<div class="doc_text">
+
+<p>The <tt>@llvm.compiler.used</tt> directive is the same as the
+<tt>@llvm.used</tt> directive, except that it only prevents the compiler from
+touching the symbol. On targets that support it, this allows an intelligent
+linker to optimize references to the symbol without being impeded as it would be
+by <tt>@llvm.used</tt>.</p>
+
+<p>This is a rare construct that should only be used in rare circumstances, and
+should not be exposed to source languages.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+<a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a>
+</div>
+
+<div class="doc_text">
+
+<p>TODO: Describe this.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+<a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a>
+</div>
+
+<div class="doc_text">
+
+<p>TODO: Describe this.</p>
+
+</div>
+
+
<!-- *********************************************************************** -->
<div class="doc_section"> <a name="instref">Instruction Reference</a> </div>
<!-- *********************************************************************** -->
<h5>Syntax:</h5>
<pre>
- <result> = add <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <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>
</pre>
<h5>Overview:</h5>
<p>Because LLVM integers use a two's complement representation, this instruction
is appropriate for both signed and unsigned integers.</p>
+<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
+ and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
+ <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt>
+ is undefined if unsigned and/or signed overflow, respectively, occurs.</p>
+
<h5>Example:</h5>
<pre>
<result> = add i32 4, %var <i>; yields {i32}:result = 4 + %var</i>
<h5>Syntax:</h5>
<pre>
- <result> = sub <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <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>
</pre>
<h5>Overview:</h5>
<p>Because LLVM integers use a two's complement representation, this instruction
is appropriate for both signed and unsigned integers.</p>
+<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
+ and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
+ <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt>
+ is undefined if unsigned and/or signed overflow, respectively, occurs.</p>
+
<h5>Example:</h5>
<pre>
<result> = sub i32 4, %var <i>; yields {i32}:result = 4 - %var</i>
<h5>Syntax:</h5>
<pre>
- <result> = mul <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <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>
</pre>
<h5>Overview:</h5>
be sign-extended or zero-extended as appropriate to the width of the full
product.</p>
+<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
+ and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
+ <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt>
+ is undefined if unsigned and/or signed overflow, respectively, occurs.</p>
+
<h5>Example:</h5>
<pre>
<result> = mul i32 4, %var <i>; yields {i32}:result = 4 * %var</i>
<h5>Syntax:</h5>
<pre>
- <result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
+ <result> = exact sdiv <ty> <op1>, <op2> <i>; yields {ty}:result</i>
</pre>
<h5>Overview:</h5>
undefined behavior; this is a rare case, but can occur, for example, by doing
a 32-bit division of -2147483648 by -1.</p>
+<p>If the <tt>exact</tt> keyword is present, the result value of the
+ <tt>sdiv</tt> is undefined if the result would be rounded or if overflow
+ would occur.</p>
+
<h5>Example:</h5>
<pre>
<result> = sdiv i32 4, %var <i>; yields {i32}:result = 4 / %var</i>
<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>
%RT = <a href="#namedtypes">type</a> { i8 , [10 x [20 x i32]], i8 }
%ST = <a href="#namedtypes">type</a> { i32, double, %RT }
-define i32* %foo(%ST* %s) {
+define i32* @foo(%ST* %s) {
entry:
%reg = getelementptr %ST* %s, i32 1, i32 2, i32 1, i32 5, i32 13
ret i32* %reg
the given testcase is equivalent to:</p>
<pre>
- define i32* %foo(%ST* %s) {
+ define i32* @foo(%ST* %s) {
%t1 = getelementptr %ST* %s, i32 1 <i>; yields %ST*:%t1</i>
%t2 = getelementptr %ST* %t1, i32 0, i32 2 <i>; yields %RT*:%t2</i>
%t3 = getelementptr %RT* %t2, i32 0, i32 1 <i>; yields [10 x [20 x i32]]*:%t3</i>
}
</pre>
-<p>Note that it is undefined to access an array out of bounds: array and pointer
- indexes must always be within the defined bounds of the array type when
- accessed with an instruction that dereferences the pointer (e.g. a load or
- store instruction). The one exception for this rule is zero length arrays.
- These arrays are defined to be accessible as variable length arrays, which
- requires access beyond the zero'th element.</p>
+<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
+ formed by successive addition of the offsets implied by the indices to
+ the base address 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 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>
projects / oota-llvm.git / blobdiff