<li><a href="#i_br" >'<tt>br</tt>' Instruction</a>
<li><a href="#i_switch">'<tt>switch</tt>' Instruction</a>
<li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a>
+ <li><a href="#i_unwind" >'<tt>unwind</tt>' Instruction</a>
</ol>
<li><a href="#binaryops">Binary Operations</a>
<ol>
<li><a href="#i_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
<li><a href="#i_va_end" >'<tt>llvm.va_end</tt>' Intrinsic</a>
<li><a href="#i_va_copy" >'<tt>llvm.va_copy</tt>' Intrinsic</a>
- <li><a href="#i_unwind" >'<tt>llvm.unwind</tt>' Intrinsic</a>
</ol>
</ol>
<blockquote>
This document is a reference manual for the LLVM assembly language. LLVM is
- an SSA based representation that provides type safety, low level operations,
- flexibility, and the capability of representing 'all' high level languages
+ an SSA based representation that provides type safety, low-level operations,
+ flexibility, and the capability of representing 'all' high-level languages
cleanly. It is the common code representation used throughout all phases of
the LLVM compilation strategy.
</blockquote>
<!-- *********************************************************************** -->
The LLVM code representation is designed to be used in three different forms: as
-an in-memory compiler IR, as an on-disk bytecode representation, suitable for
-fast loading by a dynamic compiler, and as a human readable assembly language
-representation. This allows LLVM to provide a powerful intermediate
+an in-memory compiler IR, as an on-disk bytecode representation (suitable for
+fast loading by a Just-In-Time compiler), and as a human readable assembly
+language representation. This allows LLVM to provide a powerful intermediate
representation for efficient compiler transformations and analysis, while
providing a natural means to debug and visualize the transformations. The three
different forms of LLVM are all equivalent. This document describes the human
readable representation and notation.<p>
-The LLVM representation aims to be a light weight and low level while being
+The LLVM representation aims to be a light-weight and low-level while being
expressive, typed, and extensible at the same time. It aims to be a "universal
-IR" of sorts, by being at a low enough level that high level ideas may be
+IR" of sorts, by being at a low enough level that high-level ideas may be
cleanly mapped to it (similar to how microprocessors are "universal IR's",
allowing many source languages to be mapped to them). By providing type
information, LLVM can be used as the target of optimizations: for example,
LLVM uses three different forms of identifiers, for different purposes:<p>
<ol>
-<li>Numeric constants are represented as you would expect: 12, -3 123.421, etc. Floating point constants have an optional hexidecimal notation.
-<li>Named values are represented as a string of characters with a '%' prefix. For example, %foo, %DivisionByZero, %a.really.long.identifier. The actual regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'.
-<li>Unnamed values are represented as an unsigned numeric value with a '%' prefix. For example, %12, %2, %44.
+<li>Numeric constants are represented as you would expect: 12, -3 123.421, etc.
+Floating point constants have an optional hexidecimal notation.
+
+<li>Named values are represented as a string of characters with a '%' prefix.
+For example, %foo, %DivisionByZero, %a.really.long.identifier. The actual
+regular expression used is '<tt>%[a-zA-Z$._][a-zA-Z$._0-9]*</tt>'. Identifiers
+which require other characters in their names can be surrounded with quotes. In
+this way, anything except a <tt>"</tt> character can be used in a name.
+
+<li>Unnamed values are represented as an unsigned numeric value with a '%'
+prefix. For example, %12, %2, %44.
</ol><p>
LLVM requires the values start with a '%' sign for two reasons: Compilers don't
<ul>
<table border=0 cellpadding=0 cellspacing=0>
<tr><td><tt>[3 x [4 x int]]</tt></td><td>: 3x4 array integer values.</td></tr>
-<tr><td><tt>[12 x [10 x float]]</tt></td><td>: 2x10 array of single precision floating point values.</td></tr>
+<tr><td><tt>[12 x [10 x float]]</tt></td><td>: 12x10 array of single precision floating point values.</td></tr>
<tr><td><tt>[2 x [3 x [4 x uint]]]</tt></td><td>: 2x3x4 array of unsigned integer values.</td></tr>
</table>
</ul>
Where '<tt><parameter list></tt>' is a comma-separated list of type
specifiers. Optionally, the parameter list may include a type <tt>...</tt>,
-which indicates that the function takes a variable number of arguments. Note
-that there currently is no way to define a function in LLVM that takes a
-variable number of arguments, but it is possible to <b>call</b> a function that
+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.
+<p>
<h5>Examples:</h5>
<ul>
<pre>
<i>; Declare the string constant as a global constant...</i>
-<a href="#identifiers">%.LC0</a> = <a href="#linkage_
decl">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x sbyte]</a> c"hello world\0A\00" <i>; [13 x sbyte]*</i>
+<a href="#identifiers">%.LC0</a> = <a href="#linkage_
internal">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x sbyte]</a> c"hello world\0A\00" <i>; [13 x sbyte]*</i>
-<i>; Forward declaration of puts</i>
-<a href="#functionstructure">declare</a> int "puts"(sbyte*) <i>; int(sbyte*)* </i>
+<i>; External declaration of the puts function</i>
+<a href="#functionstructure">declare</a> int %puts(sbyte*) <i>; int(sbyte*)* </i>
<i>; Definition of main function</i>
-int "main"() { <i>; int()* </i>
+int %main() { <i>; int()* </i>
<i>; Convert [13x sbyte]* to sbyte *...</i>
%cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, long 0, long 0 <i>; sbyte*</i>
"<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function, and a
<a href="#functionstructure">function definition</a> for "<tt>main</tt>".<p>
-<a name="linkage_decl">
+<a name="linkage">
In general, a module is made up of a list of global values, where both functions
and global variables are global values. Global values are represented by a
pointer to a memory location (in this case, a pointer to an array of char, and a
-pointer to a function), and can be either "internal" or externally accessible
-(which corresponds to the static keyword in C, when used at global scope).<p>
+pointer to a function), and have one of the following linkage types:<p>
+
+<dl>
+<a name="linkage_internal">
+<dt><tt><b>internal</b></tt>
+
+<dd>Global values with internal linkage are only directly accessible by objects
+in the current module. In particular, linking code into a module with an
+internal global value may cause the internal to be renamed as necessary to avoid
+collisions. Because the symbol is internal to the module, all references can be
+updated. This corresponds to the notion of the '<tt>static</tt>' keyword in C,
+or the idea of "anonymous namespaces" in C++.<p>
+
+<a name="linkage_linkonce">
+<dt><tt><b>linkonce</b></tt>:
+
+<dd>"<tt>linkonce</tt>" linkage is similar to <tt>internal</tt> linkage, with
+the twist that linking together two modules defining the same <tt>linkonce</tt>
+globals will cause one of the globals to be discarded. This is typically used
+to implement inline functions.<p>
+
+<a name="linkage_appending">
+<dt><tt><b>appending</b></tt>:
+
+<dd>"<tt>appending</tt>" linkage may only applied to global variables of pointer
+to array type. When two global variables with appending linkage are linked
+together, the two global arrays are appended together. This is the LLVM,
+typesafe, equivalent of having the system linker append together "sections" with
+identical names when .o files are linked.<p>
+
+<a name="linkage_external">
+<dt><tt><b>externally visible</b></tt>:
+
+<dd>If none of the above identifiers are used, the global is externally visible,
+meaning that it participates in linkage and can be used to resolve external
+symbol references.<p>
+
+</dl><p>
+
For example, since the "<tt>.LC0</tt>" variable is defined to be internal, if
another module defined a "<tt>.LC0</tt>" variable and was linked with this one,
one of the two would be renamed, preventing a collision. Since "<tt>main</tt>"
-and "<tt>puts</tt>" are external (i.e., lacking "<tt>internal</tt>"
-declarations), they are accessible outside of the current module. It is illegal
-
for a function declaration to be "<tt>internal</tt>".<p>
+and "<tt>puts</tt>" are external (i.e., lacking any linkage declarations), they
+are accessible outside of the current module. It is illegal for a function
+
<i>declaration</i> to have any linkage type other than "externally visible".<p>
<!-- ======================================================================= -->
<!-- ======================================================================= -->
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
<tr><td> </td><td width="100%"> <font color="#EEEEFF" face="Georgia,Palatino"><b>
-<a name="functionstructure">Function Structure
+<a name="functionstructure">Functions
</b></font></td></tr></table><ul>
LLVM functions definitions are composed of a (possibly empty) argument list, an
The first basic block in program is special in two ways: it is immediately
executed on entrance to the function, and it is not allowed to have predecessor
basic blocks (i.e. there can not be any branches to the entry block of a
-function).<p>
+function). Because the block can have no predecessors, it also cannot have any
+<a href="#i_phi">PHI nodes</a>.<p>
<!-- *********************************************************************** -->
(the one exception being the '<a href="#i_invoke"><tt>invoke</tt></a>'
instruction).<p>
-There are f
our different terminator instructions: the '<a
+There are f
ive different terminator instructions: the '<a
href="#i_ret"><tt>ret</tt></a>' instruction, the '<a
href="#i_br"><tt>br</tt></a>' instruction, the '<a
-href="#i_switch"><tt>switch</tt></a>' instruction, and the '<a
-href="#i_invoke"><tt>invoke</tt></a>' instruction.<p>
+href="#i_switch"><tt>switch</tt></a>' instruction, the '<a
+href="#i_invoke"><tt>invoke</tt></a>' instruction, and the '<a
+href="#i_unwind"><tt>unwind</tt></a>' instruction.<p>
<!-- _______________________________________________________________________ -->
<h5>Semantics:</h5>
When the '<tt>ret</tt>' instruction is executed, control flow returns back to
-the calling function's context. If the instruction returns a value, that value
-shall be propagated into the calling function's data space.<p>
+the calling function's context. If the caller is a "<a
+href="#i_call"><tt>call</tt></a> instruction, execution continues at the
+instruction after the call. If the caller was an "<a
+href="#i_invoke"><tt>invoke</tt></a>" instruction, execution continues at the
+beginning "normal" of the destination block. If the instruction returns a
+value, that value shall set the call or invoke instruction's return value.<p>
+
<h5>Example:</h5>
<pre>
Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>bool</tt>'
argument is evaluated. If the value is <tt>true</tt>, control flows to the
-'<tt>iftrue</tt>' '<tt>label</tt>' argument. If "cond" is <tt>false</tt>,
-control flows to the '<tt>iffalse</tt>'
'<tt>label</tt>' argument.<p>
+'<tt>iftrue</tt>' <tt>label</tt> argument. If "cond" is <tt>false</tt>,
+control flows to the '<tt>iffalse</tt>'
<tt>label</tt> argument.<p>
<h5>Example:</h5>
<pre>
<h5>Syntax:</h5>
<pre>
- switch int <value>, label <defaultdest> [ int <val>, label &dest>, ... ]
+ switch uint <value>, label <defaultdest> [ int <val>, label &dest>, ... ]
</pre>
<pre>
<i>; Emulate a conditional br instruction</i>
%Val = <a href="#i_cast">cast</a> bool %value to uint
- switch int %Val, label %truedest [int 0, label %falsedest ]
+ switch uint %Val, label %truedest [int 0, label %falsedest ]
<i>; Emulate an unconditional br instruction</i>
- switch int 0, label %dest [ ]
+ switch uint 0, label %dest [ ]
<i>; Implement a jump table:</i>
- switch int %val, label %otherwise [ int 0, label %onzero,
- int 1, label %onone,
- int 2, label %ontwo ]
+ switch uint %val, label %otherwise [ int 0, label %onzero,
+ int 1, label %onone,
+ int 2, label %ontwo ]
</pre>
The '<tt>invoke</tt>' instruction causes control to transfer to a specified
function, with the possibility of control flow transfer to either the
-'<tt>normal label</tt>' label or the '<tt>exception label</tt>'. If the callee
-function invokes the "<tt><a href="#i_ret">ret</a></tt>" instruction, control
-flow will return to the "normal" label. If the callee (or any indirect callees)
-calls the "<a href="#i_unwind"><tt>llvm.unwind</tt></a>" intrinsic, control is
-interrupted, and continued at the "except" label.<p>
+'<tt>normal</tt>' <tt>label</tt> label or the '<tt>exception</tt>'
+<tt>label</tt>. If the callee function returns with the "<tt><a
+href="#i_ret">ret</a></tt>" instruction, control flow will return to the
+"normal" label. If the callee (or any indirect callees) returns with the "<a
+href="#i_unwind"><tt>unwind</tt></a>" instruction, control is interrupted, and
+continued at the dynamically nearest "except" label.<p>
<h5>Arguments:</h5>
<li>'<tt>normal label</tt>': the label reached when the called function executes
a '<tt><a href="#i_ret">ret</a></tt>' instruction.
-<li>'<tt>exception label</tt>': the label reached when a callee calls the <a
-href="#i_unwind"><tt>llvm.unwind</tt></a> intrinsic.
+<li>'<tt>exception label</tt>': the label reached when a callee returns with the
+<a href="#i_unwind"><tt>unwind</tt></a> instruction.
</ol>
<h5>Semantics:</h5>
except label %TestCleanup <i>; {int}:retval set</i>
</pre>
+<!-- _______________________________________________________________________ -->
+</ul><a name="i_unwind"><h4><hr size=0>'<tt>unwind</tt>' Instruction</h4><ul>
+
+<h5>Syntax:</h5>
+<pre>
+ unwind
+</pre>
+
+<h5>Overview:</h5>
+
+The '<tt>unwind</tt>' instruction unwinds the stack, continuing control flow at
+the first callee in the dynamic call stack which used an <a
+href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is
+primarily used to implement exception handling.
+
+<h5>Semantics:</h5>
+
+The '<tt>unwind</tt>' intrinsic causes execution of the current function to
+immediately halt. The dynamic call stack is then searched for the first <a
+href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found,
+execution continues at the "exceptional" destination block specified by the
+<tt>invoke</tt> instruction. If there is no <tt>invoke</tt> instruction in the
+dynamic call chain, undefined behavior results.
+
<!-- ======================================================================= -->
Binary operators are used to do most of the computation in a program. They
require two operands, execute an operation on them, and produce a single value.
-The result value of a binary operator is not neccesarily the same type as its
+The result value of a binary operator is not necessarily the same type as its
operands.<p>
There are several different binary operators:<p>
'<tt>label</tt>'s, '<tt>array</tt>'s, '<tt>structure</tt>' or '<tt>void</tt>'
values, etc...). Both arguments must have identical types.<p>
-The '<tt>setlt</tt>', '<tt>setgt</tt>', '<tt>setle</tt>', and '<tt>setge</tt>'
-instructions do not operate on '<tt>bool</tt>' typed arguments.<p>
-
<h5>Semantics:</h5>
The '<tt>seteq</tt>' instruction yields a <tt>true</tt> '<tt>bool</tt>' value if
<h5>Overview:</h5>
The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of its
-two operands.<p>
+two operands. The <tt>xor</tt> is used to implement the "one's complement"
+operation, which is the "~" operator in C.<p>
<h5>Arguments:</h5>
<result> = xor int 4, %var <i>; yields {int}:result = 4 ^ %var</i>
<result> = xor int 15, 40 <i>; yields {int}:result = 39</i>
<result> = xor int 4, 8 <i>; yields {int}:result = 12</i>
+ <result> = xor int %V, -1 <i>; yields {int}:result = ~%V</i>
</pre>
<a name="memoryops">Memory Access Operations
</b></font></td></tr></table><ul>
-Accessing memory in SSA form is, well, sticky at best. This section describes how to read, write, allocate and free memory in LLVM.<p>
+A key design point of an SSA-based representation is how it represents memory.
+In LLVM, no memory locations are in SSA form, which makes things very simple.
+This section describes how to read, write, allocate and free memory in LLVM.<p>
<!-- _______________________________________________________________________ -->
second form of the instruction is a shorter version of the first instruction
that defaults to allocating one element.<p>
-'<tt>type</tt>' must be a sized type<p>
+'<tt>type</tt>' must be a sized type
.<p>
<h5>Semantics:</h5>
-Memory is allocated, a pointer is returned.<p>
+
+Memory is allocated using the system "<tt>malloc</tt>" function, and a pointer
+is returned.<p>
<h5>Example:</h5>
<pre>
Memory is allocated, a pointer is returned. '<tt>alloca</tt>'d memory is
automatically released when the function returns. The '<tt>alloca</tt>'
instruction is commonly used to represent automatic variables that must have an
-address available, as well as spilled variables.<p>
+address available. When the function returns (either with the <tt><a
+href="#i_ret">ret</a></tt> or <tt><a href="#i_invoke">invoke</a></tt>
+instructions), the memory is reclaimed.<p>
<h5>Example:</h5>
<pre>
<h5>Syntax:</h5>
<pre>
<result> = load <ty>* <pointer>
+ <result> = volatile load <ty>* <pointer>
</pre>
<h5>Overview:</h5>
<h5>Arguments:</h5>
-The argument to the '<tt>load</tt>' instruction specifies the memory address to load from. The pointer must point to a <a href="t_firstclass">first class</a> type.<p>
+The argument to the '<tt>load</tt>' instruction specifies the memory address to
+load from. The pointer must point to a <a href="t_firstclass">first class</a>
+type. If the <tt>load</tt> is marked as <tt>volatile</tt> then the optimizer is
+not allowed to modify the number or order of execution of this <tt>load</tt>
+with other volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
+instructions. <p>
<h5>Semantics:</h5>
<h5>Syntax:</h5>
<pre>
store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
+ volatile store <ty> <value>, <ty>* <pointer> <i>; yields {void}</i>
</pre>
<h5>Overview:</h5>
There are two arguments to the '<tt>store</tt>' instruction: a value to store
and an address to store it into. The type of the '<tt><pointer></tt>'
-operand must be a pointer to the type of the '<tt><value></tt>'
-operand.<p>
+operand must be a pointer to the type of the '<tt><value></tt>' operand.
+If the <tt>store</tt> is marked as <tt>volatile</tt> then the optimizer is not
+allowed to modify the number or order of execution of this <tt>store</tt> with
+other volatile <tt>load</tt> and <tt><a href="#i_store">store</a></tt>
+instructions.<p>
<h5>Semantics:</h5> The contents of memory are updated to contain
'<tt><value></tt>' at the location specified by the
<a name="otherops">Other Operations
</b></font></td></tr></table><ul>
-The instructions in this catagory are the "miscellaneous"
functions, that defy better classification.<p>
+The instructions in this catagory are the "miscellaneous"
instructions, which defy better classification.<p>
<!-- _______________________________________________________________________ -->
arbitrarily complex and require memory allocation, for example.<p>
-<!-- _______________________________________________________________________ -->
-</ul><a name="i_unwind"><h4><hr size=0>'<tt>llvm.unwind</tt>' Intrinsic</h4><ul>
-
-<h5>Syntax:</h5>
-<pre>
- call void (void)* %llvm.unwind()
-</pre>
-
-<h5>Overview:</h5>
-
-The '<tt>llvm.unwind</tt>' intrinsic unwinds the stack, continuing control flow
-at the first callee in the dynamic call stack which used an <a
-href="#i_invoke"><tt>invoke</tt></a> instruction to perform the call. This is
-primarily used to implement exception handling.
-
-<h5>Semantics:</h5>
-
-The '<tt>llvm.unwind</tt>' intrinsic causes execution of the current function to
-immediately halt. The dynamic call stack is then searched for the first <a
-href="#i_invoke"><tt>invoke</tt></a> instruction on the call stack. Once found,
-execution continues at the "exceptional" destination block specified by the
-invoke instruction. If there is no <tt>invoke</tt> instruction in the dynamic
-call chain, undefined behavior results.
-
-
-
<!-- *********************************************************************** -->
</ul>
<!-- *********************************************************************** -->
<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
<!-- hhmts start -->
-Last modified: Thu Aug 28 17:11:50 CDT 2003
+Last modified: Mon Sep 8 13:27:14 CDT 2003
<!-- hhmts end -->
</font>
</body></html>
projects / oota-llvm.git / blobdiff