Prevented ExceptionDemo example being built on WINDOWS via if( NOT WIN32 )
[oota-llvm.git] / docs / LangRef.html
index 4308d312730e67620a87aa9de90c486af964e87a..fed2f80696c3cbcfb4b06dbaee8d5ae39cea1f51 100644 (file)
@@ -5,7 +5,7 @@
   <title>LLVM Assembly Language Reference Manual</title>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   <meta name="author" content="Chris Lattner">
-  <meta name="description" 
+  <meta name="description"
   content="LLVM Assembly Language Reference Manual.">
   <link rel="stylesheet" href="llvm.css" type="text/css">
 </head>
@@ -31,7 +31,7 @@
           <li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li>
           <li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li>
           <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li>
-          <li><a href="#linkage_linkonce">'<tt>linkonce_odr</tt>' Linkage</a></li>
+          <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li>
           <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li>
           <li><a href="#linkage_external">'<tt>externally visible</tt>' Linkage</a></li>
           <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li>
@@ -43,6 +43,7 @@
       <li><a href="#globalvars">Global Variables</a></li>
       <li><a href="#functionstructure">Functions</a></li>
       <li><a href="#aliasstructure">Aliases</a></li>
+      <li><a href="#namedmetadatastructure">Named Metadata</a></li>
       <li><a href="#paramattrs">Parameter Attributes</a></li>
       <li><a href="#fnattrs">Function Attributes</a></li>
       <li><a href="#gc">Garbage Collector Names</a></li>
@@ -54,8 +55,9 @@
   <li><a href="#typesystem">Type System</a>
     <ol>
       <li><a href="#t_classifications">Type Classifications</a></li>
-      <li><a href="#t_primitive">Primitive Types</a>    
+      <li><a href="#t_primitive">Primitive Types</a>
         <ol>
+          <li><a href="#t_integer">Integer Type</a></li>
           <li><a href="#t_floating">Floating Point Types</a></li>
           <li><a href="#t_void">Void Type</a></li>
           <li><a href="#t_label">Label Type</a></li>
@@ -64,7 +66,6 @@
       </li>
       <li><a href="#t_derived">Derived Types</a>
         <ol>
-          <li><a href="#t_integer">Integer Type</a></li>
           <li><a href="#t_array">Array Type</a></li>
           <li><a href="#t_function">Function Type</a></li>
           <li><a href="#t_pointer">Pointer Type</a></li>
       <li><a href="#complexconstants">Complex Constants</a></li>
       <li><a href="#globalconstants">Global Variable and Function Addresses</a></li>
       <li><a href="#undefvalues">Undefined Values</a></li>
+      <li><a href="#blockaddress">Addresses of Basic Blocks</a></li>
       <li><a href="#constantexprs">Constant Expressions</a></li>
-      <li><a href="#metadata">Embedded Metadata</a></li>
     </ol>
   </li>
   <li><a href="#othervalues">Other Values</a>
     <ol>
       <li><a href="#inlineasm">Inline Assembler Expressions</a></li>
+      <li><a href="#metadata">Metadata Nodes and Metadata Strings</a></li>
     </ol>
   </li>
   <li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
           <li><a href="#i_ret">'<tt>ret</tt>' Instruction</a></li>
           <li><a href="#i_br">'<tt>br</tt>' Instruction</a></li>
           <li><a href="#i_switch">'<tt>switch</tt>' Instruction</a></li>
+          <li><a href="#i_indirectbr">'<tt>indirectbr</tt>' Instruction</a></li>
           <li><a href="#i_invoke">'<tt>invoke</tt>' Instruction</a></li>
           <li><a href="#i_unwind">'<tt>unwind</tt>'  Instruction</a></li>
           <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
       </li>
       <li><a href="#memoryops">Memory Access and Addressing Operations</a>
         <ol>
-          <li><a href="#i_malloc">'<tt>malloc</tt>'   Instruction</a></li>
-          <li><a href="#i_free">'<tt>free</tt>'     Instruction</a></li>
           <li><a href="#i_alloca">'<tt>alloca</tt>'   Instruction</a></li>
          <li><a href="#i_load">'<tt>load</tt>'     Instruction</a></li>
          <li><a href="#i_store">'<tt>store</tt>'    Instruction</a></li>
           <li><a href="#int_atomic_load_umin"><tt>llvm.atomic.load.umin</tt></a></li>
         </ol>
       </li>
+      <li><a href="#int_memorymarkers">Memory Use Markers</a>
+        <ol>
+          <li><a href="#int_lifetime_start"><tt>llvm.lifetime.start</tt></a></li>
+          <li><a href="#int_lifetime_end"><tt>llvm.lifetime.end</tt></a></li>
+          <li><a href="#int_invariant_start"><tt>llvm.invariant.start</tt></a></li>
+          <li><a href="#int_invariant_end"><tt>llvm.invariant.end</tt></a></li>
+        </ol>
+      </li>
       <li><a href="#int_general">General intrinsics</a>
         <ol>
           <li><a href="#int_var_annotation">
             '<tt>llvm.trap</tt>' Intrinsic</a></li>
           <li><a href="#int_stackprotector">
             '<tt>llvm.stackprotector</tt>' Intrinsic</a></li>
+         <li><a href="#int_objectsize">
+            '<tt>llvm.objectsize</tt>' Intrinsic</a></li>
         </ol>
       </li>
     </ol>
    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
+   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>
 
 </div>
 </pre>
 </div>
 
-<p>...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 bitcode.  The violations pointed out by the verifier pass indicate
-   bugs in transformation passes or input to the parser.</p>
+<p>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
+   bitcode.  The violations pointed out by the verifier pass indicate bugs in
+   transformation passes or input to the parser.</p>
 
 </div>
 
 
 <div class="doc_code">
 <pre>
-<a href="#i_add">add</a> i32 %X, %X           <i>; yields {i32}:%0</i>
-<a href="#i_add">add</a> i32 %0, %0           <i>; yields {i32}:%1</i>
+%0 = <a href="#i_add">add</a> i32 %X, %X           <i>; yields {i32}:%0</i>
+%1 = <a href="#i_add">add</a> i32 %0, %0           <i>; yields {i32}:%1</i>
 %result = <a href="#i_add">add</a> i32 %1, %1
 </pre>
 </div>
   <li>Unnamed temporaries are numbered sequentially</li>
 </ol>
 
-<p>...and it also shows a convention that we follow in this document.  When
+<p>It also shows a convention that we follow in this document.  When
    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 "hello world" module:</p>
 
 <div class="doc_code">
-<pre><i>; Declare the string constant as a global constant...</i>
-<a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a
- href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00"          <i>; [13 x i8]*</i>
+<pre>
+<i>; Declare the string constant as a global constant.</i>
+<a href="#identifiers">@.LC0</a> = <a href="#linkage_internal">internal</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00"    <i>; [13 x i8]*</i>
 
 <i>; External declaration of the puts function</i>
-<a href="#functionstructure">declare</a> i32 @puts(i8 *)                                           <i>; i32(i8 *)* </i>
+<a href="#functionstructure">declare</a> i32 @puts(i8 *)                                     <i>; i32(i8 *)* </i>
 
 <i>; Definition of main function</i>
-define i32 @main() {                                              <i>; i32()* </i>
-        <i>; Convert [13 x i8]* to i8  *...</i>
-        %cast210 = <a
- href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0   <i>; i8 *</i>
+define i32 @main() {                                        <i>; i32()* </i>
+  <i>; Convert [13 x i8]* to i8  *...</i>
+  %cast210 = <a href="#i_getelementptr">getelementptr</a> [13 x i8]* @.LC0, i64 0, i64 0   <i>; i8 *</i>
 
-        <i>; Call puts function to write out the string to stdout...</i>
-        <a
- href="#i_call">call</a> i32 @puts(i8 * %cast210)                             <i>; i32</i>
-        <a
- href="#i_ret">ret</a> i32 0<br>}<br>
+  <i>; Call puts function to write out the string to stdout.</i>
+  <a href="#i_call">call</a> i32 @puts(i8 * %cast210)                             <i>; i32</i>
+  <a href="#i_ret">ret</a> i32 0<br>}
+
+<i>; Named metadata</i>
+!1 = metadata !{i32 41}
+!foo = !{!1, null}
 </pre>
 </div>
 
 <p>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
+   "<tt>.LC0</tt>", an external declaration of the "<tt>puts</tt>" function,
    a <a href="#functionstructure">function definition</a> for
-   "<tt>main</tt>".</p>
+   "<tt>main</tt>" and <a href="#namedmetadatastructure">named metadata</a> 
+   "<tt>foo"</tt>.</p>
 
 <p>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
