<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html><head><title>llvm Assembly Language Reference Manual</title></head>
+<html><head><title>LLVM Assembly Language Reference Manual</title></head>
<body bgcolor=white>
<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
-<tr><td> <font size=+5 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>llvm Assembly Language Reference Manual</b></font></td>
+<tr><td> <font size=+5 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>LLVM Language Reference Manual</b></font></td>
</tr></table>
<ol>
<li><a href="#t_function">Function Type</a>
<li><a href="#t_pointer">Pointer Type</a>
<li><a href="#t_struct" >Structure Type</a>
- <li><a href="#t_packed" >Packed Type</a>
+ <!-- <li><a href="#t_packed" >Packed Type</a> -->
</ol>
</ol>
<li><a href="#highlevel">High Level Structure</a>
<li><a href="#i_switch">'<tt>switch</tt>' Instruction</a>
<li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a>
</ol>
- <li><a href="#unaryops">Unary Operations</a>
- <ol>
- <li><a href="#i_not" >'<tt>not</tt>' Instruction</a>
- </ol>
<li><a href="#binaryops">Binary Operations</a>
<ol>
<li><a href="#i_add" >'<tt>add</tt>' Instruction</a>
<li><a href="#i_phi" >'<tt>phi</tt>' Instruction</a>
<li><a href="#i_cast">'<tt>cast .. to</tt>' Instruction</a>
<li><a href="#i_call" >'<tt>call</tt>' Instruction</a>
+ <li><a href="#i_va_arg">'<tt>va_arg</tt>' Instruction</a>
</ol>
</ol>
-<!--
- <li><a href="#related">Related Work</a>
--->
+ <li><a href="#intrinsics">Intrinsic Functions</a>
+ <ol>
+ <li><a href="#int_varargs">Variable Argument Handling Intrinsics</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>
+
+ <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and <A href="mailto:vadve@cs.uiuc.edu">Vikram Adve</a></b><p>
+
+
</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
-expressive, type safe, 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 cleanly mapped to it (similar to how microprocessors are "universal
-IR's", allowing many source languages to be mapped to them). By providing type
-safety, LLVM can be used as the target of optimizations: for example, through
-pointer analysis, it can be proven that a C automatic variable is never accessed
-outside of the current function... allowing it to be promoted to a simple SSA
-value instead of a memory location.<p>
+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
+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,
+through pointer analysis, it can be proven that a C automatic variable is never
+accessed outside of the current function... allowing it to be promoted to a
+
simple SSA value instead of a memory location.<p>
<!-- _______________________________________________________________________ -->
</ul><a name="wellformed"><h4><hr size=0>Well Formedness</h4><ul>
-It is important to note that this document describes 'well formed' llvm assembly
+It is important to note that this document describes 'well formed' LLVM assembly
language. There is a difference between what the parser accepts and what is
considered 'well formed'. For example, the following instruction is
syntactically okay, but not well formed:<p>
%x = <a href="#i_add">add</a> int 1, %x
</pre>
-...because the definition of %x does not dominate all of its uses. The LLVM
-infrastructure provides a verification pass that may be used to verify that an
-LLVM module is well formed. This pass is automatically run by the parser after
-parsing input assembly, and by the optimizer before it outputs bytecode. The
-violations pointed out by the verifier pass indicate bugs in transformation
+...because the definition of <tt>%x</tt> does not dominate all of its uses. The
+LLVM infrastructure provides a verification pass that may be used to verify that
+an LLVM module is well formed. This pass is automatically run by the parser
+after parsing input assembly, and by the optimizer before it outputs bytecode.
+The violations pointed out by the verifier pass indicate bugs in transformation
passes or input to the parser.<p>
<!-- Describe the typesetting conventions here. -->
defines the type and name of value produced. Comments are shown in italic
text.<p>
-The one unintuitive notation for constants is the optional hexidecimal form of
+The one non-intuitive notation for constants is the optional hexidecimal form of
floating point constants. For example, the form '<tt>double
0x432ff973cafa8000</tt>' is equivalent to (but harder to read than) '<tt>double
4.5e+15</tt>' which is also supported by the parser. The only time hexadecimal
<!-- *********************************************************************** -->
The LLVM type system is one of the most important features of the intermediate
-representation. Being strongly typed enables a number of optimizations to be
-performed on the IR directly, without having to do extra analyses on the side
-before the transformation. A strong type system makes it easier to read the
-generated code and enables novel analyses and transformations that are not
-
feasible to perform on normal three address code representations.<p>
+representation. Being typed enables a number of optimizations to be performed
+on the IR directly, without having to do extra analyses on the side before the
+transformation. A strong type system makes it easier to read the generated code
+and enables novel analyses and transformations that are not feasible to perform
+on normal three address code representations.<p>
<!-- The written form for the type system was heavily influenced by the
syntactic problems with types in the C language<sup><a
<table border=1 cellspacing=0 cellpadding=4 align=center>
<tr><td><a name="t_signed">signed</td> <td><tt>sbyte, short, int, long, float, double</tt></td></tr>
<tr><td><a name="t_unsigned">unsigned</td><td><tt>ubyte, ushort, uint, ulong</tt></td></tr>
-<tr><td><a name="t_integral">integral</td><td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td></tr>
+<tr><td><a name="t_integer">integer</td><td><tt>ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td></tr>
+<tr><td><a name="t_integral">integral</td><td><tt>bool, ubyte, sbyte, ushort, short, uint, int, ulong, long</tt></td></tr>
<tr><td><a name="t_floating">floating point</td><td><tt>float, double</tt></td></tr>
<tr><td><a name="t_firstclass">first class</td><td><tt>bool, ubyte, sbyte, ushort, short,<br> uint, int, ulong, long, float, double, <a href="#t_pointer">pointer</a></tt></td></tr>
</table><p>
<returntype> (<parameter list>)
</pre>
-Where '<tt><parameter list></tt>' is a comma seperated list of type
+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
<i>; Definition of main function</i>
int "main"() { <i>; int()* </i>
<i>; Convert [13x sbyte]* to sbyte *...</i>
- %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, uint 0, uint 0 <i>; sbyte*</i>
+ %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x sbyte]* %.LC0, long 0, long 0 <i>; sbyte*</i>
<i>; Call puts function to write out the string to stdout...</i>
<a href="#i_call">call</a> int %puts(sbyte* %cast210) <i>; int</i>
<!-- *********************************************************************** -->
The LLVM instruction set consists of several different classifications of
-instructions: <a href="#terminators">terminator instructions</a>, a <a
-href="#unaryops">unary instruction</a>, <a href="#binaryops">binary
-instructions</a>, <a href="#memoryops">memory instructions</a>, and <a
-href="#otherops">other instructions</a>.<p>
+instructions: <a href="#terminators">terminator instructions</a>, <a
+href="#binaryops">binary instructions</a>, <a href="#memoryops">memory
+instructions</a>, and <a href="#otherops">other instructions</a>.<p>
<!-- ======================================================================= -->
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 prop
ogated into the calling function's data space.<p>
+shall be prop
agated into the calling function's data space.<p>
<h5>Example:</h5>
<pre>
<h5>Syntax:</h5>
<pre>
- <i>; Definitions for lookup indirect branch</i>
- %switchtype = type [<anysize> x { uint, label }]
+ switch int <value>, label <defaultdest> [ int <val>, label &dest>, ... ]
- <i>; Lookup indirect branch</i>
- switch uint <value>, label <defaultdest>, %switchtype <switchtable>
-
- <i>; Indexed indirect branch</i>
- switch uint <idxvalue>, label <defaultdest>, [<anysize> x label] <desttable>
</pre>
<h5>Overview:</h5>
several different places. It is a generalization of the '<tt>br</tt>'
instruction, allowing a branch to occur to one of many possible destinations.<p>
-The '<tt>switch</tt>' statement supports two different styles of indirect
-branching: lookup branching and indexed branching. Lookup branching is
-generally useful if the values to switch on are spread far appart, where index
-branching is useful if the values to switch on are generally dense.<p>
-
-The two different forms of the '<tt>switch</tt>' statement are simple hints to
-the underlying implementation. For example, the compiler may choose to
-implement a small indirect branch table as a series of predicated comparisons:
-if it is faster for the target architecture.<p>
-
<h5>Arguments:</h5>
-The lookup form of the '<tt>switch</tt>' instruction uses three parameters: a
-'<tt>uint</tt>' comparison value '<tt>value</tt>', a default '<tt>label</tt>'
-destination, and an array of pairs of comparison value constants and
-'<tt>label</tt>'s. The sized array must be a constant value.<p>
-
-The indexed form of the '<tt>switch</tt>' instruction uses three parameters: an
-'<tt>uint</tt>' index value, a default '<tt>label</tt>' and a sized array of
-'<tt>label</tt>'s. The '<tt>dests</tt>' array must be a constant array.
+The '<tt>switch</tt>' instruction uses three parameters: a '<tt>uint</tt>'
+comparison value '<tt>value</tt>', a default '<tt>label</tt>' destination, and
+an array of pairs of comparison value constants and '<tt>label</tt>'s.<p>
<h5>Semantics:</h5>
-The lookup style switch statement specifies a table of values and destinations.
+The <tt>switch</tt> instruction specifies a table of values and destinations.
When the '<tt>switch</tt>' instruction is executed, this table is searched for
the given value. If the value is found, the corresponding destination is
+branched to
, otherwise the default value it transfered to.<p>
-The index branch form simply looks up a label element directly in a table and
-branches to it.<p>
+<h5>Implementation:</h5>
-In either case, the compiler knows the static size of the array, because it is
-provided as part of the constant values type.<p>
+Depending on properties of the target machine and the particular <tt>switch</tt>
+instruction, this instruction may be code generated as a series of chained
+conditional branches, or with a lookup table.<p>
<h5>Example:</h5>
<pre>
<i>; Emulate a conditional br instruction</i>
%Val = <a href="#i_cast">cast</a> bool %value to uint
- switch uint %Val, label %truedest, [1 x label] [label %falsedest ]
+ switch int %Val, label %truedest [int 0, label %falsedest ]
<i>; Emulate an unconditional br instruction</i>
- switch uint 0, label %dest, [ 0 x label] [ ]
+ switch int 0, label %dest [ ]
<i>; Implement a jump table:</i>
- switch uint %val, label %otherwise, [3 x label] [ label %onzero,
- label %onone,
- label %ontwo ]
-
+ switch int %val, label %otherwise [ int 0, label %onzero,
+ int 1, label %onone,
+ int 2, label %ontwo ]
</pre>
<h5>Overview:</h5>
-The '<tt>invoke</tt>' instruction is used to cause control flow 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>'. The '<tt><a
-href="#i_call">call</a></tt>' instruction is closely related, but guarantees
-that control flow either never returns from the called function, or that it
-returns to the instruction following the '<tt><a href="#i_call">call</a></tt>'
-instruction.<p>
+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>
+
<h5>Arguments:</h5>
<li>'<tt>ptr to function ty</tt>': shall be the signature of the pointer to
function value being invoked. In most cases, this is a direct function
-invocation, but indirect <tt>invoke</tt>'s are just as possible, branching off
-an arbitrary pointer to function value.<p>
+invocation, but indirect <tt>invoke</tt>s are just as possible, branching off
+an arbitrary pointer to function value.
<li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
function to be invoked.
<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 an exception is thrown.
+<li>'<tt>exception label</tt>': the label reached when a callee calls the <a
+href="#i_unwind"><tt>llvm.unwind</tt></a> intrinsic.
</ol>
<h5>Semantics:</h5>
This instruction is designed to operate as a standard '<tt><a
href="#i_call">call</a></tt>' instruction in most regards. The primary
-difference is that it associates a label with the function invocation that may
-be accessed via the runtime library provided by the execution environment. This
-instruction is used in languages with destructors to ensure that proper cleanup
-is performed in the case of either a <tt>longjmp</tt> or a thrown exception.
-Additionally, this is important for implementation of '<tt>catch</tt>' clauses
-in high-level languages that support them.<p>
+difference is that it establishes an association with a label, which is used by the runtime library to unwind the stack.<p>
-<!-- For a more comprehensive explanation of how this instruction is used, look in the llvm/docs/2001-05-18-ExceptionHandling.txt document.<p> -->
+This instruction is used in languages with destructors to ensure that proper
+cleanup is performed in the case of either a <tt>longjmp</tt> or a thrown
+exception. Additionally, this is important for implementation of
+'<tt>catch</tt>' clauses in high-level languages that support them.<p>
<h5>Example:</h5>
<pre>
%retval = invoke int %Test(int 15)
- to label %Continue except label %TestCleanup <i>; {int}:retval set</i>
-</pre>
-
-
-
-<!-- ======================================================================= -->
-</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="unaryops">Unary Operations
-</b></font></td></tr></table><ul>
-
-Unary operators are used to do a simple operation to a single value.<p>
-
-There is only one unary operator: the '<a href="#i_not"><tt>not</tt></a>' instruction.<p>
-
-
-<!-- _______________________________________________________________________ -->
-</ul><a name="i_not"><h4><hr size=0>'<tt>not</tt>' Instruction</h4><ul>
-
-<h5>Syntax:</h5>
-<pre>
- <result> = not <ty> <var> <i>; yields {ty}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-The '<tt>not</tt>' instruction returns the bitwise complement of its operand.<p>
-
-<h5>Arguments:</h5>
-The single argument to '<tt>not</tt>' must be of of <a href="#t_integral">integral</a> or bool type.<p>
-
-
-<h5>Semantics:</h5> The '<tt>not</tt>' instruction returns the bitwise
-complement (AKA ones complement) of an <a href="#t_integral">integral</a>
-type.<p>
-
-<pre>
- <result> = xor bool true, <var> <i>; yields {bool}:result</i>
-</pre>
-
-<h5>Example:</h5>
-<pre>
- %x = not int 1 <i>; {int}:x is now equal to -2</i>
- %x = not bool true <i>; {bool}:x is now equal to false</i>
+ to label %Continue
+ except label %TestCleanup <i>; {int}:retval set</i>
</pre>
The '<tt>add</tt>' instruction returns the sum of its two operands.<p>
<h5>Arguments:</h5>
-The two arguments to the '<tt>add</tt>' instruction must be either <a href="#t_integ
ral">integral</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
+The two arguments to the '<tt>add</tt>' instruction must be either <a href="#t_integ
er">integer</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
<h5>Semantics:</h5>
-The value produced is the integ
ral or floating point sum of the two operands.<p>
+The value produced is the integ
er or floating point sum of the two operands.<p>
<h5>Example:</h5>
<pre>
<h5>Arguments:</h5>
The two arguments to the '<tt>sub</tt>' instruction must be either <a
-href="#t_integ
ral">integral</a> or <a href="#t_floating">floating point</a>
+href="#t_integ
er">integer</a> or <a href="#t_floating">floating point</a>
values. Both arguments must have identical types.<p>
<h5>Semantics:</h5>
-The value produced is the integral or floating point difference of the two
+The value produced is the integer or floating point difference of the two
operands.<p>
<h5>Example:</h5>
The '<tt>mul</tt>' instruction returns the product of its two operands.<p>
<h5>Arguments:</h5>
-The two arguments to the '<tt>mul</tt>' instruction must be either <a href="#t_integ
ral">integral</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
+The two arguments to the '<tt>mul</tt>' instruction must be either <a href="#t_integ
er">integer</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
<h5>Semantics:</h5>
-The value produced is the integral or floating point product of the two
+The value produced is the integer or floating point product of the two
operands.<p>
There is no signed vs unsigned multiplication. The appropriate action is taken
<h5>Arguments:</h5>
The two arguments to the '<tt>div</tt>' instruction must be either <a
-href="#t_integ
ral">integral</a> or <a href="#t_floating">floating point</a>
+href="#t_integ
er">integer</a> or <a href="#t_floating">floating point</a>
values. Both arguments must have identical types.<p>
<h5>Semantics:</h5>
-The value produced is the integral or floating point quotient of the two
+The value produced is the integer or floating point quotient of the two
operands.<p>
<h5>Example:</h5>
The '<tt>rem</tt>' instruction returns the remainder from the division of its two operands.<p>
<h5>Arguments:</h5>
-The two arguments to the '<tt>rem</tt>' instruction must be either <a href="#t_integ
ral">integral</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
+The two arguments to the '<tt>rem</tt>' instruction must be either <a href="#t_integ
er">integer</a> or <a href="#t_floating">floating point</a> values. Both arguments must have identical types.<p>
<h5>Semantics:</h5>
<h5>Arguments:</h5>
-The two arguments to the '<tt>and</tt>' instruction must be
either <a
-href="#t_integral">integral</a> or <tt>bool</tt> values. Both arguments must
-
have identical types.<p>
+The two arguments to the '<tt>and</tt>' instruction must be <a
+href="#t_integral">integral</a> values. Both arguments must have identical
+types.<p>
<h5>Semantics:</h5>
<h5>Arguments:</h5>
-The two arguments to the '<tt>or</tt>' instruction must be
either <a
-href="#t_integral">integral</a> or <tt>bool</tt> values. Both arguments must
-
have identical types.<p>
+The two arguments to the '<tt>or</tt>' instruction must be <a
+href="#t_integral">integral</a> values. Both arguments must have identical
+types.<p>
<h5>Semantics:</h5>
<h5>Arguments:</h5>
-The two arguments to the '<tt>xor</tt>' instruction must be
either <a
-href="#t_integral">integral</a> or <tt>bool</tt> values. Both arguments must
-
have identical types.<p>
+The two arguments to the '<tt>xor</tt>' instruction must be <a
+href="#t_integral">integral</a> values. Both arguments must have identical
+types.<p>
<h5>Semantics:</h5>
<h5>Arguments:</h5>
The first argument to the '<tt>shl</tt>' instruction must be an <a
-href="#t_integral">integral</a> type. The second argument must be an
+href="#t_integer">integer</a> type. The second argument must be an
'<tt>ubyte</tt>' type.<p>
<h5>Semantics:</h5>
The '<tt>shr</tt>' instruction returns the first operand shifted to the right a specified number of bits.
<h5>Arguments:</h5>
-The first argument to the '<tt>shr</tt>' instruction must be an <a href="#t_integ
ral">integral</a> type. The second argument must be an '<tt>ubyte</tt>' type.<p>
+The first argument to the '<tt>shr</tt>' instruction must be an <a href="#t_integ
er">integer</a> type. The second argument must be an '<tt>ubyte</tt>' type.<p>
<h5>Semantics:</h5>
<h5>Example:</h5>
<pre>
<result> = shr int 4, ubyte %var <i>; yields {int}:result = 4 >> %var</i>
- <result> = shr int 4, ubyte 1 <i>; yields {int}:result = 2</i>
+ <result> = shr uint 4, ubyte 1 <i>; yields {uint}:result = 2</i>
<result> = shr int 4, ubyte 2 <i>; yields {int}:result = 1</i>
- <result> = shr int 4, ubyte 3 <i>; yields {int}:result = 0</i>
+ <result> = shr sbyte 4, ubyte 3 <i>; yields {sbyte}:result = 0</i>
+ <result> = shr sbyte -2, ubyte 1 <i>; yields {sbyte}:result = -1</i>
</pre>
<h5>Syntax:</h5>
<pre>
- <result> = getelementptr <ty>* <ptrval>{, uint <aidx>|, ubyte <sidx>}*
+ <result> = getelementptr <ty>* <ptrval>{, long <aidx>|, ubyte <sidx>}*
</pre>
<h5>Overview:</h5>
<h5>Arguments:</h5>
-This instruction takes a list of <tt>uint</tt> values and <tt>ubyte</tt>
+This instruction takes a list of <tt>long</tt> values and <tt>ubyte</tt>
constants that indicate what form of addressing to perform. The actual types of
the arguments provided depend on the type of the first pointer argument. The
'<tt>getelementptr</tt>' instruction is used to index down through the type
%ST = type { int, double, %RT }
int* "foo"(%ST* %s) {
- %reg = getelementptr %ST* %s, uint 1, ubyte 2, ubyte 1, uint 5, uint 13
+ %reg = getelementptr %ST* %s, long 1, ubyte 2, ubyte 1, long 5, long 13
ret int* %reg
}
</pre>
The index types specified for the '<tt>getelementptr</tt>' instruction depend on
the pointer type that is being index into. <a href="t_pointer">Pointer</a> and
-<a href="t_array">array</a> types require '<tt>
uint</tt>' values, and <a
+<a href="t_array">array</a> types require '<tt>
long</tt>' values, and <a
href="t_struct">structure</a> types require '<tt>ubyte</tt>'
<b>constants</b>.<p>
<pre>
int* "foo"(%ST* %s) {
- %t1 = getelementptr %ST* %s , uint 1 <i>; yields %ST*:%t1</i>
- %t2 = getelementptr %ST* %t1, uint 0, ubyte 2 <i>; yields %RT*:%t2</i>
- %t3 = getelementptr %RT* %t2, uint 0, ubyte 1 <i>; yields [10 x [20 x int]]*:%t3</i>
- %t4 = getelementptr [10 x [20 x int]]* %t3, uint 0, uint 5 <i>; yields [20 x int]*:%t4</i>
- %t5 = getelementptr [20 x int]* %t4, uint 0, uint 13 <i>; yields int*:%t5</i>
+ %t1 = getelementptr %ST* %s , long 1 <i>; yields %ST*:%t1</i>
+ %t2 = getelementptr %ST* %t1, long 0, ubyte 2 <i>; yields %RT*:%t2</i>
+ %t3 = getelementptr %RT* %t2, long 0, ubyte 1 <i>; yields [10 x [20 x int]]*:%t3</i>
+ %t4 = getelementptr [10 x [20 x int]]* %t3, long 0, long 5 <i>; yields [20 x int]*:%t4</i>
+ %t5 = getelementptr [20 x int]* %t4, long 0, long 13 <i>; yields int*:%t5</i>
ret int* %t5
}
</pre>
<h5>Example:</h5>
<pre>
- <i>; yields {[12 x ubyte]*}:aptr</i>
- %aptr = getelementptr {int, [12 x ubyte]}* %sptr, uint 0, ubyte 1
+ <i>; yields [12 x ubyte]*:aptr</i>
+ %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1
</pre>
a C '<tt>if</tt>' condition is converted to the boolean '<tt>true</tt>' values,
all else are '<tt>false</tt>'.<p>
+When extending an integral value from a type of one signness to another (for
+example '<tt>sbyte</tt>' to '<tt>ulong</tt>'), the value is sign-extended if the
+<b>source</b> value is signed, and zero-extended if the source value is
+unsigned. <tt>bool</tt> values are always zero extended into either zero or
+one.<p>
+
<h5>Example:</h5>
<pre>
%X = cast int 257 to ubyte <i>; yields ubyte:1</i>
<li>'<tt>fnptrval</tt>': An LLVM value containing a pointer to a function to be
invoked. In most cases, this is a direct function invocation, but indirect
-<tt>call</tt>'s are just as possible, calling an arbitrary pointer to function
+<tt>call</tt>s are just as possible, calling an arbitrary pointer to function
values.<p>
<li>'<tt>function args</tt>': argument list whose types match the function
</pre>
-<!--
+<!-- _______________________________________________________________________ -->
+</ul><a name="i_va_arg"><h4><hr size=0>'<tt>va_arg</tt>' Instruction</h4><ul>
+
+<h5>Syntax:</h5>
+<pre>
+ <result> = va_arg <va_list>* <arglist>, <retty>
+</pre>
-<!x- *********************************************************************** -x>
+<h5>Overview:</h5>
+
+The '<tt>va_arg</tt>' instruction is used to access arguments passed through the
+"variable argument" area of a function call. It corresponds directly to the
+<tt>va_arg</tt> macro in C.<p>
+
+<h5>Arguments:</h5>
+
+This instruction takes a pointer to a <tt>valist</tt> value to read a new
+argument from. The return type of the instruction is defined by the second
+argument, a type.<p>
+
+<h5>Semantics:</h5>
+
+The '<tt>va_arg</tt>' instruction works just like the <tt>va_arg</tt> macro
+available in C. In a target-dependent way, it reads the argument indicated by
+the value the arglist points to, updates the arglist, then returns a value of
+the specified type. This instruction should be used in conjunction with the
+variable argument handling <a href="#int_varargs">Intrinsic Functions</a>.<p>
+
+It is legal for this instruction to be called in a function which does not take
+a variable number of arguments, for example, the <tt>vfprintf</tt> function.<p>
+
+<tt>va_arg</tt> is an LLVM instruction instead of an <a
+href="#intrinsics">intrinsic function</a> because the return type depends on an
+argument.<p>
+
+<h5>Example:</h5>
+
+See the <a href="#int_varargs">variable argument processing</a> section.<p>
+
+<!-- *********************************************************************** -->
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
-<a name="related">Related Work
+<a name="intrinsics">Intrinsic Functions
+</b></font></td></tr></table><ul>
+<!-- *********************************************************************** -->
+
+LLVM supports the notion of an "intrinsic function". These functions have well
+known names and semantics, and are required to follow certain restrictions.
+Overall, these instructions represent an extension mechanism for the LLVM
+language that does not require changing all of the transformations in LLVM to
+add to the language (or the bytecode reader/writer, the parser, etc...).<p>
+
+Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix, this
+prefix is reserved in LLVM for intrinsic names, thus functions may not be named
+this. Intrinsic functions must always be external functions: you cannot define
+the body of intrinsic functions. Intrinsic functions may only be used in call
+or invoke instructions: it is illegal to take the address of an intrinsic
+function. Additionally, because intrinsic functions are part of the LLVM
+language, it is required that they all be documented here if any are added.<p>
+
+Unless an intrinsic function is target-specific, there must be a lowering pass
+to eliminate the intrinsic or all backends must support the intrinsic
+function.<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="int_varargs">Variable Argument Handling Intrinsics
</b></font></td></tr></table><ul>
-<!x- *********************************************************************** -x>
+Variable argument support is defined in LLVM with the <a
+href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three intrinsic
+functions. These function correspond almost directly to the similarly named
+macros defined in the <tt><stdarg.h></tt> header file.<p>
+
+All of these functions operate on arguments that use a target-specific type
+"<tt>va_list</tt>". The LLVM assembly language reference manual does not define
+what this type is, so all transformations should be prepared to handle
+intrinsics with any type used.<p>
+
+This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction
+and the variable argument handling intrinsic functions are used.<p>
+
+<pre>
+int %test(int %X, ...) {
+ ; Allocate two va_list items. On this target, va_list is of type sbyte*
+ %ap = alloca sbyte*
+ %aq = alloca sbyte*
+
+ ; Initialize variable argument processing
+ call void (sbyte**)* %<a href="#i_va_start">llvm.va_start</a>(sbyte** %ap)
+
+ ; Read a single integer argument
+ %tmp = <a href="#i_va_arg">va_arg</a> sbyte** %ap, int
+
+ ; Demonstrate usage of llvm.va_copy and llvm_va_end
+ %apv = load sbyte** %ap
+ call void %<a href="#i_va_copy">llvm.va_copy</a>(sbyte** %aq, sbyte* %apv)
+ call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %aq)
+
+ ; Stop processing of arguments.
+ call void %<a href="#i_va_end">llvm.va_end</a>(sbyte** %ap)
+ ret int %tmp
+}
+</pre>
-Codesigned virtual machines.<p>
+<!-- _______________________________________________________________________ -->
+</ul><a name="i_va_start"><h4><hr size=0>'<tt>llvm.va_start</tt>' Intrinsic</h4><ul>
-<dl>
-<a name="rw_safetsa">
-<dt>SafeTSA
-<DD>Description here<p>
+<h5>Syntax:</h5>
+<pre>
+ call void (va_list*)* %llvm.va_start(<va_list>* <arglist>)
+</pre>
-<a name="rw_java">
-<dt><a href="http://www.javasoft.com">Java</a>
-<DD>Desciption here<p>
+<h5>Overview:</h5>
-<a name="rw_net">
-<dt><a href="http://www.microsoft.com/net">Microsoft .net</a>
-<DD>Desciption here<p>
+The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*<arglist></tt> for
+subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt> and <tt><a
+href="#i_va_end">llvm.va_end</a></tt>, and must be called before either are
+invoked.<p>
-<a name="rw_gccrtl">
-<dt><a href="http://www.math.umn.edu/systems_guide/gcc-2.95.1/gcc_15.html">GNU RTL Intermediate Representation</a>
-<DD>Desciption here<p>
+<h5>Arguments:</h5>
-<a name="rw_ia64">
-<dt><a href="http://developer.intel.com/design/ia-64/index.htm">IA64 Architecture & Instruction Set</a>
-<DD>Desciption here<p>
+The argument is a pointer to a <tt>va_list</tt> element to initialize.<p>
-<a name="rw_mmix">
-<dt><a href="http://www-cs-faculty.stanford.edu/~knuth/mmix-news.html">MMIX Instruction Set</a>
-<DD>Desciption here<p>
+<h5>Semantics:</h5>
-<a name="rw_stroustrup">
-<dt><a href="http://www.research.att.com/~bs/devXinterview.html">"Interview With Bjarne Stroustrup"</a>
-<DD>This interview influenced the design and thought process behind LLVM in several ways, most notably the way that derived types are written in text format. See the question that starts with "you defined the C declarator syntax as an experiment that failed".<p>
-</dl>
+The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
+macro available in C. In a target-dependent way, it initializes the
+<tt>va_list</tt> element the argument points to, so that the next call to
+<tt>va_arg</tt> will produce the first variable argument passed to the function.
+Unlike the C <tt>va_start</tt> macro, this intrinsic does not need to know the
+last argument of the function, the compiler can figure that out.<p>
-<!x- _______________________________________________________________________ -x>
-</ul><a name="rw_vectorization"><h3><hr size=0>Vectorized Architectures</h3><ul>
-<dl>
-<a name="rw_intel_simd">
-<dt>Intel MMX, MMX2, SSE, SSE2
-<DD>Description here<p>
+<!-- _______________________________________________________________________ -->
+</ul><a name="i_va_end"><h4><hr size=0>'<tt>llvm.va_end</tt>' Intrinsic</h4><ul>
-<a name="rw_amd_simd">
-<dt><a href="http://www.nondot.org/~sabre/os/H1ChipFeatures/3DNow!TechnologyManual.pdf">AMD 3Dnow!, 3Dnow! 2</a>
-<DD>Desciption here<p>
+<h5>Syntax:</h5>
+<pre>
+ call void (va_list*)* %llvm.va_end(<va_list>* <arglist>)
+</pre>
-<a name="rw_sun_simd">
-<dt><a href="http://www.nondot.org/~sabre/os/H1ChipFeatures/VISInstructionSetUsersManual.pdf">Sun VIS ISA</a>
-<DD>Desciption here<p>
+<h5>Overview:</h5>
-<a name="rw_powerpc_simd">
-<dt>PowerPC Altivec
+The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*<arglist></tt> which
+has been initialized previously with <tt><a
+
href="#i_va_begin">llvm.va_begin</a></tt>.<p>
-</dl>
+<h5>Arguments:</h5>
-more...
+The argument is a pointer to a <tt>va_list</tt> element to destroy.<p>
+
+<h5>Semantics:</h5>
+
+The '<tt>llvm.va_end</tt>' intrinsic works just like the <tt>va_end</tt> macro
+available in C. In a target-dependent way, it destroys the <tt>va_list</tt>
+that the argument points to. Calls to <a
+href="#i_va_start"><tt>llvm.va_start</tt></a> and <a
+href="#i_va_copy"><tt>llvm.va_copy</tt></a> must be matched exactly with calls
+to <tt>llvm.va_end</tt>.<p>
+
+
+
+<!-- _______________________________________________________________________ -->
+</ul><a name="i_va_copy"><h4><hr size=0>'<tt>llvm.va_copy</tt>' Intrinsic</h4><ul>
+
+<h5>Syntax:</h5>
+<pre>
+ call void (va_list*, va_list)* %va_copy(<va_list>* <destarglist>,
+ <va_list> <srcarglist>)
+</pre>
+
+<h5>Overview:</h5>
+
+The '<tt>llvm.va_copy</tt>' intrinsic copies the current argument position from
+the source argument list to the destination argument list.<p>
+
+<h5>Arguments:</h5>
+
+The first argument is a pointer to a <tt>va_list</tt> element to initialize.
+The second argument is a <tt>va_list</tt> element to copy from.<p>
+
+
+<h5>Semantics:</h5>
+
+The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt> macro
+available in C. In a target-dependent way, it copies the source
+<tt>va_list</tt> element into the destination list. This intrinsic is necessary
+because the <tt><a href="i_va_begin">llvm.va_begin</a></tt> intrinsic may be
+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.
--->
<!-- *********************************************************************** -->
<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
<!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
<!-- hhmts start -->
-Last modified: Tue Jun 25 13:05:52 CDT 2002
+Last modified: Tue Sep 2 18:38:09 CDT 2003
<!-- hhmts end -->
</font>
</body></html>
projects / oota-llvm.git / blobdiff