Merged in RELEASE_1.
[oota-llvm.git] / docs / LangRef.html
index 0bfbef8bb1f633b57a84c7a82795b2c1a74d7f10..e7bfe91a661d876dd818d409eca106ecf1cd1c33 100644 (file)
@@ -1,9 +1,9 @@
 <!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>&nbsp; <font size=+5 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>llvm Assembly Language Reference Manual</b></font></td>
+<tr><td>&nbsp; <font size=+5 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>LLVM Language Reference Manual</b></font></td>
 </tr></table>
 
 <ol>
@@ -39,6 +39,7 @@
           <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_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_vanext">'<tt>vanext</tt>' Instruction</a>
+          <li><a href="#i_vaarg" >'<tt>vaarg</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>
+    </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 representationsuitable 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,
@@ -126,7 +139,7 @@ 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>
@@ -135,11 +148,11 @@ 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. -->
@@ -155,9 +168,17 @@ passes or input to the parser.<p>
 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
@@ -208,7 +229,7 @@ demonstrating instructions, we will follow an instruction with a comment that
 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
@@ -284,7 +305,8 @@ These different primitive types fall into a few useful classifications:<p>
 <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>
@@ -333,7 +355,7 @@ Here are some examples of multidimensional arrays:<p>
 <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>
@@ -354,12 +376,12 @@ functions), for indirect function calls, and when defining a function.<p>
   &lt;returntype&gt; (&lt;parameter list&gt;)
 </pre>
 
-Where '<tt>&lt;parameter list&gt;</tt>' is a comma seperated list of type
+Where '<tt>&lt;parameter list&gt;</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
-is vararg.<p>
+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>
@@ -477,15 +499,15 @@ declarations, and merges symbol table entries. Here is an example of the "hello
 
 <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, 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>
@@ -497,19 +519,64 @@ This example is made up of a <a href="#globalvars">global variable</a> named
 "<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.  Unreferenced <tt>linkonce</tt> globals are
+allowed to be discarded.<p>
+
+<a name="linkage_weak">
+<dt><tt><b>weak</b></tt>:
+
+<dd>"<tt>weak</tt>" linkage is exactly the same as <tt>linkonce</tt> linkage,
+except that unreferenced <tt>weak</tt> globals may not be discarded.  This is
+used to implement constructs in C such as "<tt>int X;</tt>" at global scope.<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>
 
 
 <!-- ======================================================================= -->
@@ -534,7 +601,7 @@ of memory, and all memory objects in LLVM are accessed through pointers.<p>
 <!-- ======================================================================= -->
 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 <tr><td>&nbsp;</td><td width="100%">&nbsp; <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
@@ -551,7 +618,8 @@ return).<p>
 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>
 
 
 <!-- *********************************************************************** -->
@@ -580,11 +648,12 @@ typically yield a '<tt>void</tt>' value: they produce control flow, not values
 (the one exception being the '<a href="#i_invoke"><tt>invoke</tt></a>'
 instruction).<p>
 
-There are four different terminator instructions: the '<a
+There are five 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>
 
 
 <!-- _______________________________________________________________________ -->
@@ -615,8 +684,13 @@ that returns a value that does not match the return type of the function.<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 propogated 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>
@@ -652,8 +726,8 @@ target.<p>
 
 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>
@@ -672,14 +746,8 @@ IfUnequal:
 
 <h5>Syntax:</h5>
 <pre>
-  <i>; Definitions for lookup indirect branch</i>
-  %switchtype = type [&lt;anysize&gt; x { uint, label }]
-
-  <i>; Lookup indirect branch</i>
-  switch uint &lt;value&gt;, label &lt;defaultdest&gt;, %switchtype &lt;switchtable&gt;
+  switch uint &lt;value&gt;, label &lt;defaultdest&gt; [ int &lt;val&gt;, label &dest&gt;, ... ]
 
-  <i>; Indexed indirect branch</i>
-  switch uint &lt;idxvalue&gt;, label &lt;defaultdest&gt;, [&lt;anysize&gt; x label] &lt;desttable&gt;
 </pre>
 
 <h5>Overview:</h5>