@@ -519,7 +532,7 @@ define i32 @main() {                                              <i>; i32()* </
    linkage:</p>
 
 <dl>
-  <dt><tt><b><a name="linkage_private">private</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_private">private</a></b></tt></dt>
   <dd>Global values with private linkage are only directly accessible by objects
       in the current module.  In particular, linking code into a module with an
       private global value may cause the private to be renamed as necessary to
@@ -527,7 +540,7 @@ define i32 @main() {                                              <i>; i32()* </
       references can be updated. This doesn't show up in any symbol table in the
       object file.</dd>
 
-  <dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_linker_private">linker_private</a></b></tt></dt>
   <dd>Similar to private, but the symbol is passed through the assembler and
       removed by the linker after evaluation.  Note that (unlike private
       symbols) linker_private symbols are subject to coalescing by the linker:
@@ -535,12 +548,12 @@ define i32 @main() {                                              <i>; i32()* </
       normal strong symbols, they are removed by the linker from the final
       linked image (executable or dynamic library).</dd>
 
-  <dt><tt><b><a name="linkage_internal">internal</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_internal">internal</a></b></tt></dt>
   <dd>Similar to private, but the value shows as a local symbol
       (<tt>STB_LOCAL</tt> in the case of ELF) in the object file. This
       corresponds to the notion of the '<tt>static</tt>' keyword in C.</dd>
 
-  <dt><tt><b><a name="linkage_available_externally">available_externally</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_available_externally">available_externally</a></b></tt></dt>
   <dd>Globals with "<tt>available_externally</tt>" linkage are never emitted
       into the object file corresponding to the LLVM module.  They exist to
       allow inlining and other optimizations to take place given knowledge of
@@ -549,45 +562,52 @@ define i32 @main() {                                              <i>; i32()* </
       be discarded at will, and are otherwise the same as <tt>linkonce_odr</tt>.
       This linkage type is only allowed on definitions, not declarations.</dd>
 
-  <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_linkonce">linkonce</a></b></tt></dt>
   <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of
-      the same name when linkage occurs.  This is typically used to implement
-      inline functions, templates, or other code which must be generated in each
-      translation unit that uses it.  Unreferenced <tt>linkonce</tt> globals are
-      allowed to be discarded.</dd>
-
-  <dt><tt><b><a name="linkage_weak">weak</a></b></tt>: </dt>
+      the same name when linkage occurs.  This can be used to implement
+      some forms of inline functions, templates, or other code which must be
+      generated in each translation unit that uses it, but where the body may
+      be overridden with a more definitive definition later.  Unreferenced
+      <tt>linkonce</tt> globals are allowed to be discarded.  Note that
+      <tt>linkonce</tt> linkage does not actually allow the optimizer to
+      inline the body of this function into callers because it doesn't know if
+      this definition of the function is the definitive definition within the
+      program or whether it will be overridden by a stronger definition.
+      To enable inlining and other optimizations, use "<tt>linkonce_odr</tt>"
+      linkage.</dd>
+
+  <dt><tt><b><a name="linkage_weak">weak</a></b></tt></dt>
   <dd>"<tt>weak</tt>" linkage has the same merging semantics as
       <tt>linkonce</tt> linkage, except that unreferenced globals with
       <tt>weak</tt> linkage may not be discarded.  This is used for globals that
       are declared "weak" in C source code.</dd>
 
-  <dt><tt><b><a name="linkage_common">common</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_common">common</a></b></tt></dt>
   <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but
       they are used for tentative definitions in C, such as "<tt>int X;</tt>" at
       global scope.
       Symbols with "<tt>common</tt>" linkage are merged in the same way as
       <tt>weak symbols</tt>, and they may not be deleted if unreferenced.
       <tt>common</tt> symbols may not have an explicit section,
-      must have a zero initializer, and may not be marked '<a 
+      must have a zero initializer, and may not be marked '<a
       href="#globalvars"><tt>constant</tt></a>'.  Functions and aliases may not
       have common linkage.</dd>
 
 
-  <dt><tt><b><a name="linkage_appending">appending</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_appending">appending</a></b></tt></dt>
   <dd>"<tt>appending</tt>" linkage may only be applied to global variables of
       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.</dd>
 
-  <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_externweak">extern_weak</a></b></tt></dt>
   <dd>The semantics of this linkage follow the ELF object file model: the symbol
       is weak until linked, if not linked, the symbol becomes null instead of
       being an undefined reference.</dd>
 
-  <dt><tt><b><a name="linkage_linkonce">linkonce_odr</a></b></tt>: </dt>
-  <dt><tt><b><a name="linkage_weak">weak_odr</a></b></tt>: </dt>
+  <dt><tt><b><a name="linkage_linkonce_odr">linkonce_odr</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_weak_odr">weak_odr</a></b></tt></dt>
   <dd>Some languages allow differing globals to be merged, such as two functions
       with different semantics.  Other languages, such as <tt>C++</tt>, ensure
       that only equivalent globals are ever merged (the "one definition rule" -
@@ -607,14 +627,14 @@ define i32 @main() {                                              <i>; i32()* </
    DLLs (Dynamic Link Libraries).</p>
 
 <dl>
-  <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_dllimport">dllimport</a></b></tt></dt>
   <dd>"<tt>dllimport</tt>" linkage causes the compiler to reference a function
       or variable via a global pointer to a pointer that is set up by the DLL
       exporting the symbol. On Microsoft Windows targets, the pointer name is
       formed by combining <code>__imp_</code> and the function or variable
       name.</dd>
 
-  <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt></dt>
+  <dt><tt><b><a name="linkage_dllexport">dllexport</a></b></tt></dt>
   <dd>"<tt>dllexport</tt>" linkage causes the compiler to provide a global
       pointer to a pointer in a DLL, so that it can be referenced with the
       <tt>dllimport</tt> attribute. On Microsoft Windows targets, the pointer
@@ -664,9 +684,9 @@ define i32 @main() {                                              <i>; i32()* </
       (e.g. by passing things in registers).  This calling convention allows the
       target to use whatever tricks it wants to produce fast code for the
       target, without having to conform to an externally specified ABI
-      (Application Binary Interface).  Implementations of this convention should
-      allow arbitrary <a href="CodeGenerator.html#tailcallopt">tail call
-      optimization</a> to be supported.  This calling convention does not
+      (Application Binary Interface).
+      <a href="CodeGenerator.html#tailcallopt">Tail calls can only be optimized
+      when this convention is used.</a>  This calling convention does not
       support varargs and requires the prototype of all callees to exactly match
       the prototype of the function definition.</dd>
 
@@ -836,7 +856,7 @@ define i32 @main() {                                              <i>; i32()* </
 
 <p>LLVM function declarations consist of the "<tt>declare</tt>" keyword, an
    optional <a href="#linkage">linkage type</a>, an optional
-   <a href="#visibility">visibility style</a>, an optional 
+   <a href="#visibility">visibility style</a>, an optional
    <a href="#callingconv">calling convention</a>, a return type, an optional
    <a href="#paramattrs">parameter attribute</a> for the return type, a function
    name, a possibly empty list of arguments, an optional alignment, and an
@@ -897,6 +917,27 @@ define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>]
 
 </div>
 
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="namedmetadatastructure">Named Metadata</a>
+</div>
+
+<div class="doc_text">
+
+<p>Named metadata is a collection of metadata. <a href="#metadata">Metadata
+   nodes</a> (but not metadata strings) and null are the only valid operands for
+   a named metadata.</p>
+
+<h5>Syntax:</h5>
+<div class="doc_code">
+<pre>
+!1 = metadata !{metadata !"one"}
+!name = !{null, !1}
+</pre>
+</div>
+
+</div>
+
 <!-- ======================================================================= -->
 <div class="doc_subsection"><a name="paramattrs">Parameter Attributes</a></div>
 
@@ -927,24 +968,24 @@ declare signext i8 @returns_signed_char()
 <p>Currently, only the following parameter attributes are defined:</p>
 
 <dl>
-  <dt><tt>zeroext</tt></dt>
+  <dt><tt><b>zeroext</b></tt></dt>
   <dd>This indicates to the code generator that the parameter or return value
       should be zero-extended to a 32-bit value by the caller (for a parameter)
       or the callee (for a return value).</dd>
 
-  <dt><tt>signext</tt></dt>
+  <dt><tt><b>signext</b></tt></dt>
   <dd>This indicates to the code generator that the parameter or return value
       should be sign-extended to a 32-bit value by the caller (for a parameter)
       or the callee (for a return value).</dd>
 
-  <dt><tt>inreg</tt></dt>
+  <dt><tt><b>inreg</b></tt></dt>
   <dd>This indicates that this parameter or return value should be treated in a
       special target-dependent fashion during while emitting code for a function
       call or return (usually, by putting it in a register as opposed to memory,
       though some targets use it to distinguish between two different kinds of
       registers).  Use of this attribute is target-specific.</dd>
 
-  <dt><tt><a name="byval">byval</a></tt></dt>
+  <dt><tt><b><a name="byval">byval</a></b></tt></dt>
   <dd>This indicates that the pointer parameter should really be passed by value
       to the function.  The attribute implies that a hidden copy of the pointee
       is made between the caller and the callee, so the callee is unable to
@@ -959,7 +1000,7 @@ declare signext i8 @returns_signed_char()
       generator that usually indicates a desired alignment for the synthesized
       stack slot.</dd>
 
-  <dt><tt>sret</tt></dt>
+  <dt><tt><b>sret</b></tt></dt>
   <dd>This indicates that the pointer parameter specifies the address of a
       structure that is the return value of the function in the source program.
       This pointer must be guaranteed by the caller to be valid: loads and
@@ -967,7 +1008,7 @@ declare signext i8 @returns_signed_char()
       may only be applied to the first parameter. This is not a valid attribute
       for return values. </dd>
 
-  <dt><tt>noalias</tt></dt>
+  <dt><tt><b>noalias</b></tt></dt>
   <dd>This indicates that the pointer does not alias any global or any other
       parameter.  The caller is responsible for ensuring that this is the
       case. On a function return value, <tt>noalias</tt> additionally indicates
@@ -977,12 +1018,12 @@ declare signext i8 @returns_signed_char()
       <a href="http://llvm.org/docs/AliasAnalysis.html#MustMayNo">alias
       analysis</a>.</dd>
 
-  <dt><tt>nocapture</tt></dt>
+  <dt><tt><b>nocapture</b></tt></dt>
   <dd>This indicates that the callee does not make any copies of the pointer
       that outlive the callee itself. This is not a valid attribute for return
       values.</dd>
 
-  <dt><tt>nest</tt></dt>
+  <dt><tt><b>nest</b></tt></dt>
   <dd>This indicates that the pointer parameter can be excised using the
       <a href="#int_trampoline">trampoline intrinsics</a>. This is not a valid
       attribute for return values.</dd>
@@ -1002,7 +1043,7 @@ declare signext i8 @returns_signed_char()
 
 <div class="doc_code">
 <pre>
-define void @f() gc "name" { ...
+define void @f() gc "name" { ... }
 </pre>
 </div>
 
@@ -1032,42 +1073,42 @@ define void @f() gc "name" { ...
 define void @f() noinline { ... }
 define void @f() alwaysinline { ... }
 define void @f() alwaysinline optsize { ... }
-define void @f() optsize
+define void @f() optsize { ... }
 </pre>
 </div>
 
 <dl>
-  <dt><tt>alwaysinline</tt></dt>
+  <dt><tt><b>alwaysinline</b></tt></dt>
   <dd>This attribute indicates that the inliner should attempt to inline this
       function into callers whenever possible, ignoring any active inlining size
       threshold for this caller.</dd>
 
-  <dt><tt>inlinehint</tt></dt>
+  <dt><tt><b>inlinehint</b></tt></dt>
   <dd>This attribute indicates that the source code contained a hint that inlining
       this function is desirable (such as the "inline" keyword in C/C++).  It
       is just a hint; it imposes no requirements on the inliner.</dd>
 
-  <dt><tt>noinline</tt></dt>
+  <dt><tt><b>noinline</b></tt></dt>
   <dd>This attribute indicates that the inliner should never inline this
       function in any situation. This attribute may not be used together with
       the <tt>alwaysinline</tt> attribute.</dd>
 
-  <dt><tt>optsize</tt></dt>
+  <dt><tt><b>optsize</b></tt></dt>
   <dd>This attribute suggests that optimization passes and code generator passes
       make choices that keep the code size of this function low, and otherwise
       do optimizations specifically to reduce code size.</dd>
 
-  <dt><tt>noreturn</tt></dt>
+  <dt><tt><b>noreturn</b></tt></dt>
   <dd>This function attribute indicates that the function never returns
       normally.  This produces undefined behavior at runtime if the function
       ever does dynamically return.</dd>
 
-  <dt><tt>nounwind</tt></dt>
+  <dt><tt><b>nounwind</b></tt></dt>
   <dd>This function attribute indicates that the function never returns with an
       unwind or exceptional control flow.  If the function does unwind, its
       runtime behavior is undefined.</dd>
 
-  <dt><tt>readnone</tt></dt>
+  <dt><tt><b>readnone</b></tt></dt>
   <dd>This attribute indicates that the function computes its result (or decides
       to unwind an exception) based strictly on its arguments, without
       dereferencing any pointer arguments or otherwise accessing any mutable
@@ -1078,7 +1119,7 @@ define void @f() optsize
       exceptions by calling the <tt>C++</tt> exception throwing methods, but
       could use the <tt>unwind</tt> instruction.</dd>
 
-  <dt><tt><a name="readonly">readonly</a></tt></dt>
+  <dt><tt><b><a name="readonly">readonly</a></b></tt></dt>
   <dd>This attribute indicates that the function does not write through any
       pointer arguments (including <tt><a href="#byval">byval</a></tt>
       arguments) or otherwise modify any state (e.g. memory, control registers,
@@ -1089,7 +1130,7 @@ define void @f() optsize
       exception by calling the <tt>C++</tt> exception throwing methods, but may
       use the <tt>unwind</tt> instruction.</dd>
 
-  <dt><tt><a name="ssp">ssp</a></tt></dt>
+  <dt><tt><b><a name="ssp">ssp</a></b></tt></dt>
   <dd>This attribute indicates that the function should emit a stack smashing
       protector. It is in the form of a "canary"&mdash;a random value placed on
       the stack before the local variables that's checked upon return from the
@@ -1100,7 +1141,7 @@ define void @f() optsize
       function that doesn't have an <tt>ssp</tt> attribute, then the resulting
       function will have an <tt>ssp</tt> attribute.</dd>
 
-  <dt><tt>sspreq</tt></dt>
+  <dt><tt><b>sspreq</b></tt></dt>
   <dd>This attribute indicates that the function should <em>always</em> emit a
       stack smashing protector. This overrides
       the <tt><a href="#ssp">ssp</a></tt> function attribute.<br>
@@ -1110,14 +1151,14 @@ define void @f() optsize
       an <tt>ssp</tt> attribute, then the resulting function will have
       an <tt>sspreq</tt> attribute.</dd>
 
-  <dt><tt>noredzone</tt></dt>
+  <dt><tt><b>noredzone</b></tt></dt>
   <dd>This attribute indicates that the code generator should not use a red
       zone, even if the target-specific ABI normally permits it.</dd>
 
-  <dt><tt>noimplicitfloat</tt></dt>
+  <dt><tt><b>noimplicitfloat</b></tt></dt>
   <dd>This attributes disables implicit floating point instructions.</dd>
 
-  <dt><tt>naked</tt></dt>
+  <dt><tt><b>naked</b></tt></dt>
   <dd>This attribute disables prologue / epilogue emission for the function.
       This can have very system-specific consequences.</dd>
 </dl>
@@ -1185,7 +1226,7 @@ target datalayout = "<i>layout specification</i>"
       location.</dd>
 
   <dt><tt>p:<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
-  <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and 
+  <dd>This specifies the <i>size</i> of a pointer and its <i>abi</i> and
       <i>preferred</i> alignments. All sizes are in bits. Specifying
       the <i>pref</i> alignment is optional. If omitted, the
       preceding <tt>:</tt> should be omitted too.</dd>
@@ -1195,11 +1236,11 @@ target datalayout = "<i>layout specification</i>"
       <i>size</i>. The value of <i>size</i> must be in the range [1,2^23).</dd>
 
   <dt><tt>v<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
-  <dd>This specifies the alignment for a vector type of a given bit 
+  <dd>This specifies the alignment for a vector type of a given bit
       <i>size</i>.</dd>
 
   <dt><tt>f<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
-  <dd>This specifies the alignment for a floating point type of a given bit 
+  <dd>This specifies the alignment for a floating point type of a given bit
       <i>size</i>. The value of <i>size</i> must be either 32 (float) or 64
       (double).</dd>
 
@@ -1210,6 +1251,13 @@ target datalayout = "<i>layout specification</i>"
   <dt><tt>s<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
   <dd>This specifies the alignment for a stack object of a given bit
       <i>size</i>.</dd>
+
+  <dt><tt>n<i>size1</i>:<i>size2</i>:<i>size3</i>...</tt></dt>
+  <dd>This specifies a set of native integer widths for the target CPU
+      in bits.  For example, it might contain "n32" for 32-bit PowerPC,
+      "n32:64" for PowerPC 64, or "n8:16:32:64" for X86-64.  Elements of
+      this set are considered to support most general arithmetic
+      operations efficiently.</dd>
 </dl>
 
 <p>When constructing the data layout for a given target, LLVM starts with a
@@ -1380,7 +1428,7 @@ Classifications</a> </div>
 
 <p>The <a href="#t_firstclass">first class</a> types are perhaps the most
    important.  Values of these types are the only ones which can be produced by
-   instructions, passed as arguments, or used as operands to instructions.</p>
+   instructions.</p>
 
 </div>
 
@@ -1394,6 +1442,42 @@ Classifications</a> </div>
 
 </div>
 
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div>
+
+<div class="doc_text">
+
+<h5>Overview:</h5>
+<p>The integer type is a very simple type that simply specifies an arbitrary
+   bit width for the integer type desired. Any bit width from 1 bit to
+   2<sup>23</sup>-1 (about 8 million) can be specified.</p>
+
+<h5>Syntax:</h5>
+<pre>
+  iN
+</pre>
+
+<p>The number of bits the integer will occupy is specified by the <tt>N</tt>
+   value.</p>
+
+<h5>Examples:</h5>
+<table class="layout">
+  <tr class="layout">
+    <td class="left"><tt>i1</tt></td>
+    <td class="left">a single-bit integer.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>i32</tt></td>
+    <td class="left">a 32-bit integer.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>i1942652</tt></td>
+    <td class="left">a really big integer of over 1 million bits.</td>
+  </tr>
+</table>
+
+</div>
+
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsubsection"> <a name="t_floating">Floating Point Types</a> </div>
 
@@ -1448,9 +1532,9 @@ Classifications</a> </div>
 <div class="doc_text">
 
 <h5>Overview:</h5>
-<p>The metadata type represents embedded metadata. The only derived type that
-   may contain metadata is <tt>metadata*</tt> or a function type that returns or
-   takes metadata typed parameters, but not pointer to metadata types.</p>
+<p>The metadata type represents embedded metadata. No derived types may be
+   created from metadata except for <a href="#t_function">function</a>
+   arguments.
 
 <h5>Syntax:</h5>
 <pre>
@@ -1467,49 +1551,10 @@ Classifications</a> </div>
 
 <p>The real power in LLVM comes from the derived types in the system.  This is
    what allows a programmer to represent arrays, functions, pointers, and other
-   useful types.  Note that these derived types may be recursive: For example,
-   it is possible to have a two dimensional array.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection"> <a name="t_integer">Integer Type</a> </div>
-
-<div class="doc_text">
-
-<h5>Overview:</h5>
-<p>The integer type is a very simple derived type that simply specifies an
-   arbitrary bit width for the integer type desired. Any bit width from 1 bit to
-   2^23-1 (about 8 million) can be specified.</p>
-
-<h5>Syntax:</h5>
-<pre>
-  iN
-</pre>
-
-<p>The number of bits the integer will occupy is specified by the <tt>N</tt>
-   value.</p>
-
-<h5>Examples:</h5>
-<table class="layout">
-  <tr class="layout">
-    <td class="left"><tt>i1</tt></td>
-    <td class="left">a single-bit integer.</td>
-  </tr>
-  <tr class="layout">
-    <td class="left"><tt>i32</tt></td>
-    <td class="left">a 32-bit integer.</td>
-  </tr>
-  <tr class="layout">
-    <td class="left"><tt>i1942652</tt></td>
-    <td class="left">a really big integer of over 1 million bits.</td>
-  </tr>
-</table>
-
-<p>Note that the code generator does not yet support large integer types to be
-   used as function return types. The specific limit on how large a return type
-   the code generator can currently handle is target-dependent; currently it's
-   often 64 bits for 32-bit targets and 128 bits for 64-bit targets.</p>
+   useful types.  Each of these types contain one or more element types which
+   may be a primitive type, or another derived type.  For example, it is
+   possible to have a two dimensional array, using an array as the element type
+   of another array.</p>
 
 </div>
 
@@ -1562,17 +1607,12 @@ Classifications</a> </div>
   </tr>
 </table>
 
-<p>Note that 'variable sized arrays' can be implemented in LLVM with a zero
-   length array.  Normally, accesses past the end of an array are undefined in
-   LLVM (e.g. it is illegal to access the 5th element of a 3 element array).  As
-   a special case, however, zero length arrays are recognized to be variable
-   length.  This allows implementation of 'pascal style arrays' with the LLVM
-   type "<tt>{ i32, [0 x float]}</tt>", for example.</p>
-
-<p>Note that the code generator does not yet support large aggregate types to be
-   used as function return types. The specific limit on how large an aggregate
-   return type the code generator can currently handle is target-dependent, and
-   also dependent on the aggregate element types.</p>
+<p>There is no restriction on indexing beyond the end of the array implied by
+   a static type (though there are restrictions on indexing beyond the bounds
+   of an allocated object in some cases). This means that single-dimension
+   'variable sized array' addressing can be implemented in LLVM with a zero
+   length array type. An implementation of 'pascal style arrays' in LLVM could
+   use the type "<tt>{ i32, [0 x float]}</tt>", for example.</p>
 
 </div>
 
@@ -1590,7 +1630,7 @@ Classifications</a> </div>
 
 <h5>Syntax:</h5>
 <pre>
-  &lt;returntype list&gt; (&lt;parameter list&gt;)
+  &lt;returntype&gt; (&lt;parameter list&gt;)
 </pre>
 
 <p>...where '<tt>&lt;parameter list&gt;</tt>' is a comma-separated list of type
@@ -1598,8 +1638,8 @@ Classifications</a> </div>
    which indicates that the function takes a variable number of arguments.
    Variable argument functions can access their arguments with
    the <a href="#int_varargs">variable argument handling intrinsic</a>
-   functions.  '<tt>&lt;returntype list&gt;</tt>' is a comma-separated list of
-   <a href="#t_firstclass">first class</a> type specifiers.</p>
+   functions.  '<tt>&lt;returntype&gt;</tt>' is a any type except
+   <a href="#t_label">label</a>.</p>
 
 <h5>Examples:</h5>
 <table class="layout">
@@ -1610,22 +1650,22 @@ Classifications</a> </div>
   </tr><tr class="layout">
     <td class="left"><tt>float&nbsp;(i16&nbsp;signext,&nbsp;i32&nbsp;*)&nbsp;*
     </tt></td>
-    <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes 
-      an <tt>i16</tt> that should be sign extended and a 
-      <a href="#t_pointer">pointer</a> to <tt>i32</tt>, returning 
+    <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
+      an <tt>i16</tt> that should be sign extended and a
+      <a href="#t_pointer">pointer</a> to <tt>i32</tt>, returning
       <tt>float</tt>.
     </td>
   </tr><tr class="layout">
     <td class="left"><tt>i32 (i8*, ...)</tt></td>
-    <td class="left">A vararg function that takes at least one 
-      <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C), 
-      which returns an integer.  This is the signature for <tt>printf</tt> in 
+    <td class="left">A vararg function that takes at least one
+      <a href="#t_pointer">pointer</a> to <tt>i8 </tt> (char in C),
+      which returns an integer.  This is the signature for <tt>printf</tt> in
       LLVM.
     </td>
   </tr><tr class="layout">
     <td class="left"><tt>{i32, i32} (i32)</tt></td>
-    <td class="left">A function taking an <tt>i32</tt>, returning two 
-        <tt>i32</tt> values as an aggregate of type <tt>{ i32, i32 }</tt>
+    <td class="left">A function taking an <tt>i32</tt>, returning a
+        <a href="#t_struct">structure</a> containing two <tt>i32</tt> values
     </td>
   </tr>
 </table>
@@ -1643,10 +1683,12 @@ Classifications</a> </div>
    underlying processor.  The elements of a structure may be any type that has a
    size.</p>
 
-<p>Structures are accessed using '<tt><a href="#i_load">load</a></tt> and
-   '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field with
-   the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
-
+<p>Structures in memory are accessed using '<tt><a href="#i_load">load</a></tt>'
+   and '<tt><a href="#i_store">store</a></tt>' by getting a pointer to a field
+   with the '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.
+   Structures in registers are accessed using the
+   '<tt><a href="#i_extractvalue">extractvalue</a></tt>' and
+   '<tt><a href="#i_insertvalue">insertvalue</a></tt>' instructions.</p>
 <h5>Syntax:</h5>
 <pre>
   { &lt;type list&gt; }
@@ -1666,11 +1708,6 @@ Classifications</a> </div>
   </tr>
 </table>
 
-<p>Note that the code generator does not yet support large aggregate types to be
-   used as function return types. The specific limit on how large an aggregate
-   return type the code generator can currently handle is target-dependent, and
-   also dependent on the aggregate element types.</p>
-
 </div>
 
 <!-- _______________________________________________________________________ -->
@@ -1761,8 +1798,7 @@ Classifications</a> </div>
 <p>A vector type is a simple derived type that represents a vector of elements.
    Vector types are used when multiple primitive data are operated in parallel
    using a single instruction (SIMD).  A vector type requires a size (number of
-   elements) and an underlying primitive data type.  Vectors must have a power
-   of two length (1, 2, 4, 8, 16 ...).  Vector types are considered
+   elements) and an underlying primitive data type.  Vector types are considered
    <a href="#t_firstclass">first class</a>.</p>
 
 <h5>Syntax:</h5>
@@ -1789,11 +1825,6 @@ Classifications</a> </div>
   </tr>
 </table>
 
-<p>Note that the code generator does not yet support large vector types to be
-   used as function return types. The specific limit on how large a vector
-   return type codegen can currently handle is target-dependent; currently it's
-   often a few times longer than a hardware vector register.</p>
-
 </div>
 
 <!-- _______________________________________________________________________ -->
@@ -1888,7 +1919,7 @@ Classifications</a> </div>
 <dl>
   <dt><b>Boolean constants</b></dt>
   <dd>The two strings '<tt>true</tt>' and '<tt>false</tt>' are both valid
-      constants of the <tt><a href="#t_primitive">i1</a></tt> type.</dd>
+      constants of the <tt><a href="#t_integer">i1</a></tt> type.</dd>
 
   <dt><b>Integer constants</b></dt>
   <dd>Standard integers (such as '4') are constants of
@@ -2017,11 +2048,11 @@ Classifications</a> </div>
 <div class="doc_text">
 
 <p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and
-   indicates that the user of the value may recieve an unspecified bit-pattern.
+   indicates that the user of the value may receive an unspecified bit-pattern.
    Undefined values may be of any type (other than label or void) and be used
    anywhere a constant is permitted.</p>
 
-<p>Undefined values are useful, because it indicates to the compiler that the
+<p>Undefined values are useful because they indicate to the compiler that the
    program is well defined no matter what value is used.  This gives the
    compiler more freedom to optimize.  Here are some examples of (potentially
    surprising) transformations that are valid (in pseudo IR):</p>
@@ -2058,10 +2089,11 @@ Unsafe:
 <p>These logical operations have bits that are not always affected by the input.
 For example, if "%X" has a zero bit, then the output of the 'and' operation will
 always be a zero, no matter what the corresponding bit from the undef is.  As
-such, it is unsafe to optimizer or assume that the result of the and is undef.
-However, it is safe to assume that all bits of the undef are 0, and optimize the
-and to 0.  Likewise, it is safe to assume that all the bits of the undef operand
-to the or could be set, allowing the or to be folded to -1.</p>
+such, it is unsafe to optimize or assume that the result of the and is undef.
+However, it is safe to assume that all bits of the undef could be 0, and
+optimize the and to 0.  Likewise, it is safe to assume that all the bits of
+the undef operand to the or could be set, allowing the or to be folded to
+-1.</p>
 
 <div class="doc_code">
 <pre>
@@ -2090,7 +2122,7 @@ the optimizer is allowed to assume that the undef operand could be the same as
 <div class="doc_code">
 <pre>
   %A = xor undef, undef
-  
+
   %B = undef
   %C = xor %B, %B
 
@@ -2115,12 +2147,79 @@ number of reasons, but the short answer is that an undef "variable" can
 arbitrarily change its value over its "live range".  This is true because the
 "variable" doesn't actually <em>have a live range</em>.  Instead, the value is
 logically read from arbitrary registers that happen to be around when needed,
-so the value is not neccesarily consistent over time.  In fact, %A and %C need
-to have the same semantics of the core LLVM "replace all uses with" concept
+so the value is not necessarily consistent over time.  In fact, %A and %C need
+to have the same semantics or the core LLVM "replace all uses with" concept
 would not hold.</p>
-  
+
+<div class="doc_code">
+<pre>
+  %A = fdiv undef, %X
+  %B = fdiv %X, undef
+Safe:
+  %A = undef
+b: unreachable
+</pre>
 </div>
 
+<p>These examples show the crucial difference between an <em>undefined
+value</em> and <em>undefined behavior</em>.  An undefined value (like undef) is
+allowed to have an arbitrary bit-pattern.  This means that the %A operation
+can be constant folded to undef because the undef could be an SNaN, and fdiv is
+not (currently) defined on SNaN's.  However, in the second example, we can make
+a more aggressive assumption: because the undef is allowed to be an arbitrary
+value, we are allowed to assume that it could be zero.  Since a divide by zero
+has <em>undefined behavior</em>, we are allowed to assume that the operation
+does not execute at all.  This allows us to delete the divide and all code after
+it: since the undefined operation "can't happen", the optimizer can assume that
+it occurs in dead code.
+</p>
+
+<div class="doc_code">
+<pre>
+a:  store undef -> %X
+b:  store %X -> undef
+Safe:
+a: &lt;deleted&gt;
+b: unreachable
+</pre>
+</div>
+
+<p>These examples reiterate the fdiv example: a store "of" an undefined value
+can be assumed to not have any effect: we can assume that the value is
+overwritten with bits that happen to match what was already there.  However, a
+store "to" an undefined location could clobber arbitrary memory, therefore, it
+has undefined behavior.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="blockaddress">Addresses of Basic
+    Blocks</a></div>
+<div class="doc_text">
+
+<p><b><tt>blockaddress(@function, %block)</tt></b></p>
+
+<p>The '<tt>blockaddress</tt>' constant computes the address of the specified
+   basic block in the specified function, and always has an i8* type.  Taking
+   the address of the entry block is illegal.</p>
+
+<p>This value only has defined behavior when used as an operand to the
+   '<a href="#i_indirectbr"><tt>indirectbr</tt></a>' instruction or for comparisons
+   against null.  Pointer equality tests between labels addresses is undefined
+   behavior - though, again, comparison against null is ok, and no label is
+   equal to the null pointer.  This may also be passed around as an opaque
+   pointer sized value as long as the bits are not inspected.  This allows
+   <tt>ptrtoint</tt> and arithmetic to be performed on these values so long as
+   the original value is reconstituted before the <tt>indirectbr</tt>.</p>
+
+<p>Finally, some targets may provide defined semantics when
+   using the value as the operand to an inline assembly, but that is target
+   specific.
+   </p>
+
+</div>
+
+
 <!-- ======================================================================= -->
 <div class="doc_subsection"><a name="constantexprs">Constant Expressions</a>
 </div>
@@ -2241,38 +2340,6 @@ would not hold.</p>
 
 </div>
 
-<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="metadata">Embedded Metadata</a>
-</div>
-
-<div class="doc_text">
-
-<p>Embedded metadata provides a way to attach arbitrary data to the instruction
-   stream without affecting the behaviour of the program.  There are two
-   metadata primitives, strings and nodes. All metadata has the
-   <tt>metadata</tt> type and is identified in syntax by a preceding exclamation
-   point ('<tt>!</tt>').</p>
-
-<p>A metadata string is a string surrounded by double quotes.  It can contain
-   any character by escaping non-printable characters with "\xx" where "xx" is
-   the two digit hex code.  For example: "<tt>!"test\00"</tt>".</p>
-
-<p>Metadata nodes are represented with notation similar to structure constants
-   (a comma separated list of elements, surrounded by braces and preceeded by an
-   exclamation point).  For example: "<tt>!{ metadata !"test\00", i32
-   10}</tt>".</p>
-
-<p>A metadata node will attempt to track changes to the values it holds. In the
-   event that a value is deleted, it will be replaced with a typeless
-   "<tt>null</tt>", such as "<tt>metadata !{null, i32 10}</tt>".</p>
-
-<p>Optimizations may rely on metadata to provide additional information about
-   the program that isn't available in the instructions, or that isn't easily
-   computable. Similarly, the code generator may expect a certain metadata
-   format to be used to express debugging information.</p>
-
-</div>
-
 <!-- *********************************************************************** -->
 <div class="doc_section"> <a name="othervalues">Other Values</a> </div>
 <!-- *********************************************************************** -->
@@ -2288,8 +2355,10 @@ would not hold.</p>
    to <a href="#moduleasm"> Module-Level Inline Assembly</a>) through the use of
    a special value.  This value represents the inline assembler as a string
    (containing the instructions to emit), a list of operand constraints (stored
-   as a string), and a flag that indicates whether or not the inline asm
-   expression has side effects.  An example inline assembler expression is:</p>
+   as a string), a flag that indicates whether or not the inline asm
+   expression has side effects, and a flag indicating whether the function
+   containing the asm needs to align its stack conservatively.  An example
+   inline assembler expression is:</p>
 
 <div class="doc_code">
 <pre>
@@ -2317,6 +2386,22 @@ call void asm sideeffect "eieio", ""()
 </pre>
 </div>
 
+<p>In some cases inline asms will contain code that will not work unless the
+   stack is aligned in some way, such as calls or SSE instructions on x86,
+   yet will not contain code that does that alignment within the asm.
+   The compiler should make conservative assumptions about what the asm might
+   contain and should generate its usual stack alignment code in the prologue
+   if the '<tt>alignstack</tt>' keyword is present:</p>
+
+<div class="doc_code">
+<pre>
+call void asm alignstack "eieio", ""()
+</pre>
+</div>
+
+<p>If both keywords appear the '<tt>sideeffect</tt>' keyword must come
+   first.</p>
+
 <p>TODO: The format of the asm and constraints string still need to be
    documented here.  Constraints on what can be done (e.g. duplication, moving,
    etc need to be documented).  This is probably best done by reference to
@@ -2324,6 +2409,35 @@ call void asm sideeffect "eieio", ""()
 
 </div>
 
+<!-- ======================================================================= -->
+<div class="doc_subsection"><a name="metadata">Metadata Nodes and Metadata
+  Strings</a>
+</div>
+
+<div class="doc_text">
+
+<p>LLVM IR allows metadata to be attached to instructions in the program that
+   can convey extra information about the code to the optimizers and code
+   generator.  One example application of metadata is source-level debug
+   information.  There are two metadata primitives: strings and nodes. All
+   metadata has the <tt>metadata</tt> type and is identified in syntax by a
+   preceding exclamation point ('<tt>!</tt>').</p>
+
+<p>A metadata string is a string surrounded by double quotes.  It can contain
+   any character by escaping non-printable characters with "\xx" where "xx" is
+   the two digit hex code.  For example: "<tt>!"test\00"</tt>".</p>
+
+<p>Metadata nodes are represented with notation similar to structure constants
+   (a comma separated list of elements, surrounded by braces and preceded by an
+   exclamation point).  For example: "<tt>!{ metadata !"test\00", i32
+   10}</tt>".  Metadata nodes can have any values as their operand.</p>
+
+<p>A <a href="#namedmetadatastructure">named metadata</a> is a collection of 
+   metadata nodes, which can be looked up in the module symbol table. For
+   example: "<tt>!foo =  metadata !{!4, !3}</tt>".
+
+</div>
+
 
 <!-- *********************************************************************** -->
 <div class="doc_section">
@@ -2445,6 +2559,7 @@ Instructions</a> </div>
    '<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, the
+   '<a href="#i_indirectbr">'<tt>indirectbr</tt></a>' Instruction, the
    '<a href="#i_invoke"><tt>invoke</tt></a>' instruction, the
    '<a href="#i_unwind"><tt>unwind</tt></a>' instruction, and the
    '<a href="#i_unreachable"><tt>unreachable</tt></a>' instruction.</p>
@@ -2499,14 +2614,6 @@ Instruction</a> </div>
   ret { i32, i8 } { i32 4, i8 2 } <i>; Return a struct of values 4 and 2</i>
 </pre>
 
-<p>Note that the code generator does not yet fully support large
-   return values. The specific sizes that are currently supported are
-   dependent on the target. For integers, on 32-bit targets the limit
-   is often 64 bits, and on 64-bit targets the limit is often 128 bits.
-   For aggregate types, the current limits are dependent on the element
-   types; for example targets are often limited to 2 total integer
-   elements and 2 total floating-point elements.</p>
-
 </div>
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsubsection"> <a name="i_br">'<tt>br</tt>' Instruction</a> </div>
@@ -2577,8 +2684,8 @@ IfUnequal:
 <p>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, control flow is
-   transfered to the corresponding destination; otherwise, control flow is
-   transfered to the default destination.</p>
+   transferred to the corresponding destination; otherwise, control flow is
+   transferred to the default destination.</p>
 
 <h5>Implementation:</h5>
 <p>Depending on properties of the target machine and the particular
@@ -2603,6 +2710,55 @@ IfUnequal:
 
 </div>
 
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+   <a name="i_indirectbr">'<tt>indirectbr</tt>' Instruction</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  indirectbr &lt;somety&gt;* &lt;address&gt;, [ label &lt;dest1&gt;, label &lt;dest2&gt;, ... ]
+</pre>
+
+<h5>Overview:</h5>
+
+<p>The '<tt>indirectbr</tt>' instruction implements an indirect branch to a label
+   within the current function, whose address is specified by
+   "<tt>address</tt>".  Address must be derived from a <a
+   href="#blockaddress">blockaddress</a> constant.</p>
+
+<h5>Arguments:</h5>
+
+<p>The '<tt>address</tt>' argument is the address of the label to jump to.  The
+   rest of the arguments indicate the full set of possible destinations that the
+   address may point to.  Blocks are allowed to occur multiple times in the
+   destination list, though this isn't particularly useful.</p>
+
+<p>This destination list is required so that dataflow analysis has an accurate
+   understanding of the CFG.</p>
+
+<h5>Semantics:</h5>
+
+<p>Control transfers to the block specified in the address argument.  All
+   possible destination blocks must be listed in the label list, otherwise this
+   instruction has undefined behavior.  This implies that jumps to labels
+   defined in other functions have undefined behavior as well.</p>
+
+<h5>Implementation:</h5>
+
+<p>This is typically implemented with a jump through a register.</p>
+
+<h5>Example:</h5>
+<pre>
+ indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
+</pre>
+
+</div>
+
+
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsubsection">
   <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
@@ -2678,6 +2834,9 @@ IfUnequal:
    block to the "normal" label. If the callee unwinds then no return value is
    available.</p>
 
+<p>Note that the code generator does not yet completely support unwind, and
+that the invoke/unwind semantics are likely to change in future versions.</p>
+
 <h5>Example:</h5>
 <pre>
   %retval = invoke i32 @Test(i32 15) to label %Continue
@@ -2714,6 +2873,9 @@ Instruction</a> </div>
    specified by the <tt>invoke</tt> instruction.  If there is no <tt>invoke</tt>
    instruction in the dynamic call chain, undefined behavior results.</p>
 
+<p>Note that the code generator does not yet completely support unwind, and
+that the invoke/unwind semantics are likely to change in future versions.</p>
+
 </div>
 
 <!-- _______________________________________________________________________ -->
@@ -2937,7 +3099,7 @@ Instruction</a> </div>
 <p>The two arguments to the '<tt>mul</tt>' instruction must
    be <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
    integer values.  Both arguments must have identical types.</p>
+
 <h5>Semantics:</h5>
 <p>The value produced is the integer product of the two operands.</p>
 
@@ -3009,7 +3171,7 @@ Instruction</a> </div>
 <p>The '<tt>udiv</tt>' instruction returns the quotient of its two operands.</p>
 
 <h5>Arguments:</h5>
-<p>The two arguments to the '<tt>udiv</tt>' instruction must be 
+<p>The two arguments to the '<tt>udiv</tt>' instruction must be
    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
    values.  Both arguments must have identical types.</p>
 
@@ -3044,7 +3206,7 @@ Instruction</a> </div>
 <p>The '<tt>sdiv</tt>' instruction returns the quotient of its two operands.</p>
 
 <h5>Arguments:</h5>
-<p>The two arguments to the '<tt>sdiv</tt>' instruction must be 
+<p>The two arguments to the '<tt>sdiv</tt>' instruction must be
    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
    values.  Both arguments must have identical types.</p>
 
@@ -3115,7 +3277,7 @@ Instruction</a> </div>
    division of its two arguments.</p>
 
 <h5>Arguments:</h5>
-<p>The two arguments to the '<tt>urem</tt>' instruction must be 
+<p>The two arguments to the '<tt>urem</tt>' instruction must be
    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
    values.  Both arguments must have identical types.</p>
 
@@ -3155,7 +3317,7 @@ Instruction</a> </div>
    elements must be integers.</p>
 
 <h5>Arguments:</h5>
-<p>The two arguments to the '<tt>srem</tt>' instruction must be 
+<p>The two arguments to the '<tt>srem</tt>' instruction must be
    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
    values.  Both arguments must have identical types.</p>
 
@@ -3250,7 +3412,7 @@ Instruction</a> </div>
 <p>Both arguments to the '<tt>shl</tt>' instruction must be the
     same <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of
     integer type.  '<tt>op2</tt>' is treated as an unsigned value.</p>
+
 <h5>Semantics:</h5>
 <p>The value produced is <tt>op1</tt> * 2<sup><tt>op2</tt></sup> mod
    2<sup>n</sup>, where <tt>n</tt> is the width of the result.  If <tt>op2</tt>
@@ -3286,7 +3448,7 @@ Instruction</a> </div>
    operand shifted to the right a specified number of bits with zero fill.</p>
 
 <h5>Arguments:</h5>
-<p>Both arguments to the '<tt>lshr</tt>' instruction must be the same 
+<p>Both arguments to the '<tt>lshr</tt>' instruction must be the same
    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
    type. '<tt>op2</tt>' is treated as an unsigned value.</p>
 
@@ -3326,7 +3488,7 @@ Instruction</a> </div>
    extension.</p>
 
 <h5>Arguments:</h5>
-<p>Both arguments to the '<tt>ashr</tt>' instruction must be the same 
+<p>Both arguments to the '<tt>ashr</tt>' instruction must be the same
    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
    type.  '<tt>op2</tt>' is treated as an unsigned value.</p>
 
@@ -3366,7 +3528,7 @@ Instruction</a> </div>
    operands.</p>
 
 <h5>Arguments:</h5>
-<p>The two arguments to the '<tt>and</tt>' instruction must be 
+<p>The two arguments to the '<tt>and</tt>' instruction must be
    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
    values.  Both arguments must have identical types.</p>
 
@@ -3425,7 +3587,7 @@ Instruction</a> </div>
    two operands.</p>
 
 <h5>Arguments:</h5>
-<p>The two arguments to the '<tt>or</tt>' instruction must be 
+<p>The two arguments to the '<tt>or</tt>' instruction must be
    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
    values.  Both arguments must have identical types.</p>
 
@@ -3488,7 +3650,7 @@ Instruction</a> </div>
    complement" operation, which is the "~" operator in C.</p>
 
 <h5>Arguments:</h5>
-<p>The two arguments to the '<tt>xor</tt>' instruction must be 
+<p>The two arguments to the '<tt>xor</tt>' instruction must be
    <a href="#t_integer">integer</a> or <a href="#t_vector">vector</a> of integer
    values.  Both arguments must have identical types.</p>
 
@@ -3536,7 +3698,7 @@ Instruction</a> </div>
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection"> 
+<div class="doc_subsection">
   <a name="vectorops">Vector Operations</a>
 </div>
 
@@ -3582,7 +3744,7 @@ Instruction</a> </div>
 
 <h5>Example:</h5>
 <pre>
-  %result = extractelement &lt;4 x i32&gt; %vec, i32 0    <i>; yields i32</i>
+  &lt;result&gt; = extractelement &lt;4 x i32&gt; %vec, i32 0    <i>; yields i32</i>
 </pre>
 
 </div>
@@ -3618,7 +3780,7 @@ Instruction</a> </div>
 
 <h5>Example:</h5>
 <pre>
-  %result = insertelement &lt;4 x i32&gt; %vec, i32 1, i32 0    <i>; yields &lt;4 x i32&gt;</i>
+  &lt;result&gt; = insertelement &lt;4 x i32&gt; %vec, i32 1, i32 0    <i>; yields &lt;4 x i32&gt;</i>
 </pre>
 
 </div>
@@ -3659,20 +3821,20 @@ Instruction</a> </div>
 
 <h5>Example:</h5>
 <pre>
-  %result = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2, 
+  &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2,
                           &lt;4 x i32&gt; &lt;i32 0, i32 4, i32 1, i32 5&gt;  <i>; yields &lt;4 x i32&gt;</i>
-  %result = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; undef, 
+  &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; undef,
                           &lt;4 x i32&gt; &lt;i32 0, i32 1, i32 2, i32 3&gt;  <i>; yields &lt;4 x i32&gt;</i> - Identity shuffle.
-  %result = shufflevector &lt;8 x i32&gt; %v1, &lt;8 x i32&gt; undef, 
+  &lt;result&gt; = shufflevector &lt;8 x i32&gt; %v1, &lt;8 x i32&gt; undef,
                           &lt;4 x i32&gt; &lt;i32 0, i32 1, i32 2, i32 3&gt;  <i>; yields &lt;4 x i32&gt;</i>
-  %result = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2, 
+  &lt;result&gt; = shufflevector &lt;4 x i32&gt; %v1, &lt;4 x i32&gt; %v2,
                           &lt;8 x i32&gt; &lt;i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 &gt;  <i>; yields &lt;8 x i32&gt;</i>
 </pre>
 
 </div>
 
 <!-- ======================================================================= -->
-<div class="doc_subsection"> 
+<div class="doc_subsection">
   <a name="aggregateops">Aggregate Operations</a>
 </div>
 
@@ -3711,7 +3873,7 @@ Instruction</a> </div>
 
 <h5>Example:</h5>
 <pre>
-  %result = extractvalue {i32, float} %agg, 0    <i>; yields i32</i>
+  &lt;result&gt; = extractvalue {i32, float} %agg, 0    <i>; yields i32</i>
 </pre>
 
 </div>
@@ -3725,7 +3887,7 @@ Instruction</a> </div>
 
 <h5>Syntax:</h5>
 <pre>
-  &lt;result&gt; = insertvalue &lt;aggregate type&gt; &lt;val&gt;, &lt;ty&gt; &lt;val&gt;, &lt;idx&gt;    <i>; yields &lt;n x &lt;ty&gt;&gt;</i>
+  &lt;result&gt; = insertvalue &lt;aggregate type&gt; &lt;val&gt;, &lt;ty&gt; &lt;elt&gt;, &lt;idx&gt;    <i>; yields &lt;aggregate type&gt;</i>
 </pre>
 
 <h5>Overview:</h5>
@@ -3750,14 +3912,15 @@ Instruction</a> </div>
 
 <h5>Example:</h5>
 <pre>
-  %result = insertvalue {i32, float} %agg, i32 1, 0    <i>; yields {i32, float}</i>
+  %agg1 = insertvalue {i32, float} undef, i32 1, 0         <i>; yields {i32 1, float undef}</i>
+  %agg2 = insertvalue {i32, float} %agg1, float %val, 1    <i>; yields {i32 1, float %val}</i>
 </pre>
 
 </div>
 
 
 <!-- ======================================================================= -->
-<div class="doc_subsection"> 
+<div class="doc_subsection">
   <a name="memoryops">Memory Access and Addressing Operations</a>
 </div>
 
@@ -3765,93 +3928,11 @@ Instruction</a> </div>
 
 <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
+   very simple.  This section describes how to read, write, and allocate
    memory in LLVM.</p>
 
 </div>
 
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
-  <a name="i_malloc">'<tt>malloc</tt>' Instruction</a>
-</div>
-
-<div class="doc_text">
-
-<h5>Syntax:</h5>
-<pre>
-  &lt;result&gt; = malloc &lt;type&gt;[, i32 &lt;NumElements&gt;][, align &lt;alignment&gt;]     <i>; yields {type*}:result</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>malloc</tt>' instruction allocates memory from the system heap and
-   returns a pointer to it. The object is always allocated in the generic
-   address space (address space zero).</p>
-
-<h5>Arguments:</h5>
-<p>The '<tt>malloc</tt>' instruction allocates
-   <tt>sizeof(&lt;type&gt;)*NumElements</tt> bytes of memory from the operating
-   system and returns a pointer of the appropriate type to the program.  If
-   "NumElements" is specified, it is the number of elements allocated, otherwise
-   "NumElements" is defaulted to be one.  If a constant alignment is specified,
-   the value result of the allocation is guaranteed to be aligned to at least
-   that boundary.  If not specified, or if zero, the target can choose to align
-   the allocation on any convenient boundary compatible with the type.</p>
-
-<p>'<tt>type</tt>' must be a sized type.</p>
-
-<h5>Semantics:</h5>
-<p>Memory is allocated using the system "<tt>malloc</tt>" function, and a
-   pointer is returned.  The result of a zero byte allocation is undefined.  The
-   result is null if there is insufficient memory available.</p>
-
-<h5>Example:</h5>
-<pre>
-  %array  = malloc [4 x i8]                     <i>; yields {[%4 x i8]*}:array</i>
-
-  %size   = <a href="#i_add">add</a> i32 2, 2                        <i>; yields {i32}:size = i32 4</i>
-  %array1 = malloc i8, i32 4                    <i>; yields {i8*}:array1</i>
-  %array2 = malloc [12 x i8], i32 %size         <i>; yields {[12 x i8]*}:array2</i>
-  %array3 = malloc i32, i32 4, align 1024       <i>; yields {i32*}:array3</i>
-  %array4 = malloc i32, align 1024              <i>; yields {i32*}:array4</i>
-</pre>
-
-<p>Note that the code generator does not yet respect the alignment value.</p>
-
-</div>
-
-<!-- _______________________________________________________________________ -->
-<div class="doc_subsubsection">
-  <a name="i_free">'<tt>free</tt>' Instruction</a>
-</div>
-
-<div class="doc_text">
-
-<h5>Syntax:</h5>
-<pre>
-  free &lt;type&gt; &lt;value&gt;                           <i>; yields {void}</i>
-</pre>
-
-<h5>Overview:</h5>
-<p>The '<tt>free</tt>' instruction returns memory back to the unused memory heap
-   to be reallocated in the future.</p>
-
-<h5>Arguments:</h5>
-<p>'<tt>value</tt>' shall be a pointer value that points to a value that was
-   allocated with the '<tt><a href="#i_malloc">malloc</a></tt>' instruction.</p>
-
-<h5>Semantics:</h5>
-<p>Access to the memory pointed to by the pointer is no longer defined after
-   this instruction executes.  If the pointer is null, the operation is a
-   noop.</p>
-
-<h5>Example:</h5>
-<pre>
-  %array  = <a href="#i_malloc">malloc</a> [4 x i8]                     <i>; yields {[4 x i8]*}:array</i>
-            free   [4 x i8]* %array
-</pre>
-
-</div>
-
 <!-- _______________________________________________________________________ -->
 <div class="doc_subsubsection">
   <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
@@ -4185,7 +4266,7 @@ entry:
 <pre>
   %X = trunc i32 257 to i8              <i>; yields i8:1</i>
   %Y = trunc i32 123 to i1              <i>; yields i1:true</i>
-  %Y = trunc i32 122 to i1              <i>; yields i1:false</i>
+  %Z = trunc i32 122 to i1              <i>; yields i1:false</i>
 </pre>
 
 </div>
@@ -4202,15 +4283,15 @@ entry:
 </pre>
 
 <h5>Overview:</h5>
-<p>The '<tt>zext</tt>' instruction zero extends its operand to type 
+<p>The '<tt>zext</tt>' instruction zero extends its operand to type
    <tt>ty2</tt>.</p>
 
 
 <h5>Arguments:</h5>
-<p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of 
+<p>The '<tt>zext</tt>' instruction takes a value to cast, which must be of
    <a href="#t_integer">integer</a> type, and a type to cast it to, which must
    also be of <a href="#t_integer">integer</a> type. The bit size of the
-   <tt>value</tt> must be smaller than the bit size of the destination type, 
+   <tt>value</tt> must be smaller than the bit size of the destination type,
    <tt>ty2</tt>.</p>
 
 <h5>Semantics:</h5>
@@ -4242,10 +4323,10 @@ entry:
 <p>The '<tt>sext</tt>' sign extends <tt>value</tt> to the type <tt>ty2</tt>.</p>
 
 <h5>Arguments:</h5>
-<p>The '<tt>sext</tt>' instruction takes a value to cast, which must be of 
+<p>The '<tt>sext</tt>' instruction takes a value to cast, which must be of
    <a href="#t_integer">integer</a> type, and a type to cast it to, which must
    also be of <a href="#t_integer">integer</a> type.  The bit size of the
-   <tt>value</tt> must be smaller than the bit size of the destination type, 
+   <tt>value</tt> must be smaller than the bit size of the destination type,
    <tt>ty2</tt>.</p>
 
 <h5>Semantics:</h5>
@@ -4283,12 +4364,12 @@ entry:
 <p>The '<tt>fptrunc</tt>' instruction takes a <a href="#t_floating">floating
    point</a> value to cast and a <a href="#t_floating">floating point</a> type
    to cast it to. The size of <tt>value</tt> must be larger than the size of
-   <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a 
+   <tt>ty2</tt>. This implies that <tt>fptrunc</tt> cannot be used to make a
    <i>no-op cast</i>.</p>
 
 <h5>Semantics:</h5>
 <p>The '<tt>fptrunc</tt>' instruction truncates a <tt>value</tt> from a larger
-   <a href="#t_floating">floating point</a> type to a smaller 
+   <a href="#t_floating">floating point</a> type to a smaller
    <a href="#t_floating">floating point</a> type.  If the value cannot fit
    within the destination type, <tt>ty2</tt>, then the results are
    undefined.</p>
@@ -4317,7 +4398,7 @@ entry:
    floating point value.</p>
 
 <h5>Arguments:</h5>
-<p>The '<tt>fpext</tt>' instruction takes a 
+<p>The '<tt>fpext</tt>' instruction takes a
    <a href="#t_floating">floating point</a> <tt>value</tt> to cast, and
    a <a href="#t_floating">floating point</a> type to cast it to. The source
    type must be smaller than the destination type.</p>
@@ -4360,7 +4441,7 @@ entry:
    vector integer type with the same number of elements as <tt>ty</tt></p>
 
 <h5>Semantics:</h5>
-<p>The '<tt>fptoui</tt>' instruction converts its 
+<p>The '<tt>fptoui</tt>' instruction converts its
    <a href="#t_floating">floating point</a> operand into the nearest (rounding
    towards zero) unsigned integer value. If the value cannot fit
    in <tt>ty2</tt>, the results are undefined.</p>
@@ -4369,7 +4450,7 @@ entry:
 <pre>
   %X = fptoui double 123.0 to i32      <i>; yields i32:123</i>
   %Y = fptoui float 1.0E+300 to i1     <i>; yields undefined:1</i>
-  %X = fptoui float 1.04E+17 to i8     <i>; yields undefined:1</i>
+  %Z = fptoui float 1.04E+17 to i8     <i>; yields undefined:1</i>
 </pre>
 
 </div>
@@ -4386,7 +4467,7 @@ entry:
 </pre>
 
 <h5>Overview:</h5>
-<p>The '<tt>fptosi</tt>' instruction converts 
+<p>The '<tt>fptosi</tt>' instruction converts
    <a href="#t_floating">floating point</a> <tt>value</tt> to
    type <tt>ty2</tt>.</p>
 
@@ -4398,7 +4479,7 @@ entry:
    vector integer type with the same number of elements as <tt>ty</tt></p>
 
 <h5>Semantics:</h5>
-<p>The '<tt>fptosi</tt>' instruction converts its 
+<p>The '<tt>fptosi</tt>' instruction converts its
    <a href="#t_floating">floating point</a> operand into the nearest (rounding
    towards zero) signed integer value. If the value cannot fit in <tt>ty2</tt>,
    the results are undefined.</p>
@@ -4407,7 +4488,7 @@ entry:
 <pre>
   %X = fptosi double -123.0 to i32      <i>; yields i32:-123</i>
   %Y = fptosi float 1.0E-247 to i1      <i>; yields undefined:1</i>
-  %X = fptosi float 1.04E+17 to i8      <i>; yields undefined:1</i>
+  %Z = fptosi float 1.04E+17 to i8      <i>; yields undefined:1</i>
 </pre>
 
 </div>
@@ -4551,8 +4632,8 @@ entry:
 <h5>Example:</h5>
 <pre>
   %X = inttoptr i32 255 to i32*          <i>; yields zero extension on 64-bit architecture</i>
-  %X = inttoptr i32 255 to i32*          <i>; yields no-op on 32-bit architecture</i>
-  %Y = inttoptr i64 0 to i32*            <i>; yields truncation on 32-bit architecture</i>
+  %Y = inttoptr i32 255 to i32*          <i>; yields no-op on 32-bit architecture</i>
+  %Z = inttoptr i64 0 to i32*            <i>; yields truncation on 32-bit architecture</i>
 </pre>
 
 </div>
@@ -4595,7 +4676,7 @@ entry:
 <pre>
   %X = bitcast i8 255 to i8              <i>; yields i8 :-1</i>
   %Y = bitcast i32* %x to sint*          <i>; yields sint*:%x</i>
-  %Z = bitcast &lt;2 x int&gt; %V to i64;      <i>; yields i64: %V</i>   
+  %Z = bitcast &lt;2 x int&gt; %V to i64;      <i>; yields i64: %V</i>
 </pre>
 
 </div>
@@ -4651,15 +4732,15 @@ entry:
 <h5>Semantics:</h5>
 <p>The '<tt>icmp</tt>' compares <tt>op1</tt> and <tt>op2</tt> according to the
    condition code given as <tt>cond</tt>. The comparison performed always yields
-   either an <a href="#t_primitive"><tt>i1</tt></a> or vector of <tt>i1</tt>
+   either an <a href="#t_integer"><tt>i1</tt></a> or vector of <tt>i1</tt>
    result, as follows:</p>
 
 <ol>
-  <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal, 
+  <li><tt>eq</tt>: yields <tt>true</tt> if the operands are equal,
       <tt>false</tt> otherwise. No sign interpretation is necessary or
       performed.</li>
 
-  <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal, 
+  <li><tt>ne</tt>: yields <tt>true</tt> if the operands are unequal,
       <tt>false</tt> otherwise. No sign interpretation is necessary or
       performed.</li>
 
@@ -4728,7 +4809,7 @@ entry:
    values based on comparison of its operands.</p>
 
 <p>If the operands are floating point scalars, then the result type is a boolean
-(<a href="#t_primitive"><tt>i1</tt></a>).</p>
+(<a href="#t_integer"><tt>i1</tt></a>).</p>
 
 <p>If the operands are floating point vectors, then the result type is a vector
    of boolean with the same number of elements as the operands being
@@ -4770,48 +4851,48 @@ entry:
 <p>The '<tt>fcmp</tt>' instruction compares <tt>op1</tt> and <tt>op2</tt>
    according to the condition code given as <tt>cond</tt>.  If the operands are
    vectors, then the vectors are compared element by element.  Each comparison
-   performed always yields an <a href="#t_primitive">i1</a> result, as
+   performed always yields an <a href="#t_integer">i1</a> result, as
    follows:</p>
 
 <ol>
   <li><tt>false</tt>: always yields <tt>false</tt>, regardless of operands.</li>
 
-  <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and 
+  <li><tt>oeq</tt>: yields <tt>true</tt> if both operands are not a QNAN and
       <tt>op1</tt> is equal to <tt>op2</tt>.</li>
 
   <li><tt>ogt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
       <tt>op1</tt> is greather than <tt>op2</tt>.</li>
 
-  <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and 
+  <li><tt>oge</tt>: yields <tt>true</tt> if both operands are not a QNAN and
       <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
 
-  <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and 
+  <li><tt>olt</tt>: yields <tt>true</tt> if both operands are not a QNAN and
       <tt>op1</tt> is less than <tt>op2</tt>.</li>
 
-  <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and 
+  <li><tt>ole</tt>: yields <tt>true</tt> if both operands are not a QNAN and
       <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
 
-  <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and 
+  <li><tt>one</tt>: yields <tt>true</tt> if both operands are not a QNAN and
       <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
 
   <li><tt>ord</tt>: yields <tt>true</tt> if both operands are not a QNAN.</li>
 
-  <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or 
+  <li><tt>ueq</tt>: yields <tt>true</tt> if either operand is a QNAN or
       <tt>op1</tt> is equal to <tt>op2</tt>.</li>
 
-  <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or 
+  <li><tt>ugt</tt>: yields <tt>true</tt> if either operand is a QNAN or
       <tt>op1</tt> is greater than <tt>op2</tt>.</li>
 
-  <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or 
+  <li><tt>uge</tt>: yields <tt>true</tt> if either operand is a QNAN or
       <tt>op1</tt> is greater than or equal to <tt>op2</tt>.</li>
 
-  <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or 
+  <li><tt>ult</tt>: yields <tt>true</tt> if either operand is a QNAN or
       <tt>op1</tt> is less than <tt>op2</tt>.</li>
 
-  <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or 
+  <li><tt>ule</tt>: yields <tt>true</tt> if either operand is a QNAN or
       <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
 
-  <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or 
+  <li><tt>une</tt>: yields <tt>true</tt> if either operand is a QNAN or
       <tt>op1</tt> is not equal to <tt>op2</tt>.</li>
 
   <li><tt>uno</tt>: yields <tt>true</tt> if either operand is a QNAN.</li>
@@ -4942,15 +5023,31 @@ Loop:       ; Infinite loop that counts from 0 on up...
 <p>This instruction requires several arguments:</p>
 
 <ol>
-  <li>The optional "tail" marker indicates whether the callee function accesses
-      any allocas or varargs in the caller.  If the "tail" marker is present,
-      the function call is eligible for tail call optimization.  Note that calls
-      may be marked "tail" even if they do not occur before
-      a <a href="#i_ret"><tt>ret</tt></a> instruction.</li>
+  <li>The optional "tail" marker indicates that the callee function does not
+      access any allocas or varargs in the caller.  Note that calls may be
+      marked "tail" even if they do not occur before
+      a <a href="#i_ret"><tt>ret</tt></a> instruction.  If the "tail" marker is
+      present, the function call is eligible for tail call optimization,
+      but <a href="CodeGenerator.html#tailcallopt">might not in fact be
+      optimized into a jump</a>.  As of this writing, the extra requirements for
+      a call to actually be optimized are:
+      <ul>
+        <li>Caller and callee both have the calling
+            convention <tt>fastcc</tt>.</li>
+        <li>The call is in tail position (ret immediately follows call and ret
+            uses value of call or is void).</li>
+        <li>Option <tt>-tailcallopt</tt> is enabled,
+            or <code>llvm::PerformTailCallOpt</code> is <code>true</code>.</li>
+        <li><a href="CodeGenerator.html#tailcallopt">Platform specific
+            constraints are met.</a></li>
+      </ul>
+  </li>
 
   <li>The optional "cconv" marker indicates which <a href="#callingconv">calling
       convention</a> the call should use.  If none is specified, the call
-      defaults to using C calling conventions.</li>
+      defaults to using C calling conventions.  The calling convention of the
+      call must match the calling convention of the target function, or else the
+      behavior is undefined.</li>
 
   <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
       return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
@@ -5005,6 +5102,12 @@ Loop:       ; Infinite loop that counts from 0 on up...
   %ZZ = call zeroext i32 @bar()                     <i>; Return value is %zero extended</i>
 </pre>
 
+<p>llvm treats calls to some functions with names and arguments that match the
+standard C99 library as being the C99 library functions, and may perform
+optimizations or generate code for them under that assumption.  This is
+something we'd like to change in the future to provide better support for
+freestanding environments and non-C-based langauges.</p>
+
 </div>
 
 <!-- _______________________________________________________________________ -->
@@ -5097,7 +5200,7 @@ Loop:       ; Infinite loop that counts from 0 on up...
    suffix is required. Because the argument's type is matched against the return
    type, it does not require its own name suffix.</p>
 
-<p>To learn how to add an intrinsic function, please see the 
+<p>To learn how to add an intrinsic function, please see the
    <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p>
 
 </div>
@@ -6532,11 +6635,11 @@ LLVM</a>.</p>
 <ul>
   <li><tt>ll</tt>: All loads before the barrier must complete before any load
       after the barrier begins.</li>
-  <li><tt>ls</tt>: All loads before the barrier must complete before any 
+  <li><tt>ls</tt>: All loads before the barrier must complete before any
       store after the barrier begins.</li>
-  <li><tt>ss</tt>: All stores before the barrier must complete before any 
+  <li><tt>ss</tt>: All stores before the barrier must complete before any
       store after the barrier begins.</li>
-  <li><tt>sl</tt>: All stores before the barrier must complete before any 
+  <li><tt>sl</tt>: All stores before the barrier must complete before any
       load after the barrier begins.</li>
 </ul>
 
@@ -6550,7 +6653,8 @@ LLVM</a>.</p>
 
 <h5>Example:</h5>
 <pre>
-%ptr      = malloc i32
+%mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr      = bitcast i8* %mallocP to i32*
             store i32 4, %ptr
 
 %result1  = load i32* %ptr      <i>; yields {i32}:result1 = 4</i>
@@ -6601,7 +6705,8 @@ LLVM</a>.</p>
 
 <h5>Examples:</h5>
 <pre>
-%ptr      = malloc i32
+%mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr      = bitcast i8* %mallocP to i32*
             store i32 4, %ptr
 
 %val1     = add i32 4, 4
@@ -6656,7 +6761,8 @@ LLVM</a>.</p>
 
 <h5>Examples:</h5>
 <pre>
-%ptr      = malloc i32
+%mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr      = bitcast i8* %mallocP to i32*
             store i32 4, %ptr
 
 %val1     = add i32 4, 4
@@ -6711,8 +6817,9 @@ LLVM</a>.</p>
 
 <h5>Examples:</h5>
 <pre>
-%ptr      = malloc i32
-        store i32 4, %ptr
+%mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr      = bitcast i8* %mallocP to i32*
+            store i32 4, %ptr
 %result1  = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 4 )
                                 <i>; yields {i32}:result1 = 4</i>
 %result2  = call i32 @llvm.atomic.load.add.i32.p0i32( i32* %ptr, i32 2 )
@@ -6745,7 +6852,7 @@ LLVM</a>.</p>
 </pre>
 
 <h5>Overview:</h5>
-<p>This intrinsic subtracts <tt>delta</tt> to the value stored in memory at 
+<p>This intrinsic subtracts <tt>delta</tt> to the value stored in memory at
    <tt>ptr</tt>. It yields the original value at <tt>ptr</tt>.</p>
 
 <h5>Arguments:</h5>
@@ -6762,8 +6869,9 @@ LLVM</a>.</p>
 
 <h5>Examples:</h5>
 <pre>
-%ptr      = malloc i32
-        store i32 8, %ptr
+%mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr      = bitcast i8* %mallocP to i32*
+            store i32 8, %ptr
 %result1  = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 4 )
                                 <i>; yields {i32}:result1 = 8</i>
 %result2  = call i32 @llvm.atomic.load.sub.i32.p0i32( i32* %ptr, i32 2 )
@@ -6839,8 +6947,9 @@ LLVM</a>.</p>
 
 <h5>Examples:</h5>
 <pre>
-%ptr      = malloc i32
-        store i32 0x0F0F, %ptr
+%mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr      = bitcast i8* %mallocP to i32*
+            store i32 0x0F0F, %ptr
 %result0  = call i32 @llvm.atomic.load.nand.i32.p0i32( i32* %ptr, i32 0xFF )
                                 <i>; yields {i32}:result0 = 0x0F0F</i>
 %result1  = call i32 @llvm.atomic.load.and.i32.p0i32( i32* %ptr, i32 0xFF )
@@ -6899,7 +7008,7 @@ LLVM</a>.</p>
 </pre>
 
 <h5>Overview:</h5>
-<p>These intrinsics takes the signed or unsigned minimum or maximum of 
+<p>These intrinsics takes the signed or unsigned minimum or maximum of
    <tt>delta</tt> and the value stored in memory at <tt>ptr</tt>. It yields the
    original value at <tt>ptr</tt>.</p>
 
@@ -6917,8 +7026,9 @@ LLVM</a>.</p>
 
 <h5>Examples:</h5>
 <pre>
-%ptr      = malloc i32
-        store i32 7, %ptr
+%mallocP  = tail call i8* @malloc(i32 ptrtoint (i32* getelementptr (i32* null, i32 1) to i32))
+%ptr      = bitcast i8* %mallocP to i32*
+            store i32 7, %ptr
 %result0  = call i32 @llvm.atomic.load.min.i32.p0i32( i32* %ptr, i32 -2 )
                                 <i>; yields {i32}:result0 = 7</i>
 %result1  = call i32 @llvm.atomic.load.max.i32.p0i32( i32* %ptr, i32 8 )
@@ -6932,6 +7042,133 @@ LLVM</a>.</p>
 
 </div>
 
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="int_memorymarkers">Memory Use Markers</a>
+</div>
+
+<div class="doc_text">
+
+<p>This class of intrinsics exists to information about the lifetime of memory
+   objects and ranges where variables are immutable.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.lifetime.start(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.lifetime.start</tt>' intrinsic specifies the start of a memory
+   object's lifetime.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is a constant integer representing the size of the
+   object, or -1 if it is variable sized.  The second argument is a pointer to
+   the object.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic indicates that before this point in the code, the value of the
+   memory pointed to by <tt>ptr</tt> is dead.  This means that it is known to
+   never be used and has an undefined value.  A load from the pointer that
+   precedes this intrinsic can be replaced with
+   <tt>'<a href="#undefvalues">undef</a>'</tt>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.lifetime.end(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.lifetime.end</tt>' intrinsic specifies the end of a memory
+   object's lifetime.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is a constant integer representing the size of the
+   object, or -1 if it is variable sized.  The second argument is a pointer to
+   the object.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic indicates that after this point in the code, the value of the
+   memory pointed to by <tt>ptr</tt> is dead.  This means that it is known to
+   never be used and has an undefined value.  Any stores into the memory object
+   following this intrinsic may be removed as dead.
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  declare {}* @llvm.invariant.start(i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;) readonly
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.invariant.start</tt>' intrinsic specifies that the contents of
+   a memory object will not change.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is a constant integer representing the size of the
+   object, or -1 if it is variable sized.  The second argument is a pointer to
+   the object.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic indicates that until an <tt>llvm.invariant.end</tt> that uses
+   the return value, the referenced memory location is constant and
+   unchanging.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.invariant.end({}* &lt;start&gt;, i64 &lt;size&gt;, i8* nocapture &lt;ptr&gt;)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.invariant.end</tt>' intrinsic specifies that the contents of
+   a memory object are mutable.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is the matching <tt>llvm.invariant.start</tt> intrinsic.
+   The second argument is a constant integer representing the size of the
+   object, or -1 if it is variable sized and the third argument is a pointer
+   to the object.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic indicates that the memory is mutable again.</p>
+
+</div>
+
 <!-- ======================================================================= -->
 <div class="doc_subsection">
   <a name="int_general">General Intrinsics</a>
@@ -7067,6 +7304,42 @@ LLVM</a>.</p>
 
 </div>
 
+<!-- _______________________________________________________________________ -->
+<div class="doc_subsubsection">
+  <a name="int_objectsize">'<tt>llvm.objectsize</tt>' Intrinsic</a>
+</div>
+
+<div class="doc_text">
+
+<h5>Syntax:</h5>
+<pre>
+  declare i32 @llvm.objectsize.i32( i8* &lt;object&gt;, i1 &lt;type&gt; )
+  declare i64 @llvm.objectsize.i64( i8* &lt;object&gt;, i1 &lt;type&gt; )
+</pre>
+
+<h5>Overview:</h5>
+<p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information
+   to the optimizers to discover at compile time either a) when an
+   operation like memcpy will either overflow a buffer that corresponds to
+   an object, or b) to determine that a runtime check for overflow isn't
+   necessary. An object in this context means an allocation of a
+   specific class, structure, array, or other object.</p>
+
+<h5>Arguments:</h5>
+<p>The <tt>llvm.objectsize</tt> intrinsic takes two arguments.  The first
+   argument is a pointer to or into the <tt>object</tt>. The second argument
+   is a boolean 0 or 1.  This argument determines whether you want the 
+   maximum (0) or minimum (1) bytes remaining.  This needs to be a literal 0 or
+   1, variables are not allowed.</p>
+   
+<h5>Semantics:</h5>
+<p>The <tt>llvm.objectsize</tt> intrinsic is lowered to either a constant
+   representing the size of the object concerned or <tt>i32/i64 -1 or 0</tt>
+   (depending on the <tt>type</tt> argument if the size cannot be determined
+   at compile time.</p>
+
+</div>
+
 <!-- *********************************************************************** -->
 <hr>
 <address>