@@ -688,54 +756,38 @@ The '<tt>switch</tt>' instruction is used to transfer control flow to one of
 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<p>
+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 uint %Val, label %truedest [int 0, label %falsedest ]
 
   <i>; Emulate an unconditional br instruction</i>
-  switch uint 0, label %dest, [ 0 x label] [ ]
+  switch uint 0, label %dest [ ]
 
   <i>; Implement a jump table:</i>
-  switch uint %val, label %otherwise, [3 x label] [ label %onzero, 
-                                                    label %onone, 
-                                                    label %ontwo ]
-
+  switch uint %val, label %otherwise [ int 0, label %onzero, 
+                                       int 1, label %onone, 
+                                       int 2, label %ontwo ]
 </pre>
 
 
@@ -751,13 +803,15 @@ provided as part of the constant values type.<p>
 
 <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</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>
 
@@ -766,8 +820,8 @@ This instruction requires several arguments:<p>
 
 <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.
@@ -779,28 +833,52 @@ accepts a variable number of arguments, the extra arguments can be specified.
 <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 returns with the
+<a href="#i_unwind"><tt>unwind</tt></a> instruction.
 </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>
+              to label %Continue
+              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.
+
 
 
 <!-- ======================================================================= -->
@@ -810,7 +888,7 @@ in high-level languages that support them.<p>
 
 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>
@@ -828,11 +906,11 @@ There are several different binary operators:<p>
 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_integral">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_integer">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 sum of the two operands.<p>
+The value produced is the integer or floating point sum of the two operands.<p>
 
 <h5>Example:</h5>
 <pre>
@@ -858,12 +936,12 @@ instruction present in most other intermediate representations.<p>
 <h5>Arguments:</h5>
 
 The two arguments to the '<tt>sub</tt>' instruction must be either <a
-href="#t_integral">integral</a> or <a href="#t_floating">floating point</a>
+href="#t_integer">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>
@@ -884,11 +962,11 @@ operands.<p>
 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_integral">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_integer">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
@@ -916,12 +994,12 @@ The  '<tt>div</tt>' instruction returns the quotient of its two operands.<p>
 <h5>Arguments:</h5>
 
 The two arguments to the '<tt>div</tt>' instruction must be either <a
-href="#t_integral">integral</a> or <a href="#t_floating">floating point</a>
+href="#t_integer">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>
@@ -942,7 +1020,7 @@ operands.<p>
 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_integral">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_integer">integer</a> or <a href="#t_floating">floating point</a> values.  Both arguments must have identical types.<p>
 
 <h5>Semantics:</h5>
 
@@ -980,9 +1058,6 @@ href="#t_pointer">pointer</a> type (it is not possible to compare
 '<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
@@ -1040,9 +1115,9 @@ The '<tt>and</tt>' instruction returns the bitwise logical and of its two operan
 
 <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>
@@ -1080,9 +1155,9 @@ inclusive or of its two operands.<p>
 
 <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>
@@ -1117,13 +1192,14 @@ The truth table used for the '<tt>or</tt>' instruction is:<p>
 <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>
 
-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>
@@ -1144,6 +1220,7 @@ The truth table used for the '<tt>xor</tt>' instruction is:<p>
   &lt;result&gt; = xor int 4, %var         <i>; yields {int}:result = 4 ^ %var</i>
   &lt;result&gt; = xor int 15, 40          <i>; yields {int}:result = 39</i>
   &lt;result&gt; = xor int 4, 8            <i>; yields {int}:result = 12</i>
+  &lt;result&gt; = xor int %V, -1          <i>; yields {int}:result = ~%V</i>
 </pre>
 
 
@@ -1163,7 +1240,7 @@ specified number of bits.
 <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>
@@ -1192,7 +1269,7 @@ The value produced is <tt>var1</tt> * 2<sup><tt>var2</tt></sup>.<p>
 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_integral">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_integer">integer</a> type.  The second argument must be an '<tt>ubyte</tt>' type.<p>
 
 <h5>Semantics:</h5>
 
@@ -1203,9 +1280,10 @@ argument is unsigned, zero bits shall fill the empty positions.<p>
 <h5>Example:</h5>
 <pre>
   &lt;result&gt; = shr int 4, ubyte %var   <i>; yields {int}:result = 4 >> %var</i>
-  &lt;result&gt; = shr int 4, ubyte 1      <i>; yields {int}:result = 2</i>
+  &lt;result&gt; = shr uint 4, ubyte 1     <i>; yields {uint}:result = 2</i>
   &lt;result&gt; = shr int 4, ubyte 2      <i>; yields {int}:result = 1</i>
-  &lt;result&gt; = shr int 4, ubyte 3      <i>; yields {int}:result = 0</i>
+  &lt;result&gt; = shr sbyte 4, ubyte 3    <i>; yields {sbyte}:result = 0</i>
+  &lt;result&gt; = shr sbyte -2, ubyte 1   <i>; yields {sbyte}:result = -1</i>
 </pre>
 
 
@@ -1218,7 +1296,9 @@ argument is unsigned, zero bits shall fill the empty positions.<p>
 <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>
 
 
 <!-- _______________________________________________________________________ -->
@@ -1241,10 +1321,12 @@ system, and returns a pointer of the appropriate type to the program.  The
 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>
@@ -1315,7 +1397,9 @@ one element.<p>
 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>
@@ -1330,6 +1414,7 @@ address available, as well as spilled variables.<p>
 <h5>Syntax:</h5>
 <pre>
   &lt;result&gt; = load &lt;ty&gt;* &lt;pointer&gt;
+  &lt;result&gt; = volatile load &lt;ty&gt;* &lt;pointer&gt;
 </pre>
 
 <h5>Overview:</h5>
@@ -1337,7 +1422,12 @@ The '<tt>load</tt>' instruction is used to read from memory.<p>
 
 <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>
 
@@ -1359,6 +1449,7 @@ The location of memory pointed to is loaded.
 <h5>Syntax:</h5>
 <pre>
   store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
+  volatile store &lt;ty&gt; &lt;value&gt;, &lt;ty&gt;* &lt;pointer&gt;                   <i>; yields {void}</i>
 </pre>
 
 <h5>Overview:</h5>
@@ -1368,8 +1459,11 @@ The '<tt>store</tt>' instruction is used to write to memory.<p>
 
 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>&lt;pointer&gt;</tt>'
-operand must be a pointer to the type of the '<tt>&lt;value&gt;</tt>'
-operand.<p>
+operand must be a pointer to the type of the '<tt>&lt;value&gt;</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>&lt;value&gt;</tt>' at the location specified by the
@@ -1390,7 +1484,7 @@ operand.<p>
 
 <h5>Syntax:</h5>
 <pre>
-  &lt;result&gt; = getelementptr &lt;ty&gt;* &lt;ptrval&gt;{, uint &lt;aidx&gt;|, ubyte &lt;sidx&gt;}*
+  &lt;result&gt; = getelementptr &lt;ty&gt;* &lt;ptrval&gt;{, long &lt;aidx&gt;|, ubyte &lt;sidx&gt;}*
 </pre>
 
 <h5>Overview:</h5>
@@ -1400,7 +1494,7 @@ subelement of an aggregate data structure.<p>
 
 <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
@@ -1433,7 +1527,7 @@ The LLVM code generated by the GCC frontend is:
 %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>
@@ -1442,7 +1536,7 @@ int* "foo"(%ST* %s) {
 
 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>
 
@@ -1462,11 +1556,11 @@ given testcase is equivalent to:<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>
@@ -1476,7 +1570,7 @@ int* "foo"(%ST* %s) {
 <h5>Example:</h5>
 <pre>
   <i>; yields [12 x ubyte]*:aptr</i>
-  %aptr = getelementptr {int, [12 x ubyte]}* %sptr, uint 0, ubyte 1
+  %aptr = getelementptr {int, [12 x ubyte]}* %sptr, long 0, ubyte 1
 </pre>
 
 
@@ -1487,7 +1581,7 @@ int* "foo"(%ST* %s) {
 <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>
 
 
 <!-- _______________________________________________________________________ -->
@@ -1592,7 +1686,7 @@ invoked.  The argument types must match the types implied by this signature.<p>
 
 <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
@@ -1616,73 +1710,233 @@ case of the <a href="#i_invoke">invoke</a> instruction.<p>
 
 </pre>
 
-<!--
+<!-- _______________________________________________________________________ -->
+</ul><a name="i_vanext"><h4><hr size=0>'<tt>vanext</tt>' Instruction</h4><ul>
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;resultarglist&gt; = vanext &lt;va_list&gt; &lt;arglist&gt;, &lt;argty&gt;
+</pre>
+
+<h5>Overview:</h5>
+
+The '<tt>vanext</tt>' instruction is used to access arguments passed through
+the "variable argument" area of a function call.  It is used to implement the
+<tt>va_arg</tt> macro in C.<p>
+
+<h5>Arguments:</h5>
+
+This instruction takes a <tt>valist</tt> value and the type of the argument.  It
+returns another <tt>valist</tt>.
+
+<h5>Semantics:</h5>
+
+The '<tt>vanext</tt>' instruction advances the specified <tt>valist</tt> past
+an argument of the specified type.  In conjunction with the <a
+href="#i_vaarg"><tt>vaarg</tt></a> instruction, it is used to implement the
+<tt>va_arg</tt> macro available in C.  For more information, see 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>vanext</tt> is an LLVM instruction instead of an <a
+href="#intrinsics">intrinsic function</a> because it takes an type as an
+argument.</p>
+
+<h5>Example:</h5>
+
+See the <a href="#int_varargs">variable argument processing</a> section.<p>
+
+
+
+<!-- _______________________________________________________________________ -->
+</ul><a name="i_vaarg"><h4><hr size=0>'<tt>vaarg</tt>' Instruction</h4><ul>
+
+<h5>Syntax:</h5>
+<pre>
+  &lt;resultval&gt; = vaarg &lt;va_list&gt; &lt;arglist&gt;, &lt;argty&gt;
+</pre>
 
-<!x- *********************************************************************** -x>
+<h5>Overview:</h5>
+
+The '<tt>vaarg</tt>' instruction is used to access arguments passed through
+the "variable argument" area of a function call.  It is used to implement the
+<tt>va_arg</tt> macro in C.<p>
+
+<h5>Arguments:</h5>
+
+This instruction takes a <tt>valist</tt> value and the type of the argument.  It
+returns a value of the specified argument type.
+
+<h5>Semantics:</h5>
+
+The '<tt>vaarg</tt>' instruction loads an argument of the specified type from
+the specified <tt>va_list</tt>.  In conjunction with the <a
+href="#i_vanext"><tt>vanext</tt></a> instruction, it is used to implement the
+<tt>va_arg</tt> macro available in C.  For more information, see 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>vaarg</tt> is an LLVM instruction instead of an <a
+href="#intrinsics">intrinsic function</a> because it takes an type as 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>
-<!x- *********************************************************************** -x>
+<!-- *********************************************************************** -->
 
+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>
 
-Codesigned virtual machines.<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>
 
-<dl>
-<a name="rw_safetsa">
-<dt>SafeTSA
-<DD>Description here<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>
 
-<a name="rw_java">
-<dt><a href="http://www.javasoft.com">Java</a>
-<DD>Desciption here<p>
 
-<a name="rw_net">
-<dt><a href="http://www.microsoft.com/net">Microsoft .net</a>
-<DD>Desciption here<p>
+<!-- ======================================================================= -->
+</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
+<tr><td>&nbsp;</td><td width="100%">&nbsp; <font color="#EEEEFF" face="Georgia,Palatino"><b>
+<a name="int_varargs">Variable Argument Handling Intrinsics
+</b></font></td></tr></table><ul>
 
-<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>
+Variable argument support is defined in LLVM with the <a
+href="#i_vanext"><tt>vanext</tt></a> instruction and these three intrinsic
+functions.  These functions are related to the similarly named macros defined in
+the <tt>&lt;stdarg.h&gt;</tt> header file.<p>
 
-<a name="rw_ia64">
-<dt><a href="http://developer.intel.com/design/ia-64/index.htm">IA64 Architecture &amp; Instruction Set</a>
-<DD>Desciption here<p>
+All of these functions operate on arguments that use a target-specific value
+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>
 
-<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>
+This example shows how the <a href="#i_vanext"><tt>vanext</tt></a> instruction
+and the variable argument handling intrinsic functions are used.<p>
 
-<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>
+<pre>
+int %test(int %X, ...) {
+  ; Initialize variable argument processing
+  %ap = call sbyte*()* %<a href="#i_va_start">llvm.va_start</a>()
 
-<!x- _______________________________________________________________________ -x>
-</ul><a name="rw_vectorization"><h3><hr size=0>Vectorized Architectures</h3><ul>
+  ; Read a single integer argument
+  %tmp = vaarg sbyte* %ap, int
 
-<dl>
-<a name="rw_intel_simd">
-<dt>Intel MMX, MMX2, SSE, SSE2
-<DD>Description here<p>
+  ; Advance to the next argument
+  %ap2 = vanext sbyte* %ap, int
 
-<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>
+  ; Demonstrate usage of llvm.va_copy and llvm.va_end
+  %aq = call sbyte* (sbyte*)* %<a href="#i_va_copy">llvm.va_copy</a>(sbyte* %ap2)
+  call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %aq)
 
-<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>
+  ; Stop processing of arguments.
+  call void %<a href="#i_va_end">llvm.va_end</a>(sbyte* %ap2)
+  ret int %tmp
+}
+</pre>
 
-<a name="rw_powerpc_simd">
-<dt>PowerPC Altivec
-<DD>Desciption here<p>
+<!-- _______________________________________________________________________ -->
+</ul><a name="i_va_start"><h4><hr size=0>'<tt>llvm.va_start</tt>' Intrinsic</h4><ul>
 
-</dl>
+<h5>Syntax:</h5>
+<pre>
+  call va_list ()* %llvm.va_start()
+</pre>
+
+<h5>Overview:</h5>
 
-more...
+The '<tt>llvm.va_start</tt>' intrinsic returns a new <tt>&lt;arglist&gt;</tt>
+for subsequent use by the variable argument intrinsics.<p>
 
--->
+<h5>Semantics:</h5>
+
+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 and returns a
+<tt>va_list</tt> element, so that the next <tt>vaarg</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>
+
+Note that this intrinsic function is only legal to be called from within the
+body of a variable argument function.<p>
+
+
+<!-- _______________________________________________________________________ -->
+</ul><a name="i_va_end"><h4><hr size=0>'<tt>llvm.va_end</tt>' Intrinsic</h4><ul>
+
+<h5>Syntax:</h5>
+<pre>
+  call void (va_list)* %llvm.va_end(va_list &lt;arglist&gt;)
+</pre>
+
+<h5>Overview:</h5>
+
+The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>&lt;arglist&gt;</tt> which has
+been initialized previously with <tt><a
+href="#i_va_start">llvm.va_start</a></tt> or <tt><a
+href="#i_va_copy">llvm.va_copy</a></tt>.<p>
+
+<h5>Arguments:</h5>
+
+The argument is a <tt>va_list</tt> 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>.
+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 va_list (va_list)* %llvm.va_copy(va_list &lt;destarglist&gt;)
+</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 argument is the <tt>va_list</tt> to copy.
+
+<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 returned list.  This intrinsic is necessary
+because the <tt><a href="i_va_start">llvm.va_start</a></tt> intrinsic may be
+arbitrarily complex and require memory allocation, for example.<p>
 
 
 <!-- *********************************************************************** -->
@@ -1693,9 +1947,11 @@ more...
 <hr>
 <font size=-1>
 <address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
+<a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
+<br>
 <!-- Created: Tue Jan 23 15:19:28 CST 2001 -->
 <!-- hhmts start -->
-Last modified: Mon Aug 19 15:52:29 CDT 2002
+Last modified: Mon Oct 27 12:00:00 CDT 2003
 <!-- hhmts end -->
 </font>
 </body></html>