[llvm-commits] [www-releases] r170845 [2/55] - in /www-releases/trunk/3.2/docs: ./ CommandGuide/ HistoricalNotes/ _static/ _templates/ _themes/ _themes/llvm-theme/ _themes/llvm-theme/static/ doxygen/ doxygen/html/ llvm-theme/ llvm-theme/static/ tutorial/

Tanya Lattner tonic at nondot.org
Thu Dec 20 22:58:17 PST 2012


Added: www-releases/trunk/3.2/docs/GetElementPtr.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/GetElementPtr.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/GetElementPtr.rst (added)
+++ www-releases/trunk/3.2/docs/GetElementPtr.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,538 @@
+.. _gep:
+
+=======================================
+The Often Misunderstood GEP Instruction
+=======================================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document seeks to dispel the mystery and confusion surrounding LLVM's
+`GetElementPtr <LangRef.html#i_getelementptr>`_ (GEP) instruction.  Questions
+about the wily GEP instruction are probably the most frequently occurring
+questions once a developer gets down to coding with LLVM. Here we lay out the
+sources of confusion and show that the GEP instruction is really quite simple.
+
+Address Computation
+===================
+
+When people are first confronted with the GEP instruction, they tend to relate
+it to known concepts from other programming paradigms, most notably C array
+indexing and field selection. GEP closely resembles C array indexing and field
+selection, however it's is a little different and this leads to the following
+questions.
+
+What is the first index of the GEP instruction?
+-----------------------------------------------
+
+Quick answer: The index stepping through the first operand.
+
+The confusion with the first index usually arises from thinking about the
+GetElementPtr instruction as if it was a C index operator. They aren't the
+same. For example, when we write, in "C":
+
+.. code-block:: c++
+
+  AType *Foo;
+  ...
+  X = &Foo->F;
+
+it is natural to think that there is only one index, the selection of the field
+``F``.  However, in this example, ``Foo`` is a pointer. That pointer
+must be indexed explicitly in LLVM. C, on the other hand, indices through it
+transparently.  To arrive at the same address location as the C code, you would
+provide the GEP instruction with two index operands. The first operand indexes
+through the pointer; the second operand indexes the field ``F`` of the
+structure, just as if you wrote:
+
+.. code-block:: c++
+
+  X = &Foo[0].F;
+
+Sometimes this question gets rephrased as:
+
+.. _GEP index through first pointer:
+
+  *Why is it okay to index through the first pointer, but subsequent pointers
+  won't be dereferenced?*
+
+The answer is simply because memory does not have to be accessed to perform the
+computation. The first operand to the GEP instruction must be a value of a
+pointer type. The value of the pointer is provided directly to the GEP
+instruction as an operand without any need for accessing memory. It must,
+therefore be indexed and requires an index operand. Consider this example:
+
+.. code-block:: c++
+
+  struct munger_struct {
+    int f1;
+    int f2;
+  };
+  void munge(struct munger_struct *P) {
+    P[0].f1 = P[1].f1 + P[2].f2;
+  }
+  ...
+  munger_struct Array[3];
+  ...
+  munge(Array);
+
+In this "C" example, the front end compiler (llvm-gcc) will generate three GEP
+instructions for the three indices through "P" in the assignment statement.  The
+function argument ``P`` will be the first operand of each of these GEP
+instructions.  The second operand indexes through that pointer.  The third
+operand will be the field offset into the ``struct munger_struct`` type, for
+either the ``f1`` or ``f2`` field. So, in LLVM assembly the ``munge`` function
+looks like:
+
+.. code-block:: llvm
+
+  void %munge(%struct.munger_struct* %P) {
+  entry:
+    %tmp = getelementptr %struct.munger_struct* %P, i32 1, i32 0
+    %tmp = load i32* %tmp
+    %tmp6 = getelementptr %struct.munger_struct* %P, i32 2, i32 1
+    %tmp7 = load i32* %tmp6
+    %tmp8 = add i32 %tmp7, %tmp
+    %tmp9 = getelementptr %struct.munger_struct* %P, i32 0, i32 0
+    store i32 %tmp8, i32* %tmp9
+    ret void
+  }
+
+In each case the first operand is the pointer through which the GEP instruction
+starts. The same is true whether the first operand is an argument, allocated
+memory, or a global variable.
+
+To make this clear, let's consider a more obtuse example:
+
+.. code-block:: llvm
+
+  %MyVar = uninitialized global i32
+  ...
+  %idx1 = getelementptr i32* %MyVar, i64 0
+  %idx2 = getelementptr i32* %MyVar, i64 1
+  %idx3 = getelementptr i32* %MyVar, i64 2
+
+These GEP instructions are simply making address computations from the base
+address of ``MyVar``.  They compute, as follows (using C syntax):
+
+.. code-block:: c++
+
+  idx1 = (char*) &MyVar + 0
+  idx2 = (char*) &MyVar + 4
+  idx3 = (char*) &MyVar + 8
+
+Since the type ``i32`` is known to be four bytes long, the indices 0, 1 and 2
+translate into memory offsets of 0, 4, and 8, respectively. No memory is
+accessed to make these computations because the address of ``%MyVar`` is passed
+directly to the GEP instructions.
+
+The obtuse part of this example is in the cases of ``%idx2`` and ``%idx3``. They
+result in the computation of addresses that point to memory past the end of the
+``%MyVar`` global, which is only one ``i32`` long, not three ``i32``\s long.
+While this is legal in LLVM, it is inadvisable because any load or store with
+the pointer that results from these GEP instructions would produce undefined
+results.
+
+Why is the extra 0 index required?
+----------------------------------
+
+Quick answer: there are no superfluous indices.
+
+This question arises most often when the GEP instruction is applied to a global
+variable which is always a pointer type. For example, consider this:
+
+.. code-block:: llvm
+
+  %MyStruct = uninitialized global { float*, i32 }
+  ...
+  %idx = getelementptr { float*, i32 }* %MyStruct, i64 0, i32 1
+
+The GEP above yields an ``i32*`` by indexing the ``i32`` typed field of the
+structure ``%MyStruct``. When people first look at it, they wonder why the ``i64
+0`` index is needed. However, a closer inspection of how globals and GEPs work
+reveals the need. Becoming aware of the following facts will dispel the
+confusion:
+
+#. The type of ``%MyStruct`` is *not* ``{ float*, i32 }`` but rather ``{ float*,
+   i32 }*``. That is, ``%MyStruct`` is a pointer to a structure containing a
+   pointer to a ``float`` and an ``i32``.
+
+#. Point #1 is evidenced by noticing the type of the first operand of the GEP
+   instruction (``%MyStruct``) which is ``{ float*, i32 }*``.
+
+#. The first index, ``i64 0`` is required to step over the global variable
+   ``%MyStruct``.  Since the first argument to the GEP instruction must always
+   be a value of pointer type, the first index steps through that pointer. A
+   value of 0 means 0 elements offset from that pointer.
+
+#. The second index, ``i32 1`` selects the second field of the structure (the
+   ``i32``).
+
+What is dereferenced by GEP?
+----------------------------
+
+Quick answer: nothing.
+
+The GetElementPtr instruction dereferences nothing. That is, it doesn't access
+memory in any way. That's what the Load and Store instructions are for.  GEP is
+only involved in the computation of addresses. For example, consider this:
+
+.. code-block:: llvm
+
+  %MyVar = uninitialized global { [40 x i32 ]* }
+  ...
+  %idx = getelementptr { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
+
+In this example, we have a global variable, ``%MyVar`` that is a pointer to a
+structure containing a pointer to an array of 40 ints. The GEP instruction seems
+to be accessing the 18th integer of the structure's array of ints. However, this
+is actually an illegal GEP instruction. It won't compile. The reason is that the
+pointer in the structure <i>must</i> be dereferenced in order to index into the
+array of 40 ints. Since the GEP instruction never accesses memory, it is
+illegal.
+
+In order to access the 18th integer in the array, you would need to do the
+following:
+
+.. code-block:: llvm
+
+  %idx = getelementptr { [40 x i32]* }* %, i64 0, i32 0
+  %arr = load [40 x i32]** %idx
+  %idx = getelementptr [40 x i32]* %arr, i64 0, i64 17
+
+In this case, we have to load the pointer in the structure with a load
+instruction before we can index into the array. If the example was changed to:
+
+.. code-block:: llvm
+
+  %MyVar = uninitialized global { [40 x i32 ] }
+  ...
+  %idx = getelementptr { [40 x i32] }*, i64 0, i32 0, i64 17
+
+then everything works fine. In this case, the structure does not contain a
+pointer and the GEP instruction can index through the global variable, into the
+first field of the structure and access the 18th ``i32`` in the array there.
+
+Why don't GEP x,0,0,1 and GEP x,1 alias?
+----------------------------------------
+
+Quick Answer: They compute different address locations.
+
+If you look at the first indices in these GEP instructions you find that they
+are different (0 and 1), therefore the address computation diverges with that
+index. Consider this example:
+
+.. code-block:: llvm
+
+  %MyVar = global { [10 x i32 ] }
+  %idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 0, i32 0, i64 1
+  %idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1
+
+In this example, ``idx1`` computes the address of the second integer in the
+array that is in the structure in ``%MyVar``, that is ``MyVar+4``. The type of
+``idx1`` is ``i32*``. However, ``idx2`` computes the address of *the next*
+structure after ``%MyVar``. The type of ``idx2`` is ``{ [10 x i32] }*`` and its
+value is equivalent to ``MyVar + 40`` because it indexes past the ten 4-byte
+integers in ``MyVar``. Obviously, in such a situation, the pointers don't
+alias.
+
+Why do GEP x,1,0,0 and GEP x,1 alias?
+-------------------------------------
+
+Quick Answer: They compute the same address location.
+
+These two GEP instructions will compute the same address because indexing
+through the 0th element does not change the address. However, it does change the
+type. Consider this example:
+
+.. code-block:: llvm
+
+  %MyVar = global { [10 x i32 ] }
+  %idx1 = getelementptr { [10 x i32 ] }* %MyVar, i64 1, i32 0, i64 0
+  %idx2 = getelementptr { [10 x i32 ] }* %MyVar, i64 1
+
+In this example, the value of ``%idx1`` is ``%MyVar+40`` and its type is
+``i32*``. The value of ``%idx2`` is also ``MyVar+40`` but its type is ``{ [10 x
+i32] }*``.
+
+Can GEP index into vector elements?
+-----------------------------------
+
+This hasn't always been forcefully disallowed, though it's not recommended.  It
+leads to awkward special cases in the optimizers, and fundamental inconsistency
+in the IR. In the future, it will probably be outright disallowed.
+
+What effect do address spaces have on GEPs?
+-------------------------------------------
+
+None, except that the address space qualifier on the first operand pointer type
+always matches the address space qualifier on the result type.
+
+How is GEP different from ``ptrtoint``, arithmetic, and ``inttoptr``?
+---------------------------------------------------------------------
+
+It's very similar; there are only subtle differences.
+
+With ptrtoint, you have to pick an integer type. One approach is to pick i64;
+this is safe on everything LLVM supports (LLVM internally assumes pointers are
+never wider than 64 bits in many places), and the optimizer will actually narrow
+the i64 arithmetic down to the actual pointer size on targets which don't
+support 64-bit arithmetic in most cases. However, there are some cases where it
+doesn't do this. With GEP you can avoid this problem.
+
+Also, GEP carries additional pointer aliasing rules. It's invalid to take a GEP
+from one object, address into a different separately allocated object, and
+dereference it. IR producers (front-ends) must follow this rule, and consumers
+(optimizers, specifically alias analysis) benefit from being able to rely on
+it. See the `Rules`_ section for more information.
+
+And, GEP is more concise in common cases.
+
+However, for the underlying integer computation implied, there is no
+difference.
+
+
+I'm writing a backend for a target which needs custom lowering for GEP. How do I do this?
+-----------------------------------------------------------------------------------------
+
+You don't. The integer computation implied by a GEP is target-independent.
+Typically what you'll need to do is make your backend pattern-match expressions
+trees involving ADD, MUL, etc., which are what GEP is lowered into. This has the
+advantage of letting your code work correctly in more cases.
+
+GEP does use target-dependent parameters for the size and layout of data types,
+which targets can customize.
+
+If you require support for addressing units which are not 8 bits, you'll need to
+fix a lot of code in the backend, with GEP lowering being only a small piece of
+the overall picture.
+
+How does VLA addressing work with GEPs?
+---------------------------------------
+
+GEPs don't natively support VLAs. LLVM's type system is entirely static, and GEP
+address computations are guided by an LLVM type.
+
+VLA indices can be implemented as linearized indices. For example, an expression
+like ``X[a][b][c]``, must be effectively lowered into a form like
+``X[a*m+b*n+c]``, so that it appears to the GEP as a single-dimensional array
+reference.
+
+This means if you want to write an analysis which understands array indices and
+you want to support VLAs, your code will have to be prepared to reverse-engineer
+the linearization. One way to solve this problem is to use the ScalarEvolution
+library, which always presents VLA and non-VLA indexing in the same manner.
+
+.. _Rules:
+
+Rules
+=====
+
+What happens if an array index is out of bounds?
+------------------------------------------------
+
+There are two senses in which an array index can be out of bounds.
+
+First, there's the array type which comes from the (static) type of the first
+operand to the GEP. Indices greater than the number of elements in the
+corresponding static array type are valid. There is no problem with out of
+bounds indices in this sense. Indexing into an array only depends on the size of
+the array element, not the number of elements.
+
+A common example of how this is used is arrays where the size is not known.
+It's common to use array types with zero length to represent these. The fact
+that the static type says there are zero elements is irrelevant; it's perfectly
+valid to compute arbitrary element indices, as the computation only depends on
+the size of the array element, not the number of elements. Note that zero-sized
+arrays are not a special case here.
+
+This sense is unconnected with ``inbounds`` keyword. The ``inbounds`` keyword is
+designed to describe low-level pointer arithmetic overflow conditions, rather
+than high-level array indexing rules.
+
+Analysis passes which wish to understand array indexing should not assume that
+the static array type bounds are respected.
+
+The second sense of being out of bounds is computing an address that's beyond
+the actual underlying allocated object.
+
+With the ``inbounds`` keyword, the result value of the GEP is undefined if the
+address is outside the actual underlying allocated object and not the address
+one-past-the-end.
+
+Without the ``inbounds`` keyword, there are no restrictions on computing
+out-of-bounds addresses. Obviously, performing a load or a store requires an
+address of allocated and sufficiently aligned memory. But the GEP itself is only
+concerned with computing addresses.
+
+Can array indices be negative?
+------------------------------
+
+Yes. This is basically a special case of array indices being out of bounds.
+
+Can I compare two values computed with GEPs?
+--------------------------------------------
+
+Yes. If both addresses are within the same allocated object, or
+one-past-the-end, you'll get the comparison result you expect. If either is
+outside of it, integer arithmetic wrapping may occur, so the comparison may not
+be meaningful.
+
+Can I do GEP with a different pointer type than the type of the underlying object?
+----------------------------------------------------------------------------------
+
+Yes. There are no restrictions on bitcasting a pointer value to an arbitrary
+pointer type. The types in a GEP serve only to define the parameters for the
+underlying integer computation. They need not correspond with the actual type of
+the underlying object.
+
+Furthermore, loads and stores don't have to use the same types as the type of
+the underlying object. Types in this context serve only to specify memory size
+and alignment. Beyond that there are merely a hint to the optimizer indicating
+how the value will likely be used.
+
+Can I cast an object's address to integer and add it to null?
+-------------------------------------------------------------
+
+You can compute an address that way, but if you use GEP to do the add, you can't
+use that pointer to actually access the object, unless the object is managed
+outside of LLVM.
+
+The underlying integer computation is sufficiently defined; null has a defined
+value --- zero --- and you can add whatever value you want to it.
+
+However, it's invalid to access (load from or store to) an LLVM-aware object
+with such a pointer. This includes ``GlobalVariables``, ``Allocas``, and objects
+pointed to by noalias pointers.
+
+If you really need this functionality, you can do the arithmetic with explicit
+integer instructions, and use inttoptr to convert the result to an address. Most
+of GEP's special aliasing rules do not apply to pointers computed from ptrtoint,
+arithmetic, and inttoptr sequences.
+
+Can I compute the distance between two objects, and add that value to one address to compute the other address?
+---------------------------------------------------------------------------------------------------------------
+
+As with arithmetic on null, You can use GEP to compute an address that way, but
+you can't use that pointer to actually access the object if you do, unless the
+object is managed outside of LLVM.
+
+Also as above, ptrtoint and inttoptr provide an alternative way to do this which
+do not have this restriction.
+
+Can I do type-based alias analysis on LLVM IR?
+----------------------------------------------
+
+You can't do type-based alias analysis using LLVM's built-in type system,
+because LLVM has no restrictions on mixing types in addressing, loads or stores.
+
+LLVM's type-based alias analysis pass uses metadata to describe a different type
+system (such as the C type system), and performs type-based aliasing on top of
+that.  Further details are in the `language reference <LangRef.html#tbaa>`_.
+
+What happens if a GEP computation overflows?
+--------------------------------------------
+
+If the GEP lacks the ``inbounds`` keyword, the value is the result from
+evaluating the implied two's complement integer computation. However, since
+there's no guarantee of where an object will be allocated in the address space,
+such values have limited meaning.
+
+If the GEP has the ``inbounds`` keyword, the result value is undefined (a "trap
+value") if the GEP overflows (i.e. wraps around the end of the address space).
+
+As such, there are some ramifications of this for inbounds GEPs: scales implied
+by array/vector/pointer indices are always known to be "nsw" since they are
+signed values that are scaled by the element size.  These values are also
+allowed to be negative (e.g. "``gep i32 *%P, i32 -1``") but the pointer itself
+is logically treated as an unsigned value.  This means that GEPs have an
+asymmetric relation between the pointer base (which is treated as unsigned) and
+the offset applied to it (which is treated as signed). The result of the
+additions within the offset calculation cannot have signed overflow, but when
+applied to the base pointer, there can be signed overflow.
+
+How can I tell if my front-end is following the rules?
+------------------------------------------------------
+
+There is currently no checker for the getelementptr rules. Currently, the only
+way to do this is to manually check each place in your front-end where
+GetElementPtr operators are created.
+
+It's not possible to write a checker which could find all rule violations
+statically. It would be possible to write a checker which works by instrumenting
+the code with dynamic checks though. Alternatively, it would be possible to
+write a static checker which catches a subset of possible problems. However, no
+such checker exists today.
+
+Rationale
+=========
+
+Why is GEP designed this way?
+-----------------------------
+
+The design of GEP has the following goals, in rough unofficial order of
+priority:
+
+* Support C, C-like languages, and languages which can be conceptually lowered
+  into C (this covers a lot).
+
+* Support optimizations such as those that are common in C compilers. In
+  particular, GEP is a cornerstone of LLVM's `pointer aliasing
+  model <LangRef.html#pointeraliasing>`_.
+
+* Provide a consistent method for computing addresses so that address
+  computations don't need to be a part of load and store instructions in the IR.
+
+* Support non-C-like languages, to the extent that it doesn't interfere with
+  other goals.
+
+* Minimize target-specific information in the IR.
+
+Why do struct member indices always use ``i32``?
+------------------------------------------------
+
+The specific type i32 is probably just a historical artifact, however it's wide
+enough for all practical purposes, so there's been no need to change it.  It
+doesn't necessarily imply i32 address arithmetic; it's just an identifier which
+identifies a field in a struct. Requiring that all struct indices be the same
+reduces the range of possibilities for cases where two GEPs are effectively the
+same but have distinct operand types.
+
+What's an uglygep?
+------------------
+
+Some LLVM optimizers operate on GEPs by internally lowering them into more
+primitive integer expressions, which allows them to be combined with other
+integer expressions and/or split into multiple separate integer expressions. If
+they've made non-trivial changes, translating back into LLVM IR can involve
+reverse-engineering the structure of the addressing in order to fit it into the
+static type of the original first operand. It isn't always possibly to fully
+reconstruct this structure; sometimes the underlying addressing doesn't
+correspond with the static type at all. In such cases the optimizer instead will
+emit a GEP with the base pointer casted to a simple address-unit pointer, using
+the name "uglygep". This isn't pretty, but it's just as valid, and it's
+sufficient to preserve the pointer aliasing guarantees that GEP provides.
+
+Summary
+=======
+
+In summary, here's some things to always remember about the GetElementPtr
+instruction:
+
+
+#. The GEP instruction never accesses memory, it only provides pointer
+   computations.
+
+#. The first operand to the GEP instruction is always a pointer and it must be
+   indexed.
+
+#. There are no superfluous indices for the GEP instruction.
+
+#. Trailing zero indices are superfluous for pointer aliasing, but not for the
+   types of the pointers.
+
+#. Leading zero indices are not superfluous for pointer aliasing nor the types
+   of the pointers.

Added: www-releases/trunk/3.2/docs/GettingStarted.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/GettingStarted.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/GettingStarted.rst (added)
+++ www-releases/trunk/3.2/docs/GettingStarted.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,1304 @@
+.. _getting_started:
+
+====================================
+Getting Started with the LLVM System  
+====================================
+
+Overview
+========
+
+Welcome to LLVM! In order to get started, you first need to know some basic
+information.
+
+First, LLVM comes in three pieces. The first piece is the LLVM suite. This
+contains all of the tools, libraries, and header files needed to use LLVM.  It
+contains an assembler, disassembler, bitcode analyzer and bitcode optimizer.  It
+also contains basic regression tests that can be used to test the LLVM tools and
+the Clang front end.
+
+The second piece is the `Clang <http://clang.llvm.org/>`_ front end.  This
+component compiles C, C++, Objective C, and Objective C++ code into LLVM
+bitcode. Once compiled into LLVM bitcode, a program can be manipulated with the
+LLVM tools from the LLVM suite.
+
+There is a third, optional piece called Test Suite.  It is a suite of programs
+with a testing harness that can be used to further test LLVM's functionality
+and performance.
+
+Getting Started Quickly (A Summary)
+===================================
+
+The LLVM Getting Started documentation may be out of date.  So, the `Clang
+Getting Started <http://clang.llvm.org/get_started.html>`_ page might also be a
+good place to start.
+
+Here's the short story for getting up and running quickly with LLVM:
+
+#. Read the documentation.
+#. Read the documentation.
+#. Remember that you were warned twice about reading the documentation.
+#. Checkout LLVM:
+
+   * ``cd where-you-want-llvm-to-live``
+   * ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
+
+#. Checkout Clang:
+
+   * ``cd where-you-want-llvm-to-live``
+   * ``cd llvm/tools``
+   * ``svn co http://llvm.org/svn/llvm-project/cfe/trunk clang``
+
+#. Checkout Compiler-RT:
+
+   * ``cd where-you-want-llvm-to-live``
+   * ``cd llvm/projects``
+   * ``svn co http://llvm.org/svn/llvm-project/compiler-rt/trunk compiler-rt``
+
+#. Get the Test Suite Source Code **[Optional]**
+
+   * ``cd where-you-want-llvm-to-live``
+   * ``cd llvm/projects``
+   * ``svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite``
+
+#. Configure and build LLVM and Clang:
+
+   * ``cd where-you-want-to-build-llvm``
+   * ``mkdir build`` (for building without polluting the source dir)
+   * ``cd build``
+   * ``../llvm/configure [options]``
+     Some common options:
+
+     * ``--prefix=directory`` ---
+
+       Specify for *directory* the full pathname of where you want the LLVM
+       tools and libraries to be installed (default ``/usr/local``).
+
+     * ``--enable-optimized`` ---
+
+       Compile with optimizations enabled (default is NO).
+
+     * ``--enable-assertions`` ---
+
+       Compile with assertion checks enabled (default is YES).
+
+   * ``make [-j]`` --- The ``-j`` specifies the number of jobs (commands) to run
+     simultaneously.  This builds both LLVM and Clang for Debug+Asserts mode.
+     The --enabled-optimized configure option is used to specify a Release
+     build.
+
+   * ``make check-all`` --- This run the regression tests to ensure everything
+     is in working order.
+  
+   * ``make update`` --- This command is used to update all the svn repositories
+     at once, rather then having to ``cd`` into the individual repositories and
+     running ``svn update``.
+
+   * It is also possible to use CMake instead of the makefiles. With CMake it is
+     also possible to generate project files for several IDEs: Eclipse CDT4,
+     CodeBlocks, Qt-Creator (use the CodeBlocks generator), KDevelop3.
+
+   * If you get an "internal compiler error (ICE)" or test failures, see
+     `below`.
+
+Consult the `Getting Started with LLVM`_ section for detailed information on
+configuring and compiling LLVM.  See `Setting Up Your Environment`_ for tips
+that simplify working with the Clang front end and LLVM tools.  Go to `Program
+Layout`_ to learn about the layout of the source code tree.
+
+Requirements
+============
+
+Before you begin to use the LLVM system, review the requirements given below.
+This may save you some trouble by knowing ahead of time what hardware and
+software you will need.
+
+Hardware
+--------
+
+LLVM is known to work on the following platforms:
+
++-----------------+----------------------+-------------------------+
+|OS               |  Arch                | Compilers               |
++=================+======================+=========================+
+|AuroraUX         | x86\ :sup:`1`        | GCC                     |
++-----------------+----------------------+-------------------------+
+|Linux            | x86\ :sup:`1`        | GCC                     |
++-----------------+----------------------+-------------------------+
+|Linux            | amd64                | GCC                     |
++-----------------+----------------------+-------------------------+
+|Solaris          | V9 (Ultrasparc)      | GCC                     |
++-----------------+----------------------+-------------------------+
+|FreeBSD          | x86\ :sup:`1`        | GCC                     |
++-----------------+----------------------+-------------------------+
+|FreeBSD          | amd64                | GCC                     |
++-----------------+----------------------+-------------------------+
+|MacOS X\ :sup:`2`| PowerPC              | GCC                     |
++-----------------+----------------------+-------------------------+
+|MacOS X\ :sup:`9`| x86                  | GCC                     |
++-----------------+----------------------+-------------------------+
+|Cygwin/Win32     | x86\ :sup:`1, 8, 11` | GCC 3.4.X, binutils 2.20|
++-----------------+----------------------+-------------------------+
+
+LLVM has partial support for the following platforms:
+
++-------------------+----------------------+-------------------------------------------+
+|OS                 |  Arch                | Compilers                                 |
++===================+======================+===========================================+
+| Windows           | x86\ :sup:`1`        | Visual Studio 2000 or higher\ :sup:`4,5`  |
++-------------------+----------------------+-------------------------------------------+
+| AIX\ :sup:`3,4`   | PowerPC              | GCC                                       |
++-------------------+----------------------+-------------------------------------------+
+| Linux\ :sup:`3,5` | PowerPC              | GCC                                       |
++-------------------+----------------------+-------------------------------------------+
+| Linux\ :sup:`7`   | Alpha                | GCC                                       |
++-------------------+----------------------+-------------------------------------------+
+| Linux\ :sup:`7`   | Itanium (IA-64)      | GCC                                       |
++-------------------+----------------------+-------------------------------------------+
+| HP-UX\ :sup:`7`   | Itanium (IA-64)      | HP aCC                                    |
++-------------------+----------------------+-------------------------------------------+
+| Windows x64       | x86-64               | mingw-w64's GCC-4.5.x\ :sup:`12`          |
++-------------------+----------------------+-------------------------------------------+
+
+.. note::
+
+  Code generation supported for Pentium processors and up
+
+  #. Code generation supported for Pentium processors and up
+  #. Code generation supported for 32-bit ABI only
+  #. No native code generation
+  #. Build is not complete: one or more tools do not link or function
+  #. The GCC-based C/C++ frontend does not build
+  #. The port is done using the MSYS shell.
+  #. Native code generation exists but is not complete.
+  #. Binutils 2.20 or later is required to build the assembler generated by LLVM properly.
+  #. Xcode 2.5 and gcc 4.0.1 (Apple Build 5370) will trip internal LLVM assert
+     messages when compiled for Release at optimization levels greater than 0
+     (i.e., ``-O1`` and higher).  Add ``OPTIMIZE_OPTION="-O0"`` to the build
+     command line if compiling for LLVM Release or bootstrapping the LLVM
+     toolchain.
+  #. For MSYS/MinGW on Windows, be sure to install the MSYS version of the perl
+     package, and be sure it appears in your path before any Windows-based
+     versions such as Strawberry Perl and ActivePerl, as these have
+     Windows-specifics that will cause the build to fail.
+  #. To use LLVM modules on Win32-based system, you may configure LLVM
+     with ``--enable-shared``.
+
+  #. To compile SPU backend, you need to add ``LDFLAGS=-Wl,--stack,16777216`` to
+     configure.
+
+Note that you will need about 1-3 GB of space for a full LLVM build in Debug
+mode, depending on the system (it is so large because of all the debugging
+information and the fact that the libraries are statically linked into multiple
+tools).  If you do not need many of the tools and you are space-conscious, you
+can pass ``ONLY_TOOLS="tools you need"`` to make.  The Release build requires
+considerably less space.
+
+The LLVM suite *may* compile on other platforms, but it is not guaranteed to do
+so.  If compilation is successful, the LLVM utilities should be able to
+assemble, disassemble, analyze, and optimize LLVM bitcode.  Code generation
+should work as well, although the generated native code may not work on your
+platform.
+
+Software
+--------
+
+Compiling LLVM requires that you have several software packages installed. The
+table below lists those required packages. The Package column is the usual name
+for the software package that LLVM depends on. The Version column provides
+"known to work" versions of the package. The Notes column describes how LLVM
+uses the package and provides other details.
+
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| Package                                                      | Version         | Notes                                       |
++==============================================================+=================+=============================================+
+| `GNU Make <http://savannah.gnu.org/projects/make>`_          | 3.79, 3.79.1    | Makefile/build processor                    |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `GCC <http://gcc.gnu.org/>`_                                 | 3.4.2           | C/C++ compiler\ :sup:`1`                    |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `TeXinfo <http://www.gnu.org/software/texinfo/>`_            | 4.5             | For building the CFE                        |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `SVN <http://subversion.tigris.org/project_packages.html>`_  | >=1.3           | Subversion access to LLVM\ :sup:`2`         |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `DejaGnu <http://savannah.gnu.org/projects/dejagnu>`_        | 1.4.2           | Automated test suite\ :sup:`3`              |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `tcl <http://www.tcl.tk/software/tcltk/>`_                   | 8.3, 8.4        | Automated test suite\ :sup:`3`              |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `expect <http://expect.nist.gov/>`_                          | 5.38.0          | Automated test suite\ :sup:`3`              |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `perl <http://www.perl.com/download.csp>`_                   | >=5.6.0         | Utilities                                   |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `GNU M4 <http://savannah.gnu.org/projects/m4>`_              | 1.4             | Macro processor for configuration\ :sup:`4` |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `GNU Autoconf <http://www.gnu.org/software/autoconf/>`_      | 2.60            | Configuration script builder\ :sup:`4`      |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `GNU Automake <http://www.gnu.org/software/automake/>`_      | 1.9.6           | aclocal macro generator\ :sup:`4`           |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+| `libtool <http://savannah.gnu.org/projects/libtool>`_        | 1.5.22          | Shared library manager\ :sup:`4`            |
++--------------------------------------------------------------+-----------------+---------------------------------------------+
+
+.. note::
+
+   #. Only the C and C++ languages are needed so there's no need to build the
+      other languages for LLVM's purposes. See `below` for specific version
+      info.
+   #. You only need Subversion if you intend to build from the latest LLVM
+      sources. If you're working from a release distribution, you don't need
+      Subversion.
+   #. Only needed if you want to run the automated test suite in the
+      ``llvm/test`` directory.
+   #. If you want to make changes to the configure scripts, you will need GNU
+      autoconf (2.60), and consequently, GNU M4 (version 1.4 or higher). You
+      will also need automake (1.9.6). We only use aclocal from that package.
+
+Additionally, your compilation host is expected to have the usual plethora of
+Unix utilities. Specifically:
+
+* **ar** --- archive library builder
+* **bzip2** --- bzip2 command for distribution generation
+* **bunzip2** --- bunzip2 command for distribution checking
+* **chmod** --- change permissions on a file
+* **cat** --- output concatenation utility
+* **cp** --- copy files
+* **date** --- print the current date/time 
+* **echo** --- print to standard output
+* **egrep** --- extended regular expression search utility
+* **find** --- find files/dirs in a file system
+* **grep** --- regular expression search utility
+* **gzip** --- gzip command for distribution generation
+* **gunzip** --- gunzip command for distribution checking
+* **install** --- install directories/files 
+* **mkdir** --- create a directory
+* **mv** --- move (rename) files
+* **ranlib** --- symbol table builder for archive libraries
+* **rm** --- remove (delete) files and directories
+* **sed** --- stream editor for transforming output
+* **sh** --- Bourne shell for make build scripts
+* **tar** --- tape archive for distribution generation
+* **test** --- test things in file system
+* **unzip** --- unzip command for distribution checking
+* **zip** --- zip command for distribution generation
+
+.. _below:
+.. _check here:
+
+Broken versions of GCC and other tools
+--------------------------------------
+
+LLVM is very demanding of the host C++ compiler, and as such tends to expose
+bugs in the compiler.  In particular, several versions of GCC crash when trying
+to compile LLVM.  We routinely use GCC 4.2 (and higher) or Clang.  Other
+versions of GCC will probably work as well.  GCC versions listed here are known
+to not work.  If you are using one of these versions, please try to upgrade your
+GCC to something more recent.  If you run into a problem with a version of GCC
+not listed here, please `let us know <mailto:llvmdev at cs.uiuc.edu>`_.  Please use
+the "``gcc -v``" command to find out which version of GCC you are using.
+
+**GCC versions prior to 3.0**: GCC 2.96.x and before had several problems in the
+STL that effectively prevent it from compiling LLVM.
+
+**GCC 3.2.2 and 3.2.3**: These versions of GCC fails to compile LLVM with a
+bogus template error.  This was fixed in later GCCs.
+
+**GCC 3.3.2**: This version of GCC suffered from a `serious bug
+<http://gcc.gnu.org/PR13392>`_ which causes it to crash in the
+"``convert_from_eh_region_ranges_1``" GCC function.
+
+**Cygwin GCC 3.3.3**: The version of GCC 3.3.3 commonly shipped with Cygwin does
+not work.
+
+**SuSE GCC 3.3.3**: The version of GCC 3.3.3 shipped with SuSE 9.1 (and possibly
+others) does not compile LLVM correctly (it appears that exception handling is
+broken in some cases).  Please download the FSF 3.3.3 or upgrade to a newer
+version of GCC.
+
+**GCC 3.4.0 on linux/x86 (32-bit)**: GCC miscompiles portions of the code
+generator, causing an infinite loop in the llvm-gcc build when built with
+optimizations enabled (i.e. a release build).
+
+**GCC 3.4.2 on linux/x86 (32-bit)**: GCC miscompiles portions of the code
+generator at -O3, as with 3.4.0.  However gcc 3.4.2 (unlike 3.4.0) correctly
+compiles LLVM at -O2.  A work around is to build release LLVM builds with
+"``make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2 ...``"
+
+**GCC 3.4.x on X86-64/amd64**: GCC `miscompiles portions of LLVM
+<http://llvm.org/PR1056>`__.
+
+**GCC 3.4.4 (CodeSourcery ARM 2005q3-2)**: this compiler miscompiles LLVM when
+building with optimizations enabled.  It appears to work with "``make
+ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O1``" or build a debug build.
+
+**IA-64 GCC 4.0.0**: The IA-64 version of GCC 4.0.0 is known to miscompile LLVM.
+
+**Apple Xcode 2.3**: GCC crashes when compiling LLVM at -O3 (which is the
+default with ENABLE_OPTIMIZED=1.  To work around this, build with
+"``ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2``".
+
+**GCC 4.1.1**: GCC fails to build LLVM with template concept check errors
+compiling some files.  At the time of this writing, GCC mainline (4.2) did not
+share the problem.
+
+**GCC 4.1.1 on X86-64/amd64**: GCC `miscompiles portions of LLVM
+<http://llvm.org/PR1063>`__ when compiling llvm itself into 64-bit code.  LLVM
+will appear to mostly work but will be buggy, e.g. failing portions of its
+testsuite.
+
+**GCC 4.1.2 on OpenSUSE**: Seg faults during libstdc++ build and on x86_64
+platforms compiling md5.c gets a mangled constant.
+
+**GCC 4.1.2 (20061115 (prerelease) (Debian 4.1.1-21)) on Debian**: Appears to
+miscompile parts of LLVM 2.4. One symptom is ValueSymbolTable complaining about
+symbols remaining in the table on destruction.
+
+**GCC 4.1.2 20071124 (Red Hat 4.1.2-42)**: Suffers from the same symptoms as the
+previous one. It appears to work with ENABLE_OPTIMIZED=0 (the default).
+
+**Cygwin GCC 4.3.2 20080827 (beta) 2**: Users `reported
+<http://llvm.org/PR4145>`_ various problems related with link errors when using
+this GCC version.
+
+**Debian GCC 4.3.2 on X86**: Crashes building some files in LLVM 2.6.
+
+**GCC 4.3.3 (Debian 4.3.3-10) on ARM**: Miscompiles parts of LLVM 2.6 when
+optimizations are turned on. The symptom is an infinite loop in
+``FoldingSetImpl::RemoveNode`` while running the code generator.
+
+**SUSE 11 GCC 4.3.4**: Miscompiles LLVM, causing crashes in ValueHandle logic.
+
+**GCC 4.3.5 and GCC 4.4.5 on ARM**: These can miscompile ``value >> 1`` even at
+``-O0``. A test failure in ``test/Assembler/alignstack.ll`` is one symptom of
+the problem.
+
+**GNU ld 2.16.X**. Some 2.16.X versions of the ld linker will produce very long
+warning messages complaining that some "``.gnu.linkonce.t.*``" symbol was
+defined in a discarded section. You can safely ignore these messages as they are
+erroneous and the linkage is correct.  These messages disappear using ld 2.17.
+
+**GNU binutils 2.17**: Binutils 2.17 contains `a bug
+<http://sourceware.org/bugzilla/show_bug.cgi?id=3111>`__ which causes huge link
+times (minutes instead of seconds) when building LLVM.  We recommend upgrading
+to a newer version (2.17.50.0.4 or later).
+
+**GNU Binutils 2.19.1 Gold**: This version of Gold contained `a bug
+<http://sourceware.org/bugzilla/show_bug.cgi?id=9836>`__ which causes
+intermittent failures when building LLVM with position independent code.  The
+symptom is an error about cyclic dependencies.  We recommend upgrading to a
+newer version of Gold.
+
+.. _Getting Started with LLVM:
+
+Getting Started with LLVM
+=========================
+
+The remainder of this guide is meant to get you up and running with LLVM and to
+give you some basic information about the LLVM environment.
+
+The later sections of this guide describe the `general layout`_ of the LLVM
+source tree, a `simple example`_ using the LLVM tool chain, and `links`_ to find
+more information about LLVM or to get help via e-mail.
+
+Terminology and Notation
+------------------------
+
+Throughout this manual, the following names are used to denote paths specific to
+the local system and working environment.  *These are not environment variables
+you need to set but just strings used in the rest of this document below*.  In
+any of the examples below, simply replace each of these names with the
+appropriate pathname on your local system.  All these paths are absolute:
+
+``SRC_ROOT``
+
+  This is the top level directory of the LLVM source tree.
+
+``OBJ_ROOT``
+
+  This is the top level directory of the LLVM object tree (i.e. the tree where
+  object files and compiled programs will be placed.  It can be the same as
+  SRC_ROOT).
+
+.. _Setting Up Your Environment:
+
+Setting Up Your Environment
+---------------------------
+
+In order to compile and use LLVM, you may need to set some environment
+variables.
+
+``LLVM_LIB_SEARCH_PATH=/path/to/your/bitcode/libs``
+
+  [Optional] This environment variable helps LLVM linking tools find the
+  locations of your bitcode libraries. It is provided only as a convenience
+  since you can specify the paths using the -L options of the tools and the
+  C/C++ front-end will automatically use the bitcode files installed in its
+  ``lib`` directory.
+
+Unpacking the LLVM Archives
+---------------------------
+
+If you have the LLVM distribution, you will need to unpack it before you can
+begin to compile it.  LLVM is distributed as a set of two files: the LLVM suite
+and the LLVM GCC front end compiled for your platform.  There is an additional
+test suite that is optional.  Each file is a TAR archive that is compressed with
+the gzip program.
+
+The files are as follows, with *x.y* marking the version number:
+
+``llvm-x.y.tar.gz``
+
+  Source release for the LLVM libraries and tools.
+
+``llvm-test-x.y.tar.gz``
+
+  Source release for the LLVM test-suite.
+
+``llvm-gcc-4.2-x.y.source.tar.gz``
+
+  Source release of the llvm-gcc-4.2 front end.  See README.LLVM in the root
+  directory for build instructions.
+
+``llvm-gcc-4.2-x.y-platform.tar.gz``
+
+  Binary release of the llvm-gcc-4.2 front end for a specific platform.
+
+Checkout LLVM from Subversion
+-----------------------------
+
+If you have access to our Subversion repository, you can get a fresh copy of the
+entire source code.  All you need to do is check it out from Subversion as
+follows:
+
+* ``cd where-you-want-llvm-to-live``
+* Read-Only: ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
+* Read-Write:``svn co https://user@llvm.org/svn/llvm-project/llvm/trunk llvm``
+
+This will create an '``llvm``' directory in the current directory and fully
+populate it with the LLVM source code, Makefiles, test directories, and local
+copies of documentation files.
+
+If you want to get a specific release (as opposed to the most recent revision),
+you can checkout it from the '``tags``' directory (instead of '``trunk``'). The
+following releases are located in the following subdirectories of the '``tags``'
+directory:
+
+* Release 3.1: **RELEASE_31/final**
+* Release 3.0: **RELEASE_30/final**
+* Release 2.9: **RELEASE_29/final**
+* Release 2.8: **RELEASE_28**
+* Release 2.7: **RELEASE_27**
+* Release 2.6: **RELEASE_26**
+* Release 2.5: **RELEASE_25**
+* Release 2.4: **RELEASE_24**
+* Release 2.3: **RELEASE_23**
+* Release 2.2: **RELEASE_22**
+* Release 2.1: **RELEASE_21**
+* Release 2.0: **RELEASE_20**
+* Release 1.9: **RELEASE_19**
+* Release 1.8: **RELEASE_18**
+* Release 1.7: **RELEASE_17**
+* Release 1.6: **RELEASE_16**
+* Release 1.5: **RELEASE_15**
+* Release 1.4: **RELEASE_14**
+* Release 1.3: **RELEASE_13**
+* Release 1.2: **RELEASE_12**
+* Release 1.1: **RELEASE_11**
+* Release 1.0: **RELEASE_1**
+
+If you would like to get the LLVM test suite (a separate package as of 1.4), you
+get it from the Subversion repository:
+
+.. code-block:: bash
+
+  % cd llvm/projects
+  % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
+
+By placing it in the ``llvm/projects``, it will be automatically configured by
+the LLVM configure script as well as automatically updated when you run ``svn
+update``.
+
+GIT mirror
+----------
+
+GIT mirrors are available for a number of LLVM subprojects. These mirrors sync
+automatically with each Subversion commit and contain all necessary git-svn
+marks (so, you can recreate git-svn metadata locally). Note that right now
+mirrors reflect only ``trunk`` for each project. You can do the read-only GIT
+clone of LLVM via:
+
+.. code-block:: bash
+
+  % git clone http://llvm.org/git/llvm.git
+
+If you want to check out clang too, run:
+
+.. code-block:: bash
+
+  % git clone http://llvm.org/git/llvm.git
+  % cd llvm/tools
+  % git clone http://llvm.org/git/clang.git
+
+Since the upstream repository is in Subversion, you should use ``git
+pull --rebase`` instead of ``git pull`` to avoid generating a non-linear history
+in your clone.  To configure ``git pull`` to pass ``--rebase`` by default on the
+master branch, run the following command:
+
+.. code-block:: bash
+
+  % git config branch.master.rebase true
+
+Sending patches with Git
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Please read `Developer Policy <DeveloperPolicy.html#one-off-patches>`_, too.
+
+Assume ``master`` points the upstream and ``mybranch`` points your working
+branch, and ``mybranch`` is rebased onto ``master``.  At first you may check
+sanity of whitespaces:
+
+.. code-block:: bash
+
+  % git diff --check master..mybranch
+
+The easiest way to generate a patch is as below:
+
+.. code-block:: bash
+
+  % git diff master..mybranch > /path/to/mybranch.diff
+
+It is a little different from svn-generated diff. git-diff-generated diff has
+prefixes like ``a/`` and ``b/``. Don't worry, most developers might know it
+could be accepted with ``patch -p1 -N``.
+
+But you may generate patchset with git-format-patch. It generates by-each-commit
+patchset. To generate patch files to attach to your article:
+
+.. code-block:: bash
+
+  % git format-patch --no-attach master..mybranch -o /path/to/your/patchset
+
+If you would like to send patches directly, you may use git-send-email or
+git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts].
+
+.. code-block:: bash
+
+  % git format-patch --attach master..mybranch --stdout | git imap-send
+
+Then, your .git/config should have [imap] sections.
+
+.. code-block:: bash
+
+  [imap]
+        host = imaps://imap.gmail.com
+        user = your.gmail.account at gmail.com
+        pass = himitsu!
+        port = 993
+        sslverify = false
+  ; in English
+        folder = "[Gmail]/Drafts"
+  ; example for Japanese, "Modified UTF-7" encoded.
+        folder = "[Gmail]/&Tgtm+DBN-"
+  ; example for Traditional Chinese
+        folder = "[Gmail]/&g0l6Pw-"
+
+For developers to work with git-svn
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To set up clone from which you can submit code using ``git-svn``, run:
+
+.. code-block:: bash
+
+  % git clone http://llvm.org/git/llvm.git
+  % cd llvm
+  % git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username>
+  % git config svn-remote.svn.fetch :refs/remotes/origin/master
+  % git svn rebase -l  # -l avoids fetching ahead of the git mirror.
+
+  # If you have clang too:
+  % cd tools
+  % git clone http://llvm.org/git/clang.git
+  % cd clang
+  % git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=<username>
+  % git config svn-remote.svn.fetch :refs/remotes/origin/master
+  % git svn rebase -l
+
+To update this clone without generating git-svn tags that conflict with the
+upstream git repo, run:
+
+.. code-block:: bash
+
+  % git fetch && (cd tools/clang && git fetch)  # Get matching revisions of both trees.
+  % git checkout master
+  % git svn rebase -l
+  % (cd tools/clang &&
+     git checkout master &&
+     git svn rebase -l)
+
+This leaves your working directories on their master branches, so you'll need to
+``checkout`` each working branch individually and ``rebase`` it on top of its
+parent branch.  (Note: This script is intended for relative newbies to git.  If
+you have more experience, you can likely improve on it.)
+
+The git-svn metadata can get out of sync after you mess around with branches and
+``dcommit``. When that happens, ``git svn dcommit`` stops working, complaining
+about files with uncommitted changes. The fix is to rebuild the metadata:
+
+.. code-block:: bash
+
+  % rm -rf .git/svn
+  % git svn rebase -l
+
+Local LLVM Configuration
+------------------------
+
+Once checked out from the Subversion repository, the LLVM suite source code must
+be configured via the ``configure`` script.  This script sets variables in the
+various ``*.in`` files, most notably ``llvm/Makefile.config`` and
+``llvm/include/Config/config.h``.  It also populates *OBJ_ROOT* with the
+Makefiles needed to begin building LLVM.
+
+The following environment variables are used by the ``configure`` script to
+configure the build system:
+
++------------+-----------------------------------------------------------+
+| Variable   | Purpose                                                   |
++============+===========================================================+
+| CC         | Tells ``configure`` which C compiler to use.  By default, |
+|            | ``configure`` will look for the first GCC C compiler in   |
+|            | ``PATH``.  Use this variable to override ``configure``\'s |
+|            | default behavior.                                         |
++------------+-----------------------------------------------------------+
+| CXX        | Tells ``configure`` which C++ compiler to use.  By        |
+|            | default, ``configure`` will look for the first GCC C++    |
+|            | compiler in ``PATH``.  Use this variable to override      |
+|            | ``configure``'s default behavior.                         |
++------------+-----------------------------------------------------------+
+
+The following options can be used to set or enable LLVM specific options:
+
+``--enable-optimized``
+
+  Enables optimized compilation (debugging symbols are removed and GCC
+  optimization flags are enabled). Note that this is the default setting if you
+  are using the LLVM distribution. The default behavior of an Subversion
+  checkout is to use an unoptimized build (also known as a debug build).
+
+``--enable-debug-runtime``
+
+  Enables debug symbols in the runtime libraries. The default is to strip debug
+  symbols from the runtime libraries.
+
+``--enable-jit``
+
+  Compile the Just In Time (JIT) compiler functionality.  This is not available
+  on all platforms.  The default is dependent on platform, so it is best to
+  explicitly enable it if you want it.
+
+``--enable-targets=target-option``
+
+  Controls which targets will be built and linked into llc. The default value
+  for ``target_options`` is "all" which builds and links all available targets.
+  The value "host-only" can be specified to build only a native compiler (no
+  cross-compiler targets available). The "native" target is selected as the
+  target of the build host. You can also specify a comma separated list of
+  target names that you want available in llc. The target names use all lower
+  case. The current set of targets is:
+
+    ``arm, cpp, hexagon, mblaze, mips, mipsel, msp430, powerpc, ptx, sparc, spu,
+    x86, x86_64, xcore``.
+
+``--enable-doxygen``
+
+  Look for the doxygen program and enable construction of doxygen based
+  documentation from the source code. This is disabled by default because
+  generating the documentation can take a long time and producess 100s of
+  megabytes of output.
+
+``--with-udis86``
+
+  LLVM can use external disassembler library for various purposes (now it's used
+  only for examining code produced by JIT). This option will enable usage of
+  `udis86 <http://udis86.sourceforge.net/>`_ x86 (both 32 and 64 bits)
+  disassembler library.
+
+To configure LLVM, follow these steps:
+
+#. Change directory into the object root directory:
+
+   .. code-block:: bash
+
+     % cd OBJ_ROOT
+
+#. Run the ``configure`` script located in the LLVM source tree:
+
+   .. code-block:: bash
+
+     % SRC_ROOT/configure --prefix=/install/path [other options]
+
+Compiling the LLVM Suite Source Code
+------------------------------------
+
+Once you have configured LLVM, you can build it.  There are three types of
+builds:
+
+Debug Builds
+
+  These builds are the default when one is using an Subversion checkout and
+  types ``gmake`` (unless the ``--enable-optimized`` option was used during
+  configuration).  The build system will compile the tools and libraries with
+  debugging information.  To get a Debug Build using the LLVM distribution the
+  ``--disable-optimized`` option must be passed to ``configure``.
+
+Release (Optimized) Builds
+
+  These builds are enabled with the ``--enable-optimized`` option to
+  ``configure`` or by specifying ``ENABLE_OPTIMIZED=1`` on the ``gmake`` command
+  line.  For these builds, the build system will compile the tools and libraries
+  with GCC optimizations enabled and strip debugging information from the
+  libraries and executables it generates.  Note that Release Builds are default
+  when using an LLVM distribution.
+
+Profile Builds
+
+  These builds are for use with profiling.  They compile profiling information
+  into the code for use with programs like ``gprof``.  Profile builds must be
+  started by specifying ``ENABLE_PROFILING=1`` on the ``gmake`` command line.
+
+Once you have LLVM configured, you can build it by entering the *OBJ_ROOT*
+directory and issuing the following command:
+
+.. code-block:: bash
+
+  % gmake
+
+If the build fails, please `check here`_ to see if you are using a version of
+GCC that is known not to compile LLVM.
+
+If you have multiple processors in your machine, you may wish to use some of the
+parallel build options provided by GNU Make.  For example, you could use the
+command:
+
+.. code-block:: bash
+
+  % gmake -j2
+
+There are several special targets which are useful when working with the LLVM
+source code:
+
+``gmake clean``
+
+  Removes all files generated by the build.  This includes object files,
+  generated C/C++ files, libraries, and executables.
+
+``gmake dist-clean``
+
+  Removes everything that ``gmake clean`` does, but also removes files generated
+  by ``configure``.  It attempts to return the source tree to the original state
+  in which it was shipped.
+
+``gmake install``
+
+  Installs LLVM header files, libraries, tools, and documentation in a hierarchy
+  under ``$PREFIX``, specified with ``./configure --prefix=[dir]``, which
+  defaults to ``/usr/local``.
+
+``gmake -C runtime install-bytecode``
+
+  Assuming you built LLVM into $OBJDIR, when this command is run, it will
+  install bitcode libraries into the GCC front end's bitcode library directory.
+  If you need to update your bitcode libraries, this is the target to use once
+  you've built them.
+
+Please see the `Makefile Guide <MakefileGuide.html>`_ for further details on
+these ``make`` targets and descriptions of other targets available.
+
+It is also possible to override default values from ``configure`` by declaring
+variables on the command line.  The following are some examples:
+
+``gmake ENABLE_OPTIMIZED=1``
+
+  Perform a Release (Optimized) build.
+
+``gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1``
+
+  Perform a Release (Optimized) build without assertions enabled.
+ 
+``gmake ENABLE_OPTIMIZED=0``
+
+  Perform a Debug build.
+
+``gmake ENABLE_PROFILING=1``
+
+  Perform a Profiling build.
+
+``gmake VERBOSE=1``
+
+  Print what ``gmake`` is doing on standard output.
+
+``gmake TOOL_VERBOSE=1``
+
+  Ask each tool invoked by the makefiles to print out what it is doing on 
+  the standard output. This also implies ``VERBOSE=1``.
+
+Every directory in the LLVM object tree includes a ``Makefile`` to build it and
+any subdirectories that it contains.  Entering any directory inside the LLVM
+object tree and typing ``gmake`` should rebuild anything in or below that
+directory that is out of date.
+
+Cross-Compiling LLVM
+--------------------
+
+It is possible to cross-compile LLVM itself. That is, you can create LLVM
+executables and libraries to be hosted on a platform different from the platform
+where they are build (a Canadian Cross build). To configure a cross-compile,
+supply the configure script with ``--build`` and ``--host`` options that are
+different. The values of these options must be legal target triples that your
+GCC compiler supports.
+
+The result of such a build is executables that are not runnable on on the build
+host (--build option) but can be executed on the compile host (--host option).
+
+The Location of LLVM Object Files
+---------------------------------
+
+The LLVM build system is capable of sharing a single LLVM source tree among
+several LLVM builds.  Hence, it is possible to build LLVM for several different
+platforms or configurations using the same source tree.
+
+This is accomplished in the typical autoconf manner:
+
+* Change directory to where the LLVM object files should live:
+
+  .. code-block:: bash
+
+    % cd OBJ_ROOT
+
+* Run the ``configure`` script found in the LLVM source directory:
+
+  .. code-block:: bash
+
+    % SRC_ROOT/configure
+
+The LLVM build will place files underneath *OBJ_ROOT* in directories named after
+the build type:
+
+Debug Builds with assertions enabled (the default)
+
+  Tools
+
+    ``OBJ_ROOT/Debug+Asserts/bin``
+
+  Libraries
+
+    ``OBJ_ROOT/Debug+Asserts/lib``
+
+Release Builds
+
+  Tools
+
+    ``OBJ_ROOT/Release/bin``
+
+  Libraries
+
+    ``OBJ_ROOT/Release/lib``
+
+Profile Builds
+
+  Tools
+
+    ``OBJ_ROOT/Profile/bin``
+
+  Libraries
+
+    ``OBJ_ROOT/Profile/lib``
+
+Optional Configuration Items
+----------------------------
+
+If you're running on a Linux system that supports the `binfmt_misc
+<http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html>`_
+module, and you have root access on the system, you can set your system up to
+execute LLVM bitcode files directly. To do this, use commands like this (the
+first command may not be required if you are already using the module):
+
+.. code-block:: bash
+
+  % mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
+  % echo ':llvm:M::BC::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register
+  % chmod u+x hello.bc   (if needed)
+  % ./hello.bc
+
+This allows you to execute LLVM bitcode files directly.  On Debian, you can also
+use this command instead of the 'echo' command above:
+
+.. code-block:: bash
+
+  % sudo update-binfmts --install llvm /path/to/lli --magic 'BC'
+
+.. _Program Layout:
+.. _general layout:
+
+Program Layout
+==============
+
+One useful source of information about the LLVM source base is the LLVM `doxygen
+<http://www.doxygen.org/>`_ documentation available at
+`<http://llvm.org/doxygen/>`_.  The following is a brief introduction to code
+layout:
+
+``llvm/examples``
+-----------------
+
+This directory contains some simple examples of how to use the LLVM IR and JIT.
+
+``llvm/include``
+----------------
+
+This directory contains public header files exported from the LLVM library. The
+three main subdirectories of this directory are:
+
+``llvm/include/llvm``
+
+  This directory contains all of the LLVM specific header files.  This directory
+  also has subdirectories for different portions of LLVM: ``Analysis``,
+  ``CodeGen``, ``Target``, ``Transforms``, etc...
+
+``llvm/include/llvm/Support``
+
+  This directory contains generic support libraries that are provided with LLVM
+  but not necessarily specific to LLVM. For example, some C++ STL utilities and
+  a Command Line option processing library store their header files here.
+
+``llvm/include/llvm/Config``
+
+  This directory contains header files configured by the ``configure`` script.
+  They wrap "standard" UNIX and C header files.  Source code can include these
+  header files which automatically take care of the conditional #includes that
+  the ``configure`` script generates.
+
+``llvm/lib``
+------------
+
+This directory contains most of the source files of the LLVM system. In LLVM,
+almost all code exists in libraries, making it very easy to share code among the
+different `tools`_.
+
+``llvm/lib/VMCore/``
+
+  This directory holds the core LLVM source files that implement core classes
+  like Instruction and BasicBlock.
+
+``llvm/lib/AsmParser/``
+
+  This directory holds the source code for the LLVM assembly language parser
+  library.
+
+``llvm/lib/BitCode/``
+
+  This directory holds code for reading and write LLVM bitcode.
+
+``llvm/lib/Analysis/``
+
+  This directory contains a variety of different program analyses, such as
+  Dominator Information, Call Graphs, Induction Variables, Interval
+  Identification, Natural Loop Identification, etc.
+
+``llvm/lib/Transforms/``
+
+  This directory contains the source code for the LLVM to LLVM program
+  transformations, such as Aggressive Dead Code Elimination, Sparse Conditional
+  Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global
+  Elimination, and many others.
+
+``llvm/lib/Target/``
+
+  This directory contains files that describe various target architectures for
+  code generation.  For example, the ``llvm/lib/Target/X86`` directory holds the
+  X86 machine description while ``llvm/lib/Target/ARM`` implements the ARM
+  backend.
+    
+``llvm/lib/CodeGen/``
+
+  This directory contains the major parts of the code generator: Instruction
+  Selector, Instruction Scheduling, and Register Allocation.
+
+``llvm/lib/MC/``
+
+  (FIXME: T.B.D.)
+
+``llvm/lib/Debugger/``
+
+  This directory contains the source level debugger library that makes it
+  possible to instrument LLVM programs so that a debugger could identify source
+  code locations at which the program is executing.
+
+``llvm/lib/ExecutionEngine/``
+
+  This directory contains libraries for executing LLVM bitcode directly at
+  runtime in both interpreted and JIT compiled fashions.
+
+``llvm/lib/Support/``
+
+  This directory contains the source code that corresponds to the header files
+  located in ``llvm/include/ADT/`` and ``llvm/include/Support/``.
+
+``llvm/projects``
+-----------------
+
+This directory contains projects that are not strictly part of LLVM but are
+shipped with LLVM. This is also the directory where you should create your own
+LLVM-based projects. See ``llvm/projects/sample`` for an example of how to set
+up your own project.
+
+``llvm/runtime``
+----------------
+
+This directory contains libraries which are compiled into LLVM bitcode and used
+when linking programs with the Clang front end.  Most of these libraries are
+skeleton versions of real libraries; for example, libc is a stripped down
+version of glibc.
+
+Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front end
+to compile.
+
+``llvm/test``
+-------------
+
+This directory contains feature and regression tests and other basic sanity
+checks on the LLVM infrastructure. These are intended to run quickly and cover a
+lot of territory without being exhaustive.
+
+``test-suite``
+--------------
+
+This is not a directory in the normal llvm module; it is a separate Subversion
+module that must be checked out (usually to ``projects/test-suite``).  This
+module contains a comprehensive correctness, performance, and benchmarking test
+suite for LLVM. It is a separate Subversion module because not every LLVM user
+is interested in downloading or building such a comprehensive test suite. For
+further details on this test suite, please see the `Testing
+Guide <TestingGuide.html>`_ document.
+
+.. _tools:
+
+``llvm/tools``
+--------------
+
+The **tools** directory contains the executables built out of the libraries
+above, which form the main part of the user interface.  You can always get help
+for a tool by typing ``tool_name -help``.  The following is a brief introduction
+to the most important tools.  More detailed information is in
+the `Command Guide <CommandGuide/index.html>`_.
+
+``bugpoint``
+
+  ``bugpoint`` is used to debug optimization passes or code generation backends
+  by narrowing down the given test case to the minimum number of passes and/or
+  instructions that still cause a problem, whether it is a crash or
+  miscompilation. See `<HowToSubmitABug.html>`_ for more information on using
+  ``bugpoint``.
+
+``llvm-ar``
+
+  The archiver produces an archive containing the given LLVM bitcode files,
+  optionally with an index for faster lookup.
+  
+``llvm-as``
+
+  The assembler transforms the human readable LLVM assembly to LLVM bitcode.
+
+``llvm-dis``
+
+  The disassembler transforms the LLVM bitcode to human readable LLVM assembly.
+
+``llvm-link``
+
+  ``llvm-link``, not surprisingly, links multiple LLVM modules into a single
+  program.
+  
+``lli``
+
+  ``lli`` is the LLVM interpreter, which can directly execute LLVM bitcode
+  (although very slowly...). For architectures that support it (currently x86,
+  Sparc, and PowerPC), by default, ``lli`` will function as a Just-In-Time
+  compiler (if the functionality was compiled in), and will execute the code
+  *much* faster than the interpreter.
+
+``llc``
+
+  ``llc`` is the LLVM backend compiler, which translates LLVM bitcode to a
+  native code assembly file or to C code (with the ``-march=c`` option).
+
+``opt``
+
+  ``opt`` reads LLVM bitcode, applies a series of LLVM to LLVM transformations
+  (which are specified on the command line), and then outputs the resultant
+  bitcode.  The '``opt -help``' command is a good way to get a list of the
+  program transformations available in LLVM.
+
+  ``opt`` can also be used to run a specific analysis on an input LLVM bitcode
+  file and print out the results.  It is primarily useful for debugging
+  analyses, or familiarizing yourself with what an analysis does.
+
+``llvm/utils``
+--------------
+
+This directory contains utilities for working with LLVM source code, and some of
+the utilities are actually required as part of the build process because they
+are code generators for parts of LLVM infrastructure.
+
+
+``codegen-diff``
+
+  ``codegen-diff`` is a script that finds differences between code that LLC
+  generates and code that LLI generates. This is a useful tool if you are
+  debugging one of them, assuming that the other generates correct output. For
+  the full user manual, run ```perldoc codegen-diff'``.
+
+``emacs/``
+
+  The ``emacs`` directory contains syntax-highlighting files which will work
+  with Emacs and XEmacs editors, providing syntax highlighting support for LLVM
+  assembly files and TableGen description files. For information on how to use
+  the syntax files, consult the ``README`` file in that directory.
+
+``getsrcs.sh``
+
+  The ``getsrcs.sh`` script finds and outputs all non-generated source files,
+  which is useful if one wishes to do a lot of development across directories
+  and does not want to individually find each file. One way to use it is to run,
+  for example: ``xemacs `utils/getsources.sh``` from the top of your LLVM source
+  tree.
+
+``llvmgrep``
+
+  This little tool performs an ``egrep -H -n`` on each source file in LLVM and
+  passes to it a regular expression provided on ``llvmgrep``'s command
+  line. This is a very efficient way of searching the source base for a
+  particular regular expression.
+
+``makellvm``
+
+  The ``makellvm`` script compiles all files in the current directory and then
+  compiles and links the tool that is the first argument. For example, assuming
+  you are in the directory ``llvm/lib/Target/Sparc``, if ``makellvm`` is in your
+  path, simply running ``makellvm llc`` will make a build of the current
+  directory, switch to directory ``llvm/tools/llc`` and build it, causing a
+  re-linking of LLC.
+
+``TableGen/``
+
+  The ``TableGen`` directory contains the tool used to generate register
+  descriptions, instruction set descriptions, and even assemblers from common
+  TableGen description files.
+
+``vim/``
+
+  The ``vim`` directory contains syntax-highlighting files which will work with
+  the VIM editor, providing syntax highlighting support for LLVM assembly files
+  and TableGen description files. For information on how to use the syntax
+  files, consult the ``README`` file in that directory.
+
+.. _simple example:
+
+An Example Using the LLVM Tool Chain
+====================================
+
+This section gives an example of using LLVM with the Clang front end.
+
+Example with clang
+------------------
+
+#. First, create a simple C file, name it 'hello.c':
+
+   .. code-block:: c
+
+     #include <stdio.h>
+
+     int main() {
+       printf("hello world\n");
+       return 0;
+     }
+
+#. Next, compile the C file into a native executable:
+
+   .. code-block:: bash
+
+     % clang hello.c -o hello
+
+   .. note::
+
+     Clang works just like GCC by default.  The standard -S and -c arguments
+     work as usual (producing a native .s or .o file, respectively).
+
+#. Next, compile the C file into a LLVM bitcode file:
+
+   .. code-block:: bash
+
+     % clang -O3 -emit-llvm hello.c -c -o hello.bc
+
+   The -emit-llvm option can be used with the -S or -c options to emit an LLVM
+   ``.ll`` or ``.bc`` file (respectively) for the code.  This allows you to use
+   the `standard LLVM tools <CommandGuide/index.html>`_ on the bitcode file.
+
+#. Run the program in both forms. To run the program, use:
+
+   .. code-block:: bash
+
+      % ./hello
+ 
+   and
+
+   .. code-block:: bash
+
+     % lli hello.bc
+
+   The second examples shows how to invoke the LLVM JIT, `lli
+   <CommandGuide/html/lli.html>`_.
+
+#. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code:
+
+   .. code-block:: bash
+
+     % llvm-dis < hello.bc | less
+
+#. Compile the program to native assembly using the LLC code generator:
+
+   .. code-block:: bash
+
+     % llc hello.bc -o hello.s
+
+#. Assemble the native assembly language file into a program:
+
+   .. code-block:: bash
+
+     **Solaris:** % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native
+
+     **Others:**  % gcc hello.s -o hello.native
+
+#. Execute the native code program:
+
+   .. code-block:: bash
+
+     % ./hello.native
+
+   Note that using clang to compile directly to native code (i.e. when the
+   ``-emit-llvm`` option is not present) does steps 6/7/8 for you.
+
+Common Problems
+===============
+
+If you are having problems building or using LLVM, or if you have any other
+general questions about LLVM, please consult the `Frequently Asked
+Questions <FAQ.html>`_ page.
+
+.. _links:
+
+Links
+=====
+
+This document is just an **introduction** on how to use LLVM to do some simple
+things... there are many more interesting and complicated things that you can do
+that aren't documented here (but we'll gladly accept a patch if you want to
+write something up!).  For more information about LLVM, check out:
+
+* `LLVM Homepage <http://llvm.org/>`_
+* `LLVM Doxygen Tree <http://llvm.org/doxygen/>`_
+* `Starting a Project that Uses LLVM <http://llvm.org/docs/Projects.html>`_

Added: www-releases/trunk/3.2/docs/GettingStartedVS.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/GettingStartedVS.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/GettingStartedVS.rst (added)
+++ www-releases/trunk/3.2/docs/GettingStartedVS.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,234 @@
+.. _winvs:
+
+==================================================================
+Getting Started with the LLVM System using Microsoft Visual Studio
+==================================================================
+
+.. contents::
+   :local:
+
+
+Overview
+========
+Welcome to LLVM on Windows! This document only covers LLVM on Windows using
+Visual Studio, not mingw or cygwin. In order to get started, you first need to
+know some basic information.
+
+There are many different projects that compose LLVM. The first is the LLVM
+suite. This contains all of the tools, libraries, and header files needed to
+use LLVM. It contains an assembler, disassembler,
+bitcode analyzer and bitcode optimizer. It also contains a test suite that can
+be used to test the LLVM tools.
+
+Another useful project on Windows is `Clang <http://clang.llvm.org/>`_.
+Clang is a C family ([Objective]C/C++) compiler. Clang mostly works on
+Windows, but does not currently understand all of the Microsoft extensions
+to C and C++. Because of this, clang cannot parse the C++ standard library
+included with Visual Studio, nor parts of the Windows Platform SDK. However,
+most standard C programs do compile. Clang can be used to emit bitcode,
+directly emit object files or even linked executables using Visual Studio's
+``link.exe``.
+
+The large LLVM test suite cannot be run on the Visual Studio port at this
+time.
+
+Most of the tools build and work.  ``bugpoint`` does build, but does
+not work.
+
+Additional information about the LLVM directory structure and tool chain
+can be found on the main `Getting Started <GettingStarted.html>`_ page.
+
+
+Requirements
+============
+Before you begin to use the LLVM system, review the requirements given
+below.  This may save you some trouble by knowing ahead of time what hardware
+and software you will need.
+
+Hardware
+--------
+Any system that can adequately run Visual Studio 2008 is fine. The LLVM
+source tree and object files, libraries and executables will consume
+approximately 3GB.
+
+Software
+--------
+You will need Visual Studio 2008 or higher.  Earlier versions of Visual
+Studio have bugs, are not completely compatible, or do not support the C++
+standard well enough.
+
+You will also need the `CMake <http://www.cmake.org/>`_ build system since it
+generates the project files you will use to build with.
+
+If you would like to run the LLVM tests you will need `Python
+<http://www.python.org/>`_. Versions 2.4-2.7 are known to work. You will need
+`GnuWin32 <http://gnuwin32.sourceforge.net/>`_ tools, too.
+
+Do not install the LLVM directory tree into a path containing spaces (e.g.
+``C:\Documents and Settings\...``) as the configure step will fail.
+
+
+Getting Started
+===============
+Here's the short story for getting up and running quickly with LLVM:
+
+1. Read the documentation.
+2. Seriously, read the documentation.
+3. Remember that you were warned twice about reading the documentation.
+4. Get the Source Code
+
+   * With the distributed files:
+
+      1. ``cd <where-you-want-llvm-to-live>``
+      2. ``gunzip --stdout llvm-VERSION.tar.gz | tar -xvf -``
+         (*or use WinZip*)
+      3. ``cd llvm``
+
+   * With anonymous Subversion access:
+
+      1. ``cd <where-you-want-llvm-to-live>``
+      2. ``svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm``
+      3. ``cd llvm``
+
+5. Use `CMake <http://www.cmake.org/>`_ to generate up-to-date project files:
+
+   * Once CMake is installed then the simplest way is to just start the
+     CMake GUI, select the directory where you have LLVM extracted to, and
+     the default options should all be fine.  One option you may really
+     want to change, regardless of anything else, might be the
+     ``CMAKE_INSTALL_PREFIX`` setting to select a directory to INSTALL to
+     once compiling is complete, although installation is not mandatory for
+     using LLVM.  Another important option is ``LLVM_TARGETS_TO_BUILD``,
+     which controls the LLVM target architectures that are included on the
+     build.
+   * See the `LLVM CMake guide <CMake.html>`_ for detailed information about
+     how to configure the LLVM build.
+
+6. Start Visual Studio
+
+   * In the directory you created the project files will have an ``llvm.sln``
+     file, just double-click on that to open Visual Studio.
+
+7. Build the LLVM Suite:
+
+   * The projects may still be built individually, but to build them all do
+     not just select all of them in batch build (as some are meant as
+     configuration projects), but rather select and build just the
+     ``ALL_BUILD`` project to build everything, or the ``INSTALL`` project,
+     which first builds the ``ALL_BUILD`` project, then installs the LLVM
+     headers, libs, and other useful things to the directory set by the
+     ``CMAKE_INSTALL_PREFIX`` setting when you first configured CMake.
+   * The Fibonacci project is a sample program that uses the JIT. Modify the
+     project's debugging properties to provide a numeric command line argument
+     or run it from the command line.  The program will print the
+     corresponding fibonacci value.
+
+8. Test LLVM on Visual Studio:
+
+   * If ``%PATH%`` does not contain GnuWin32, you may specify
+     ``LLVM_LIT_TOOLS_DIR`` on CMake for the path to GnuWin32.
+   * You can run LLVM tests by merely building the project "check". The test
+     results will be shown in the VS output window.
+
+.. FIXME: Is it up-to-date?
+
+9. Test LLVM:
+
+   * The LLVM tests can be run by changing directory to the llvm source
+     directory and running:
+
+     .. code-block:: bat
+
+        C:\..\llvm> llvm-lit test
+
+     Note that quite a few of these test will fail.
+
+     A specific test or test directory can be run with:
+
+     .. code-block:: bat
+
+        C:\..\llvm> llvm-lit test/path/to/test
+
+
+An Example Using the LLVM Tool Chain
+====================================
+
+1. First, create a simple C file, name it '``hello.c``':
+
+   .. code-block:: c
+
+      #include <stdio.h>
+      int main() {
+        printf("hello world\n");
+        return 0;
+      }
+
+2. Next, compile the C file into a LLVM bitcode file:
+
+   .. code-block:: bat
+
+      C:\..> clang -c hello.c -emit-llvm -o hello.bc
+
+   This will create the result file ``hello.bc`` which is the LLVM bitcode
+   that corresponds the compiled program and the library facilities that
+   it required.  You can execute this file directly using ``lli`` tool,
+   compile it to native assembly with the ``llc``, optimize or analyze it
+   further with the ``opt`` tool, etc.
+
+   Alternatively you can directly output an executable with clang with:
+
+   .. code-block:: bat
+
+      C:\..> clang hello.c -o hello.exe
+
+   The ``-o hello.exe`` is required because clang currently outputs ``a.out``
+   when neither ``-o`` nor ``-c`` are given.
+
+3. Run the program using the just-in-time compiler:
+
+   .. code-block:: bat
+
+      C:\..> lli hello.bc
+
+4. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code:
+
+   .. code-block:: bat
+
+      C:\..> llvm-dis < hello.bc | more
+
+5. Compile the program to object code using the LLC code generator:
+
+   .. code-block:: bat
+
+      C:\..> llc -filetype=obj hello.bc
+
+6. Link to binary using Microsoft link:
+
+   .. code-block:: bat
+
+      C:\..> link hello.obj -defaultlib:libcmt
+
+7. Execute the native code program:
+
+   .. code-block:: bat
+
+      C:\..> hello.exe
+
+
+Common Problems
+===============
+If you are having problems building or using LLVM, or if you have any other
+general questions about LLVM, please consult the `Frequently Asked Questions
+<FAQ.html>`_ page.
+
+
+Links
+=====
+This document is just an **introduction** to how to use LLVM to do some simple
+things... there are many more interesting and complicated things that you can
+do that aren't documented here (but we'll gladly accept a patch if you want to
+write something up!).  For more information about LLVM, check out:
+
+* `LLVM homepage <http://llvm.org/>`_
+* `LLVM doxygen tree <http://llvm.org/doxygen/>`_
+

Added: www-releases/trunk/3.2/docs/GoldPlugin.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/GoldPlugin.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/GoldPlugin.rst (added)
+++ www-releases/trunk/3.2/docs/GoldPlugin.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,186 @@
+.. _gold-plugin:
+
+====================
+The LLVM gold plugin
+====================
+
+.. sectionauthor:: Nick Lewycky
+
+Introduction
+============
+
+Building with link time optimization requires cooperation from
+the system linker. LTO support on Linux systems requires that you use the
+`gold linker`_ which supports LTO via plugins. This is the same mechanism
+used by the `GCC LTO`_ project.
+
+The LLVM gold plugin implements the gold plugin interface on top of
+:ref:`libLTO`.  The same plugin can also be used by other tools such as
+``ar`` and ``nm``.
+
+.. _`gold linker`: http://sourceware.org/binutils
+.. _`GCC LTO`: http://gcc.gnu.org/wiki/LinkTimeOptimization
+.. _`gold plugin interface`: http://gcc.gnu.org/wiki/whopr/driver
+
+.. _lto-how-to-build:
+
+How to build it
+===============
+
+You need to have gold with plugin support and build the LLVMgold plugin.
+Check whether you have gold running ``/usr/bin/ld -v``. It will report "GNU
+gold" or else "GNU ld" if not. If you have gold, check for plugin support
+by running ``/usr/bin/ld -plugin``. If it complains "missing argument" then
+you have plugin support. If not, such as an "unknown option" error then you
+will either need to build gold or install a version with plugin support.
+
+* To build gold with plugin support:
+
+  .. code-block:: bash
+
+     $ mkdir binutils
+     $ cd binutils
+     $ cvs -z 9 -d :pserver:anoncvs at sourceware.org:/cvs/src login
+     {enter "anoncvs" as the password}
+     $ cvs -z 9 -d :pserver:anoncvs at sourceware.org:/cvs/src co binutils
+     $ mkdir build
+     $ cd build
+     $ ../src/configure --enable-gold --enable-plugins
+     $ make all-gold
+
+  That should leave you with ``binutils/build/gold/ld-new`` which supports
+  the ``-plugin`` option. It also built would have
+  ``binutils/build/binutils/ar`` and ``nm-new`` which support plugins but
+  don't have a visible -plugin option, instead relying on the gold plugin
+  being present in ``../lib/bfd-plugins`` relative to where the binaries
+  are placed.
+
+* Build the LLVMgold plugin: Configure LLVM with
+  ``--with-binutils-include=/path/to/binutils/src/include`` and run
+  ``make``.
+
+Usage
+=====
+
+The linker takes a ``-plugin`` option that points to the path of
+the plugin ``.so`` file. To find out what link command ``gcc``
+would run in a given situation, run ``gcc -v [...]`` and
+look for the line where it runs ``collect2``. Replace that with
+``ld-new -plugin /path/to/LLVMgold.so`` to test it out. Once you're
+ready to switch to using gold, backup your existing ``/usr/bin/ld``
+then replace it with ``ld-new``.
+
+You can produce bitcode files from ``clang`` using ``-emit-llvm`` or
+``-flto``, or the ``-O4`` flag which is synonymous with ``-O3 -flto``.
+
+Any of these flags will also cause ``clang`` to look for the gold plugin in
+the ``lib`` directory under its prefix and pass the ``-plugin`` option to
+``ld``. It will not look for an alternate linker, which is why you need
+gold to be the installed system linker in your path.
+
+If you want ``ar`` and ``nm`` to work seamlessly as well, install
+``LLVMgold.so`` to ``/usr/lib/bfd-plugins``. If you built your own gold, be
+sure to install the ``ar`` and ``nm-new`` you built to ``/usr/bin``.
+
+
+Example of link time optimization
+---------------------------------
+
+The following example shows a worked example of the gold plugin mixing LLVM
+bitcode and native code.
+
+.. code-block:: c
+
+   --- a.c ---
+   #include <stdio.h>
+
+   extern void foo1(void);
+   extern void foo4(void);
+
+   void foo2(void) {
+     printf("Foo2\n");
+   }
+
+   void foo3(void) {
+     foo4();
+   }
+
+   int main(void) {
+     foo1();
+   }
+
+   --- b.c ---
+   #include <stdio.h>
+
+   extern void foo2(void);
+
+   void foo1(void) {
+     foo2();
+   }
+
+   void foo4(void) {
+     printf("Foo4");
+   }
+
+.. code-block:: bash
+
+   --- command lines ---
+   $ clang -flto a.c -c -o a.o      # <-- a.o is LLVM bitcode file
+   $ ar q a.a a.o                   # <-- a.a is an archive with LLVM bitcode
+   $ clang b.c -c -o b.o            # <-- b.o is native object file
+   $ clang -flto a.a b.o -o main    # <-- link with LLVMgold plugin
+
+Gold informs the plugin that foo3 is never referenced outside the IR,
+leading LLVM to delete that function. However, unlike in the :ref:`libLTO
+example <libLTO-example>` gold does not currently eliminate foo4.
+
+Quickstart for using LTO with autotooled projects
+=================================================
+
+Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode,
+everything is in place for an easy to use LTO build of autotooled projects:
+
+* Follow the instructions :ref:`on how to build LLVMgold.so
+  <lto-how-to-build>`.
+
+* Install the newly built binutils to ``$PREFIX``
+
+* Copy ``Release/lib/LLVMgold.so`` to ``$PREFIX/lib/bfd-plugins/``
+
+* Set environment variables (``$PREFIX`` is where you installed clang and
+  binutils):
+
+  .. code-block:: bash
+
+     export CC="$PREFIX/bin/clang -flto"
+     export CXX="$PREFIX/bin/clang++ -flto"
+     export AR="$PREFIX/bin/ar"
+     export NM="$PREFIX/bin/nm"
+     export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a
+     export CFLAGS="-O4"
+
+* Or you can just set your path:
+
+  .. code-block:: bash
+
+     export PATH="$PREFIX/bin:$PATH"
+     export CC="clang -flto"
+     export CXX="clang++ -flto"
+     export RANLIB=/bin/true
+     export CFLAGS="-O4"
+* Configure and build the project as usual:
+
+  .. code-block:: bash
+
+     % ./configure && make && make check
+
+The environment variable settings may work for non-autotooled projects too,
+but you may need to set the ``LD`` environment variable as well.
+
+Licensing
+=========
+
+Gold is licensed under the GPLv3. LLVMgold uses the interface file
+``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so``
+binary is also GPLv3. This can still be used to link non-GPLv3 programs
+just as much as gold could without the plugin.

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeas.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,74 @@
+Date: Sat, 18 Nov 2000 09:19:35 -0600 (CST)
+From: Vikram Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <lattner at cs.uiuc.edu>
+Subject: a few thoughts
+
+I've been mulling over the virtual machine problem and I had some
+thoughts about some things for us to think about discuss:
+
+1. We need to be clear on our goals for the VM.  Do we want to emphasize
+   portability and safety like the Java VM?  Or shall we focus on the
+   architecture interface first (i.e., consider the code generation and
+   processor issues), since the architecture interface question is also
+   important for portable Java-type VMs?
+
+   This is important because the audiences for these two goals are very
+   different.  Architects and many compiler people care much more about
+   the second question.  The Java compiler and OS community care much more
+   about the first one.
+
+   Also, while the architecture interface question is important for
+   Java-type VMs, the design constraints are very different.
+
+
+2. Design issues to consider (an initial list that we should continue
+   to modify).  Note that I'm not trying to suggest actual solutions here,
+   but just various directions we can pursue:
+
+   a. A single-assignment VM, which we've both already been thinking about.
+
+   b. A strongly-typed VM.  One question is do we need the types to be
+      explicitly declared or should they be inferred by the dynamic compiler?
+
+   c. How do we get more high-level information into the VM while keeping
+      to a low-level VM design?
+
+        o  Explicit array references as operands?  An alternative is
+           to have just an array type, and let the index computations be
+           separate 3-operand instructions.
+
+        o  Explicit instructions to handle aliasing, e.g.s:
+           -- an instruction to say "I speculate that these two values are not
+              aliased, but check at runtime", like speculative execution in
+              EPIC?
+           -- or an instruction to check whether two values are aliased and
+              execute different code depending on the answer, somewhat like
+              predicated code in EPIC
+
+        o  (This one is a difficult but powerful idea.)
+           A "thread-id" field on every instruction that allows the static
+           compiler to generate a set of parallel threads, and then have
+           the runtime compiler and hardware do what they please with it.
+           This has very powerful uses, but thread-id on every instruction
+           is expensive in terms of instruction size and code size.
+           We would need to compactly encode it somehow.
+
+           Also, this will require some reading on at least two other
+           projects:
+                -- Multiscalar architecture from Wisconsin
+                -- Simultaneous multithreading architecture from Washington
+
+        o  Or forget all this and stick to a traditional instruction set?
+
+
+BTW, on an unrelated note, after the meeting yesterday, I did remember
+that you had suggested doing instruction scheduling on SSA form instead
+of a dependence DAG earlier in the semester.  When we talked about
+it yesterday, I didn't remember where the idea had come from but I
+remembered later.  Just giving credit where its due...
+
+Perhaps you can save the above as a file under RCS so you and I can
+continue to expand on this.
+
+--Vikram
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2000-11-18-EarlyDesignIdeasResp.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,199 @@
+Date: Sun, 19 Nov 2000 16:23:57 -0600 (CST)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram Adve <vadve at cs.uiuc.edu>
+Subject: Re: a few thoughts
+
+Okay... here are a few of my thoughts on this (it's good to know that we
+think so alike!):
+
+> 1. We need to be clear on our goals for the VM.  Do we want to emphasize
+>    portability and safety like the Java VM?  Or shall we focus on the
+>    architecture interface first (i.e., consider the code generation and
+>    processor issues), since the architecture interface question is also
+>    important for portable Java-type VMs?
+
+I forsee the architecture looking kinda like this: (which is completely
+subject to change)
+
+1. The VM code is NOT guaranteed safe in a java sense.  Doing so makes it
+   basically impossible to support C like languages.  Besides that,
+   certifying a register based language as safe at run time would be a
+   pretty expensive operation to have to do.  Additionally, we would like
+   to be able to statically eliminate many bounds checks in Java
+   programs... for example.
+
+ 2. Instead, we can do the following (eventually): 
+   * Java bytecode is used as our "safe" representation (to avoid
+     reinventing something that we don't add much value to).  When the
+     user chooses to execute Java bytecodes directly (ie, not
+     precompiled) the runtime compiler can do some very simple
+     transformations (JIT style) to convert it into valid input for our
+     VM.  Performance is not wonderful, but it works right.
+   * The file is scheduled to be compiled (rigorously) at a later
+     time.  This could be done by some background process or by a second
+     processor in the system during idle time or something...
+   * To keep things "safe" ie to enforce a sandbox on Java/foreign code,
+     we could sign the generated VM code with a host specific private
+     key.  Then before the code is executed/loaded, we can check to see if
+     the trusted compiler generated the code.  This would be much quicker
+     than having to validate consistency (especially if bounds checks have
+     been removed, for example)
+
+>    This is important because the audiences for these two goals are very
+>    different.  Architects and many compiler people care much more about
+>    the second question.  The Java compiler and OS community care much more
+>    about the first one.
+
+3. By focusing on a more low level virtual machine, we have much more room
+   for value add.  The nice safe "sandbox" VM can be provided as a layer
+   on top of it.  It also lets us focus on the more interesting compilers
+   related projects.
+
+> 2. Design issues to consider (an initial list that we should continue
+>    to modify).  Note that I'm not trying to suggest actual solutions here,
+>    but just various directions we can pursue:
+
+Understood.  :)
+
+>    a. A single-assignment VM, which we've both already been thinking
+>       about.
+
+Yup, I think that this makes a lot of sense.  I am still intrigued,
+however, by the prospect of a minimally allocated VM representation... I
+think that it could have definite advantages for certain applications
+(think very small machines, like PDAs).  I don't, however, think that our
+initial implementations should focus on this.  :)
+
+Here are some other auxiliary goals that I think we should consider:
+
+1. Primary goal: Support a high performance dynamic compilation
+   system.  This means that we have an "ideal" division of labor between
+   the runtime and static compilers.  Of course, the other goals of the
+   system somewhat reduce the importance of this point (f.e. portability
+   reduces performance, but hopefully not much)
+2. Portability to different processors.  Since we are most familiar with
+   x86 and solaris, I think that these two are excellent candidates when
+   we get that far...
+3. Support for all languages & styles of programming (general purpose
+   VM).  This is the point that disallows java style bytecodes, where all
+   array refs are checked for bounds, etc...
+4. Support linking between different language families.  For example, call
+   C functions directly from Java without using the nasty/slow/gross JNI
+   layer.  This involves several subpoints:
+  A. Support for languages that require garbage collectors and integration
+     with languages that don't.  As a base point, we could insist on
+     always using a conservative GC, but implement free as a noop, f.e.
+
+>    b. A strongly-typed VM.  One question is do we need the types to be
+>       explicitly declared or should they be inferred by the dynamic
+>       compiler?
+
+  B. This is kind of similar to another idea that I have: make OOP
+     constructs (virtual function tables, class heirarchies, etc) explicit
+     in the VM representation.  I believe that the number of additional
+     constructs would be fairly low, but would give us lots of important
+     information... something else that would/could be important is to
+     have exceptions as first class types so that they would be handled in
+     a uniform way for the entire VM... so that C functions can call Java
+     functions for example...
+
+>    c. How do we get more high-level information into the VM while keeping
+>       to a low-level VM design?
+>       o  Explicit array references as operands?  An alternative is
+>          to have just an array type, and let the index computations be
+>          separate 3-operand instructions.
+
+   C. In the model I was thinking of (subject to change of course), we
+      would just have an array type (distinct from the pointer
+      types).  This would allow us to have arbitrarily complex index
+      expressions, while still distinguishing "load" from "Array load",
+      for example.  Perhaps also, switch jump tables would be first class
+      types as well?  This would allow better reasoning about the program.
+
+5. Support dynamic loading of code from various sources.  Already
+   mentioned above was the example of loading java bytecodes, but we want
+   to support dynamic loading of VM code as well.  This makes the job of
+   the runtime compiler much more interesting:  it can do interprocedural
+   optimizations that the static compiler can't do, because it doesn't
+   have all of the required information (for example, inlining from
+   shared libraries, etc...)
+
+6. Define a set of generally useful annotations to add to the VM
+   representation.  For example, a function can be analysed to see if it
+   has any sideeffects when run... also, the MOD/REF sets could be
+   calculated, etc... we would have to determine what is reasonable.  This
+   would generally be used to make IP optimizations cheaper for the
+   runtime compiler...
+
+>       o  Explicit instructions to handle aliasing, e.g.s:
+>            -- an instruction to say "I speculate that these two values are not
+>               aliased, but check at runtime", like speculative execution in
+>             EPIC?
+>          -- or an instruction to check whether two values are aliased and
+>             execute different code depending on the answer, somewhat like
+>             predicated code in EPIC
+
+These are also very good points... if this can be determined at compile
+time.  I think that an epic style of representation (not the instruction
+packing, just the information presented) could be a very interesting model
+to use... more later...
+
+>         o  (This one is a difficult but powerful idea.)
+>          A "thread-id" field on every instruction that allows the static
+>          compiler to generate a set of parallel threads, and then have
+>          the runtime compiler and hardware do what they please with it.
+>          This has very powerful uses, but thread-id on every instruction
+>          is expensive in terms of instruction size and code size.
+>          We would need to compactly encode it somehow.
+
+Yes yes yes!  :)  I think it would be *VERY* useful to include this kind
+of information (which EPIC architectures *implicitly* encode.  The trend
+that we are seeing supports this greatly:
+
+1. Commodity processors are getting massive SIMD support:
+   * Intel/Amd MMX/MMX2
+   * AMD's 3Dnow!
+   * Intel's SSE/SSE2
+   * Sun's VIS
+2. SMP is becoming much more common, especially in the server space.
+3. Multiple processors on a die are right around the corner.
+
+If nothing else, not designing this in would severely limit our future
+expansion of the project...
+
+>          Also, this will require some reading on at least two other
+>          projects:
+>               -- Multiscalar architecture from Wisconsin
+>               -- Simultaneous multithreading architecture from Washington
+>
+>       o  Or forget all this and stick to a traditional instruction set?
+
+Heh... :)  Well, from a pure research point of view, it is almost more
+attactive to go with the most extreme/different ISA possible.  On one axis
+you get safety and conservatism, and on the other you get degree of
+influence that the results have.  Of course the problem with pure research
+is that often times there is no concrete product of the research... :)
+
+> BTW, on an unrelated note, after the meeting yesterday, I did remember
+> that you had suggested doing instruction scheduling on SSA form instead
+> of a dependence DAG earlier in the semester.  When we talked about
+> it yesterday, I didn't remember where the idea had come from but I
+> remembered later.  Just giving credit where its due...
+
+:) Thanks.  
+
+> Perhaps you can save the above as a file under RCS so you and I can
+> continue to expand on this.
+
+I think it makes sense to do so when we get our ideas more formalized and
+bounce it back and forth a couple of times... then I'll do a more formal
+writeup of our goals and ideas.  Obviously our first implementation will
+not want to do all of the stuff that I pointed out above... be we will
+want to design the project so that we do not artificially limit ourselves
+at sometime in the future...
+
+Anyways, let me know what you think about these ideas... and if they sound
+reasonable...
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2000-12-06-EncodingIdea.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,30 @@
+From: Chris Lattner [mailto:sabre at nondot.org]
+Sent: Wednesday, December 06, 2000 6:41 PM
+To: Vikram S. Adve
+Subject: Additional idea with respect to encoding
+
+Here's another idea with respect to keeping the common case instruction
+size down (less than 32 bits ideally):
+
+Instead of encoding an instruction to operate on two register numbers,
+have it operate on two negative offsets based on the current register
+number.  Therefore, instead of using:
+
+r57 = add r55, r56  (r57 is the implicit dest register, of course)
+
+We could use:
+
+r57 = add -2, -1
+
+My guess is that most SSA references are to recent values (especially if
+they correspond to expressions like (x+y*z+p*q/ ...), so the negative
+numbers would tend to stay small, even at the end of the procedure (where
+the implicit register destination number could be quite large).  Of course
+the negative sign is reduntant, so you would be storing small integers
+almost all of the time, and 5-6 bits worth of register number would be
+plenty for most cases...
+
+What do you think?
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2000-12-06-MeetingSummary.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,83 @@
+SUMMARY
+-------
+
+We met to discuss the LLVM instruction format and bytecode representation:
+
+ISSUES RESOLVED
+---------------
+
+1. We decided that we shall use a flat namespace to represent our 
+   variables in SSA form, as opposed to having a two dimensional namespace
+   of the original variable and the SSA instance subscript.
+
+ARGUMENT AGAINST:
+   * A two dimensional namespace would be valuable when doing alias 
+     analysis because the extra information can help limit the scope of
+     analysis.
+
+ARGUMENT FOR:
+   * Including this information would require that all users of the LLVM
+     bytecode would have to parse and handle it.  This would slow down the
+     common case and inflate the instruction representation with another
+     infinite variable space.
+
+REASONING:
+   * It was decided that because original variable sources could be
+     reconstructed from SSA form in linear time, that it would be an
+     unjustified expense for the common case to include the extra
+     information for one optimization.  Alias analysis itself is typically
+     greater than linear in asymptotic complexity, so this extra analaysis
+     would not affect the runtime of the optimization in a significant
+     way.  Additionally, this would be an unlikely optimization to do at
+     runtime.
+
+
+IDEAS TO CONSIDER
+-----------------
+
+1. Including dominator information in the LLVM bytecode
+   representation.  This is one example of an analysis result that may be
+   packaged with the bytecodes themselves.  As a conceptual implementation 
+   idea, we could include an immediate dominator number for each basic block
+   in the LLVM bytecode program.  Basic blocks could be numbered according
+   to the order of occurrence in the bytecode representation.
+
+2. Including loop header and body information.  This would facilitate
+   detection of intervals and natural loops.
+
+UNRESOLVED ISSUES 
+----------------- 
+
+1. Will oSUIF provide enough of an infrastructure to support the research
+   that we will be doing?  We know that it has less than stellar
+   performance, but hope that this will be of little importance for our
+   static compiler.  This could affect us if we decided to do some IP
+   research.  Also we do not yet understand the level of exception support
+   currently implemented.
+
+2. Should we consider the requirements of a direct hardware implementation
+   of the LLVM when we design it?  If so, several design issues should
+   have their priorities shifted.  The other option is to focus on a
+   software layer interpreting the LLVM in all cases.
+
+3. Should we use some form of packetized format to improve forward
+   compatibility?  For example, we could design the system to encode a
+   packet type and length field before analysis information, to allow a
+   runtime to skip information that it didn't understand in a bytecode
+   stream.  The obvious benefit would be for compatibility, the drawback
+   is that it would tend to splinter that 'standard' LLVM definition.
+
+4. Should we use fixed length instructions or variable length
+   instructions?  Fetching variable length instructions is expensive (for
+   either hardware or software based LLVM runtimes), but we have several
+   'infinite' spaces that instructions operate in (SSA register numbers,
+   type spaces, or packet length [if packets were implemented]).  Several
+   options were mentioned including: 
+     A. Using 16 or 32 bit numbers, which would be 'big enough'
+     B. A scheme similar to how UTF-8 works, to encode infinite numbers
+        while keeping small number small.
+     C. Use something similar to Huffman encoding, so that the most common
+        numbers are the smallest.
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-01-31-UniversalIRIdea.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,39 @@
+Date: Wed, 31 Jan 2001 12:04:33 -0600
+From: Vikram S. Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <lattner at cs.uiuc.edu>
+Subject: another thought
+
+I have a budding idea about making LLVM a little more ambitious: a
+customizable runtime system that can be used to implement language-specific
+virtual machines for many different languages.  E.g., a C vm, a C++ vm, a
+Java vm, a Lisp vm, ..
+
+The idea would be that LLVM would provide a standard set of runtime features
+(some low-level like standard assembly instructions with code generation and
+static and runtime optimization; some higher-level like type-safety and
+perhaps a garbage collection library).  Each language vm would select the
+runtime features needed for that language, extending or customizing them as
+needed.  Most of the machine-dependent code-generation and optimization
+features as well as low-level machine-independent optimizations (like PRE)
+could be provided by LLVM and should be sufficient for any language,
+simplifying the language compiler.  (This would also help interoperability
+between languages.)  Also, some or most of the higher-level
+machine-independent features like type-safety and access safety should be
+reusable by different languages, with minor extensions.  The language
+compiler could then focus on language-specific analyses and optimizations.
+
+The risk is that this sounds like a universal IR -- something that the
+compiler community has tried and failed to develop for decades, and is
+universally skeptical about.  No matter what we say, we won't be able to
+convince anyone that we have a universal IR that will work.  We need to
+think about whether LLVM is different or if has something novel that might
+convince people.  E.g., the idea of providing a package of separable
+features that different languages select from.  Also, using SSA with or
+without type-safety as the intermediate representation.
+
+One interesting starting point would be to discuss how a JVM would be
+implemented on top of LLVM a bit more.  That might give us clues on how to
+structure LLVM to support one or more language VMs.
+
+--Vikram
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebate.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,67 @@
+Date: Tue, 6 Feb 2001 20:27:37 -0600 (CST)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: Type notation debate...
+
+This is the way that I am currently planning on implementing types:
+
+Primitive Types:        
+type ::= void|bool|sbyte|ubyte|short|ushort|int|uint|long|ulong
+
+Method:
+typelist ::= typelisth | /*empty*/
+typelisth ::= type | typelisth ',' type
+type ::= type (typelist)
+
+Arrays (without and with size):
+type ::= '[' type ']' | '[' INT ',' type ']'
+
+Pointer:
+type ::= type '*'
+
+Structure:
+type ::= '{' typelist '}'
+
+Packed:
+type ::= '<' INT ',' type '>'
+
+Simple examples:
+
+[[ %4, int ]]   - array of (array of 4 (int))
+[ { int, int } ] - Array of structure
+[ < %4, int > ] - Array of 128 bit SIMD packets
+int (int, [[int, %4]])  - Method taking a 2d array and int, returning int
+
+
+Okay before you comment, please look at:
+
+http://www.research.att.com/~bs/devXinterview.html
+
+Search for "In another interview, you defined the C declarator syntax as
+an experiment that failed. However, this syntactic construct has been
+around for 27 years and perhaps more; why do you consider it problematic
+(except for its cumbersome syntax)?" and read that response for me.  :)
+
+Now with this syntax, his example would be represented as:
+
+[ %10, bool (int, int) * ] *
+
+vs 
+
+bool (*(*)[10])(int, int)
+
+in C.
+
+Basically, my argument for this type construction system is that it is
+VERY simple to use and understand (although it IS different than C, it is
+very simple and straightforward, which C is NOT).  In fact, I would assert
+that most programmers TODAY do not understand pointers to member
+functions, and have to look up an example when they have to write them.
+
+In my opinion, it is critically important to have clear and concise type
+specifications, because types are going to be all over the programs.
+
+Let me know your thoughts on this.  :)
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp1.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,75 @@
+Date: Thu, 8 Feb 2001 08:42:04 -0600
+From: Vikram S. Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <sabre at nondot.org>
+Subject: RE: Type notation debate...
+
+Chris,
+
+> Okay before you comment, please look at:
+>
+> http://www.research.att.com/~bs/devXinterview.html
+
+I read this argument.  Even before that, I was already in agreement with you
+and him that the C declarator syntax is difficult and confusing.
+
+But in fact, if you read the entire answer carefully, he came to the same
+conclusion I do: that you have to go with familiar syntax over logical
+syntax because familiarity is such a strong force:
+
+        "However, familiarity is a strong force. To compare, in English, we
+live
+more or less happily with the absurd rules for "to be" (am, are, is, been,
+was, were, ...) and all attempts to simplify are treated with contempt or
+(preferably) humor. It be a curious world and it always beed."
+
+> Basically, my argument for this type construction system is that it is
+> VERY simple to use and understand (although it IS different than C, it is
+> very simple and straightforward, which C is NOT).  In fact, I would assert
+> that most programmers TODAY do not understand pointers to member
+> functions, and have to look up an example when they have to write them.
+
+Again, I don't disagree with this at all.  But to some extent this
+particular problem is inherently difficult.  Your syntax for the above
+example may be easier for you to read because this is the way you have been
+thinking about it.  Honestly, I don't find it much easier than the C syntax.
+In either case, I would have to look up an example to write pointers to
+member functions.
+
+But pointers to member functions are nowhere near as common as arrays.  And
+the old array syntax:
+        type [ int, int, ...]
+is just much more familiar and clear to people than anything new you
+introduce, no matter how logical it is.  Introducing a new syntax that may
+make function pointers easier but makes arrays much more difficult seems
+very risky to me.
+
+> In my opinion, it is critically important to have clear and concise type
+> specifications, because types are going to be all over the programs.
+
+I absolutely agree.  But the question is, what is more clear and concise?
+The syntax programmers are used to out of years of experience or a new
+syntax that they have never seen that has a more logical structure.  I think
+the answer is the former.  Sometimes, you have to give up a better idea
+because you can't overcome sociological barriers to it.  Qwerty keyboards
+and Windows are two classic examples of bad technology that are difficult to
+root out.
+
+P.S.  Also, while I agree that most your syntax is more logical, there is
+one part that isn't:
+
+Arrays (without and with size):
+type ::= '[' type ']' | '[' INT ',' type ']'.
+
+The arrays with size lists the dimensions and the type in a single list.
+That is just too confusing:
+        [10, 40, int]
+This seems to be a 3-D array where the third dimension is something strange.
+It is too confusing to have a list of 3 things, some of which are dimensions
+and one is a type.  Either of the following would be better:
+
+        array [10, 40] of int
+or
+        int [10, 40]
+
+--Vikram
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp2.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,53 @@
+Date: Thu, 8 Feb 2001 14:31:05 -0600 (CST)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: RE: Type notation debate...
+
+> Arrays (without and with size):
+> type ::= '[' type ']' | '[' INT ',' type ']'.
+> 
+> The arrays with size lists the dimensions and the type in a single list.
+> That is just too confusing:
+
+>       [10, 40, int]
+> This seems to be a 3-D array where the third dimension is something strange.
+> It is too confusing to have a list of 3 things, some of which are dimensions
+> and one is a type. 
+
+The above grammar indicates that there is only one integer parameter, ie
+the upper bound.  The lower bound is always implied to be zero, for
+several reasons:
+
+* As a low level VM, we want to expose addressing computations
+  explicitly.  Since the lower bound must always be known in a high level
+  language statically, the language front end can do the translation
+  automatically.
+* This fits more closely with what Java needs, ie what we need in the
+  short term.  Java arrays are always zero based.
+
+If a two element list is too confusing, I would recommend an alternate
+syntax of:
+
+type ::= '[' type ']' | '[' INT 'x' type ']'.
+
+For example:
+  [12 x int]
+  [12x int]
+  [ 12 x [ 4x int ]]
+
+Which is syntactically nicer, and more explicit.
+
+> Either of the following would be better:
+>       array [10, 40] of int
+
+I considered this approach for arrays in general (ie array of int/ array
+of 12 int), but found that it made declarations WAY too long.  Remember
+that because of the nature of llvm, you get a lot of types strewn all over
+the program, and using the 'typedef' like facility is not a wonderful
+option, because then types aren't explicit anymore.
+
+I find this email interesting, because you contradict the previous email
+you sent, where you recommend that we stick to C syntax....
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-06-TypeNotationDebateResp4.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,89 @@
+> But in fact, if you read the entire answer carefully, he came to the same
+> conclusion I do: that you have to go with familiar syntax over logical
+> syntax because familiarity is such a strong force:
+>       "However, familiarity is a strong force. To compare, in English, we
+live
+> more or less happily with the absurd rules for "to be" (am, are, is, been,
+> was, were, ...) and all attempts to simplify are treated with contempt or
+> (preferably) humor. It be a curious world and it always beed."
+
+Although you have to remember that his situation was considerably
+different than ours.  He was in a position where he was designing a high
+level language that had to be COMPATIBLE with C.  Our language is such
+that a new person would have to learn the new, different, syntax
+anyways.  Making them learn about the type system does not seem like much
+of a stretch from learning the opcodes and how SSA form works, and how
+everything ties together...
+
+> > Basically, my argument for this type construction system is that it is
+> > VERY simple to use and understand (although it IS different than C, it is
+> > very simple and straightforward, which C is NOT).  In fact, I would assert
+> > that most programmers TODAY do not understand pointers to member
+> > functions, and have to look up an example when they have to write them.
+
+> Again, I don't disagree with this at all.  But to some extent this
+> particular problem is inherently difficult.  Your syntax for the above
+> example may be easier for you to read because this is the way you have been
+> thinking about it.  Honestly, I don't find it much easier than the C syntax.
+> In either case, I would have to look up an example to write pointers to
+> member functions.
+
+I would argue that because the lexical structure of the language is self
+consistent, any person who spent a significant amount of time programming
+in LLVM directly would understand how to do it without looking it up in a
+manual.  The reason this does not work for C is because you rarely have to
+declare these pointers, and the syntax is inconsistent with the method
+declaration and calling syntax.
+
+> But pointers to member functions are nowhere near as common as arrays.
+
+Very true.  If you're implementing an object oriented language, however,
+remember that you have to do all the pointer to member function stuff
+yourself.... so every time you invoke a virtual method one is involved
+(instead of having C++ hide it for you behind "syntactic sugar").
+
+> And the old array syntax:
+>       type [ int, int, ...]
+> is just much more familiar and clear to people than anything new you
+> introduce, no matter how logical it is.  
+
+Erm... excuse me but how is this the "old array syntax"?  If you are
+arguing for consistency with C, you should be asking for 'type int []',
+which is significantly different than the above (beside the above
+introduces a new operator and duplicates information
+needlessly).  Basically what I am suggesting is exactly the above without
+the fluff.  So instead of:
+
+       type [ int, int, ...]
+
+you use:
+
+       type [ int ]
+
+> Introducing a new syntax that may
+> make function pointers easier but makes arrays much more difficult seems
+> very risky to me.
+
+This is not about function pointers.  This is about consistency in the
+type system, and consistency with the rest of the language.  The point
+above does not make arrays any more difficult to use, and makes the
+structure of types much more obvious than the "c way".
+
+> > In my opinion, it is critically important to have clear and concise type
+> > specifications, because types are going to be all over the programs.
+> 
+> I absolutely agree.  But the question is, what is more clear and concise?
+> The syntax programmers are used to out of years of experience or a new
+> syntax that they have never seen that has a more logical structure.  I think
+> the answer is the former.  Sometimes, you have to give up a better idea
+> because you can't overcome sociological barriers to it.  Qwerty keyboards
+> and Windows are two classic examples of bad technology that are difficult to
+> root out.
+
+Very true, but you seem to be advocating a completely different Type
+system than C has, in addition to it not offering the advantages of clear
+structure that the system I recommended does... so you seem to not have a
+problem with changing this, just with what I change it to.  :)
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-09-AdveComments.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-09-AdveComments.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-09-AdveComments.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-09-AdveComments.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,120 @@
+Ok, here are my comments and suggestions about the LLVM instruction set.
+We should discuss some now, but can discuss many of them later, when we
+revisit synchronization, type inference, and other issues.
+(We have discussed some of the comments already.)
+
+
+o  We should consider eliminating the type annotation in cases where it is
+   essentially obvious from the instruction type, e.g., in br, it is obvious
+   that the first arg. should be a bool and the other args should be labels:
+
+	br bool <cond>, label <iftrue>, label <iffalse>
+
+   I think your point was that making all types explicit improves clarity
+   and readability.  I agree to some extent, but it also comes at the cost
+   of verbosity.  And when the types are obvious from people's experience
+   (e.g., in the br instruction), it doesn't seem to help as much.
+
+
+o  On reflection, I really like your idea of having the two different switch
+   types (even though they encode implementation techniques rather than
+   semantics).  It should simplify building the CFG and my guess is it could
+   enable some significant optimizations, though we should think about which.
+
+
+o  In the lookup-indirect form of the switch, is there a reason not to make
+   the val-type uint?  Most HLL switch statements (including Java and C++)
+   require that anyway.  And it would also make the val-type uniform 
+   in the two forms of the switch.
+
+   I did see the switch-on-bool examples and, while cute, we can just use
+   the branch instructions in that particular case.
+
+
+o  I agree with your comment that we don't need 'neg'.
+
+
+o  There's a trade-off with the cast instruction:
+   +  it avoids having to define all the upcasts and downcasts that are
+      valid for the operands of each instruction  (you probably have thought
+      of other benefits also)
+   -  it could make the bytecode significantly larger because there could
+      be a lot of cast operations
+
+
+o  Making the second arg. to 'shl' a ubyte seems good enough to me.
+   255 positions seems adequate for several generations of machines
+   and is more compact than uint.
+
+
+o  I still have some major concerns about including malloc and free in the
+   language (either as builtin functions or instructions).  LLVM must be
+   able to represent code from many different languages.  Languages such as
+   C, C++ Java and Fortran 90 would not be able to use our malloc anyway
+   because each of them will want to provide a library implementation of it.
+
+   This gets even worse when code from different languages is linked
+   into a single executable (which is fairly common in large apps).
+   Having a single malloc would just not suffice, and instead would simply
+   complicate the picture further because it adds an extra variant in
+   addition to the one each language provides.
+
+   Instead, providing a default library version of malloc and free
+   (and perhaps a malloc_gc with garbage collection instead of free)
+   would make a good implementation available to anyone who wants it.
+
+   I don't recall all your arguments in favor so let's discuss this again,
+   and soon.
+
+
+o  'alloca' on the other hand sounds like a good idea, and the
+   implementation seems fairly language-independent so it doesn't have the
+   problems with malloc listed above.
+
+
+o  About indirect call:
+   Your option #2 sounded good to me.  I'm not sure I understand your
+   concern about an explicit 'icall' instruction?
+
+
+o  A pair of important synchronization instr'ns to think about:
+     load-linked
+     store-conditional
+
+
+o  Other classes of instructions that are valuable for pipeline performance:
+     conditional-move		 
+     predicated instructions
+
+
+o  I believe tail calls are relatively easy to identify; do you know why
+   .NET has a tailcall instruction?
+
+
+o  I agree that we need a static data space.  Otherwise, emulating global
+   data gets unnecessarily complex.
+
+
+o  About explicit parallelism:
+
+   We once talked about adding a symbolic thread-id field to each
+   instruction.  (It could be optional so single-threaded codes are
+   not penalized.)  This could map well to multi-threaded architectures
+   while providing easy ILP for single-threaded onces.  But it is probably
+   too radical an idea to include in a base version of LLVM.  Instead, it
+   could a great topic for a separate study.
+
+   What is the semantics of the IA64 stop bit?
+
+
+
+
+o  And finally, another thought about the syntax for arrays :-)
+
+   Although this syntax:
+	  array <dimension-list> of <type>
+   is verbose, it will be used only in the human-readable assembly code so
+   size should not matter.  I think we should consider it because I find it
+   to be the clearest syntax.  It could even make arrays of function
+   pointers somewhat readable.
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-09-AdveCommentsResponse.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,245 @@
+From: Chris Lattner <sabre at nondot.org>
+To: "Vikram S. Adve" <vadve at cs.uiuc.edu>
+Subject: Re: LLVM Feedback
+
+I've included your feedback in the /home/vadve/lattner/llvm/docs directory
+so that it will live in CVS eventually with the rest of LLVM.  I've
+significantly updated the documentation to reflect the changes you
+suggested, as specified below:
+
+> We should consider eliminating the type annotation in cases where it is
+> essentially obvious from the instruction type:
+>        br bool <cond>, label <iftrue>, label <iffalse>
+> I think your point was that making all types explicit improves clarity
+> and readability.  I agree to some extent, but it also comes at the
+> cost of verbosity.  And when the types are obvious from people's
+> experience (e.g., in the br instruction), it doesn't seem to help as
+> much.
+
+Very true.  We should discuss this more, but my reasoning is more of a
+consistency argument.  There are VERY few instructions that can have all
+of the types eliminated, and doing so when available unnecessarily makes
+the language more difficult to handle.  Especially when you see 'int
+%this' and 'bool %that' all over the place, I think it would be
+disorienting to see:
+
+  br %predicate, %iftrue, %iffalse
+
+for branches.  Even just typing that once gives me the creeps. ;)  Like I
+said, we should probably discuss this further in person...
+
+> On reflection, I really like your idea of having the two different
+> switch types (even though they encode implementation techniques rather
+> than semantics).  It should simplify building the CFG and my guess is it
+> could enable some significant optimizations, though we should think
+> about which.
+
+Great.  I added a note to the switch section commenting on how the VM
+should just use the instruction type as a hint, and that the
+implementation may choose altermate representations (such as predicated
+branches).
+
+> In the lookup-indirect form of the switch, is there a reason not to
+> make the val-type uint?
+
+No.  This was something I was debating for a while, and didn't really feel
+strongly about either way.  It is common to switch on other types in HLL's
+(for example signed int's are particularly common), but in this case, all
+that will be added is an additional 'cast' instruction.  I removed that
+from the spec.
+
+> I agree with your comment that we don't need 'neg'
+
+Removed.
+
+> There's a trade-off with the cast instruction:
+>  +  it avoids having to define all the upcasts and downcasts that are
+>     valid for the operands of each instruction  (you probably have
+>     thought of other benefits also)
+>  -  it could make the bytecode significantly larger because there could
+>     be a lot of cast operations
+
+ + You NEED casts to represent things like:
+    void foo(float);
+    ...
+    int x;
+    ...
+    foo(x);
+   in a language like C.  Even in a Java like language, you need upcasts
+   and some way to implement dynamic downcasts.
+ + Not all forms of instructions take every type (for example you can't
+   shift by a floating point number of bits), thus SOME programs will need
+   implicit casts.
+
+To be efficient and to avoid your '-' point above, we just have to be
+careful to specify that the instructions shall operate on all common
+types, therefore casting should be relatively uncommon.  For example all
+of the arithmetic operations work on almost all data types.
+
+> Making the second arg. to 'shl' a ubyte seems good enough to me.
+> 255 positions seems adequate for several generations of machines
+
+Okay, that comment is removed.
+
+> and is more compact than uint.
+
+No, it isn't.  Remember that the bytecode encoding saves value slots into
+the bytecode instructions themselves, not constant values.  This is
+another case where we may introduce more cast instructions (but we will
+also reduce the number of opcode variants that must be supported by a
+virtual machine).  Because most shifts are by constant values, I don't
+think that we'll have to cast many shifts.  :)
+
+> I still have some major concerns about including malloc and free in the
+> language (either as builtin functions or instructions).
+
+Agreed.  How about this proposal:
+
+malloc/free are either built in functions or actual opcodes.  They provide
+all of the type safety that the document would indicate, blah blah
+blah. :)
+
+Now, because of all of the excellent points that you raised, an
+implementation may want to override the default malloc/free behavior of
+the program.  To do this, they simply implement a "malloc" and
+"free" function.  The virtual machine will then be defined to use the user
+defined malloc/free function (which return/take void*'s, not type'd
+pointers like the builtin function would) if one is available, otherwise
+fall back on a system malloc/free.
+
+Does this sound like a good compromise?  It would give us all of the
+typesafety/elegance in the language while still allowing the user to do
+all the cool stuff they want to...
+
+>  'alloca' on the other hand sounds like a good idea, and the
+>  implementation seems fairly language-independent so it doesn't have the
+>  problems with malloc listed above.
+
+Okay, once we get the above stuff figured out, I'll put it all in the
+spec.
+
+>  About indirect call:
+>  Your option #2 sounded good to me.  I'm not sure I understand your
+>  concern about an explicit 'icall' instruction?
+
+I worry too much.  :)  The other alternative has been removed. 'icall' is
+now up in the instruction list next to 'call'.
+
+> I believe tail calls are relatively easy to identify; do you know why
+> .NET has a tailcall instruction?
+
+Although I am just guessing, I believe it probably has to do with the fact
+that they want languages like Haskell and lisp to be efficiently runnable
+on their VM.  Of course this means that the VM MUST implement tail calls
+'correctly', or else life will suck.  :)  I would put this into a future
+feature bin, because it could be pretty handy...
+
+>  A pair of important synchronization instr'ns to think about:
+>    load-linked
+>    store-conditional
+
+What is 'load-linked'?  I think that (at least for now) I should add these
+to the 'possible extensions' section, because they are not immediately
+needed...
+
+> Other classes of instructions that are valuable for pipeline
+> performance:
+>    conditional-move            
+>    predicated instructions
+
+Conditional move is effectly a special case of a predicated
+instruction... and I think that all predicated instructions can possibly
+be implemented later in LLVM.  It would significantly change things, and
+it doesn't seem to be very necessary right now.  It would seem to
+complicate flow control analysis a LOT in the virtual machine.  I would
+tend to prefer that a predicated architecture like IA64 convert from a
+"basic block" representation to a predicated rep as part of it's dynamic
+complication phase.  Also, if a basic block contains ONLY a move, then
+that can be trivally translated into a conditional move...
+
+> I agree that we need a static data space.  Otherwise, emulating global
+> data gets unnecessarily complex.
+
+Definitely.  Also a later item though.  :)
+
+> We once talked about adding a symbolic thread-id field to each
+> ..
+> Instead, it could a great topic for a separate study.
+
+Agreed.  :)
+
+> What is the semantics of the IA64 stop bit?
+
+Basically, the IA64 writes instructions like this:
+mov ...
+add ...
+sub ...
+op xxx
+op xxx
+;;
+mov ...
+add ...
+sub ...
+op xxx
+op xxx
+;;
+
+Where the ;; delimits a group of instruction with no dependencies between
+them, which can all be executed concurrently (to the limits of the
+available functional units).  The ;; gets translated into a bit set in one
+of the opcodes.
+
+The advantages of this representation is that you don't have to do some
+kind of 'thread id scheduling' pass by having to specify ahead of time how
+many threads to use, and the representation doesn't have a per instruction
+overhead...
+
+> And finally, another thought about the syntax for arrays :-)
+>  Although this syntax:
+>         array <dimension-list> of <type>
+>  is verbose, it will be used only in the human-readable assembly code so
+>  size should not matter.  I think we should consider it because I find it
+>  to be the clearest syntax.  It could even make arrays of function
+>  pointers somewhat readable.
+
+My only comment will be to give you an example of why this is a bad
+idea.  :)
+
+Here is an example of using the switch statement (with my recommended
+syntax):
+
+switch uint %val, label %otherwise, 
+       [%3 x {uint, label}] [ { uint %57, label %l1 }, 
+                              { uint %20, label %l2 }, 
+                              { uint %14, label %l3 } ]
+
+Here it is with the syntax you are proposing:
+
+switch uint %val, label %otherwise, 
+       array %3 of {uint, label} 
+              array of {uint, label}
+                              { uint %57, label %l1 },
+                              { uint %20, label %l2 },
+                              { uint %14, label %l3 }
+
+Which is ambiguous and very verbose. It would be possible to specify
+constants with [] brackets as in my syntax, which would look like this:
+
+switch uint %val, label %otherwise,
+       array %3 of {uint, label}  [ { uint %57, label %l1 },
+                                    { uint %20, label %l2 },
+                                    { uint %14, label %l3 } ]
+
+But then the syntax is inconsistent between type definition and constant
+definition (why do []'s enclose the constants but not the types??).  
+
+Anyways, I'm sure that there is much debate still to be had over
+this... :)
+
+-Chris
+
+http://www.nondot.org/~sabre/os/
+http://www.nondot.org/MagicStats/
+http://korbit.sourceforge.net/
+
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-13-Reference-Memory.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,39 @@
+Date: Tue, 13 Feb 2001 13:29:52 -0600 (CST)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: LLVM Concerns...
+
+
+I've updated the documentation to include load store and allocation
+instructions (please take a look and let me know if I'm on the right
+track):
+
+file:/home/vadve/lattner/llvm/docs/LangRef.html#memoryops
+
+I have a couple of concerns I would like to bring up:
+
+1. Reference types
+   Right now, I've spec'd out the language to have a pointer type, which
+   works fine for lots of stuff... except that Java really has
+   references: constrained pointers that cannot be manipulated: added and
+   subtracted, moved, etc... Do we want to have a type like this?  It
+   could be very nice for analysis (pointer always points to the start of
+   an object, etc...) and more closely matches Java semantics.  The
+   pointer type would be kept for C++ like semantics.  Through analysis,
+   C++ pointers could be promoted to references in the LLVM
+   representation.
+
+2. Our "implicit" memory references in assembly language:
+   After thinking about it, this model has two problems:
+      A. If you do pointer analysis and realize that two stores are
+         independent and can share the same memory source object, there is
+         no way to represent this in either the bytecode or assembly.
+      B. When parsing assembly/bytecode, we effectively have to do a full
+         SSA generation/PHI node insertion pass to build the dependencies
+         when we don't want the "pinned" representation.  This is not
+         cool.
+   I'm tempted to make memory references explicit in both the assembly and
+   bytecode to get around this... what do you think?
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-02-13-Reference-MemoryResponse.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,47 @@
+Date: Tue, 13 Feb 2001 18:25:42 -0600
+From: Vikram S. Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <sabre at nondot.org>
+Subject: RE: LLVM Concerns...
+
+> 1. Reference types
+>    Right now, I've spec'd out the language to have a pointer type, which
+>    works fine for lots of stuff... except that Java really has
+>    references: constrained pointers that cannot be manipulated: added and
+>    subtracted, moved, etc... Do we want to have a type like this?  It
+>    could be very nice for analysis (pointer always points to the start of
+>    an object, etc...) and more closely matches Java semantics.  The
+>    pointer type would be kept for C++ like semantics.  Through analysis,
+>    C++ pointers could be promoted to references in the LLVM
+>    representation.
+
+
+You're right, having references would be useful.  Even for C++ the *static*
+compiler could generate references instead of pointers with fairly
+straightforward analysis.  Let's include a reference type for now.  But I'm
+also really concerned that LLVM is becoming big and complex and (perhaps)
+too high-level.  After we get some initial performance results, we may have
+a clearer idea of what our goals should be and we should revisit this
+question then.
+
+> 2. Our "implicit" memory references in assembly language:
+>    After thinking about it, this model has two problems:
+>       A. If you do pointer analysis and realize that two stores are
+>          independent and can share the same memory source object,
+
+not sure what you meant by "share the same memory source object"
+
+> there is
+>          no way to represent this in either the bytecode or assembly.
+>       B. When parsing assembly/bytecode, we effectively have to do a full
+>          SSA generation/PHI node insertion pass to build the dependencies
+>          when we don't want the "pinned" representation.  This is not
+>          cool.
+
+I understand the concern.  But again, let's focus on the performance first
+and then look at the language design issues.  E.g., it would be good to know
+how big the bytecode files are before expanding them further.  I am pretty
+keen to explore the implications of LLVM for mobile devices.  Both bytecode
+size and power consumption are important to consider there.
+
+--Vikram
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-04-16-DynamicCompilation.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,49 @@
+By Chris:
+
+LLVM has been designed with two primary goals in mind.  First we strive to 
+enable the best possible division of labor between static and dynamic 
+compilers, and second, we need a flexible and powerful interface 
+between these two complementary stages of compilation.  We feel that 
+providing a solution to these two goals will yield an excellent solution 
+to the performance problem faced by modern architectures and programming 
+languages.
+
+A key insight into current compiler and runtime systems is that a 
+compiler may fall in anywhere in a "continuum of compilation" to do its 
+job.  On one side, scripting languages statically compile nothing and 
+dynamically compile (or equivalently, interpret) everything.  On the far 
+other side, traditional static compilers process everything statically and 
+nothing dynamically.  These approaches have typically been seen as a 
+tradeoff between performance and portability.  On a deeper level, however, 
+there are two reasons that optimal system performance may be obtained by a
+system somewhere in between these two extremes: Dynamic application 
+behavior and social constraints.
+
+From a technical perspective, pure static compilation cannot ever give 
+optimal performance in all cases, because applications have varying dynamic
+behavior that the static compiler cannot take into consideration.  Even 
+compilers that support profile guided optimization generate poor code in 
+the real world, because using such optimization tunes that application 
+to one particular usage pattern, whereas real programs (as opposed to 
+benchmarks) often have several different usage patterns.
+
+On a social level, static compilation is a very shortsighted solution to 
+the performance problem.  Instruction set architectures (ISAs) continuously 
+evolve, and each implementation of an ISA (a processor) must choose a set 
+of tradeoffs that make sense in the market context that it is designed for.  
+With every new processor introduced, the vendor faces two fundamental 
+problems: First, there is a lag time between when a processor is introduced 
+to when compilers generate quality code for the architecture.  Secondly, 
+even when compilers catch up to the new architecture there is often a large 
+body of legacy code that was compiled for previous generations and will 
+not or can not be upgraded.  Thus a large percentage of code running on a 
+processor may be compiled quite sub-optimally for the current 
+characteristics of the dynamic execution environment.
+
+For these reasons, LLVM has been designed from the beginning as a long-term 
+solution to these problems.  Its design allows the large body of platform 
+independent, static, program optimizations currently in compilers to be 
+reused unchanged in their current form.  It also provides important static 
+type information to enable powerful dynamic and link time optimizations 
+to be performed quickly and efficiently.  This combination enables an 
+increase in effective system performance for real world environments.

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-05-18-ExceptionHandling.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,202 @@
+Meeting notes: Implementation idea: Exception Handling in C++/Java
+
+The 5/18/01 meeting discussed ideas for implementing exceptions in LLVM.
+We decided that the best solution requires a set of library calls provided by
+the VM, as well as an extension to the LLVM function invocation syntax.
+
+The LLVM function invocation instruction previously looks like this (ignoring
+types):
+
+  call func(arg1, arg2, arg3)
+
+The extension discussed today adds an optional "with" clause that 
+associates a label with the call site.  The new syntax looks like this:
+
+  call func(arg1, arg2, arg3) with funcCleanup
+
+This funcHandler always stays tightly associated with the call site (being
+encoded directly into the call opcode itself), and should be used whenever
+there is cleanup work that needs to be done for the current function if 
+an exception is thrown by func (or if we are in a try block).
+
+To support this, the VM/Runtime provide the following simple library 
+functions (all syntax in this document is very abstract):
+
+typedef struct { something } %frame;
+  The VM must export a "frame type", that is an opaque structure used to 
+  implement different types of stack walking that may be used by various
+  language runtime libraries. We imagine that it would be typical to 
+  represent a frame with a PC and frame pointer pair, although that is not 
+  required.
+
+%frame getStackCurrentFrame();
+  Get a frame object for the current function.  Note that if the current
+  function was inlined into its caller, the "current" frame will belong to
+  the "caller".
+
+bool isFirstFrame(%frame f);
+  Returns true if the specified frame is the top level (first activated) frame
+  for this thread.  For the main thread, this corresponds to the main() 
+  function, for a spawned thread, it corresponds to the thread function.
+
+%frame getNextFrame(%frame f);
+  Return the previous frame on the stack.  This function is undefined if f
+  satisfies the predicate isFirstFrame(f).
+
+Label *getFrameLabel(%frame f);
+  If a label was associated with f (as discussed below), this function returns
+  it.  Otherwise, it returns a null pointer.
+
+doNonLocalBranch(Label *L);
+  At this point, it is not clear whether this should be a function or 
+  intrinsic.  It should probably be an intrinsic in LLVM, but we'll deal with
+  this issue later.
+
+
+Here is a motivating example that illustrates how these facilities could be
+used to implement the C++ exception model:
+
+void TestFunction(...) {
+  A a; B b;
+  foo();        // Any function call may throw
+  bar();
+  C c;
+
+  try {
+    D d;
+    baz();
+  } catch (int) {
+    ...int Stuff...
+    // execution continues after the try block: the exception is consumed
+  } catch (double) {
+    ...double stuff...
+   throw;            // Exception is propogated
+  }
+}
+
+This function would compile to approximately the following code (heavy 
+pseudo code follows):
+
+Func:
+  %a = alloca A
+  A::A(%a)        // These ctors & dtors could throw, but we ignore this 
+  %b = alloca B   // minor detail for this example
+  B::B(%b)
+
+  call foo() with fooCleanup // An exception in foo is propogated to fooCleanup
+  call bar() with barCleanup // An exception in bar is propogated to barCleanup
+
+  %c = alloca C
+  C::C(c)
+  %d = alloca D
+  D::D(d)
+  call baz() with bazCleanup // An exception in baz is propogated to bazCleanup
+  d->~D();
+EndTry:                   // This label corresponds to the end of the try block
+  c->~C()       // These could also throw, these are also ignored
+  b->~B()
+  a->~A()
+  return
+
+Note that this is a very straight forward and literal translation: exactly
+what we want for zero cost (when unused) exception handling.  Especially on
+platforms with many registers (ie, the IA64) setjmp/longjmp style exception
+handling is *very* impractical.  Also, the "with" clauses describe the 
+control flow paths explicitly so that analysis is not adversly effected.
+
+The foo/barCleanup labels are implemented as:
+
+TryCleanup:          // Executed if an exception escapes the try block  
+  c->~C()
+barCleanup:          // Executed if an exception escapes from bar()
+  // fall through
+fooCleanup:          // Executed if an exception escapes from foo()
+  b->~B()
+  a->~A()
+  Exception *E = getThreadLocalException()
+  call throw(E)      // Implemented by the C++ runtime, described below
+
+Which does the work one would expect.  getThreadLocalException is a function
+implemented by the C++ support library.  It returns the current exception 
+object for the current thread.  Note that we do not attempt to recycle the 
+shutdown code from before, because performance of the mainline code is 
+critically important.  Also, obviously fooCleanup and barCleanup may be 
+merged and one of them eliminated.  This just shows how the code generator 
+would most likely emit code.
+
+The bazCleanup label is more interesting.  Because the exception may be caught
+by the try block, we must dispatch to its handler... but it does not exist
+on the call stack (it does not have a VM Call->Label mapping installed), so 
+we must dispatch statically with a goto.  The bazHandler thus appears as:
+
+bazHandler:
+  d->~D();    // destruct D as it goes out of scope when entering catch clauses
+  goto TryHandler
+
+In general, TryHandler is not the same as bazHandler, because multiple 
+function calls could be made from the try block.  In this case, trivial 
+optimization could merge the two basic blocks.  TryHandler is the code 
+that actually determines the type of exception, based on the Exception object
+itself.  For this discussion, assume that the exception object contains *at
+least*:
+
+1. A pointer to the RTTI info for the contained object
+2. A pointer to the dtor for the contained object
+3. The contained object itself
+
+Note that it is necessary to maintain #1 & #2 in the exception object itself
+because objects without virtual function tables may be thrown (as in this 
+example).  Assuming this, TryHandler would look something like this:
+
+TryHandler: 
+  Exception *E = getThreadLocalException();
+  switch (E->RTTIType) {
+  case IntRTTIInfo:
+    ...int Stuff...       // The action to perform from the catch block
+    break;
+  case DoubleRTTIInfo:
+    ...double Stuff...    // The action to perform from the catch block
+    goto TryCleanup       // This catch block rethrows the exception
+    break;                // Redundant, eliminated by the optimizer
+  default:
+    goto TryCleanup       // Exception not caught, rethrow
+  }
+
+  // Exception was consumed
+  if (E->dtor)
+    E->dtor(E->object)    // Invoke the dtor on the object if it exists
+  goto EndTry             // Continue mainline code...
+
+And that is all there is to it.
+
+The throw(E) function would then be implemented like this (which may be 
+inlined into the caller through standard optimization):
+
+function throw(Exception *E) {
+  // Get the start of the stack trace...
+  %frame %f = call getStackCurrentFrame()
+
+  // Get the label information that corresponds to it
+  label * %L = call getFrameLabel(%f)
+  while (%L == 0 && !isFirstFrame(%f)) {
+    // Loop until a cleanup handler is found
+    %f = call getNextFrame(%f)
+    %L = call getFrameLabel(%f)
+  }
+
+  if (%L != 0) {
+    call setThreadLocalException(E)   // Allow handlers access to this...
+    call doNonLocalBranch(%L)
+  }
+  // No handler found!
+  call BlowUp()         // Ends up calling the terminate() method in use
+}
+
+That's a brief rundown of how C++ exception handling could be implemented in
+llvm.  Java would be very similar, except it only uses destructors to unlock
+synchronized blocks, not to destroy data.  Also, it uses two stack walks: a
+nondestructive walk that builds a stack trace, then a destructive walk that
+unwinds the stack as shown here. 
+
+It would be trivial to get exception interoperability between C++ and Java.
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-05-19-ExceptionResponse.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,45 @@
+Date: Sat, 19 May 2001 19:09:13 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: RE: Meeting writeup
+
+> I read it through and it looks great!
+
+Thanks!
+
+> The finally clause in Java may need more thought.  The code for this clause
+> is like a subroutine because it needs to be entered from many points (end of
+> try block and beginning of each catch block), and then needs to *return to
+> the place from where the code was entered*.  That's why JVM has the
+> jsr/jsr_w instruction.
+
+Hrm... I guess that is an implementation decision.  It can either be
+modelled as a subroutine (as java bytecodes do), which is really
+gross... or it can be modelled as code duplication (emitted once inline,
+then once in the exception path).  Because this could, at worst,
+slightly less than double the amount of code in a function (it is
+bounded) I don't think this is a big deal.  One of the really nice things
+about the LLVM representation is that it still allows for runtime code
+generation for exception paths (exceptions paths are not compiled until
+needed).  Obviously a static compiler couldn't do this though.  :)
+
+In this case, only one copy of the code would be compiled... until the
+other one is needed on demand.  Also this strategy fits with the "zero
+cost" exception model... the standard case is not burdened with extra
+branches or "call"s.
+
+> I suppose you could save the return address in a particular register
+> (specific to this finally block), jump to the finally block, and then at the
+> end of the finally block, jump back indirectly through this register.  It
+> will complicate building the CFG but I suppose that can be handled.  It is
+> also unsafe in terms of checking where control returns (which is I suppose
+> why the JVM doesn't use this).
+
+I think that a code duplication method would be cleaner, and would avoid
+the caveats that you mention.  Also, it does not slow down the normal case
+with an indirect branch...
+
+Like everything, we can probably defer a final decision until later.  :)
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,63 @@
+Date: Fri, 1 Jun 2001 16:38:17 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: Interesting: GCC passes
+
+
+Take a look at this document (which describes the order of optimizations
+that GCC performs):
+
+http://gcc.gnu.org/onlinedocs/gcc_17.html
+
+The rundown is that after RTL generation, the following happens:
+
+1 . [t] jump optimization (jumps to jumps, etc)
+2 . [t] Delete unreachable code
+3 .     Compute live ranges for CSE
+4 . [t] Jump threading (jumps to jumps with identical or inverse conditions)
+5 . [t] CSE
+6 . *** Conversion to SSA 
+7 . [t] SSA Based DCE
+8 . *** Conversion to LLVM
+9 .     UnSSA
+10.     GCSE
+11.     LICM
+12.     Strength Reduction
+13.     Loop unrolling
+14. [t] CSE
+15. [t] DCE
+16.     Instruction combination, register movement, scheduling... etc.
+
+I've marked optimizations with a [t] to indicate things that I believe to
+be relatively trivial to implement in LLVM itself.  The time consuming
+things to reimplement would be SSA based PRE, Strength reduction & loop
+unrolling... these would be the major things we would miss out on if we
+did LLVM creation from tree code [inlining and other high level
+optimizations are done on the tree representation].
+
+Given the lack of "strong" optimizations that would take a long time to
+reimplement, I am leaning a bit more towards creating LLVM from the tree
+code.  Especially given that SGI has GPL'd their compiler, including many
+SSA based optimizations that could be adapted (besides the fact that their
+code looks MUCH nicer than GCC :)
+
+Even if we choose to do LLVM code emission from RTL, we will almost
+certainly want to move LLVM emission from step 8 down until at least CSE
+has been rerun... which causes me to wonder if the SSA generation code
+will still work (due to global variable dependencies and stuff).  I assume
+that it can be made to work, but might be a little more involved than we
+would like.
+
+I'm continuing to look at the Tree -> RTL code.  It is pretty gross
+because they do some of the translation a statement at a time, and some
+of it a function at a time...  I'm not quite clear why and how the
+distinction is drawn, but it does not appear that there is a wonderful
+place to attach extra info.
+
+Anyways, I'm proceeding with the RTL -> LLVM conversion phase for now.  We
+can talk about this more on Monday.
+
+Wouldn't it be nice if there were a obvious decision to be made?  :)
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-01-GCCOptimizations2.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,71 @@
+Date: Fri, 1 Jun 2001 17:08:44 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: RE: Interesting: GCC passes
+
+> That is very interesting.  I agree that some of these could be done on LLVM
+> at link-time, but it is the extra time required that concerns me.  Link-time
+> optimization is severely time-constrained.
+
+If we were to reimplement any of these optimizations, I assume that we
+could do them a translation unit at a time, just as GCC does now.  This
+would lead to a pipeline like this:
+
+Static optimizations, xlation unit at a time:
+.c --GCC--> .llvm --llvmopt--> .llvm 
+
+Link time optimizations:
+.llvm --llvm-ld--> .llvm --llvm-link-opt--> .llvm 
+
+Of course, many optimizations could be shared between llvmopt and
+llvm-link-opt, but the wouldn't need to be shared...  Thus compile time
+could be faster, because we are using a "smarter" IR (SSA based).
+
+> BTW, about SGI, "borrowing" SSA-based optimizations from one compiler and
+> putting it into another is not necessarily easier than re-doing it.
+> Optimization code is usually heavily tied in to the specific IR they use.
+
+Understood.  The only reason that I brought this up is because SGI's IR is
+more similar to LLVM than it is different in many respects (SSA based,
+relatively low level, etc), and could be easily adapted.  Also their
+optimizations are written in C++ and are actually somewhat
+structured... of course it would be no walk in the park, but it would be
+much less time consuming to adapt, say, SSA-PRE than to rewrite it.
+
+> But your larger point is valid that adding SSA based optimizations is
+> feasible and should be fun.  (Again, link time cost is the issue.)
+
+Assuming linktime cost wasn't an issue, the question is: 
+Does using GCC's backend buy us anything?
+
+> It also occurs to me that GCC is probably doing quite a bit of back-end
+> optimization (step 16 in your list).  Do you have a breakdown of that?
+
+Not really.  The irritating part of GCC is that it mixes it all up and
+doesn't have a clean separation of concerns.  A lot of the "back end
+optimization" happens right along with other data optimizations (ie, CSE
+of machine specific things).
+
+As far as REAL back end optimizations go, it looks something like this:
+
+1. Instruction combination: try to make CISCy instructions, if available
+2. Register movement: try to get registers in the right places for the
+architecture to avoid register to register moves.  For example, try to get
+the first argument of a function to naturally land in %o0 for sparc.
+3. Instruction scheduling: 'nuff said :)
+4. Register class preferencing: ??
+5. Local register allocation
+6. global register allocation
+7. Spilling
+8. Local regalloc
+9. Jump optimization
+10. Delay slot scheduling
+11. Branch shorting for CISC machines
+12. Instruction selection & peephole optimization
+13. Debug info output
+
+But none of this would be usable for LLVM anyways, unless we were using
+GCC as a static compiler.
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-06-20-.NET-Differences.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,30 @@
+Date: Wed, 20 Jun 2001 12:32:22 -0500
+From: Vikram Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <lattner at cs.uiuc.edu>
+Subject: .NET vs. our VM
+
+One significant difference between .NET CLR and our VM is that the CLR
+includes full information about classes and inheritance.  In fact, I just
+sat through the paper on adding templates to .NET CLR, and the speaker
+indicated that the goal seems to be to do simple static compilation (very
+little lowering or optimization).  Also, the templates implementation in CLR
+"relies on dynamic class loading and JIT compilation".
+
+This is an important difference because I think there are some significant
+advantages to have a much lower level VM layer, and do significant static
+analysis and optimization.
+
+I also talked to the lead guy for KAI's C++ compiler (Arch Robison) and he
+said that SGI and other commercial compilers have included options to export
+their *IR* next to the object code (i.e., .il files) and use them for
+link-time code generation.  In fact, he said that the .o file was nearly
+empty and was entirely generated from the .il at link-time.  But he agreed
+that this limited the link-time interprocedural optimization to modules
+compiled by the same compiler, whereas our approach allows us to link and
+optimize modules from multiple different compilers.  (Also, of course, they
+don't do anything for runtime optimization).
+
+All issues to bring up in Related Work.
+
+--Vikram
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-07-06-LoweringIRForCodeGen.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,31 @@
+Date: Fri, 6 Jul 2001 16:56:56 -0500
+From: Vikram S. Adve <vadve at cs.uiuc.edu>
+To: Chris Lattner <lattner at cs.uiuc.edu>
+Subject: lowering the IR
+
+BTW, I do think that we should consider lowering the IR as you said.  I
+didn't get time to raise it today, but it comes up with the SPARC
+move-conditional instruction.  I don't think we want to put that in the core
+VM -- it is a little too specialized.  But without a corresponding
+conditional move instruction in the VM, it is pretty difficult to maintain a
+close mapping between VM and machine code.  Other architectures may have
+other such instructions.
+
+What I was going to suggest was that for a particular processor, we define
+additional VM instructions that match some of the unusual opcodes on the
+processor but have VM semantics otherwise, i.e., all operands are in SSA
+form and typed.  This means that we can re-generate core VM code from the
+more specialized code any time we want (so that portability is not lost).
+
+Typically, a static compiler like gcc would generate just the core VM, which
+is relatively portable.  Anyone (an offline tool, the linker, etc., or even
+the static compiler itself if it chooses) can transform that into more
+specialized target-specific VM code for a particular architecture.  If the
+linker does it, it can do it after all machine-independent optimizations.
+This would be the most convenient, but not necessary.
+
+The main benefit of lowering will be that we will be able to retain a close
+mapping between VM and machine code.
+
+--Vikram
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2001-09-18-OptimizeExceptions.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,56 @@
+Date: Tue, 18 Sep 2001 00:38:37 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: Vikram S. Adve <vadve at cs.uiuc.edu>
+Subject: Idea for a simple, useful link time optimization
+
+
+In C++ programs, exceptions suck, and here's why:
+
+1. In virtually all function calls, you must assume that the function
+   throws an exception, unless it is defined as 'nothrow'.  This means
+   that every function call has to have code to invoke dtors on objects
+   locally if one is thrown by the function.  Most functions don't throw
+   exceptions, so this code is dead [with all the bad effects of dead
+   code, including icache pollution].
+2. Declaring a function nothrow causes catch blocks to be added to every
+   call that isnot  provably nothrow.  This makes them very slow.
+3. Extra extraneous exception edges reduce the opportunity for code
+   motion.
+4. EH is typically implemented with large lookup tables.  Ours is going to
+   be much smaller (than the "standard" way of doing it) to start with,
+   but eliminating it entirely would be nice. :)
+5. It is physically impossible to correctly put (accurate, correct)
+   exception specifications on generic, templated code.  But it is trivial
+   to analyze instantiations of said code.
+6. Most large C++ programs throw few exceptions.  Most well designed
+   programs only throw exceptions in specific planned portions of the
+   code.
+
+Given our _planned_ model of handling exceptions, all of this would be
+pretty trivial to eliminate through some pretty simplistic interprocedural
+analysis.  The DCE factor alone could probably be pretty significant.  The
+extra code motion opportunities could also be exploited though...
+
+Additionally, this optimization can be implemented in a straight forward
+conservative manner, allowing libraries to be optimized or individual
+files even (if there are leaf functions visible in the translation unit
+that are called).
+
+I think it's a reasonable optimization that hasn't really been addressed
+(because assembly is way too low level for this), and could have decent
+payoffs... without being a overly complex optimization.
+
+After I wrote all of that, I found this page that is talking about
+basically the same thing I just wrote, except that it is translation unit
+at a time, tree based approach:
+http://www.ocston.org/~jls/ehopt.html
+
+but is very useful from "expected gain" and references perspective.  Note
+that their compiler is apparently unable to inline functions that use
+exceptions, so there numbers are pretty worthless... also our results
+would (hopefully) be better because it's interprocedural...
+
+What do you think?
+
+-Chris
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2002-05-12-InstListChange.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2002-05-12-InstListChange.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2002-05-12-InstListChange.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2002-05-12-InstListChange.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,55 @@
+Date: Sun, 12 May 2002 17:12:53 -0500 (CDT)
+From: Chris Lattner <sabre at nondot.org>
+To: "Vikram S. Adve" <vadve at cs.uiuc.edu>
+Subject: LLVM change
+
+There is a fairly fundemental change that I would like to make to the LLVM 
+infrastructure, but I'd like to know if you see any drawbacks that I 
+don't...
+
+Basically right now at the basic block level, each basic block contains an 
+instruction list (returned by getInstList()) that is a ValueHolder of 
+instructions.  To iterate over instructions, we must actually iterate over 
+the instlist, and access the instructions through the instlist.
+
+To add or remove an instruction from a basic block, we need to get an 
+iterator to an instruction, which, given just an Instruction*, requires a 
+linear search of the basic block the instruction is contained in... just 
+to insert an instruction before another instruction, or to delete an 
+instruction!  This complicates algorithms that should be very simple (like 
+simple constant propagation), because they aren't actually sparse anymore,
+they have to traverse basic blocks to remove constant propogated 
+instructions.
+
+Additionally, adding or removing instructions to a basic block 
+_invalidates all iterators_ pointing into that block, which is really 
+irritating.
+
+To fix these problems (and others), I would like to make the ordering of
+the instructions be represented with a doubly linked list in the
+instructions themselves, instead of an external data structure.  This is 
+how many other representations do it, and frankly I can't remember why I 
+originally implemented it the way I did.
+
+Long term, all of the code that depends on the nasty features in the 
+instruction list (which can be found by grep'ing for getInstList()) will 
+be changed to do nice local transformations.  In the short term, I'll 
+change the representation, but preserve the interface (including 
+getInstList()) so that all of the code doesn't have to change.
+
+Iteration over the instructions in a basic block remains the simple:
+for (BasicBlock::iterator I = BB->begin(), E = BB->end(); I != E; ++I) ...
+
+But we will also support:
+for (Instruction *I = BB->front(); I; I = I->getNext()) ...
+
+After converting instructions over, I'll convert basic blocks and 
+functions to have a similar interface.
+
+The only negative aspect of this change that I see is that it increases 
+the amount of memory consumed by one pointer per instruction.  Given the 
+benefits, I think this is a very reasonable tradeoff. 
+
+What do you think?
+
+-Chris

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2002-06-25-MegaPatchInfo.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,72 @@
+Changes:
+* Change the casting code to be const correct.  Now, doing this is invalid:
+     const Value *V = ...;
+     Instruction *I = dyn_cast<Instruction>(V);
+  instead, the second line should be:
+     const Instruction *I = dyn_cast<Instruction>(V);
+
+* Change the casting code to allow casting a reference value thus:
+     const Value &V = ...;
+     Instruction &I = cast<Instruction>(V);
+
+  dyn_cast does not work with references, because it must return a null pointer
+  on failure.
+
+* Fundamentally change how instructions and other values are represented.
+  Before, every llvm container was an instance of the ValueHolder template,
+  instantiated for each container type.  This ValueHolder was effectively a
+  wrapper around a vector of pointers to the sub-objects.
+
+  Now, instead of having a vector to pointers of objects, the objects are
+  maintained in a doubly linked list of values (ie each Instruction now has
+  Next & Previous fields).  The containers are now instances of ilist (intrusive
+  linked list class), which use the next and previous fields to chain them
+  together.  The advantage of this implementation is that iterators can be
+  formed directly from pointers to the LLVM value, and invalidation is much
+  easier to handle.
+
+* As part of the above change, dereferencing an iterator (for example:
+  BasicBlock::iterator) now produces a reference to the underlying type (same
+  example: Instruction&) instead of a pointer to the underlying object.  This
+  makes it much easier to write nested loops that iterator over things, changing
+  this:
+
+    for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI)
+      for (BasicBlock::iterator II = (*BI)->begin(); II != (*BI)->end(); ++II)
+        (*II)->dump();
+
+  into:
+
+    for (Function::iterator BI = Func->begin(); BI != Func->end(); ++BI)
+      for (BasicBlock::iterator II = BI->begin(); II != BI->end(); ++II)
+        II->dump();
+
+  which is much more natural and what users expect.
+
+* Simplification of #include's: Before, it was necessary for a .cpp file to
+  include every .h file that it used.  Now things are batched a little bit more
+  to make it easier to use.  Specifically, the include graph now includes these
+  edges:
+    Module.h -> Function.h, GlobalVariable.h
+    Function.h -> BasicBlock.h, Argument.h
+    BasicBlock.h -> Instruction.h
+
+  Which means that #including Function.h is usually sufficient for getting the
+  lower level #includes.
+
+* Printing out a Value* has now changed: Printing a Value* will soon print out
+  the address of the value instead of the contents of the Value.  To print out
+  the contents, you must convert it to a reference with (for example)
+  'cout << *I' instead of 'cout << I;'.  This conversion is not yet complete,
+  but will be eventually.  In the mean time, both forms print out the contents.
+
+* References are used much more throughout the code base.  In general, if a
+  pointer is known to never be null, it is passed in as a reference instead of a
+  pointer.  For example, the instruction visitor class uses references instead
+  of pointers, and that Pass subclasses now all receive references to Values
+  instead of pointers, because they may never be null.
+
+* The Function class now has helper functions for accessing the Arguments list.
+  Instead of having to go through getArgumentList for simple things like
+  iterator over the arguments, now the a*() methods can be used to access them.
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2003-01-23-CygwinNotes.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,28 @@
+Date: Mon, 20 Jan 2003 00:00:28 -0600
+From: Brian R. Gaeke <gaeke at uiuc.edu>
+Subject: windows vs. llvm
+
+If you're interested, here are some of the major problems compiling LLVM
+under Cygwin and/or Mingw.
+
+1. Cygwin doesn't have <inttypes.h> or <stdint.h>, so all the INT*_MAX
+   symbols and standard int*_t types are off in limbo somewhere. Mingw has
+   <stdint.h>, but Cygwin doesn't like it.
+
+2. Mingw doesn't have <dlfcn.h> (because Windows doesn't have it.)
+
+3. SA_SIGINFO and friends are not around; only signal() seems to work.
+
+4. Relink, aka ld -r, doesn't work (probably an ld bug); you need
+   DONT_BUILD_RELINKED. This breaks all the tools makefiles; you just need to
+   change them to have .a's.
+
+5. There isn't a <values.h>.
+
+6. There isn't a mallinfo() (or, at least, it's documented, but it doesn't seem
+   to link).
+
+7. The version of Bison that cygwin (and newer Linux versions) comes with
+   does not like = signs in rules. Burg's gram.yc source file uses them. I think
+   you can just take them out.
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2003-06-25-Reoptimizer1.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,137 @@
+Wed Jun 25 15:13:51 CDT 2003
+
+First-level instrumentation
+---------------------------
+
+We use opt to do Bytecode-to-bytecode instrumentation. Look at
+back-edges and insert llvm_first_trigger() function call which takes
+no arguments and no return value. This instrumentation is designed to
+be easy to remove, for instance by writing a NOP over the function
+call instruction.
+
+Keep count of every call to llvm_first_trigger(), and maintain
+counters in a map indexed by return address. If the trigger count
+exceeds a threshold, we identify a hot loop and perform second-level
+instrumentation on the hot loop region (the instructions between the
+target of the back-edge and the branch that causes the back-edge).  We
+do not move code across basic-block boundaries.
+
+
+Second-level instrumentation
+---------------------------
+
+We remove the first-level instrumentation by overwriting the CALL to
+llvm_first_trigger() with a NOP.
+
+The reoptimizer maintains a map between machine-code basic blocks and
+LLVM BasicBlock*s.  We only keep track of paths that start at the
+first machine-code basic block of the hot loop region.
+
+How do we keep track of which edges to instrument, and which edges are
+exits from the hot region? 3 step process.
+
+1) Do a DFS from the first machine-code basic block of the hot loop
+region and mark reachable edges.
+
+2) Do a DFS from the last machine-code basic block of the hot loop
+region IGNORING back edges, and mark the edges which are reachable in
+1) and also in 2) (i.e., must be reachable from both the start BB and
+the end BB of the hot region).
+
+3) Mark BBs which end in edges that exit the hot region; we need to
+instrument these differently.
+
+Assume that there is 1 free register. On SPARC we use %g1, which LLC
+has agreed not to use.  Shift a 1 into it at the beginning. At every
+edge which corresponds to a conditional branch, we shift 0 for not
+taken and 1 for taken into a register. This uniquely numbers the paths
+through the hot region. Silently fail if we need more than 64 bits.
+
+At the end BB we call countPath and increment the counter based on %g1
+and the return address of the countPath call.  We keep track of the
+number of iterations and the number of paths.  We only run this
+version 30 or 40 times.
+
+Find the BBs that total 90% or more of execution, and aggregate them
+together to form our trace. But we do not allow more than 5 paths; if
+we have more than 5 we take the ones that are executed the most.  We
+verify our assumption that we picked a hot back-edge in first-level
+instrumentation, by making sure that the number of times we took an
+exit edge from the hot trace is less than 10% of the number of
+iterations.
+
+LLC has been taught to recognize llvm_first_trigger() calls and NOT
+generate saves and restores of caller-saved registers around these
+calls.
+
+
+Phase behavior
+--------------
+
+We turn off llvm_first_trigger() calls with NOPs, but this would hide
+phase behavior from us (when some funcs/traces stop being hot and
+others become hot.)
+
+We have a SIGALRM timer that counts time for us. Every time we get a
+SIGALRM we look at our priority queue of locations where we have
+removed llvm_first_trigger() calls. Each location is inserted along
+with a time when we will next turn instrumentation back on for that
+call site. If the time has arrived for a particular call site, we pop
+that off the prio. queue and turn instrumentation back on for that
+call site.
+
+
+Generating traces
+-----------------
+
+When we finally generate an optimized trace we first copy the code
+into the trace cache. This leaves us with 3 copies of the code: the
+original code, the instrumented code, and the optimized trace. The
+optimized trace does not have instrumentation. The original code and
+the instrumented code are modified to have a branch to the trace
+cache, where the optimized traces are kept.
+
+We copy the code from the original to the instrumentation version
+by tracing the LLVM-to-Machine code basic block map and then copying
+each machine code basic block we think is in the hot region into the
+trace cache. Then we instrument that code. The process is similar for
+generating the final optimized trace; we copy the same basic blocks
+because we might need to put in fixup code for exit BBs.
+
+LLVM basic blocks are not typically used in the Reoptimizer except
+for the mapping information.
+
+We are restricted to using single instructions to branch between the
+original code, trace, and instrumented code. So we have to keep the
+code copies in memory near the original code (they can't be far enough
+away that a single pc-relative branch would not work.) Malloc() or
+data region space is too far away. this impacts the design of the 
+trace cache.
+
+We use a dummy function that is full of a bunch of for loops which we
+overwrite with trace-cache code. The trace manager keeps track of
+whether or not we have enough space in the trace cache, etc.
+
+The trace insertion routine takes an original start address, a vector
+of machine instructions representing the trace, index of branches and
+their corresponding absolute targets, and index of calls and their
+corresponding absolute targets.
+
+The trace insertion routine is responsible for inserting branches from
+the beginning of the original code to the beginning of the optimized
+trace. This is because at some point the trace cache may run out of
+space and it may have to evict a trace, at which point the branch to
+the trace would also have to be removed. It uses a round-robin
+replacement policy; we have found that this is almost as good as LRU
+and better than random (especially because of problems fitting the new
+trace in.)
+
+We cannot deal with discontiguous trace cache areas.  The trace cache
+is supposed to be cache-line-aligned, but it is not page-aligned.
+
+We generate instrumentation traces and optimized traces into separate
+trace caches. We keep the instrumented code around because you don't
+want to delete a trace when you still might have to return to it
+(i.e., return from a llvm_first_trigger() or countPath() call.)
+
+

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2003-06-26-Reoptimizer2.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,110 @@
+Thu Jun 26 14:43:04 CDT 2003
+
+Information about BinInterface
+------------------------------
+
+Take in a set of instructions with some particular register
+allocation. It allows you to add, modify, or delete some instructions,
+in SSA form (kind of like LLVM's MachineInstrs.) Then re-allocate
+registers. It assumes that the transformations you are doing are safe.
+It does not update the mapping information or the LLVM representation
+for the modified trace (so it would not, for instance, support
+multiple optimization passes; passes have to be aware of and update
+manually the mapping information.)
+
+The way you use it is you take the original code and provide it to
+BinInterface; then you do optimizations to it, then you put it in the
+trace cache.
+
+The BinInterface tries to find live-outs for traces so that it can do
+register allocation on just the trace, and stitch the trace back into
+the original code. It has to preserve the live-ins and live-outs when
+it does its register allocation.  (On exits from the trace we have
+epilogues that copy live-outs back into the right registers, but
+live-ins have to be in the right registers.)
+
+
+Limitations of BinInterface
+---------------------------
+
+It does copy insertions for PHIs, which it infers from the machine
+code. The mapping info inserted by LLC is not sufficient to determine
+the PHIs.
+
+It does not handle integer or floating-point condition codes and it
+does not handle floating-point register allocation.
+
+It is not aggressively able to use lots of registers.
+
+There is a problem with alloca: we cannot find our spill space for
+spilling registers, normally allocated on the stack, if the trace
+follows an alloca(). What might be an acceptable solution would be to
+disable trace generation on functions that have variable-sized
+alloca()s. Variable-sized allocas in the trace would also probably
+screw things up.
+
+Because of the FP and alloca limitations, the BinInterface is
+completely disabled right now.
+
+
+Demo
+----
+
+This is a demo of the Ball & Larus version that does NOT use 2-level
+profiling.
+
+1. Compile program with llvm-gcc.
+2. Run opt -lowerswitch -paths -emitfuncs on the bytecode.
+   -lowerswitch change switch statements to branches
+   -paths       Ball & Larus path-profiling algorithm
+   -emitfuncs   emit the table of functions
+3. Run llc to generate SPARC assembly code for the result of step 2.
+4. Use g++ to link the (instrumented) assembly code.
+
+We use a script to do all this:
+------------------------------------------------------------------------------
+#!/bin/sh
+llvm-gcc $1.c -o $1
+opt -lowerswitch -paths -emitfuncs $1.bc > $1.run.bc
+llc -f $1.run.bc 
+LIBS=$HOME/llvm_sparc/lib/Debug
+GXX=/usr/dcs/software/evaluation/bin/g++
+$GXX -g -L $LIBS $1.run.s -o $1.run.llc \
+$LIBS/tracecache.o \
+$LIBS/mapinfo.o \
+$LIBS/trigger.o \
+$LIBS/profpaths.o \
+$LIBS/bininterface.o \
+$LIBS/support.o \
+$LIBS/vmcore.o \
+$LIBS/transformutils.o \
+$LIBS/bcreader.o \
+-lscalaropts -lscalaropts -lanalysis \
+-lmalloc -lcpc -lm -ldl
+------------------------------------------------------------------------------
+
+5. Run the resulting binary.  You will see output from BinInterface
+(described below) intermixed with the output from the program.
+
+
+Output from BinInterface
+------------------------
+
+BinInterface's debugging code prints out the following stuff in order:
+
+1. Initial code provided to BinInterface with original register
+allocation.
+
+2. Section 0 is the trace prolog, consisting mainly of live-ins and
+register saves which will be restored in epilogs.
+
+3. Section 1 is the trace itself, in SSA form used by BinInterface,
+along with the PHIs that are inserted.
+PHIs are followed by the copies that implement them.
+Each branch (i.e., out of the trace) is annotated with the
+section number that represents the epilog it branches to.
+
+4. All the other sections starting with Section 2 are trace epilogs.
+Every branch from the trace has to go to some epilog.
+
+5. After the last section is the register allocation output.

Added: www-releases/trunk/3.2/docs/HistoricalNotes/2007-OriginalClangReadme.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HistoricalNotes/2007-OriginalClangReadme.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HistoricalNotes/2007-OriginalClangReadme.txt (added)
+++ www-releases/trunk/3.2/docs/HistoricalNotes/2007-OriginalClangReadme.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,178 @@
+//===----------------------------------------------------------------------===//
+// C Language Family Front-end
+//===----------------------------------------------------------------------===//
+                                                             Chris Lattner
+
+I. Introduction:
+ 
+ clang: noun
+    1. A loud, resonant, metallic sound.
+    2. The strident call of a crane or goose.
+    3. C-language family front-end toolkit.
+
+ The world needs better compiler tools, tools which are built as libraries. This
+ design point allows reuse of the tools in new and novel ways. However, building
+ the tools as libraries isn't enough: they must have clean APIs, be as
+ decoupled from each other as possible, and be easy to modify/extend.  This
+ requires clean layering, decent design, and avoiding tying the libraries to a
+ specific use.  Oh yeah, did I mention that we want the resultant libraries to
+ be as fast as possible? :)
+
+ This front-end is built as a component of the LLVM toolkit that can be used
+ with the LLVM backend or independently of it.  In this spirit, the API has been
+ carefully designed as the following components:
+ 
+   libsupport  - Basic support library, reused from LLVM.
+
+   libsystem   - System abstraction library, reused from LLVM.
+   
+   libbasic    - Diagnostics, SourceLocations, SourceBuffer abstraction,
+                 file system caching for input source files.  This depends on
+                 libsupport and libsystem.
+
+   libast      - Provides classes to represent the C AST, the C type system,
+                 builtin functions, and various helpers for analyzing and
+                 manipulating the AST (visitors, pretty printers, etc).  This
+                 library depends on libbasic.
+
+
+   liblex      - C/C++/ObjC lexing and preprocessing, identifier hash table,
+                 pragma handling, tokens, and macros.  This depends on libbasic.
+
+   libparse    - C (for now) parsing and local semantic analysis. This library
+                 invokes coarse-grained 'Actions' provided by the client to do
+                 stuff (e.g. libsema builds ASTs).  This depends on liblex.
+
+   libsema     - Provides a set of parser actions to build a standardized AST
+                 for programs.  AST's are 'streamed' out a top-level declaration
+                 at a time, allowing clients to use decl-at-a-time processing,
+                 build up entire translation units, or even build 'whole
+                 program' ASTs depending on how they use the APIs.  This depends
+                 on libast and libparse.
+
+   librewrite  - Fast, scalable rewriting of source code.  This operates on
+                 the raw syntactic text of source code, allowing a client
+                 to insert and delete text in very large source files using
+                 the same source location information embedded in ASTs.  This
+                 is intended to be a low-level API that is useful for
+                 higher-level clients and libraries such as code refactoring.
+
+   libanalysis - Source-level dataflow analysis useful for performing analyses
+                 such as computing live variables.  It also includes a
+                 path-sensitive "graph-reachability" engine for writing
+                 analyses that reason about different possible paths of
+                 execution through source code.  This is currently being
+                 employed to write a set of checks for finding bugs in software.
+
+   libcodegen  - Lower the AST to LLVM IR for optimization & codegen.  Depends
+                 on libast.
+                 
+   clang       - An example driver, client of the libraries at various levels.
+                 This depends on all these libraries, and on LLVM VMCore.
+
+ This front-end has been intentionally built as a DAG of libraries, making it
+ easy to  reuse individual parts or replace pieces if desired. For example, to
+ build a preprocessor, you take the Basic and Lexer libraries. If you want an
+ indexer, you take those plus the Parser library and provide some actions for
+ indexing.  If you want a refactoring, static analysis, or source-to-source
+ compiler tool, it makes sense to take those plus the AST building and semantic
+ analyzer library.  Finally, if you want to use this with the LLVM backend,
+ you'd take these components plus the AST to LLVM lowering code.
+ 
+ In the future I hope this toolkit will grow to include new and interesting
+ components, including a C++ front-end, ObjC support, and a whole lot of other
+ things.
+
+ Finally, it should be pointed out that the goal here is to build something that
+ is high-quality and industrial-strength: all the obnoxious features of the C
+ family must be correctly supported (trigraphs, preprocessor arcana, K&R-style
+ prototypes, GCC/MS extensions, etc).  It cannot be used if it is not 'real'.
+
+
+II. Usage of clang driver:
+
+ * Basic Command-Line Options:
+   - Help: clang --help
+   - Standard GCC options accepted: -E, -I*, -i*, -pedantic, -std=c90, etc.
+   - To make diagnostics more gcc-like: -fno-caret-diagnostics -fno-show-column
+   - Enable metric printing: -stats
+
+ * -fsyntax-only is currently the default mode.
+
+ * -E mode works the same way as GCC.
+
+ * -Eonly mode does all preprocessing, but does not print the output,
+     useful for timing the preprocessor.
+ 
+ * -fsyntax-only is currently partially implemented, lacking some
+     semantic analysis (some errors and warnings are not produced).
+
+ * -parse-noop parses code without building an AST.  This is useful
+     for timing the cost of the parser without including AST building
+     time.
+ 
+ * -parse-ast builds ASTs, but doesn't print them.  This is most
+     useful for timing AST building vs -parse-noop.
+ 
+ * -parse-ast-print pretty prints most expression and statements nodes.
+
+ * -parse-ast-check checks that diagnostic messages that are expected
+     are reported and that those which are reported are expected.
+
+ * -dump-cfg builds ASTs and then CFGs.  CFGs are then pretty-printed.
+
+ * -view-cfg builds ASTs and then CFGs.  CFGs are then visualized by
+     invoking Graphviz.
+
+     For more information on getting Graphviz to work with clang/LLVM,
+     see: http://llvm.org/docs/ProgrammersManual.html#ViewGraph
+
+
+III. Current advantages over GCC:
+
+ * Column numbers are fully tracked (no 256 col limit, no GCC-style pruning).
+ * All diagnostics have column numbers, includes 'caret diagnostics', and they
+   highlight regions of interesting code (e.g. the LHS and RHS of a binop).
+ * Full diagnostic customization by client (can format diagnostics however they
+   like, e.g. in an IDE or refactoring tool) through DiagnosticClient interface.
+ * Built as a framework, can be reused by multiple tools.
+ * All languages supported linked into same library (no cc1,cc1obj, ...).
+ * mmap's code in read-only, does not dirty the pages like GCC (mem footprint).
+ * LLVM License, can be linked into non-GPL projects.
+ * Full diagnostic control, per diagnostic.  Diagnostics are identified by ID.
+ * Significantly faster than GCC at semantic analysis, parsing, preprocessing
+   and lexing.
+ * Defers exposing platform-specific stuff to as late as possible, tracks use of
+   platform-specific features (e.g. #ifdef PPC) to allow 'portable bytecodes'.
+ * The lexer doesn't rely on the "lexer hack": it has no notion of scope and
+   does not categorize identifiers as types or variables -- this is up to the
+   parser to decide.
+
+Potential Future Features:
+
+ * Fine grained diag control within the source (#pragma enable/disable warning).
+ * Better token tracking within macros?  (Token came from this line, which is
+   a macro argument instantiated here, recursively instantiated here).
+ * Fast #import with a module system.
+ * Dependency tracking: change to header file doesn't recompile every function
+   that texually depends on it: recompile only those functions that need it.
+   This is aka 'incremental parsing'.
+
+
+IV. Missing Functionality / Improvements
+
+Lexer:
+ * Source character mapping.  GCC supports ASCII and UTF-8.
+   See GCC options: -ftarget-charset and -ftarget-wide-charset.
+ * Universal character support.  Experimental in GCC, enabled with
+   -fextended-identifiers.
+ * -fpreprocessed mode.
+
+Preprocessor:
+ * #assert/#unassert
+ * MSExtension: "L#param" stringizes to a wide string literal.
+ * Add support for -M*
+
+Traditional Preprocessor:
+ * Currently, we have none. :)
+

Added: www-releases/trunk/3.2/docs/HowToAddABuilder.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HowToAddABuilder.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HowToAddABuilder.rst (added)
+++ www-releases/trunk/3.2/docs/HowToAddABuilder.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,90 @@
+.. _how_to_add_a_builder:
+
+===================================================================
+How To Add Your Build Configuration To LLVM Buildbot Infrastructure
+===================================================================
+
+.. sectionauthor:: Galina Kistanova <gkistanova at gmail.com>
+
+Introduction
+============
+
+This document contains information about adding a build configuration and
+buildslave to private slave builder to LLVM Buildbot Infrastructure
+`<http://lab.llvm.org:8011>`_.
+
+
+Steps To Add Builder To LLVM Buildbot
+=====================================
+Volunteers can provide their build machines to work as build slaves to
+public LLVM Buildbot.
+
+Here are the steps you can follow to do so:
+
+#. Check the existing build configurations to make sure the one you are
+   interested in is not covered yet or gets built on your computer much
+   faster than on the existing one. We prefer faster builds so developers
+   will get feedback sooner after changes get committed.
+
+#. The computer you will be registering with the LLVM buildbot
+   infrastructure should have all dependencies installed and you can
+   actually build your configuration successfully. Please check what degree
+   of parallelism (-j param) would give the fastest build.  You can build
+   multiple configurations on one computer.
+
+#. Install buildslave (currently we are using buildbot version 0.8.5).
+   Depending on the platform, buildslave could be available to download and
+   install with your packet manager, or you can download it directly from
+   `<http://trac.buildbot.net>`_ and install it manually.
+
+#. Create a designated user account, your buildslave will be running under,
+   and set appropriate permissions.
+
+#. Choose the buildslave root directory (all builds will be placed under
+   it), buildslave access name and password the build master will be using
+   to authenticate your buildslave.
+
+#. Create a buildslave in context of that buildslave account.  Point it to
+   the **lab.llvm.org** port **9990** (see `Buildbot documentation,
+   Creating a slave
+   <http://buildbot.net/buildbot/docs/current/full.html#creating-a-slave>`_
+   for more details) by running the following command:
+
+    .. code-block:: bash
+
+       $ buildslave create-slave <buildslave-root-directory> \
+                    lab.llvm.org:9990 \
+                    <buildslave-access-name> <buildslave-access-password>
+
+#. Fill the buildslave description and admin name/e-mail.  Here is an
+   example of the buildslave description::
+
+       Windows 7 x64
+       Core i7 (2.66GHz), 16GB of RAM
+
+       g++.exe (TDM-1 mingw32) 4.4.0
+       GNU Binutils 2.19.1
+       cmake version 2.8.4
+       Microsoft(R) 32-bit C/C++ Optimizing Compiler Version 16.00.40219.01 for 80x86
+
+#. Make sure you can actually start the buildslave successfully. Then set
+   up your buildslave to start automatically at the start up time.  See the
+   buildbot documentation for help.  You may want to restart your computer
+   to see if it works.
+
+#. Send a patch which adds your build slave and your builder to zorg.
+
+   * slaves are added to ``buildbot/osuosl/master/config/slaves.py``
+   * builders are added to ``buildbot/osuosl/master/config/builders.py``
+
+#. Send the buildslave access name and the access password directly to
+   `Galina Kistanova <mailto:gkistanova at gmail.com>`_, and wait till she
+   will let you know that your changes are applied and buildmaster is
+   reconfigured.
+
+#. Check the status of your buildslave on the `Waterfall Display
+   <http://lab.llvm.org:8011/waterfall>`_ to make sure it is connected, and
+   ``http://lab.llvm.org:8011/buildslaves/<your-buildslave-name>`` to see
+   if administrator contact and slave information are correct.
+
+#. Wait for the first build to succeed and enjoy.

Added: www-releases/trunk/3.2/docs/HowToBuildOnARM.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HowToBuildOnARM.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HowToBuildOnARM.rst (added)
+++ www-releases/trunk/3.2/docs/HowToBuildOnARM.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,47 @@
+.. _how_to_build_on_arm:
+
+===================================================================
+How To Build On ARM
+===================================================================
+
+.. sectionauthor:: Wei-Ren Chen (陳韋任) <chenwj at iis.sinica.edu.tw>
+
+Introduction
+============
+
+This document contains information about building/testing LLVM and
+Clang on ARM.
+
+Notes On Building LLVM/Clang on ARM
+=====================================
+Here are some notes on building/testing LLVM/Clang on ARM. Note that
+ARM encompasses a wide variety of CPUs; this advice is primarily based
+on the ARMv6 and ARMv7 architectures and may be inapplicable to older chips.
+
+#. If you are building LLVM/Clang on an ARM board with 1G of memory or less,
+   please use ``gold`` rather then GNU ``ld``.
+   Building LLVM/Clang with ``--enable-optimized``
+   is prefered since it consumes less memory. Otherwise, the building
+   process will very likely fail due to insufficient memory. In any
+   case it is probably a good idea to set up a swap partition.
+
+#. If you want to run ``make
+   check-all`` after building LLVM/Clang, to avoid false alarms (eg, ARCMT
+   failure) please use at least the following configuration:
+
+   .. code-block:: bash
+
+     $ ../$LLVM_SRC_DIR/configure --with-abi=aapcs-vfp
+
+#. The most popular linaro/ubuntu OS's for ARM boards, eg, the
+   Pandaboard, have become hard-float platforms. The following set
+   of configuration options appears to be a good choice for this
+   platform:
+
+   .. code-block:: bash
+
+     ./configure --build=armv7l-unknown-linux-gnueabihf
+     --host=armv7l-unknown-linux-gnueabihf
+     --target=armv7l-unknown-linux-gnueabihf --with-cpu=cortex-a9
+     --with-float=hard --with-abi=aapcs-vfp --with-fpu=neon
+     --enable-targets=arm --disable-optimized --enable-assertions

Added: www-releases/trunk/3.2/docs/HowToReleaseLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HowToReleaseLLVM.html?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HowToReleaseLLVM.html (added)
+++ www-releases/trunk/3.2/docs/HowToReleaseLLVM.html Fri Dec 21 00:57:24 2012
@@ -0,0 +1,581 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                      "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+  <title>How To Release LLVM To The Public</title>
+  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>How To Release LLVM To The Public</h1>
+<ol>
+  <li><a href="#introduction">Introduction</a></li>
+  <li><a href="#criteria">Qualification Criteria</a></li>
+  <li><a href="#introduction">Release Timeline</a></li>
+  <li><a href="#process">Release Process</a></li>
+</ol>
+<div class="doc_author">
+  <p>Written by <a href="mailto:tonic at nondot.org">Tanya Lattner</a>,
+  <a href="mailto:rspencer at x10sys.com">Reid Spencer</a>,
+  <a href="mailto:criswell at cs.uiuc.edu">John Criswell</a>, &
+  <a href="mailto:wendling at apple.com">Bill Wendling</a>
+  </p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="introduction">Introduction</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This document contains information about successfully releasing LLVM —
+   including subprojects: e.g., <tt>clang</tt> and <tt>dragonegg</tt> — to
+   the public. It is the Release Manager's responsibility to ensure that a high
+   quality build of LLVM is released.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="process">Release Timeline</a></h2>
+<!-- *********************************************************************** -->
+<div>
+
+<p>LLVM is released on a time based schedule — roughly every 6 months. We
+   do not normally have dot releases because of the nature of LLVM's incremental
+   development philosophy. That said, the only thing preventing dot releases for
+   critical bug fixes from happening is a lack of resources — testers,
+   machines, time, etc. And, because of the high quality we desire for LLVM
+   releases, we cannot allow for a truncated form of release qualification.</p>
+
+<p>The release process is roughly as follows:</p>
+
+<ul>
+  <li><p>Set code freeze and branch creation date for 6 months after last code
+      freeze date. Announce release schedule to the LLVM community and update
+      the website.</p></li>
+
+  <li><p>Create release branch and begin release process.</p></li>
+
+  <li><p>Send out release candidate sources for first round of testing. Testing
+      lasts 7-10 days. During the first round of testing, any regressions found
+      should be fixed. Patches are merged from mainline into the release
+      branch. Also, all features need to be completed during this time. Any
+      features not completed at the end of the first round of testing will be
+      removed or disabled for the release.</p></li>
+
+  <li><p>Generate and send out the second release candidate sources. Only
+      <em>critial</em> bugs found during this testing phase will be fixed. Any
+      bugs introduced by merged patches will be fixed. If so a third round of
+      testing is needed.</p></li>
+
+  <li><p>The release notes are updated.</p></li>
+
+  <li><p>Finally, release!</p></li>
+</ul>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="process">Release Process</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<ol>
+  <li><a href="#release-admin">Release Administrative Tasks</a>
+  <ol>
+    <li><a href="#branch">Create Release Branch</a></li>
+    <li><a href="#verchanges">Update Version Numbers</a></li>
+  </ol>
+  </li>
+  <li><a href="#release-build">Building the Release</a>
+  <ol>
+    <li><a href="#dist">Build the LLVM Source Distributions</a></li>
+    <li><a href="#build">Build LLVM</a></li>
+    <li><a href="#clangbin">Build the Clang Binary Distribution</a></li>
+    <li><a href="#target-build">Target Specific Build Details</a></li>
+  </ol>
+  </li>
+  <li><a href="#release-qualify">Release Qualification Criteria</a>
+  <ol>
+    <li><a href="#llvm-qualify">Qualify LLVM</a></li>
+    <li><a href="#clang-qualify">Qualify Clang</a></li>
+    <li><a href="#targets">Specific Target Qualification Details</a></li>
+  </ol>
+  </li>
+
+  <li><a href="#commTest">Community Testing</a></li>    
+  <li><a href="#release-patch">Release Patch Rules</a></li>
+  <li><a href="#release-final">Release final tasks</a>
+  <ol>
+    <li><a href="#updocs">Update Documentation</a></li>
+    <li><a href="#tag">Tag the LLVM Final Release</a></li>
+    <li><a href="#updemo">Update the LLVM Demo Page</a></li>
+    <li><a href="#webupdates">Update the LLVM Website</a></li>
+    <li><a href="#announce">Announce the Release</a></li>
+  </ol>
+  </li>
+</ol>
+
+<!-- ======================================================================= -->
+<h3><a name="release-admin">Release Administrative Tasks</a></h3>
+
+<div>
+
+<p>This section describes a few administrative tasks that need to be done for
+   the release process to begin. Specifically, it involves:</p>
+
+<ul>
+  <li>Creating the release branch,</li>
+  <li>Setting version numbers, and</li>
+  <li>Tagging release candidates for the release team to begin testing</li>
+</ul>
+
+<!-- ======================================================================= -->
+<h4><a name="branch">Create Release Branch</a></h4>
+
+<div>
+
+<p>Branch the Subversion trunk using the following procedure:</p>
+
+<ol>
+  <li><p>Remind developers that the release branching is imminent and to refrain
+      from committing patches that might break the build. E.g., new features,
+      large patches for works in progress, an overhaul of the type system, an
+      exciting new TableGen feature, etc.</p></li>
+
+  <li><p>Verify that the current Subversion trunk is in decent shape by
+      examining nightly tester and buildbot results.</p></li>
+
+  <li><p>Create the release branch for <tt>llvm</tt>, <tt>clang</tt>,
+      the <tt>test-suite</tt>, and <tt>dragonegg</tt> from the last known good
+      revision. The branch's name is <tt>release_<i>XY</i></tt>,
+      where <tt>X</tt> is the major and <tt>Y</tt> the minor release
+      numbers. The branches should be created using the following commands:</p>
+  
+<div class="doc_code">
+<pre>
+$ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
+           https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i>
+
+$ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
+           https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i>
+
+$ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \
+           https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i>
+
+$ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
+           https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i>
+</pre>
+</div></li>
+
+  <li><p>Advise developers that they may now check their patches into the
+      Subversion tree again.</p></li>
+
+  <li><p>The Release Manager should switch to the release branch, because all
+      changes to the release will now be done in the branch. The easiest way to
+      do this is to grab a working copy using the following commands:</p>
+
+<div class="doc_code">
+<pre>
+$ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i> llvm-<i>X.Y</i>
+
+$ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> clang-<i>X.Y</i>
+
+$ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i> dragonegg-<i>X.Y</i>
+
+$ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> test-suite-<i>X.Y</i>
+</pre>
+</div></li>
+</ol>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4><a name="verchanges">Update LLVM Version</a></h4>
+
+<div>
+
+<p>After creating the LLVM release branch, update the release branches'
+   <tt>autoconf</tt> and <tt>configure.ac</tt> versions from '<tt>X.Ysvn</tt>'
+   to '<tt>X.Y</tt>'. Update it on mainline as well to be the next version
+   ('<tt>X.Y+1svn</tt>'). Regenerate the configure scripts for both
+   <tt>llvm</tt> and the <tt>test-suite</tt>.</p>
+
+<p>In addition, the version numbers of all the Bugzilla components must be
+   updated for the next release.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4><a name="dist">Build the LLVM Release Candidates</a></h4>
+
+<div>
+
+<p>Create release candidates for <tt>llvm</tt>, <tt>clang</tt>,
+   <tt>dragonegg</tt>, and the LLVM <tt>test-suite</tt> by tagging the branch
+   with the respective release candidate number. For instance, to
+   create <b>Release Candidate 1</b> you would issue the following commands:</p>
+
+<div class="doc_code">
+<pre>
+$ svn mkdir https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>
+$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XY</i> \
+           https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/rc1
+
+$ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>
+$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_<i>XY</i> \
+           https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/rc1
+
+$ svn mkdir https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>
+$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_<i>XY</i> \
+           https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/rc1
+
+$ svn mkdir https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>
+$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XY</i> \
+           https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/rc1
+</pre>
+</div>
+
+<p>Similarly, <b>Release Candidate 2</b> would be named <tt>RC2</tt> and so
+   on. This keeps a permanent copy of the release candidate around for people to
+   export and build as they wish. The final released sources will be tagged in
+   the <tt>RELEASE_<i>XY</i></tt> directory as <tt>Final</tt>
+   (c.f. <a href="#tag">Tag the LLVM Final Release</a>).</p>
+
+<p>The Release Manager may supply pre-packaged source tarballs for users. This
+   can be done with the following commands:</p>
+
+<div class="doc_code">
+<pre>
+$ svn export https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/rc1 llvm-<i>X.Y</i>rc1
+$ svn export https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/rc1 clang-<i>X.Y</i>rc1
+$ svn export https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/rc1 dragonegg-<i>X.Y</i>rc1
+$ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/rc1 llvm-test-<i>X.Y</i>rc1
+
+$ tar -cvf - llvm-<i>X.Y</i>rc1        | gzip > llvm-<i>X.Y</i>rc1.src.tar.gz
+$ tar -cvf - clang-<i>X.Y</i>rc1       | gzip > clang-<i>X.Y</i>rc1.src.tar.gz
+$ tar -cvf - dragonegg-<i>X.Y</i>rc1   | gzip > dragonegg-<i>X.Y</i>rc1.src.tar.gz
+$ tar -cvf - llvm-test-<i>X.Y</i>rc1   | gzip > llvm-test-<i>X.Y</i>rc1.src.tar.gz
+</pre>
+</div>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="release-build">Building the Release</a></h3>
+
+<div>
+
+<p>The builds of <tt>llvm</tt>, <tt>clang</tt>, and <tt>dragonegg</tt>
+   <em>must</em> be free of errors and warnings in Debug, Release+Asserts, and
+   Release builds. If all builds are clean, then the release passes Build
+   Qualification.</p>
+
+<p>The <tt>make</tt> options for building the different modes:</p>
+
+<table>
+  <tr><th>Mode</th><th>Options</th></tr>
+  <tr align="left"><td>Debug</td><td><tt>ENABLE_OPTIMIZED=0</tt></td></tr>
+  <tr align="left"><td>Release+Asserts</td><td><tt>ENABLE_OPTIMIZED=1</tt></td></tr>
+  <tr align="left"><td>Release</td><td><tt>ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</tt></td></tr>
+</table>
+
+<!-- ======================================================================= -->
+<h4><a name="build">Build LLVM</a></h4>
+
+<div>
+
+<p>Build <tt>Debug</tt>, <tt>Release+Asserts</tt>, and <tt>Release</tt> versions
+   of <tt>llvm</tt> on all supported platforms. Directions to build
+   <tt>llvm</tt> are <a href="GettingStarted.html#quickstart">here</a>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4><a name="clangbin">Build Clang Binary Distribution</a></h4>
+
+<div>
+
+<p>Creating the <tt>clang</tt> binary distribution
+   (Debug/Release+Asserts/Release) requires performing the following steps for
+   each supported platform:</p>
+
+<ol>
+  <li>Build clang according to the directions
+      <a href="http://clang.llvm.org/get_started.html">here</a>.</li>
+
+  <li>Build both a Debug and Release version of clang. The binary will be the
+      Release build.</lI>
+
+  <li>Package <tt>clang</tt> (details to follow).</li>
+</ol>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4><a name="target-build">Target Specific Build Details</a></h4>
+
+<div>
+
+<p>The table below specifies which compilers are used for each Arch/OS
+   combination when qualifying the build of <tt>llvm</tt>, <tt>clang</tt>,
+   and <tt>dragonegg</tt>.</p>
+
+<table>
+  <tr><th>Architecture</th> <th>OS</th>          <th>compiler</th></tr>
+  <tr><td>x86-32</td>       <td>Mac OS 10.5</td> <td>gcc 4.0.1</td></tr>
+  <tr><td>x86-32</td>       <td>Linux</td>       <td>gcc 4.2.X, gcc 4.3.X</td></tr>
+  <tr><td>x86-32</td>       <td>FreeBSD</td>     <td>gcc 4.2.X</td></tr>
+  <tr><td>x86-32</td>       <td>mingw</td>       <td>gcc 3.4.5</td></tr>
+  <tr><td>x86-64</td>       <td>Mac OS 10.5</td> <td>gcc 4.0.1</td></tr>
+  <tr><td>x86-64</td>       <td>Linux</td>       <td>gcc 4.2.X, gcc 4.3.X</td></tr>
+  <tr><td>x86-64</td>       <td>FreeBSD</td>     <td>gcc 4.2.X</td></tr>
+</table> 
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="release-qualify">Building the Release</a></h3>
+
+<div>
+
+<p>A release is qualified when it has no regressions from the previous release
+   (or baseline). Regressions are related to correctness first and performance
+   second. (We may tolerate some minor performance regressions if they are
+   deemed necessary for the general quality of the compiler.)</p>
+
+<p><b>Regressions are new failures in the set of tests that are used to qualify
+   each product and only include things on the list. Every release will have
+   some bugs in it. It is the reality of developing a complex piece of
+   software. We need a very concrete and definitive release criteria that
+   ensures we have monotonically improving quality on some metric. The metric we
+   use is described below. This doesn't mean that we don't care about other
+   criteria, but these are the criteria which we found to be most important and
+   which must be satisfied before a release can go out</b></p>
+
+<!-- ======================================================================= -->
+<h4><a name="llvm-qualify">Qualify LLVM</a></h4>
+
+<div>
+
+<p>LLVM is qualified when it has a clean test run without a front-end. And it
+   has no regressions when using either <tt>clang</tt> or <tt>dragonegg</tt>
+   with the <tt>test-suite</tt> from the previous release.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4><a name="clang-qualify">Qualify Clang</a></h4>
+
+<div>
+
+<p><tt>Clang</tt> is qualified when front-end specific tests in the 
+   <tt>llvm</tt> dejagnu test suite all pass, clang's own test suite passes
+   cleanly, and there are no regressions in the <tt>test-suite</tt>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4><a name="targets">Specific Target Qualification Details</a></h4>
+
+<div>
+
+<table>
+  <tr><th>Architecture</th> <th>OS</th>          <th>clang baseline</th> <th>tests</th></tr>
+  <tr><td>x86-32</td>       <td>Linux</td>       <td>last release</td>   <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr>
+  <tr><td>x86-32</td>       <td>FreeBSD</td>     <td>last release</td>   <td>llvm dejagnu, clang tests, test-suite</td></tr>
+  <tr><td>x86-32</td>       <td>mingw</td>       <td>none</td>           <td>QT</td></tr>
+  <tr><td>x86-64</td>       <td>Mac OS 10.X</td> <td>last release</td>   <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr>
+  <tr><td>x86-64</td>       <td>Linux</td>       <td>last release</td>   <td>llvm dejagnu, clang tests, test-suite (including spec)</td></tr>
+  <tr><td>x86-64</td>       <td>FreeBSD</td>     <td>last release</td>   <td>llvm dejagnu, clang tests, test-suite</td></tr>
+</table>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="commTest">Community Testing</a></h3>
+<div>
+
+<p>Once all testing has been completed and appropriate bugs filed, the release
+   candidate tarballs are put on the website and the LLVM community is
+   notified. Ask that all LLVM developers test the release in 2 ways:</p>
+
+<ol>
+  <li>Download <tt>llvm-<i>X.Y</i></tt>, <tt>llvm-test-<i>X.Y</i></tt>, and the
+      appropriate <tt>clang</tt> binary. Build LLVM. Run <tt>make check</tt> and
+      the full LLVM test suite (<tt>make TEST=nightly report</tt>).</li>
+
+  <li>Download <tt>llvm-<i>X.Y</i></tt>, <tt>llvm-test-<i>X.Y</i></tt>, and the
+      <tt>clang</tt> sources. Compile everything. Run <tt>make check</tt> and
+      the full LLVM test suite (<tt>make TEST=nightly report</tt>).</li>
+</ol>
+
+<p>Ask LLVM developers to submit the test suite report and <tt>make check</tt>
+   results to the list. Verify that there are no regressions from the previous
+   release. The results are not used to qualify a release, but to spot other
+   potential problems. For unsupported targets, verify that <tt>make check</tt>
+   is at least clean.</p>
+  
+<p>During the first round of testing, all regressions must be fixed before the
+   second release candidate is tagged.</p>
+  
+<p>If this is the second round of testing, the testing is only to ensure that
+   bug fixes previously merged in have not created new major problems. <i>This
+   is not the time to solve additional and unrelated bugs!</i> If no patches are
+   merged in, the release is determined to be ready and the release manager may
+   move onto the next stage.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="release-patch">Release Patch Rules</a></h3>
+
+<div>
+
+<p>Below are the rules regarding patching the release branch:</p>
+
+<ol>
+  <li><p>Patches applied to the release branch may only be applied by the
+      release manager.</p></li>
+
+  <li><p>During the first round of testing, patches that fix regressions or that
+      are small and relatively risk free (verified by the appropriate code
+      owner) are applied to the branch. Code owners are asked to be very
+      conservative in approving patches for the branch. We reserve the right to
+      reject any patch that does not fix a regression as previously
+      defined.</p></li>
+
+  <li><p>During the remaining rounds of testing, only patches that fix critical
+      regressions may be applied.</p></li>
+</ol>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="release-final">Release Final Tasks</a></h3>
+
+<div>
+
+<p>The final stages of the release process involves tagging the "final" release
+   branch, updating documentation that refers to the release, and updating the
+   demo page.</p>
+
+<!-- ======================================================================= -->
+<h4><a name="updocs">Update Documentation</a></h4>
+
+<div>
+
+<p>Review the documentation and ensure that it is up to date. The "Release
+   Notes" must be updated to reflect new features, bug fixes, new known issues,
+   and changes in the list of supported platforms. The "Getting Started Guide"
+   should be updated to reflect the new release version number tag available from
+   Subversion and changes in basic system requirements. Merge both changes from
+   mainline into the release branch.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4><a name="tag">Tag the LLVM Final Release</a></h4>
+
+<div>
+
+<p>Tag the final release sources using the following procedure:</p>
+
+<div class="doc_code">
+<pre>
+$ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
+           https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XY</i>/Final
+
+$ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
+           https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_<i>XY</i>/Final
+
+$ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
+           https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_<i>XY</i>/Final
+
+$ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
+           https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XY</i>/Final
+</pre>
+</div>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3><a name="updemo">Update the LLVM Demo Page</a></h3>
+
+<div>
+
+<p>The LLVM demo page must be updated to use the new release. This consists of
+   using the new <tt>clang</tt> binary and building LLVM.</p>
+
+<!-- ======================================================================= -->
+<h4><a name="webupdates">Update the LLVM Website</a></h4>
+
+<div>
+
+<p>The website must be updated before the release announcement is sent out. Here
+   is what to do:</p>
+
+<ol>
+  <li>Check out the <tt>www</tt> module from Subversion.</li>
+
+  <li>Create a new subdirectory <tt>X.Y</tt> in the releases directory.</li>
+
+  <li>Commit the <tt>llvm</tt>, <tt>test-suite</tt>, <tt>clang</tt> source,
+      <tt>clang binaries</tt>, <tt>dragonegg</tt> source, and <tt>dragonegg</tt>
+      binaries in this new directory.</li>
+
+  <li>Copy and commit the <tt>llvm/docs</tt> and <tt>LICENSE.txt</tt> files
+      into this new directory. The docs should be built with
+      <tt>BUILD_FOR_WEBSITE=1</tt>.</li>
+
+  <li>Commit the <tt>index.html</tt> to the <tt>release/X.Y</tt> directory to
+      redirect (use from previous release.</li>
+
+  <li>Update the <tt>releases/download.html</tt> file with the new release.</li>
+
+  <li>Update the <tt>releases/index.html</tt> with the new release and link to
+      release documentation.</li>
+
+  <li>Finally, update the main page (<tt>index.html</tt> and sidebar) to point
+      to the new release and release announcement. Make sure this all gets
+      committed back into Subversion.</li>
+</ol>
+
+</div>
+
+<!-- ======================================================================= -->
+<h4><a name="announce">Announce the Release</a></h4>
+
+<div>
+
+<p>Have Chris send out the release announcement when everything is finished.</p>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<hr>
+<address>
+  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+  <a href="http://validator.w3.org/check/referer"><img
+  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+  <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
+  <br>
+  Last modified: $Date: 2012-07-31 02:05:57 -0500 (Tue, 31 Jul 2012) $
+</address>
+</body>
+</html>

Added: www-releases/trunk/3.2/docs/HowToSetUpLLVMStyleRTTI.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HowToSetUpLLVMStyleRTTI.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HowToSetUpLLVMStyleRTTI.rst (added)
+++ www-releases/trunk/3.2/docs/HowToSetUpLLVMStyleRTTI.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,332 @@
+.. _how-to-set-up-llvm-style-rtti:
+
+======================================================
+How to set up LLVM-style RTTI for your class hierarchy
+======================================================
+
+.. sectionauthor:: Sean Silva <silvas at purdue.edu>
+
+.. contents::
+
+Background
+==========
+
+LLVM avoids using C++'s built in RTTI. Instead, it  pervasively uses its
+own hand-rolled form of RTTI which is much more efficient and flexible,
+although it requires a bit more work from you as a class author.
+
+A description of how to use LLVM-style RTTI from a client's perspective is
+given in the `Programmer's Manual <ProgrammersManual.html#isa>`_. This
+document, in contrast, discusses the steps you need to take as a class
+hierarchy author to make LLVM-style RTTI available to your clients.
+
+Before diving in, make sure that you are familiar with the Object Oriented
+Programming concept of "`is-a`_".
+
+.. _is-a: http://en.wikipedia.org/wiki/Is-a
+
+Basic Setup
+===========
+
+This section describes how to set up the most basic form of LLVM-style RTTI
+(which is sufficient for 99.9% of the cases). We will set up LLVM-style
+RTTI for this class hierarchy:
+
+.. code-block:: c++
+
+   class Shape {
+   public:
+     Shape() {}
+     virtual double computeArea() = 0;
+   };
+
+   class Square : public Shape {
+     double SideLength;
+   public:
+     Square(double S) : SideLength(S) {}
+     double computeArea() /* override */;
+   };
+
+   class Circle : public Shape {
+     double Radius;
+   public:
+     Circle(double R) : Radius(R) {}
+     double computeArea() /* override */;
+   };
+
+The most basic working setup for LLVM-style RTTI requires the following
+steps:
+
+#. In the header where you declare ``Shape``, you will want to ``#include
+   "llvm/Support/Casting.h"``, which declares LLVM's RTTI templates. That
+   way your clients don't even have to think about it.
+
+   .. code-block:: c++
+
+      #include "llvm/Support/Casting.h"
+
+#. In the base class, introduce an enum which discriminates all of the
+   different concrete classes in the hierarchy, and stash the enum value
+   somewhere in the base class.
+
+   Here is the code after introducing this change:
+
+   .. code-block:: c++
+
+       class Shape {
+       public:
+      +  /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)
+      +  enum ShapeKind {
+      +    SK_Square,
+      +    SK_Circle
+      +  };
+      +private:
+      +  const ShapeKind Kind;
+      +public:
+      +  ShapeKind getKind() const { return Kind; }
+      +
+         Shape() {}
+         virtual double computeArea() = 0;
+       };
+
+   You will usually want to keep the ``Kind`` member encapsulated and
+   private, but let the enum ``ShapeKind`` be public along with providing a
+   ``getKind()`` method. This is convenient for clients so that they can do
+   a ``switch`` over the enum.
+
+   A common naming convention is that these enums are "kind"s, to avoid
+   ambiguity with the words "type" or "class" which have overloaded meanings
+   in many contexts within LLVM. Sometimes there will be a natural name for
+   it, like "opcode". Don't bikeshed over this; when in doubt use ``Kind``.
+
+   You might wonder why the ``Kind`` enum doesn't have an entry for
+   ``Shape``. The reason for this is that since ``Shape`` is abstract
+   (``computeArea() = 0;``), you will never actually have non-derived
+   instances of exactly that class (only subclasses). See `Concrete Bases
+   and Deeper Hierarchies`_ for information on how to deal with
+   non-abstract bases. It's worth mentioning here that unlike
+   ``dynamic_cast<>``, LLVM-style RTTI can be used (and is often used) for
+   classes that don't have v-tables.
+
+#. Next, you need to make sure that the ``Kind`` gets initialized to the
+   value corresponding to the dynamic type of the class. Typically, you will
+   want to have it be an argument to the constructor of the base class, and
+   then pass in the respective ``XXXKind`` from subclass constructors.
+
+   Here is the code after that change:
+
+   .. code-block:: c++
+
+       class Shape {
+       public:
+         /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)
+         enum ShapeKind {
+           SK_Square,
+           SK_Circle
+         };
+       private:
+         const ShapeKind Kind;
+       public:
+         ShapeKind getKind() const { return Kind; }
+
+      -  Shape() {}
+      +  Shape(ShapeKind K) : Kind(K) {}
+         virtual double computeArea() = 0;
+       };
+
+       class Square : public Shape {
+         double SideLength;
+       public:
+      -  Square(double S) : SideLength(S) {}
+      +  Square(double S) : Shape(SK_Square), SideLength(S) {}
+         double computeArea() /* override */;
+       };
+
+       class Circle : public Shape {
+         double Radius;
+       public:
+      -  Circle(double R) : Radius(R) {}
+      +  Circle(double R) : Shape(SK_Circle), Radius(R) {}
+         double computeArea() /* override */;
+       };
+
+#. Finally, you need to inform LLVM's RTTI templates how to dynamically
+   determine the type of a class (i.e. whether the ``isa<>``/``dyn_cast<>``
+   should succeed). The default "99.9% of use cases" way to accomplish this
+   is through a small static member function ``classof``. In order to have
+   proper context for an explanation, we will display this code first, and
+   then below describe each part:
+
+   .. code-block:: c++
+
+       class Shape {
+       public:
+         /// Discriminator for LLVM-style RTTI (dyn_cast<> et al.)
+         enum ShapeKind {
+           SK_Square,
+           SK_Circle
+         };
+       private:
+         const ShapeKind Kind;
+       public:
+         ShapeKind getKind() const { return Kind; }
+
+         Shape(ShapeKind K) : Kind(K) {}
+         virtual double computeArea() = 0;
+       };
+
+       class Square : public Shape {
+         double SideLength;
+       public:
+         Square(double S) : Shape(SK_Square), SideLength(S) {}
+         double computeArea() /* override */;
+      +
+      +  static bool classof(const Shape *S) {
+      +    return S->getKind() == SK_Square;
+      +  }
+       };
+
+       class Circle : public Shape {
+         double Radius;
+       public:
+         Circle(double R) : Shape(SK_Circle), Radius(R) {}
+         double computeArea() /* override */;
+      +
+      +  static bool classof(const Shape *S) {
+      +    return S->getKind() == SK_Circle;
+      +  }
+       };
+
+   The job of ``classof`` is to dynamically determine whether an object of
+   a base class is in fact of a particular derived class.  In order to
+   downcast a type ``Base`` to a type ``Derived``, there needs to be a
+   ``classof`` in ``Derived`` which will accept an object of type ``Base``.
+
+   To be concrete, consider the following code:
+
+   .. code-block:: c++
+
+      Shape *S = ...;
+      if (isa<Circle>(S)) {
+        /* do something ... */
+      }
+
+   The code of the ``isa<>`` test in this code will eventually boil
+   down---after template instantiation and some other machinery---to a
+   check roughly like ``Circle::classof(S)``. For more information, see
+   :ref:`classof-contract`.
+
+   The argument to ``classof`` should always be an *ancestor* class because
+   the implementation has logic to allow and optimize away
+   upcasts/up-``isa<>``'s automatically. It is as though every class
+   ``Foo`` automatically has a ``classof`` like:
+
+   .. code-block:: c++
+
+      class Foo {
+        [...]
+        template <class T>
+        static bool classof(const T *,
+                            ::llvm::enable_if_c<
+                              ::llvm::is_base_of<Foo, T>::value
+                            >::type* = 0) { return true; }
+        [...]
+      };
+
+   Note that this is the reason that we did not need to introduce a
+   ``classof`` into ``Shape``: all relevant classes derive from ``Shape``,
+   and ``Shape`` itself is abstract (has no entry in the ``Kind`` enum),
+   so this notional inferred ``classof`` is all we need. See `Concrete
+   Bases and Deeper Hierarchies`_ for more information about how to extend
+   this example to more general hierarchies.
+
+Although for this small example setting up LLVM-style RTTI seems like a lot
+of "boilerplate", if your classes are doing anything interesting then this
+will end up being a tiny fraction of the code.
+
+Concrete Bases and Deeper Hierarchies
+=====================================
+
+For concrete bases (i.e. non-abstract interior nodes of the inheritance
+tree), the ``Kind`` check inside ``classof`` needs to be a bit more
+complicated. The situation differs from the example above in that
+
+* Since the class is concrete, it must itself have an entry in the ``Kind``
+  enum because it is possible to have objects with this class as a dynamic
+  type.
+
+* Since the class has children, the check inside ``classof`` must take them
+  into account.
+
+Say that ``SpecialSquare`` and ``OtherSpecialSquare`` derive
+from ``Square``, and so ``ShapeKind`` becomes:
+
+.. code-block:: c++
+
+    enum ShapeKind {
+      SK_Square,
+   +  SK_SpecialSquare,
+   +  SK_OtherSpecialSquare,
+      SK_Circle
+    }
+
+Then in ``Square``, we would need to modify the ``classof`` like so:
+
+.. code-block:: c++
+
+   -  static bool classof(const Shape *S) {
+   -    return S->getKind() == SK_Square;
+   -  }
+   +  static bool classof(const Shape *S) {
+   +    return S->getKind() >= SK_Square &&
+   +           S->getKind() <= SK_OtherSpecialSquare;
+   +  }
+
+The reason that we need to test a range like this instead of just equality
+is that both ``SpecialSquare`` and ``OtherSpecialSquare`` "is-a"
+``Square``, and so ``classof`` needs to return ``true`` for them.
+
+This approach can be made to scale to arbitrarily deep hierarchies. The
+trick is that you arrange the enum values so that they correspond to a
+preorder traversal of the class hierarchy tree. With that arrangement, all
+subclass tests can be done with two comparisons as shown above. If you just
+list the class hierarchy like a list of bullet points, you'll get the
+ordering right::
+
+   | Shape
+     | Square
+       | SpecialSquare
+       | OtherSpecialSquare
+     | Circle
+
+.. _classof-contract:
+
+The Contract of ``classof``
+---------------------------
+
+To be more precise, let ``classof`` be inside a class ``C``.  Then the
+contract for ``classof`` is "return ``true`` if the dynamic type of the
+argument is-a ``C``".  As long as your implementation fulfills this
+contract, you can tweak and optimize it as much as you want.
+
+.. TODO::
+
+   Touch on some of the more advanced features, like ``isa_impl`` and
+   ``simplify_type``. However, those two need reference documentation in
+   the form of doxygen comments as well. We need the doxygen so that we can
+   say "for full details, see http://llvm.org/doxygen/..."
+
+Rules of Thumb
+==============
+
+#. The ``Kind`` enum should have one entry per concrete class, ordered
+   according to a preorder traversal of the inheritance tree.
+#. The argument to ``classof`` should be a ``const Base *``, where ``Base``
+   is some ancestor in the inheritance hierarchy. The argument should
+   *never* be a derived class or the class itself: the template machinery
+   for ``isa<>`` already handles this case and optimizes it.
+#. For each class in the hierarchy that has no children, implement a
+   ``classof`` that checks only against its ``Kind``.
+#. For each class in the hierarchy that has children, implement a
+   ``classof`` that checks a range of the first child's ``Kind`` and the
+   last child's ``Kind``.

Added: www-releases/trunk/3.2/docs/HowToSubmitABug.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HowToSubmitABug.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HowToSubmitABug.rst (added)
+++ www-releases/trunk/3.2/docs/HowToSubmitABug.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,233 @@
+.. _how-to-submit-a-bug-report:
+
+================================
+How to submit an LLVM bug report
+================================
+
+.. sectionauthor:: Chris Lattner <sabre at nondot.org> and Misha Brukman <http://misha.brukman.net>
+
+Introduction - Got bugs?
+========================
+
+
+If you're working with LLVM and run into a bug, we definitely want to know
+about it.  This document describes what you can do to increase the odds of
+getting it fixed quickly.
+
+Basically you have to do two things at a minimum.  First, decide whether
+the bug `crashes the compiler`_ (or an LLVM pass), or if the
+compiler is `miscompiling`_ the program (i.e., the
+compiler successfully produces an executable, but it doesn't run right).
+Based on what type of bug it is, follow the instructions in the linked
+section to narrow down the bug so that the person who fixes it will be able
+to find the problem more easily.
+
+Once you have a reduced test-case, go to `the LLVM Bug Tracking System
+<http://llvm.org/bugs/enter_bug.cgi>`_ and fill out the form with the
+necessary details (note that you don't need to pick a category, just use
+the "new-bugs" category if you're not sure).  The bug description should
+contain the following information:
+
+* All information necessary to reproduce the problem.
+* The reduced test-case that triggers the bug.
+* The location where you obtained LLVM (if not from our Subversion
+  repository).
+
+Thanks for helping us make LLVM better!
+
+.. _crashes the compiler:
+
+Crashing Bugs
+=============
+
+More often than not, bugs in the compiler cause it to crash---often due to
+an assertion failure of some sort. The most important piece of the puzzle
+is to figure out if it is crashing in the GCC front-end or if it is one of
+the LLVM libraries (e.g. the optimizer or code generator) that has
+problems.
+
+To figure out which component is crashing (the front-end, optimizer or code
+generator), run the ``llvm-gcc`` command line as you were when the crash
+occurred, but with the following extra command line options:
+
+* ``-O0 -emit-llvm``: If ``llvm-gcc`` still crashes when passed these
+  options (which disable the optimizer and code generator), then the crash
+  is in the front-end.  Jump ahead to the section on :ref:`front-end bugs
+  <front-end>`.
+
+* ``-emit-llvm``: If ``llvm-gcc`` crashes with this option (which disables
+  the code generator), you found an optimizer bug.  Jump ahead to
+  `compile-time optimization bugs`_.
+
+* Otherwise, you have a code generator crash. Jump ahead to `code
+  generator bugs`_.
+
+.. _front-end bug:
+.. _front-end:
+
+Front-end bugs
+--------------
+
+If the problem is in the front-end, you should re-run the same ``llvm-gcc``
+command that resulted in the crash, but add the ``-save-temps`` option.
+The compiler will crash again, but it will leave behind a ``foo.i`` file
+(containing preprocessed C source code) and possibly ``foo.s`` for each
+compiled ``foo.c`` file. Send us the ``foo.i`` file, along with the options
+you passed to ``llvm-gcc``, and a brief description of the error it caused.
+
+The `delta <http://delta.tigris.org/>`_ tool helps to reduce the
+preprocessed file down to the smallest amount of code that still replicates
+the problem. You're encouraged to use delta to reduce the code to make the
+developers' lives easier. `This website
+<http://gcc.gnu.org/wiki/A_guide_to_testcase_reduction>`_ has instructions
+on the best way to use delta.
+
+.. _compile-time optimization bugs:
+
+Compile-time optimization bugs
+------------------------------
+
+If you find that a bug crashes in the optimizer, compile your test-case to a
+``.bc`` file by passing "``-emit-llvm -O0 -c -o foo.bc``".
+Then run:
+
+.. code-block:: bash
+
+   opt -std-compile-opts -debug-pass=Arguments foo.bc -disable-output
+
+This command should do two things: it should print out a list of passes, and
+then it should crash in the same way as llvm-gcc.  If it doesn't crash, please
+follow the instructions for a `front-end bug`_.
+
+If this does crash, then you should be able to debug this with the following
+bugpoint command:
+
+.. code-block:: bash
+
+   bugpoint foo.bc <list of passes printed by opt>
+
+Please run this, then file a bug with the instructions and reduced .bc
+files that bugpoint emits.  If something goes wrong with bugpoint, please
+submit the "foo.bc" file and the list of passes printed by ``opt``.
+
+.. _code generator bugs:
+
+Code generator bugs
+-------------------
+
+If you find a bug that crashes llvm-gcc in the code generator, compile your
+source file to a .bc file by passing "``-emit-llvm -c -o foo.bc``" to
+llvm-gcc (in addition to the options you already pass).  Once your have
+foo.bc, one of the following commands should fail:
+
+#. ``llc foo.bc``
+#. ``llc foo.bc -relocation-model=pic``
+#. ``llc foo.bc -relocation-model=static``
+
+If none of these crash, please follow the instructions for a `front-end
+bug`_.  If one of these do crash, you should be able to reduce this with
+one of the following bugpoint command lines (use the one corresponding to
+the command above that failed):
+
+#. ``bugpoint -run-llc foo.bc``
+#. ``bugpoint -run-llc foo.bc --tool-args -relocation-model=pic``
+#. ``bugpoint -run-llc foo.bc --tool-args -relocation-model=static``
+
+Please run this, then file a bug with the instructions and reduced .bc file
+that bugpoint emits.  If something goes wrong with bugpoint, please submit
+the "foo.bc" file and the option that llc crashes with.
+
+.. _miscompiling:
+
+Miscompilations
+===============
+
+If llvm-gcc successfully produces an executable, but that executable
+doesn't run right, this is either a bug in the code or a bug in the
+compiler.  The first thing to check is to make sure it is not using
+undefined behavior (e.g. reading a variable before it is defined). In
+particular, check to see if the program `valgrind
+<http://valgrind.org/>`_'s clean, passes purify, or some other memory
+checker tool. Many of the "LLVM bugs" that we have chased down ended up
+being bugs in the program being compiled, not LLVM.
+
+Once you determine that the program itself is not buggy, you should choose
+which code generator you wish to compile the program with (e.g. LLC or the JIT)
+and optionally a series of LLVM passes to run.  For example:
+
+.. code-block:: bash
+
+   bugpoint -run-llc [... optzn passes ...] file-to-test.bc --args -- [program arguments]
+
+bugpoint will try to narrow down your list of passes to the one pass that
+causes an error, and simplify the bitcode file as much as it can to assist
+you. It will print a message letting you know how to reproduce the
+resulting error.
+
+Incorrect code generation
+=========================
+
+Similarly to debugging incorrect compilation by mis-behaving passes, you
+can debug incorrect code generation by either LLC or the JIT, using
+``bugpoint``. The process ``bugpoint`` follows in this case is to try to
+narrow the code down to a function that is miscompiled by one or the other
+method, but since for correctness, the entire program must be run,
+``bugpoint`` will compile the code it deems to not be affected with the C
+Backend, and then link in the shared object it generates.
+
+To debug the JIT:
+
+.. code-block:: bash
+
+   bugpoint -run-jit -output=[correct output file] [bitcode file]  \
+            --tool-args -- [arguments to pass to lli]              \
+            --args -- [program arguments]
+
+Similarly, to debug the LLC, one would run:
+
+.. code-block:: bash
+
+   bugpoint -run-llc -output=[correct output file] [bitcode file]  \
+            --tool-args -- [arguments to pass to llc]              \
+            --args -- [program arguments]
+
+**Special note:** if you are debugging MultiSource or SPEC tests that
+already exist in the ``llvm/test`` hierarchy, there is an easier way to
+debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which
+will pass the program options specified in the Makefiles:
+
+.. code-block:: bash
+
+   cd llvm/test/../../program
+   make bugpoint-jit
+
+At the end of a successful ``bugpoint`` run, you will be presented
+with two bitcode files: a *safe* file which can be compiled with the C
+backend and the *test* file which either LLC or the JIT
+mis-codegenerates, and thus causes the error.
+
+To reproduce the error that ``bugpoint`` found, it is sufficient to do
+the following:
+
+#. Regenerate the shared object from the safe bitcode file:
+
+   .. code-block:: bash
+
+      llc -march=c safe.bc -o safe.c
+      gcc -shared safe.c -o safe.so
+
+#. If debugging LLC, compile test bitcode native and link with the shared
+   object:
+
+   .. code-block:: bash
+
+      llc test.bc -o test.s
+      gcc test.s safe.so -o test.llc
+      ./test.llc [program options]
+
+#. If debugging the JIT, load the shared object and supply the test
+   bitcode:
+
+   .. code-block:: bash
+
+      lli -load=safe.so test.bc [program options]

Added: www-releases/trunk/3.2/docs/HowToUseInstrMappings.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/HowToUseInstrMappings.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/HowToUseInstrMappings.rst (added)
+++ www-releases/trunk/3.2/docs/HowToUseInstrMappings.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,179 @@
+.. _how_to_use_instruction_mappings:
+
+===============================
+How To Use Instruction Mappings
+===============================
+
+.. sectionauthor:: Jyotsna Verma <jverma at codeaurora.org>
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document contains information about adding instruction mapping support
+for a target. The motivation behind this feature comes from the need to switch
+between different instruction formats during various optimizations. One approach
+could be to use switch cases which list all the instructions along with formats
+they can transition to. However, it has large maintenance overhead
+because of the hardcoded instruction names. Also, whenever a new instruction is
+added in the .td files, all the relevant switch cases should be modified
+accordingly. Instead, the same functionality could be achieved with TableGen and
+some support from the .td files for a fraction of maintenance cost.
+
+``InstrMapping`` Class Overview
+===============================
+
+TableGen uses relationship models to map instructions with each other. These
+models are described using ``InstrMapping`` class as a base. Each model sets
+various fields of the ``InstrMapping`` class such that they can uniquely
+describe all the instructions using that model. TableGen parses all the relation
+models and uses the information to construct relation tables which relate
+instructions with each other. These tables are emitted in the
+``XXXInstrInfo.inc`` file along with the functions to query them. Following
+is the definition of ``InstrMapping`` class definied in Target.td file:
+
+.. code-block:: llvm
+
+  class InstrMapping {
+    // Used to reduce search space only to the instructions using this
+    // relation model.
+    string FilterClass;
+
+    // List of fields/attributes that should be same for all the instructions in
+    // a row of the relation table. Think of this as a set of properties shared
+    // by all the instructions related by this relationship.
+    list<string> RowFields = [];
+
+    // List of fields/attributes that are same for all the instructions
+    // in a column of the relation table.
+    list<string> ColFields = [];
+
+    // Values for the fields/attributes listed in 'ColFields' corresponding to
+    // the key instruction. This is the instruction that will be transformed
+    // using this relation model.
+    list<string> KeyCol = [];
+
+    // List of values for the fields/attributes listed in 'ColFields', one for
+    // each column in the relation table. These are the instructions a key
+    // instruction will be transformed into.
+    list<list<string> > ValueCols = [];
+  }
+
+Sample Example
+--------------
+
+Let's say that we want to have a function
+``int getPredOpcode(uint16_t Opcode, enum PredSense inPredSense)`` which
+takes a non-predicated instruction and returns its predicated true or false form
+depending on some input flag, ``inPredSense``. The first step in the process is
+to define a relationship model that relates predicated instructions to their
+non-predicated form by assigning appropriate values to the ``InstrMapping``
+fields. For this relationship, non-predicated instructions are treated as key
+instruction since they are the one used to query the interface function.
+
+.. code-block:: llvm
+
+  def getPredOpcode : InstrMapping {
+    // Choose a FilterClass that is used as a base class for all the
+    // instructions modeling this relationship. This is done to reduce the
+    // search space only to these set of instructions.
+    let FilterClass = "PredRel";
+
+    // Instructions with same values for all the fields in RowFields form a
+    // row in the resulting relation table.
+    // For example, if we want to relate 'ADD' (non-predicated) with 'Add_pt'
+    // (predicated true) and 'Add_pf' (predicated false), then all 3
+    // instructions need to have same value for BaseOpcode field. It can be any
+    // unique value (Ex: XYZ) and should not be shared with any other
+    // instruction not related to 'add'.
+    let RowFields = ["BaseOpcode"];
+
+    // List of attributes that can be used to define key and column instructions
+    // for a relation. Key instruction is passed as an argument
+    // to the function used for querying relation tables. Column instructions
+    // are the instructions they (key) can transform into.
+    //
+    // Here, we choose 'PredSense' as ColFields since this is the unique
+    // attribute of the key (non-predicated) and column (true/false)
+    // instructions involved in this relationship model.
+    let ColFields = ["PredSense"];
+
+    // The key column contains non-predicated instructions.
+    let KeyCol = ["none"];
+
+    // Two value columns - first column contains instructions with
+    // PredSense=true while second column has instructions with PredSense=false.
+    let ValueCols = [["true"], ["false"]];
+  }
+
+TableGen uses the above relationship model to emit relation table that maps
+non-predicated instructions with their predicated forms. It also outputs the
+interface function
+``int getPredOpcode(uint16_t Opcode, enum PredSense inPredSense)`` to query
+the table. Here, Function ``getPredOpcode`` takes two arguments, opcode of the
+current instruction and PredSense of the desired instruction, and returns
+predicated form of the instruction, if found in the relation table.
+In order for an instruction to be added into the relation table, it needs
+to include relevant information in its definition. For example, consider
+following to be the current definitions of ADD, ADD_pt (true) and ADD_pf (false)
+instructions:
+
+.. code-block::llvm
+
+  def ADD : ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b),
+              "$dst = add($a, $b)",
+              [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a),
+                                             (i32 IntRegs:$b)))]>;
+
+  def ADD_Pt : ALU32_rr<(outs IntRegs:$dst),
+                         (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+              "if ($p) $dst = add($a, $b)",
+              []>;
+
+  def ADD_Pf : ALU32_rr<(outs IntRegs:$dst),
+                         (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+              "if (!$p) $dst = add($a, $b)",
+              []>;
+
+In this step, we modify these instructions to include the information
+required by the relationship model, <tt>getPredOpcode</tt>, so that they can
+be related.
+
+.. code-block::llvm
+
+  def ADD : PredRel, ALU32_rr<(outs IntRegs:$dst), (ins IntRegs:$a, IntRegs:$b),
+              "$dst = add($a, $b)",
+              [(set (i32 IntRegs:$dst), (add (i32 IntRegs:$a),
+                                             (i32 IntRegs:$b)))]> {
+    let BaseOpcode = "ADD";
+    let PredSense = "none";
+  }
+
+  def ADD_Pt : PredRel, ALU32_rr<(outs IntRegs:$dst),
+                         (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+              "if ($p) $dst = add($a, $b)",
+              []> {
+    let BaseOpcode = "ADD";
+    let PredSense = "true";
+  }
+
+  def ADD_Pf : PredRel, ALU32_rr<(outs IntRegs:$dst),
+                         (ins PredRegs:$p, IntRegs:$a, IntRegs:$b),
+              "if (!$p) $dst = add($a, $b)",
+              []> {
+    let BaseOpcode = "ADD";
+    let PredSense = "false";
+  }
+
+Please note that all the above instructions use ``PredRel`` as a base class.
+This is extremely important since TableGen uses it as a filter for selecting
+instructions for ``getPredOpcode`` model. Any instruction not derived from
+``PredRel`` is excluded from the analysis. ``BaseOpcode`` is another important
+field. Since it's selected as a ``RowFields`` of the model, it is required
+to have the same value for all 3 instructions in order to be related. Next,
+``PredSense`` is used to determine their column positions by comparing its value
+with ``KeyCol`` and ``ValueCols``. If an instruction sets its ``PredSense``
+value to something not used in the relation model, it will not be assigned
+a column in the relation table.

Propchange: www-releases/trunk/3.2/docs/HowToUseInstrMappings.rst
------------------------------------------------------------------------------
    svn:executable = *

Added: www-releases/trunk/3.2/docs/LLVMBuild.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/LLVMBuild.html?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/LLVMBuild.html (added)
+++ www-releases/trunk/3.2/docs/LLVMBuild.html Fri Dec 21 00:57:24 2012
@@ -0,0 +1,368 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+  <title>LLVMBuild Documentation</title>
+  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>LLVMBuild Guide</h1>
+
+<ol>
+  <li><a href="#introduction">Introduction</a></li>
+  <li><a href="#projectorg">Project Organization</a></li>
+  <li><a href="#buildintegration">Build Integration</a></li>
+  <li><a href="#componentoverview">Component Overview</a></li>
+  <li><a href="#formatreference">Format Reference</a></li>
+</ol>
+
+<!-- *********************************************************************** -->
+<h2><a name="introduction">Introduction</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+  <p>This document describes the <tt>LLVMBuild</tt> organization and files which
+  we use to describe parts of the LLVM ecosystem. For description of specific
+  LLVMBuild related tools, please see the command guide.</p>
+
+  <p>LLVM is designed to be a modular set of libraries which can be flexibly
+  mixed together in order to build a variety of tools, like compilers, JITs,
+  custom code generators, optimization passes, interpreters, and so on. Related
+  projects in the LLVM system like Clang and LLDB also tend to follow this
+  philosophy.</p>
+
+  <p>In order to support this usage style, LLVM has a fairly strict structure as
+  to how the source code and various components are organized. The
+  <tt>LLVMBuild.txt</tt> files are the explicit specification of that structure,
+  and are used by the build systems and other tools in order to develop the LLVM
+  project.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="projectorg">Project Organization</a></h2>
+<!-- *********************************************************************** -->
+
+<!-- FIXME: We should probably have an explicit top level project object. Good
+place to hang project level data, name, etc. Also useful for serving as the
+$ROOT of project trees for things which can be checked out separately. -->
+
+<div>
+  <p>The source code for LLVM projects using the LLVMBuild system (LLVM, Clang,
+  and LLDB) is organized into <em>components</em>, which define the separate
+  pieces of functionality that make up the project. These projects may consist
+  of many libraries, associated tools, build tools, or other utility tools (for
+  example, testing tools).</p>
+
+  <p>For the most part, the project contents are organized around defining one
+  main component per each subdirectory. Each such directory contains
+  an <tt>LLVMBuild.txt</tt> which contains the component definitions.</p>
+
+  <p>The component descriptions for the project as a whole are automatically
+  gathered by the LLVMBuild tools. The tools automatically traverse the source
+  directory structure to find all of the component description files. NOTE: For
+  performance/sanity reasons, we only traverse into subdirectories when the
+  parent itself contains an <tt>LLVMBuild.txt</tt> description file.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="buildintegration">Build Integration</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+  <p>The LLVMBuild files themselves are just a declarative way to describe the
+  project structure. The actual building of the LLVM project is handled by
+  another build system (currently we support
+  both <a href="MakefileGuide.html">Makefiles</a>
+  and <a href="CMake.html">CMake</a>.</p>
+
+  <p>The build system implementation will load the relevant contents of the
+  LLVMBuild files and use that to drive the actual project build. Typically, the
+  build system will only need to load this information at "configure" time, and
+  use it to generative native information. Build systems will also handle
+  automatically reconfiguring their information when the contents of
+  the <i>LLVMBuild.txt</i> files change.</p>
+
+  <p>Developers generally are not expected to need to be aware of the details of
+  how the LLVMBuild system is integrated into their build. Ideally, LLVM
+  developers who are not working on the build system would only ever need to
+  modify the contents of the <i>LLVMBuild.txt</i> description files (although we
+  have not reached this goal yet).</p>
+
+  <p>For more information on the utility tool we provide to help interfacing
+  with the build system, please see
+  the <a href="CommandGuide/html/llvm-build.html">llvm-build</a>
+  documentation.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="componentoverview">Component Overview</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+  <p>As mentioned earlier, LLVM projects are organized into
+  logical <em>components</em>. Every component is typically grouped into its
+  own subdirectory. Generally, a component is organized around a coherent group
+  of sources which have some kind of clear API separation from other parts of
+  the code.</p>
+
+  <p>LLVM primarily uses the following types of components:</p>
+  <ul>
+    <li><em>Libraries</em> - Library components define a distinct API which can
+    be independently linked into LLVM client applications. Libraries typically
+    have private and public header files, and may specify a link of required
+    libraries that they build on top of.</li>
+
+    <li><em>Build Tools</em> - Build tools are applications which are designed
+    to be run as part of the build process (typically to generate other source
+    files). Currently, LLVM uses one main build tool
+    called <a href="TableGenFundamentals.html">TableGen</a> to generate a
+    variety of source files.</li>
+
+    <li><em>Tools</em> - Command line applications which are built using the
+    LLVM component libraries. Most LLVM tools are small and are primarily
+    frontends to the library interfaces.</li>
+
+<!-- FIXME: We also need shared libraries as a first class component, but this
+     is not yet implemented. -->
+  </ul>
+
+  <p>Components are described using <em>LLVMBuild.txt</em> files in the
+  directories that define the component. See
+  the <a href="#formatreference">Format Reference</a> section for information on
+  the exact format of these files.</p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="formatreference">LLVMBuild Format Reference</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+  <p>LLVMBuild files are written in a simple variant of the INI or configuration
+  file format (<a href="http://en.wikipedia.org/wiki/INI_file">Wikipedia
+  entry</a>). The format defines a list of sections each of which may contain
+  some number of properties. A simple example of the file format is below:</p>
+  <div class="doc_code">
+  <pre>
+<i>; Comments start with a semi-colon.</i>
+
+<i>; Sections are declared using square brackets.</i>
+[component_0]
+
+<i>; Properties are declared using '=' and are contained in the previous section.
+;
+; We support simple string and boolean scalar values and list values, where
+; items are separated by spaces. There is no support for quoting, and so
+; property values may not contain spaces.</i>
+property_name = property_value
+list_property_name = value_1 value_2 <em>...</em> value_n
+boolean_property_name = 1 <em>(or 0)</em>
+</pre>
+  </div>
+
+  <p>LLVMBuild files are expected to define a strict set of sections and
+  properties. An typical component description file for a library
+  component would look typically look like the following example:</p>
+  <div class="doc_code">
+  <pre>
+[component_0]
+type = Library
+name = Linker
+parent = Libraries
+required_libraries = Archive BitReader Core Support TransformUtils
+</pre>
+  </div>
+
+  <p>A full description of the exact sections and properties which are allowed
+ follows.</p>
+
+  <p>Each file may define exactly one common component, named "common". The
+  common component may define the following properties:</p>
+  <ul>
+    <li><i>subdirectories</i> <b>[optional]</b>
+      <p>If given, a list of the names of the subdirectories from the current
+        subpath to search for additional LLVMBuild files.</p></li>
+  </ul>
+
+  <p>Each file may define multiple components. Each component is described by a
+  section who name starts with "component". The remainder of the section name is
+  ignored, but each section name must be unique. Typically components are just
+  number in order for files with multiple components ("component_0",
+  "component_1", and so on).<p>
+
+  <p><b>Section names not matching this format (or the "common" section) are
+  currently unused and are disallowed.</b></p>
+
+  <p>Every component is defined by the properties in the section. The exact list
+  of properties that are allowed depends on the component
+  type. Components <b>may not</b> define any properties other than those
+  expected by the component type.</p>
+
+  <p>Every component must define the following properties:</p>
+  <ul>
+    <li><i>type</i> <b>[required]</b>
+      <p>The type of the component. Supported component types are
+      detailed below. Most components will define additional properties which
+      may be required or optional.</p></li>
+
+    <li><i>name</i> <b>[required]</b>
+      <p>The name of the component. Names are required to be unique
+      across the entire project.</p></li>
+
+    <li><i>parent</i> <b>[required]</b>
+      <p>The name of the logical parent of the component. Components are
+      organized into a logical tree to make it easier to navigate and organize
+      groups of components. The parents have no semantics as far as the project
+      build is concerned, however. Typically, the parent will be the main
+      component of the parent directory.</p>
+
+      <!-- FIXME: Should we make the parent optional, and default to parent
+      directories component? -->
+
+      <p>Components may reference the root pseudo component using '$ROOT' to
+      indicate they should logically be grouped at the top-level.</p>
+    </li>
+  </ul>
+
+  <p>Components may define the following properties:</p>
+  <ul>
+    <li><i>dependencies</i> <b>[optional]</b>
+      <p>If specified, a list of names of components which <i>must</i> be built
+      prior to this one. This should only be exactly those components which
+      produce some tool or source code required for building the
+      component.</p>
+
+      <p><em>NOTE:</em> Group and LibraryGroup components have no semantics for
+      the actual build, and are not allowed to specify dependencies.</p></li>
+  </ul>
+
+  <p>The following section lists the available component types, as well as the
+  properties which are associated with that component.</p>
+
+  <ul>
+    <li><i>type = Group</i>
+      <p>Group components exist purely to allow additional arbitrary structuring
+      of the logical components tree. For example, one might define a
+      "Libraries" group to hold all of the root library components.</p>
+
+      <p>Group components have no additionally properties.</p>
+    </li>
+
+    <li><i>type = Library</i>
+      <p>Library components define an individual library which should be built
+      from the source code in the component directory.</p>
+
+      <p>Components with this type use the following properties:</p>
+      <ul>
+        <li><i>library_name</i> <b>[optional]</b>
+          <p>If given, the name to use for the actual library file on disk. If
+          not given, the name is derived from the component name
+          itself.</p></li>
+
+        <li><i>required_libraries</i> <b>[optional]</b>
+          <p>If given, a list of the names of Library or LibraryGroup components
+          which must also be linked in whenever this library is used. That is,
+          the link time dependencies for this component. When tools are built,
+          the build system will include the transitive closure of
+          all <i>required_libraries</i> for the components the tool needs.</p></li>
+
+        <li><i>add_to_library_groups</i> <b>[optional]</b>
+          <p>If given, a list of the names of LibraryGroup components which this
+          component is also part of. This allows nesting groups of
+          components. For example, the <i>X86</i> target might define a library
+          group for all of the <i>X86</i> components. That library group might
+          then be included in the <i>all-targets</i> library group.</p></li>
+
+        <li><i>installed</i> <b>[optional]</b> <b>[boolean]</b>
+          <p>Whether this library is installed. Libraries that are not installed
+          are only reported by <tt>llvm-config</tt> when it is run as part of a
+          development directory.</p></li>
+      </ul>
+    </li>
+
+    <li><i>type = LibraryGroup</i>
+      <p>LibraryGroup components are a mechanism to allow easy definition of
+      useful sets of related components. In particular, we use them to easily
+      specify things like "all targets", or "all assembly printers".</p>
+
+      <p>Components with this type use the following properties:</p>
+      <ul>
+        <li><i>required_libraries</i> <b>[optional]</b>
+          <p>See the Library type for a description of this property.</p></li>
+
+        <li><i>add_to_library_groups</i> <b>[optional]</b>
+          <p>See the Library type for a description of this property.</p></li>
+      </ul>
+    </li>
+
+    <li><i>type = TargetGroup</i>
+      <p>TargetGroup components are an extension of LibraryGroups, specifically
+      for defining LLVM targets (which are handled specially in a few
+      places).</p>
+
+      <p>The name of the component should always be the name of the target.</p>
+
+      <p>Components with this type use the LibraryGroup properties in addition
+      to:</p>
+      <ul>
+        <li><i>has_asmparser</i> <b>[optional]</b> <b>[boolean]</b>
+          <p>Whether this target defines an assembly parser.</p></li>
+        <li><i>has_asmprinter</i> <b>[optional]</b> <b>[boolean]</b>
+          <p>Whether this target defines an assembly printer.</p></li>
+        <li><i>has_disassembler</i> <b>[optional]</b> <b>[boolean]</b>
+          <p>Whether this target defines a disassembler.</p></li>
+        <li><i>has_jit</i> <b>[optional]</b> <b>[boolean]</b>
+          <p>Whether this target supports JIT compilation.</p></li>
+      </ul>
+    </li>
+
+    <li><i>type = Tool</i>
+      <p>Tool components define standalone command line tools which should be
+      built from the source code in the component directory and linked.</p>
+
+      <p>Components with this type use the following properties:</p>
+      <ul>
+        <li><i>required_libraries</i> <b>[optional]</b>
+
+          <p>If given, a list of the names of Library or LibraryGroup components
+          which this tool is required to be linked with. <b>NOTE:</b> The values
+          should be the component names, which may not always match up with the
+          actual library names on disk.</p>
+
+          <p>Build systems are expected to properly include all of the libraries
+          required by the linked components (i.e., the transitive closer
+          of <em>required_libraries</em>).</p>
+
+          <p>Build systems are also expected to understand that those library
+          components must be built prior to linking -- they do not also need to
+          be listed under <i>dependencies</i>.</p></li>
+      </ul>
+    </li>
+
+    <li><i>type = BuildTool</i>
+      <p>BuildTool components are like Tool components, except that the tool is
+      supposed to be built for the platform where the build is running (instead
+      of that platform being targetted). Build systems are expected to handle
+      the fact that required libraries may need to be built for multiple
+      platforms in order to be able to link this tool.</p>
+
+      <p>BuildTool components currently use the exact same properties as Tool
+      components, the type distinction is only used to differentiate what the
+      tool is built for.</p>
+    </li>
+  </ul>
+</div>
+
+<!-- *********************************************************************** -->
+<hr>
+<address>
+  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+  <a href="http://validator.w3.org/check/referer"><img
+  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+  <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+  Last modified: $Date$
+</address>
+</body>
+</html>

Added: www-releases/trunk/3.2/docs/LLVMBuild.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/LLVMBuild.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/LLVMBuild.txt (added)
+++ www-releases/trunk/3.2/docs/LLVMBuild.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,21 @@
+;===- ./docs/LLVMBuild.txt -------------------------------------*- Conf -*--===;
+;
+;                     The LLVM Compiler Infrastructure
+;
+; This file is distributed under the University of Illinois Open Source
+; License. See LICENSE.TXT for details.
+;
+;===------------------------------------------------------------------------===;
+;
+; This is an LLVMBuild description file for the components in this subdirectory.
+;
+; For more information on the LLVMBuild system, please see:
+;
+;   http://llvm.org/docs/LLVMBuild.html
+;
+;===------------------------------------------------------------------------===;
+
+[component_0]
+type = Group
+name = Docs
+parent = $ROOT

Added: www-releases/trunk/3.2/docs/LangRef.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/LangRef.html?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/LangRef.html (added)
+++ www-releases/trunk/3.2/docs/LangRef.html Fri Dec 21 00:57:24 2012
@@ -0,0 +1,8776 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                      "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+  <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"
+  content="LLVM Assembly Language Reference Manual.">
+  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
+</head>
+
+<body>
+
+<h1>LLVM Language Reference Manual</h1>
+<ol>
+  <li><a href="#abstract">Abstract</a></li>
+  <li><a href="#introduction">Introduction</a></li>
+  <li><a href="#identifiers">Identifiers</a></li>
+  <li><a href="#highlevel">High Level Structure</a>
+    <ol>
+      <li><a href="#modulestructure">Module Structure</a></li>
+      <li><a href="#linkage">Linkage Types</a>
+        <ol>
+          <li><a href="#linkage_private">'<tt>private</tt>' Linkage</a></li>
+          <li><a href="#linkage_linker_private">'<tt>linker_private</tt>' Linkage</a></li>
+          <li><a href="#linkage_linker_private_weak">'<tt>linker_private_weak</tt>' Linkage</a></li>
+          <li><a href="#linkage_internal">'<tt>internal</tt>' Linkage</a></li>
+          <li><a href="#linkage_available_externally">'<tt>available_externally</tt>' Linkage</a></li>
+          <li><a href="#linkage_linkonce">'<tt>linkonce</tt>' Linkage</a></li>
+          <li><a href="#linkage_common">'<tt>common</tt>' Linkage</a></li>
+          <li><a href="#linkage_weak">'<tt>weak</tt>' Linkage</a></li>
+          <li><a href="#linkage_appending">'<tt>appending</tt>' Linkage</a></li>
+          <li><a href="#linkage_externweak">'<tt>extern_weak</tt>' Linkage</a></li>
+          <li><a href="#linkage_linkonce_odr">'<tt>linkonce_odr</tt>' Linkage</a></li>
+          <li><a href="#linkage_linkonce_odr_auto_hide">'<tt>linkonce_odr_auto_hide</tt>' Linkage</a></li>
+          <li><a href="#linkage_weak">'<tt>weak_odr</tt>' Linkage</a></li>
+          <li><a href="#linkage_external">'<tt>external</tt>' Linkage</a></li>
+          <li><a href="#linkage_dllimport">'<tt>dllimport</tt>' Linkage</a></li>
+          <li><a href="#linkage_dllexport">'<tt>dllexport</tt>' Linkage</a></li>
+        </ol>
+      </li>
+      <li><a href="#callingconv">Calling Conventions</a></li>
+      <li><a href="#namedtypes">Named Types</a></li>
+      <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>
+      <li><a href="#moduleasm">Module-Level Inline Assembly</a></li>
+      <li><a href="#datalayout">Data Layout</a></li>
+      <li><a href="#pointeraliasing">Pointer Aliasing Rules</a></li>
+      <li><a href="#volatile">Volatile Memory Accesses</a></li>
+      <li><a href="#memmodel">Memory Model for Concurrent Operations</a></li>
+      <li><a href="#ordering">Atomic Memory Ordering Constraints</a></li>
+    </ol>
+  </li>
+  <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>
+        <ol>
+          <li><a href="#t_integer">Integer Type</a></li>
+          <li><a href="#t_floating">Floating Point Types</a></li>
+          <li><a href="#t_x86mmx">X86mmx Type</a></li>
+          <li><a href="#t_void">Void Type</a></li>
+          <li><a href="#t_label">Label Type</a></li>
+          <li><a href="#t_metadata">Metadata Type</a></li>
+        </ol>
+      </li>
+      <li><a href="#t_derived">Derived Types</a>
+        <ol>
+          <li><a href="#t_aggregate">Aggregate Types</a>
+            <ol>
+              <li><a href="#t_array">Array Type</a></li>
+              <li><a href="#t_struct">Structure Type</a></li>
+              <li><a href="#t_opaque">Opaque Structure Types</a></li>
+              <li><a href="#t_vector">Vector Type</a></li>
+            </ol>
+          </li>
+          <li><a href="#t_function">Function Type</a></li>
+          <li><a href="#t_pointer">Pointer Type</a></li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li><a href="#constants">Constants</a>
+    <ol>
+      <li><a href="#simpleconstants">Simple Constants</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="#poisonvalues">Poison Values</a></li>
+      <li><a href="#blockaddress">Addresses of Basic Blocks</a></li>
+      <li><a href="#constantexprs">Constant Expressions</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>
+        <ol>
+          <li><a href="#tbaa">'<tt>tbaa</tt>' Metadata</a></li>
+          <li><a href="#tbaa.struct">'<tt>tbaa.struct</tt>' Metadata</a></li>
+          <li><a href="#fpmath">'<tt>fpmath</tt>' Metadata</a></li>
+          <li><a href="#range">'<tt>range</tt>' Metadata</a></li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li><a href="#module_flags">Module Flags Metadata</a>
+    <ol>
+      <li><a href="#objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a></li>
+    </ol>
+  </li>
+  <li><a href="#intrinsic_globals">Intrinsic Global Variables</a>
+    <ol>
+      <li><a href="#intg_used">The '<tt>llvm.used</tt>' Global Variable</a></li>
+      <li><a href="#intg_compiler_used">The '<tt>llvm.compiler.used</tt>'
+          Global Variable</a></li>
+      <li><a href="#intg_global_ctors">The '<tt>llvm.global_ctors</tt>'
+         Global Variable</a></li>
+      <li><a href="#intg_global_dtors">The '<tt>llvm.global_dtors</tt>'
+         Global Variable</a></li>
+    </ol>
+  </li>
+  <li><a href="#instref">Instruction Reference</a>
+    <ol>
+      <li><a href="#terminators">Terminator Instructions</a>
+        <ol>
+          <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_resume">'<tt>resume</tt>'  Instruction</a></li>
+          <li><a href="#i_unreachable">'<tt>unreachable</tt>' Instruction</a></li>
+        </ol>
+      </li>
+      <li><a href="#binaryops">Binary Operations</a>
+        <ol>
+          <li><a href="#i_add">'<tt>add</tt>' Instruction</a></li>
+          <li><a href="#i_fadd">'<tt>fadd</tt>' Instruction</a></li>
+          <li><a href="#i_sub">'<tt>sub</tt>' Instruction</a></li>
+          <li><a href="#i_fsub">'<tt>fsub</tt>' Instruction</a></li>
+          <li><a href="#i_mul">'<tt>mul</tt>' Instruction</a></li>
+          <li><a href="#i_fmul">'<tt>fmul</tt>' Instruction</a></li>
+          <li><a href="#i_udiv">'<tt>udiv</tt>' Instruction</a></li>
+          <li><a href="#i_sdiv">'<tt>sdiv</tt>' Instruction</a></li>
+          <li><a href="#i_fdiv">'<tt>fdiv</tt>' Instruction</a></li>
+          <li><a href="#i_urem">'<tt>urem</tt>' Instruction</a></li>
+          <li><a href="#i_srem">'<tt>srem</tt>' Instruction</a></li>
+          <li><a href="#i_frem">'<tt>frem</tt>' Instruction</a></li>
+        </ol>
+      </li>
+      <li><a href="#bitwiseops">Bitwise Binary Operations</a>
+        <ol>
+          <li><a href="#i_shl">'<tt>shl</tt>' Instruction</a></li>
+          <li><a href="#i_lshr">'<tt>lshr</tt>' Instruction</a></li>
+          <li><a href="#i_ashr">'<tt>ashr</tt>' Instruction</a></li>
+          <li><a href="#i_and">'<tt>and</tt>' Instruction</a></li>
+          <li><a href="#i_or">'<tt>or</tt>'  Instruction</a></li>
+          <li><a href="#i_xor">'<tt>xor</tt>' Instruction</a></li>
+        </ol>
+      </li>
+      <li><a href="#vectorops">Vector Operations</a>
+        <ol>
+          <li><a href="#i_extractelement">'<tt>extractelement</tt>' Instruction</a></li>
+          <li><a href="#i_insertelement">'<tt>insertelement</tt>' Instruction</a></li>
+          <li><a href="#i_shufflevector">'<tt>shufflevector</tt>' Instruction</a></li>
+        </ol>
+      </li>
+      <li><a href="#aggregateops">Aggregate Operations</a>
+        <ol>
+          <li><a href="#i_extractvalue">'<tt>extractvalue</tt>' Instruction</a></li>
+          <li><a href="#i_insertvalue">'<tt>insertvalue</tt>' Instruction</a></li>
+        </ol>
+      </li>
+      <li><a href="#memoryops">Memory Access and Addressing Operations</a>
+        <ol>
+          <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="#i_fence">'<tt>fence</tt>' Instruction</a></li>
+         <li><a href="#i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a></li>
+         <li><a href="#i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a></li>
+         <li><a href="#i_getelementptr">'<tt>getelementptr</tt>' Instruction</a></li>
+        </ol>
+      </li>
+      <li><a href="#convertops">Conversion Operations</a>
+        <ol>
+          <li><a href="#i_trunc">'<tt>trunc .. to</tt>' Instruction</a></li>
+          <li><a href="#i_zext">'<tt>zext .. to</tt>' Instruction</a></li>
+          <li><a href="#i_sext">'<tt>sext .. to</tt>' Instruction</a></li>
+          <li><a href="#i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a></li>
+          <li><a href="#i_fpext">'<tt>fpext .. to</tt>' Instruction</a></li>
+          <li><a href="#i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a></li>
+          <li><a href="#i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a></li>
+          <li><a href="#i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a></li>
+          <li><a href="#i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a></li>
+          <li><a href="#i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a></li>
+          <li><a href="#i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a></li>
+          <li><a href="#i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a></li>
+        </ol>
+      </li>
+      <li><a href="#otherops">Other Operations</a>
+        <ol>
+          <li><a href="#i_icmp">'<tt>icmp</tt>' Instruction</a></li>
+          <li><a href="#i_fcmp">'<tt>fcmp</tt>' Instruction</a></li>
+          <li><a href="#i_phi">'<tt>phi</tt>'   Instruction</a></li>
+          <li><a href="#i_select">'<tt>select</tt>' Instruction</a></li>
+          <li><a href="#i_call">'<tt>call</tt>'  Instruction</a></li>
+          <li><a href="#i_va_arg">'<tt>va_arg</tt>'  Instruction</a></li>
+          <li><a href="#i_landingpad">'<tt>landingpad</tt>' Instruction</a></li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li><a href="#intrinsics">Intrinsic Functions</a>
+    <ol>
+      <li><a href="#int_varargs">Variable Argument Handling Intrinsics</a>
+        <ol>
+          <li><a href="#int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a></li>
+          <li><a href="#int_va_end">'<tt>llvm.va_end</tt>'   Intrinsic</a></li>
+          <li><a href="#int_va_copy">'<tt>llvm.va_copy</tt>'  Intrinsic</a></li>
+        </ol>
+      </li>
+      <li><a href="#int_gc">Accurate Garbage Collection Intrinsics</a>
+        <ol>
+          <li><a href="#int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a></li>
+          <li><a href="#int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a></li>
+          <li><a href="#int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a></li>
+        </ol>
+      </li>
+      <li><a href="#int_codegen">Code Generator Intrinsics</a>
+        <ol>
+          <li><a href="#int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a></li>
+          <li><a href="#int_frameaddress">'<tt>llvm.frameaddress</tt>'   Intrinsic</a></li>
+          <li><a href="#int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a></li>
+          <li><a href="#int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a></li>
+          <li><a href="#int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a></li>
+          <li><a href="#int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a></li>
+          <li><a href="#int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a></li>
+        </ol>
+      </li>
+      <li><a href="#int_libc">Standard C Library Intrinsics</a>
+        <ol>
+          <li><a href="#int_memcpy">'<tt>llvm.memcpy.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_memmove">'<tt>llvm.memmove.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_memset">'<tt>llvm.memset.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_log">'<tt>llvm.log.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_fabs">'<tt>llvm.fabs.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_floor">'<tt>llvm.floor.*</tt>' Intrinsic</a></li>
+        </ol>
+      </li>
+      <li><a href="#int_manip">Bit Manipulation Intrinsics</a>
+        <ol>
+          <li><a href="#int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a></li>
+          <li><a href="#int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic </a></li>
+          <li><a href="#int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic </a></li>
+          <li><a href="#int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic </a></li>
+        </ol>
+      </li>
+      <li><a href="#int_overflow">Arithmetic with Overflow Intrinsics</a>
+        <ol>
+          <li><a href="#int_sadd_overflow">'<tt>llvm.sadd.with.overflow.*</tt> Intrinsics</a></li>
+          <li><a href="#int_uadd_overflow">'<tt>llvm.uadd.with.overflow.*</tt> Intrinsics</a></li>
+          <li><a href="#int_ssub_overflow">'<tt>llvm.ssub.with.overflow.*</tt> Intrinsics</a></li>
+          <li><a href="#int_usub_overflow">'<tt>llvm.usub.with.overflow.*</tt> Intrinsics</a></li>
+          <li><a href="#int_smul_overflow">'<tt>llvm.smul.with.overflow.*</tt> Intrinsics</a></li>
+          <li><a href="#int_umul_overflow">'<tt>llvm.umul.with.overflow.*</tt> Intrinsics</a></li>
+        </ol>
+      </li>
+      <li><a href="#spec_arithmetic">Specialised Arithmetic Intrinsics</a>
+        <ol>
+          <li><a href="#fmuladd">'<tt>llvm.fmuladd</tt> Intrinsic</a></li>
+        </ol>
+      </li>
+      <li><a href="#int_fp16">Half Precision Floating Point Intrinsics</a>
+        <ol>
+          <li><a href="#int_convert_to_fp16">'<tt>llvm.convert.to.fp16</tt>' Intrinsic</a></li>
+          <li><a href="#int_convert_from_fp16">'<tt>llvm.convert.from.fp16</tt>' Intrinsic</a></li>
+        </ol>
+      </li>
+      <li><a href="#int_debugger">Debugger intrinsics</a></li>
+      <li><a href="#int_eh">Exception Handling intrinsics</a></li>
+      <li><a href="#int_trampoline">Trampoline Intrinsics</a>
+        <ol>
+          <li><a href="#int_it">'<tt>llvm.init.trampoline</tt>' Intrinsic</a></li>
+          <li><a href="#int_at">'<tt>llvm.adjust.trampoline</tt>' Intrinsic</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>' Intrinsic</a></li>
+          <li><a href="#int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a></li>
+          <li><a href="#int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a></li>
+          <li><a href="#int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a></li>
+        </ol>
+      </li>
+      <li><a href="#int_general">General intrinsics</a>
+        <ol>
+          <li><a href="#int_var_annotation">
+            '<tt>llvm.var.annotation</tt>' Intrinsic</a></li>
+          <li><a href="#int_annotation">
+            '<tt>llvm.annotation.*</tt>' Intrinsic</a></li>
+          <li><a href="#int_trap">
+            '<tt>llvm.trap</tt>' Intrinsic</a></li>
+          <li><a href="#int_debugtrap">
+            '<tt>llvm.debugtrap</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>
+          <li><a href="#int_expect">
+            '<tt>llvm.expect</tt>' Intrinsic</a></li>
+          <li><a href="#int_donothing">
+            '<tt>llvm.donothing</tt>' Intrinsic</a></li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+</ol>
+
+<div class="doc_author">
+  <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a>
+            and <a href="mailto:vadve at cs.uiuc.edu">Vikram Adve</a></p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="abstract">Abstract</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This document is a reference manual for the LLVM assembly language. LLVM is
+   a Static Single Assignment (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.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="introduction">Introduction</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>The LLVM code representation is designed to be used in three different forms:
+   as an in-memory compiler IR, as an on-disk bitcode 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>
+
+<p>The LLVM representation aims to be light-weight and low-level while being
+   expressive, typed, and extensible at the same time.  It aims to be a
+   "universal IR" of sorts, by being at a low enough level that high-level ideas
+   may be cleanly mapped to it (similar to how microprocessors are "universal
+   IR's", allowing many source languages to be mapped to them).  By providing
+   type information, LLVM can be used as the target of optimizations: for
+   example, through pointer analysis, it can be proven that a C automatic
+   variable is never accessed outside of the current function, allowing it to
+   be promoted to a simple SSA value instead of a memory location.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="wellformed">Well-Formedness</a>
+</h4>
+
+<div>
+
+<p>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>
+
+<pre class="doc_code">
+%x = <a href="#i_add">add</a> i32 1, %x
+</pre>
+
+<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>
+
+<!-- Describe the typesetting conventions here. -->
+
+<!-- *********************************************************************** -->
+<h2><a name="identifiers">Identifiers</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>LLVM identifiers come in two basic types: global and local. Global
+   identifiers (functions, global variables) begin with the <tt>'@'</tt>
+   character. Local identifiers (register names, types) begin with
+   the <tt>'%'</tt> character. Additionally, there are three different formats
+   for identifiers, for different purposes:</p>
+
+<ol>
+  <li>Named values are represented as a string of characters with their prefix.
+      For example, <tt>%foo</tt>, <tt>@DivisionByZero</tt>,
+      <tt>%a.really.long.identifier</tt>. 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. Special
+      characters may be escaped using <tt>"\xx"</tt> where <tt>xx</tt> is the
+      ASCII code for the character in hexadecimal.  In this way, any character
+      can be used in a name value, even quotes themselves.</li>
+
+  <li>Unnamed values are represented as an unsigned numeric value with their
+      prefix.  For example, <tt>%12</tt>, <tt>@2</tt>, <tt>%44</tt>.</li>
+
+  <li>Constants, which are described in a <a href="#constants">section about
+      constants</a>, below.</li>
+</ol>
+
+<p>LLVM requires that values start with a prefix for two reasons: Compilers
+   don't need to worry about name clashes with reserved words, and the set of
+   reserved words may be expanded in the future without penalty.  Additionally,
+   unnamed identifiers allow a compiler to quickly come up with a temporary
+   variable without having to avoid symbol table conflicts.</p>
+
+<p>Reserved words in LLVM are very similar to reserved words in other
+   languages. There are keywords for different opcodes
+   ('<tt><a href="#i_add">add</a></tt>',
+   '<tt><a href="#i_bitcast">bitcast</a></tt>',
+   '<tt><a href="#i_ret">ret</a></tt>', etc...), for primitive type names
+   ('<tt><a href="#t_void">void</a></tt>',
+   '<tt><a href="#t_primitive">i32</a></tt>', etc...), and others.  These
+   reserved words cannot conflict with variable names, because none of them
+   start with a prefix character (<tt>'%'</tt> or <tt>'@'</tt>).</p>
+
+<p>Here is an example of LLVM code to multiply the integer variable
+   '<tt>%X</tt>' by 8:</p>
+
+<p>The easy way:</p>
+
+<pre class="doc_code">
+%result = <a href="#i_mul">mul</a> i32 %X, 8
+</pre>
+
+<p>After strength reduction:</p>
+
+<pre class="doc_code">
+%result = <a href="#i_shl">shl</a> i32 %X, i8 3
+</pre>
+
+<p>And the hard way:</p>
+
+<pre class="doc_code">
+%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>
+
+<p>This last way of multiplying <tt>%X</tt> by 8 illustrates several important
+   lexical features of LLVM:</p>
+
+<ol>
+  <li>Comments are delimited with a '<tt>;</tt>' and go until the end of
+      line.</li>
+
+  <li>Unnamed temporaries are created when the result of a computation is not
+      assigned to a named value.</li>
+
+  <li>Unnamed temporaries are numbered sequentially</li>
+</ol>
+
+<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>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="highlevel">High Level Structure</a></h2>
+<!-- *********************************************************************** -->
+<div>
+<!-- ======================================================================= -->
+<h3>
+  <a name="modulestructure">Module Structure</a>
+</h3>
+
+<div>
+
+<p>LLVM programs are composed of <tt>Module</tt>s, each of which is a
+   translation unit of the input programs.  Each module consists of functions,
+   global variables, and symbol table entries.  Modules may be combined together
+   with the LLVM linker, which merges function (and global variable)
+   definitions, resolves forward declarations, and merges symbol table
+   entries. Here is an example of the "hello world" module:</p>
+
+<pre class="doc_code">
+<i>; Declare the string constant as a global constant.</i> 
+<a href="#identifiers">@.str</a> = <a href="#linkage_private">private</a> <a href="#globalvars">unnamed_addr</a> <a href="#globalvars">constant</a> <a href="#t_array">[13 x i8]</a> c"hello world\0A\00" 
+
+<i>; External declaration of the puts function</i> 
+<a href="#functionstructure">declare</a> i32 @puts(i8* <a href="#nocapture">nocapture</a>) <a href="#fnattrs">nounwind</a> 
+
+<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]* @.str, i64 0, i64 0
+
+  <i>; Call puts function to write out the string to stdout.</i> 
+  <a href="#i_call">call</a> i32 @puts(i8* %cast210)
+  <a href="#i_ret">ret</a> i32 0 
+}
+
+<i>; Named metadata</i>
+!1 = metadata !{i32 42}
+!foo = !{!1, null}
+</pre>
+
+<p>This example is made up of a <a href="#globalvars">global variable</a> named
+   "<tt>.str</tt>", an external declaration of the "<tt>puts</tt>" function,
+   a <a href="#functionstructure">function definition</a> for
+   "<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
+   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 have one of the
+   following <a href="#linkage">linkage types</a>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="linkage">Linkage Types</a>
+</h3>
+
+<div>
+
+<p>All Global Variables and Functions have one of the following types of
+   linkage:</p>
+
+<dl>
+  <dt><tt><b><a name="linkage_private">private</a></b></tt></dt>
+  <dd>Global values with "<tt>private</tt>" 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 avoid collisions.  Because the symbol is private to the
+      module, all 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>
+  <dd>Similar to <tt>private</tt>, but the symbol is passed through the
+      assembler and evaluated by the linker. Unlike 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_linker_private_weak">linker_private_weak</a></b></tt></dt>
+  <dd>Similar to "<tt>linker_private</tt>", but the symbol is weak. Note that
+      <tt>linker_private_weak</tt> symbols are subject to coalescing by the
+      linker. The symbols 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>
+  <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>
+  <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
+      the definition of the global, which is known to be somewhere outside the
+      module.  Globals with <tt>available_externally</tt> linkage are allowed to
+      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>
+  <dd>Globals with "<tt>linkonce</tt>" linkage are merged with other globals of
+      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>
+  <dd>"<tt>common</tt>" linkage is most similar to "<tt>weak</tt>" linkage, but
+      they are used for tentative definitions in C, such as "<tt>int X;</tt>" at
+      global scope.
+      Symbols with "<tt>common</tt>" linkage are merged in the same way as
+      <tt>weak symbols</tt>, and they may not be deleted if unreferenced.
+      <tt>common</tt> symbols may not have an explicit section,
+      must have a zero initializer, and may not be marked '<a
+      href="#globalvars"><tt>constant</tt></a>'.  Functions and aliases may not
+      have common linkage.</dd>
+
+
+  <dt><tt><b><a name="linkage_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>
+  <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_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"
+      — "ODR").  Such languages can use the <tt>linkonce_odr</tt>
+      and <tt>weak_odr</tt> linkage types to indicate that the global will only
+      be merged with equivalent globals.  These linkage types are otherwise the
+      same as their non-<tt>odr</tt> versions.</dd>
+
+  <dt><tt><b><a name="linkage_linkonce_odr_auto_hide">linkonce_odr_auto_hide</a></b></tt></dt>
+  <dd>Similar to "<tt>linkonce_odr</tt>", but nothing in the translation unit
+      takes the address of this definition. For instance, functions that had an
+      inline definition, but the compiler decided not to inline it.
+      <tt>linkonce_odr_auto_hide</tt> may have only <tt>default</tt> visibility.
+      The symbols are removed by the linker from the final linked image
+      (executable or dynamic library).</dd>
+
+  <dt><tt><b><a name="linkage_external">external</a></b></tt></dt>
+  <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.</dd>
+</dl>
+
+<p>The next two types of linkage are targeted for Microsoft Windows platform
+   only. They are designed to support importing (exporting) symbols from (to)
+   DLLs (Dynamic Link Libraries).</p>
+
+<dl>
+  <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>
+  <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
+      name is formed by combining <code>__imp_</code> and the function or
+      variable name.</dd>
+</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 any linkage
+   declarations), they are accessible outside of the current module.</p>
+
+<p>It is illegal for a function <i>declaration</i> to have any linkage type
+   other than <tt>external</tt>, <tt>dllimport</tt>
+  or <tt>extern_weak</tt>.</p>
+
+<p>Aliases can have only <tt>external</tt>, <tt>internal</tt>, <tt>weak</tt>
+   or <tt>weak_odr</tt> linkages.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="callingconv">Calling Conventions</a>
+</h3>
+
+<div>
+
+<p>LLVM <a href="#functionstructure">functions</a>, <a href="#i_call">calls</a>
+   and <a href="#i_invoke">invokes</a> can all have an optional calling
+   convention specified for the call.  The calling convention of any pair of
+   dynamic caller/callee must match, or the behavior of the program is
+   undefined.  The following calling conventions are supported by LLVM, and more
+   may be added in the future:</p>
+
+<dl>
+  <dt><b>"<tt>ccc</tt>" - The C calling convention</b>:</dt>
+  <dd>This calling convention (the default if no other calling convention is
+      specified) matches the target C calling conventions.  This calling
+      convention supports varargs function calls and tolerates some mismatch in
+      the declared prototype and implemented declaration of the function (as
+      does normal C).</dd>
+
+  <dt><b>"<tt>fastcc</tt>" - The fast calling convention</b>:</dt>
+  <dd>This calling convention attempts to make calls as fast as possible
+      (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).
+      <a href="CodeGenerator.html#tailcallopt">Tail calls can only be optimized
+      when this or the GHC 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>
+
+  <dt><b>"<tt>coldcc</tt>" - The cold calling convention</b>:</dt>
+  <dd>This calling convention attempts to make code in the caller as efficient
+      as possible under the assumption that the call is not commonly executed.
+      As such, these calls often preserve all registers so that the call does
+      not break any live ranges in the caller side.  This calling convention
+      does not support varargs and requires the prototype of all callees to
+      exactly match the prototype of the function definition.</dd>
+
+  <dt><b>"<tt>cc <em>10</em></tt>" - GHC convention</b>:</dt>
+  <dd>This calling convention has been implemented specifically for use by the
+      <a href="http://www.haskell.org/ghc">Glasgow Haskell Compiler (GHC)</a>.
+      It passes everything in registers, going to extremes to achieve this by
+      disabling callee save registers. This calling convention should not be
+      used lightly but only for specific situations such as an alternative to
+      the <em>register pinning</em> performance technique often used when
+      implementing functional programming languages.At the moment only X86
+      supports this convention and it has the following limitations:
+      <ul>
+        <li>On <em>X86-32</em> only supports up to 4 bit type parameters. No
+            floating point types are supported.</li>
+        <li>On <em>X86-64</em> only supports up to 10 bit type parameters and
+            6 floating point parameters.</li>
+      </ul>
+      This calling convention supports
+      <a href="CodeGenerator.html#tailcallopt">tail call optimization</a> but
+      requires both the caller and callee are using it.
+  </dd>
+
+  <dt><b>"<tt>cc <<em>n</em>></tt>" - Numbered convention</b>:</dt>
+  <dd>Any calling convention may be specified by number, allowing
+      target-specific calling conventions to be used.  Target specific calling
+      conventions start at 64.</dd>
+</dl>
+
+<p>More calling conventions can be added/defined on an as-needed basis, to
+   support Pascal conventions or any other well-known target-independent
+   convention.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="visibility">Visibility Styles</a>
+</h3>
+
+<div>
+
+<p>All Global Variables and Functions have one of the following visibility
+   styles:</p>
+
+<dl>
+  <dt><b>"<tt>default</tt>" - Default style</b>:</dt>
+  <dd>On targets that use the ELF object file format, default visibility means
+      that the declaration is visible to other modules and, in shared libraries,
+      means that the declared entity may be overridden. On Darwin, default
+      visibility means that the declaration is visible to other modules. Default
+      visibility corresponds to "external linkage" in the language.</dd>
+
+  <dt><b>"<tt>hidden</tt>" - Hidden style</b>:</dt>
+  <dd>Two declarations of an object with hidden visibility refer to the same
+      object if they are in the same shared object. Usually, hidden visibility
+      indicates that the symbol will not be placed into the dynamic symbol
+      table, so no other module (executable or shared library) can reference it
+      directly.</dd>
+
+  <dt><b>"<tt>protected</tt>" - Protected style</b>:</dt>
+  <dd>On ELF, protected visibility indicates that the symbol will be placed in
+      the dynamic symbol table, but that references within the defining module
+      will bind to the local symbol. That is, the symbol cannot be overridden by
+      another module.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="namedtypes">Named Types</a>
+</h3>
+
+<div>
+
+<p>LLVM IR allows you to specify name aliases for certain types.  This can make
+   it easier to read the IR and make the IR more condensed (particularly when
+   recursive types are involved).  An example of a name specification is:</p>
+
+<pre class="doc_code">
+%mytype = type { %mytype*, i32 }
+</pre>
+
+<p>You may give a name to any <a href="#typesystem">type</a> except
+   "<a href="#t_void">void</a>".  Type name aliases may be used anywhere a type
+   is expected with the syntax "%mytype".</p>
+
+<p>Note that type names are aliases for the structural type that they indicate,
+   and that you can therefore specify multiple names for the same type.  This
+   often leads to confusing behavior when dumping out a .ll file.  Since LLVM IR
+   uses structural typing, the name is not part of the type.  When printing out
+   LLVM IR, the printer will pick <em>one name</em> to render all types of a
+   particular shape.  This means that if you have code where two different
+   source types end up having the same LLVM type, that the dumper will sometimes
+   print the "wrong" or unexpected type.  This is an important design point and
+   isn't going to change.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="globalvars">Global Variables</a>
+</h3>
+
+<div>
+
+<p>Global variables define regions of memory allocated at compilation time
+   instead of run-time.  Global variables may optionally be initialized, may
+   have an explicit section to be placed in, and may have an optional explicit
+   alignment specified.</p>
+
+<p>A variable may be defined as <tt>thread_local</tt>, which
+   means that it will not be shared by threads (each thread will have a
+   separated copy of the variable).  Not all targets support thread-local
+   variables.  Optionally, a TLS model may be specified:</p>
+
+<dl>
+  <dt><b><tt>localdynamic</tt></b>:</dt>
+  <dd>For variables that are only used within the current shared library.</dd>
+
+  <dt><b><tt>initialexec</tt></b>:</dt>
+  <dd>For variables in modules that will not be loaded dynamically.</dd>
+
+  <dt><b><tt>localexec</tt></b>:</dt>
+  <dd>For variables defined in the executable and only used within it.</dd>
+</dl>
+
+<p>The models correspond to the ELF TLS models; see
+   <a href="http://people.redhat.com/drepper/tls.pdf">ELF
+   Handling For Thread-Local Storage</a> for more information on under which
+   circumstances the different models may be used.  The target may choose a
+   different TLS model if the specified model is not supported, or if a better
+   choice of model can be made.</p>
+
+<p>A variable may be defined as a global
+   "constant," which indicates that the contents of the variable
+   will <b>never</b> be modified (enabling better optimization, allowing the
+   global data to be placed in the read-only section of an executable, etc).
+   Note that variables that need runtime initialization cannot be marked
+   "constant" as there is a store to the variable.</p>
+
+<p>LLVM explicitly allows <em>declarations</em> of global variables to be marked
+   constant, even if the final definition of the global is not.  This capability
+   can be used to enable slightly better optimization of the program, but
+   requires the language definition to guarantee that optimizations based on the
+   'constantness' are valid for the translation units that do not include the
+   definition.</p>
+
+<p>As SSA values, global variables define pointer values that are in scope
+   (i.e. they dominate) all basic blocks in the program.  Global variables
+   always define a pointer to their "content" type because they describe a
+   region of memory, and all memory objects in LLVM are accessed through
+   pointers.</p>
+
+<p>Global variables can be marked with <tt>unnamed_addr</tt> which indicates
+  that the address is not significant, only the content. Constants marked
+  like this can be merged with other constants if they have the same
+  initializer. Note that a constant with significant address <em>can</em>
+  be merged with a <tt>unnamed_addr</tt> constant, the result being a
+  constant whose address is significant.</p>
+
+<p>A global variable may be declared to reside in a target-specific numbered
+   address space. For targets that support them, address spaces may affect how
+   optimizations are performed and/or what target instructions are used to
+   access the variable. The default address space is zero. The address space
+   qualifier must precede any other attributes.</p>
+
+<p>LLVM allows an explicit section to be specified for globals.  If the target
+   supports it, it will emit globals to the section specified.</p>
+
+<p>An explicit alignment may be specified for a global, which must be a power
+   of 2.  If not present, or if the alignment is set to zero, the alignment of
+   the global is set by the target to whatever it feels convenient.  If an
+   explicit alignment is specified, the global is forced to have exactly that
+   alignment.  Targets and optimizers are not allowed to over-align the global
+   if the global has an assigned section.  In this case, the extra alignment
+   could be observable: for example, code could assume that the globals are
+   densely packed in their section and try to iterate over them as an array,
+   alignment padding would break this iteration.</p>
+
+<p>For example, the following defines a global in a numbered address space with
+   an initializer, section, and alignment:</p>
+
+<pre class="doc_code">
+ at G = addrspace(5) constant float 1.0, section "foo", align 4
+</pre>
+
+<p>The following example defines a thread-local global with
+   the <tt>initialexec</tt> TLS model:</p>
+
+<pre class="doc_code">
+ at G = thread_local(initialexec) global i32 0, align 4
+</pre>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="functionstructure">Functions</a>
+</h3>
+
+<div>
+
+<p>LLVM function definitions consist of the "<tt>define</tt>" keyword, an
+   optional <a href="#linkage">linkage type</a>, an optional
+   <a href="#visibility">visibility style</a>, an optional
+   <a href="#callingconv">calling convention</a>,
+   an optional <tt>unnamed_addr</tt> attribute, a return type, an optional
+   <a href="#paramattrs">parameter attribute</a> for the return type, a function
+   name, a (possibly empty) argument list (each with optional
+   <a href="#paramattrs">parameter attributes</a>), optional
+   <a href="#fnattrs">function attributes</a>, an optional section, an optional
+   alignment, an optional <a href="#gc">garbage collector name</a>, an opening
+   curly brace, a list of basic blocks, and a closing curly brace.</p>
+
+<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="#callingconv">calling convention</a>,
+   an optional <tt>unnamed_addr</tt> attribute, 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
+   optional <a href="#gc">garbage collector name</a>.</p>
+
+<p>A function definition contains a list of basic blocks, forming the CFG
+   (Control Flow Graph) for the function.  Each basic block may optionally start
+   with a label (giving the basic block a symbol table entry), contains a list
+   of instructions, and ends with a <a href="#terminators">terminator</a>
+   instruction (such as a branch or function return).</p>
+
+<p>The first basic block in a function 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).  Because the block can have no predecessors, it also
+   cannot have any <a href="#i_phi">PHI nodes</a>.</p>
+
+<p>LLVM allows an explicit section to be specified for functions.  If the target
+   supports it, it will emit functions to the section specified.</p>
+
+<p>An explicit alignment may be specified for a function.  If not present, or if
+   the alignment is set to zero, the alignment of the function is set by the
+   target to whatever it feels convenient.  If an explicit alignment is
+   specified, the function is forced to have at least that much alignment.  All
+   alignments must be a power of 2.</p>
+
+<p>If the <tt>unnamed_addr</tt> attribute is given, the address is know to not
+   be significant and two identical functions can be merged.</p>
+
+<h5>Syntax:</h5>
+<pre class="doc_code">
+define [<a href="#linkage">linkage</a>] [<a href="#visibility">visibility</a>]
+       [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>]
+       <ResultType> @<FunctionName> ([argument list])
+       [<a href="#fnattrs">fn Attrs</a>] [section "name"] [align N]
+       [<a href="#gc">gc</a>] { ... }
+</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="aliasstructure">Aliases</a>
+</h3>
+
+<div>
+
+<p>Aliases act as "second name" for the aliasee value (which can be either
+   function, global variable, another alias or bitcast of global value). Aliases
+   may have an optional <a href="#linkage">linkage type</a>, and an
+   optional <a href="#visibility">visibility style</a>.</p>
+
+<h5>Syntax:</h5>
+<pre class="doc_code">
+@<Name> = alias [Linkage] [Visibility] <AliaseeTy> @<Aliasee>
+</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="namedmetadatastructure">Named Metadata</a>
+</h3>
+
+<div>
+
+<p>Named metadata is a collection of metadata. <a href="#metadata">Metadata
+   nodes</a> (but not metadata strings) are the only valid operands for
+   a named metadata.</p>
+
+<h5>Syntax:</h5>
+<pre class="doc_code">
+; Some unnamed metadata nodes, which are referenced by the named metadata.
+!0 = metadata !{metadata !"zero"}
+!1 = metadata !{metadata !"one"}
+!2 = metadata !{metadata !"two"}
+; A named metadata.
+!name = !{!0, !1, !2}
+</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="paramattrs">Parameter Attributes</a>
+</h3>
+
+<div>
+
+<p>The return type and each parameter of a function type may have a set of
+   <i>parameter attributes</i> associated with them. Parameter attributes are
+   used to communicate additional information about the result or parameters of
+   a function. Parameter attributes are considered to be part of the function,
+   not of the function type, so functions with different parameter attributes
+   can have the same function type.</p>
+
+<p>Parameter attributes are simple keywords that follow the type specified. If
+   multiple parameter attributes are needed, they are space separated. For
+   example:</p>
+
+<pre class="doc_code">
+declare i32 @printf(i8* noalias nocapture, ...)
+declare i32 @atoi(i8 zeroext)
+declare signext i8 @returns_signed_char()
+</pre>
+
+<p>Note that any attributes for the function result (<tt>nounwind</tt>,
+   <tt>readonly</tt>) come immediately after the argument list.</p>
+
+<p>Currently, only the following parameter attributes are defined:</p>
+
+<dl>
+  <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 the extent required by the target's ABI (which
+      is usually 32-bits, but is 8-bits for a i1 on x86-64) by the caller (for a
+      parameter) or the callee (for a return value).</dd>
+
+  <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 the extent required by the target's ABI (which
+      is usually 32-bits) by the caller (for a parameter) or the callee (for a
+      return value).</dd>
+
+  <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><b><a name="byval">byval</a></b></tt></dt>
+  <dd><p>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
+      modify the value in the caller.  This attribute is only valid on LLVM
+      pointer arguments.  It is generally used to pass structs and arrays by
+      value, but is also valid on pointers to scalars.  The copy is considered
+      to belong to the caller not the callee (for example,
+      <tt><a href="#readonly">readonly</a></tt> functions should not write to
+      <tt>byval</tt> parameters). This is not a valid attribute for return
+      values.</p>
+      
+      <p>The byval attribute also supports specifying an alignment with
+      the align attribute.  It indicates the alignment of the stack slot to
+      form and the known alignment of the pointer specified to the call site. If
+      the alignment is not specified, then the code generator makes a
+      target-specific assumption.</p></dd>
+
+  <dt><tt><b><a name="sret">sret</a></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
+      stores to the structure may be assumed by the callee to not to trap and
+      to be properly aligned.  This may only be applied to the first parameter.
+      This is not a valid attribute for return values. </dd>
+
+  <dt><tt><b><a name="noalias">noalias</a></b></tt></dt>
+  <dd>This indicates that pointer values
+      <a href="#pointeraliasing"><i>based</i></a> on the argument or return
+      value do not alias pointer values which are not <i>based</i> on it,
+      ignoring certain "irrelevant" dependencies.
+      For a call to the parent function, dependencies between memory
+      references from before or after the call and from those during the call
+      are "irrelevant" to the <tt>noalias</tt> keyword for the arguments and
+      return value used in that call.
+      The caller shares the responsibility with the callee for ensuring that
+      these requirements are met.
+      For further details, please see the discussion of the NoAlias response in
+      <a href="AliasAnalysis.html#MustMayNo">alias analysis</a>.<br>
+<br>
+      Note that this definition of <tt>noalias</tt> is intentionally
+      similar to the definition of <tt>restrict</tt> in C99 for function
+      arguments, though it is slightly weaker.
+<br>
+      For function return values, C99's <tt>restrict</tt> is not meaningful,
+      while LLVM's <tt>noalias</tt> is.
+      </dd>
+
+  <dt><tt><b><a name="nocapture">nocapture</a></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><b><a name="nest">nest</a></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>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="gc">Garbage Collector Names</a>
+</h3>
+
+<div>
+
+<p>Each function may specify a garbage collector name, which is simply a
+   string:</p>
+
+<pre class="doc_code">
+define void @f() gc "name" { ... }
+</pre>
+
+<p>The compiler declares the supported values of <i>name</i>. Specifying a
+   collector which will cause the compiler to alter its output in order to
+   support the named garbage collection algorithm.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="fnattrs">Function Attributes</a>
+</h3>
+
+<div>
+
+<p>Function attributes are set to communicate additional information about a
+   function. Function attributes are considered to be part of the function, not
+   of the function type, so functions with different parameter attributes can
+   have the same function type.</p>
+
+<p>Function attributes are simple keywords that follow the type specified. If
+   multiple attributes are needed, they are space separated. For example:</p>
+
+<pre class="doc_code">
+define void @f() noinline { ... }
+define void @f() alwaysinline { ... }
+define void @f() alwaysinline optsize { ... }
+define void @f() optsize { ... }
+</pre>
+
+<dl>
+  <dt><tt><b>address_safety</b></tt></dt>
+  <dd>This attribute indicates that the address safety analysis
+  is enabled for this function.  </dd>
+
+  <dt><tt><b>alignstack(<<em>n</em>>)</b></tt></dt>
+  <dd>This attribute indicates that, when emitting the prologue and epilogue,
+      the backend should forcibly align the stack pointer. Specify the
+      desired alignment, which must be a power of two, in parentheses.
+
+  <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><b>nonlazybind</b></tt></dt>
+  <dd>This attribute suppresses lazy symbol binding for the function. This
+      may make calls to the function faster, at the cost of extra program
+      startup time if the function is not called during program startup.</dd>
+
+  <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><b>naked</b></tt></dt>
+  <dd>This attribute disables prologue / epilogue emission for the function.
+      This can have very system-specific consequences.</dd>
+
+  <dt><tt><b>noimplicitfloat</b></tt></dt>
+  <dd>This attributes disables implicit floating point instructions.</dd>
+
+  <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><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><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><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><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><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
+      state (e.g. memory, control registers, etc) visible to caller functions.
+      It does not write through any pointer arguments
+      (including <tt><a href="#byval">byval</a></tt> arguments) and never
+      changes any state visible to callers.  This means that it cannot unwind
+      exceptions by calling the <tt>C++</tt> exception throwing methods.</dd>
+
+  <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,
+      etc) visible to caller functions.  It may dereference pointer arguments
+      and read state that may be set in the caller.  A readonly function always
+      returns the same value (or unwinds an exception identically) when called
+      with the same set of arguments and global state.  It cannot unwind an
+      exception by calling the <tt>C++</tt> exception throwing methods.</dd>
+
+  <dt><tt><b><a name="returns_twice">returns_twice</a></b></tt></dt>
+  <dd>This attribute indicates that this function can return twice. The
+      C <code>setjmp</code> is an example of such a function.  The compiler
+      disables some optimizations (like tail calls) in the caller of these
+      functions.</dd>
+
+  <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"—a random value placed on
+      the stack before the local variables that's checked upon return from the
+      function to see if it has been overwritten. A heuristic is used to
+      determine if a function needs stack protectors or not.<br>
+<br>
+      If a function that has an <tt>ssp</tt> attribute is inlined into a
+      function that doesn't have an <tt>ssp</tt> attribute, then the resulting
+      function will have an <tt>ssp</tt> attribute.</dd>
+
+  <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>
+<br>
+      If a function that has an <tt>sspreq</tt> attribute is inlined into a
+      function that doesn't have an <tt>sspreq</tt> attribute or which has
+      an <tt>ssp</tt> attribute, then the resulting function will have
+      an <tt>sspreq</tt> attribute.</dd>
+
+  <dt><tt><b><a name="uwtable">uwtable</a></b></tt></dt>
+  <dd>This attribute indicates that the ABI being targeted requires that
+      an unwind table entry be produce for this function even if we can
+      show that no exceptions passes by it. This is normally the case for
+      the ELF x86-64 abi, but it can be disabled for some compilation
+      units.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="moduleasm">Module-Level Inline Assembly</a>
+</h3>
+
+<div>
+
+<p>Modules may contain "module-level inline asm" blocks, which corresponds to
+   the GCC "file scope inline asm" blocks.  These blocks are internally
+   concatenated by LLVM and treated as a single unit, but may be separated in
+   the <tt>.ll</tt> file if desired.  The syntax is very simple:</p>
+
+<pre class="doc_code">
+module asm "inline asm code goes here"
+module asm "more can go here"
+</pre>
+
+<p>The strings can contain any character by escaping non-printable characters.
+   The escape sequence used is simply "\xx" where "xx" is the two digit hex code
+   for the number.</p>
+
+<p>The inline asm code is simply printed to the machine code .s file when
+   assembly code is generated.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="datalayout">Data Layout</a>
+</h3>
+
+<div>
+
+<p>A module may specify a target specific data layout string that specifies how
+   data is to be laid out in memory. The syntax for the data layout is
+   simply:</p>
+
+<pre class="doc_code">
+target datalayout = "<i>layout specification</i>"
+</pre>
+
+<p>The <i>layout specification</i> consists of a list of specifications
+   separated by the minus sign character ('-').  Each specification starts with
+   a letter and may include other information after the letter to define some
+   aspect of the data layout.  The specifications accepted are as follows:</p>
+
+<dl>
+  <dt><tt>E</tt></dt>
+  <dd>Specifies that the target lays out data in big-endian form. That is, the
+      bits with the most significance have the lowest address location.</dd>
+
+  <dt><tt>e</tt></dt>
+  <dd>Specifies that the target lays out data in little-endian form. That is,
+      the bits with the least significance have the lowest address
+      location.</dd>
+
+  <dt><tt>S<i>size</i></tt></dt>
+  <dd>Specifies the natural alignment of the stack in bits. Alignment promotion
+      of stack variables is limited to the natural stack alignment to avoid
+      dynamic stack realignment. The stack alignment must be a multiple of
+      8-bits. If omitted, the natural stack alignment defaults to "unspecified",
+      which does not prevent any alignment promotions.</dd>
+
+  <dt><tt>p[n]:<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
+      <i>preferred</i> alignments for address space <i>n</i>. All sizes are in
+      bits. Specifying the <i>pref</i> alignment is optional. If omitted, the
+      preceding <tt>:</tt> should be omitted too. The address space,
+      <i>n</i> is optional, and if not specified, denotes the default address
+      space 0. The value of <i>n</i> must be in the range [1,2^23).</dd>
+
+  <dt><tt>i<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
+  <dd>This specifies the alignment for an integer type of a given bit
+      <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
+      <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
+      <i>size</i>. Only values of <i>size</i> that are supported by the target
+      will work.  32 (float) and 64 (double) are supported on all targets;
+      80 or 128 (different flavors of long double) are also supported on some
+      targets.
+
+  <dt><tt>a<i>size</i>:<i>abi</i>:<i>pref</i></tt></dt>
+  <dd>This specifies the alignment for an aggregate type of a given bit
+      <i>size</i>.</dd>
+
+  <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
+   default set of specifications which are then (possibly) overridden by the
+   specifications in the <tt>datalayout</tt> keyword. The default specifications
+   are given in this list:</p>
+
+<ul>
+  <li><tt>E</tt> - big endian</li>
+  <li><tt>p:64:64:64</tt> - 64-bit pointers with 64-bit alignment</li>
+  <li><tt>p1:32:32:32</tt> - 32-bit pointers with 32-bit alignment for
+  address space 1</li>
+  <li><tt>p2:16:32:32</tt> - 16-bit pointers with 32-bit alignment for
+  address space 2</li>
+  <li><tt>i1:8:8</tt> - i1 is 8-bit (byte) aligned</li>
+  <li><tt>i8:8:8</tt> - i8 is 8-bit (byte) aligned</li>
+  <li><tt>i16:16:16</tt> - i16 is 16-bit aligned</li>
+  <li><tt>i32:32:32</tt> - i32 is 32-bit aligned</li>
+  <li><tt>i64:32:64</tt> - i64 has ABI alignment of 32-bits but preferred
+  alignment of 64-bits</li>
+  <li><tt>f32:32:32</tt> - float is 32-bit aligned</li>
+  <li><tt>f64:64:64</tt> - double is 64-bit aligned</li>
+  <li><tt>v64:64:64</tt> - 64-bit vector is 64-bit aligned</li>
+  <li><tt>v128:128:128</tt> - 128-bit vector is 128-bit aligned</li>
+  <li><tt>a0:0:1</tt> - aggregates are 8-bit aligned</li>
+  <li><tt>s0:64:64</tt> - stack objects are 64-bit aligned</li>
+</ul>
+
+<p>When LLVM is determining the alignment for a given type, it uses the
+   following rules:</p>
+
+<ol>
+  <li>If the type sought is an exact match for one of the specifications, that
+      specification is used.</li>
+
+  <li>If no match is found, and the type sought is an integer type, then the
+      smallest integer type that is larger than the bitwidth of the sought type
+      is used. If none of the specifications are larger than the bitwidth then
+      the largest integer type is used. For example, given the default
+      specifications above, the i7 type will use the alignment of i8 (next
+      largest) while both i65 and i256 will use the alignment of i64 (largest
+      specified).</li>
+
+  <li>If no match is found, and the type sought is a vector type, then the
+      largest vector type that is smaller than the sought vector type will be
+      used as a fall back.  This happens because <128 x double> can be
+      implemented in terms of 64 <2 x double>, for example.</li>
+</ol>
+
+<p>The function of the data layout string may not be what you expect.  Notably,
+   this is not a specification from the frontend of what alignment the code
+   generator should use.</p>
+
+<p>Instead, if specified, the target data layout is required to match what the 
+   ultimate <em>code generator</em> expects.  This string is used by the 
+   mid-level optimizers to
+   improve code, and this only works if it matches what the ultimate code 
+   generator uses.  If you would like to generate IR that does not embed this
+   target-specific detail into the IR, then you don't have to specify the 
+   string.  This will disable some optimizations that require precise layout
+   information, but this also prevents those optimizations from introducing
+   target specificity into the IR.</p>
+
+
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="pointeraliasing">Pointer Aliasing Rules</a>
+</h3>
+
+<div>
+
+<p>Any memory access must be done through a pointer value associated
+with an address range of the memory access, otherwise the behavior
+is undefined. Pointer values are associated with address ranges
+according to the following rules:</p>
+
+<ul>
+  <li>A pointer value is associated with the addresses associated with
+      any value it is <i>based</i> on.
+  <li>An address of a global variable is associated with the address
+      range of the variable's storage.</li>
+  <li>The result value of an allocation instruction is associated with
+      the address range of the allocated storage.</li>
+  <li>A null pointer in the default address-space is associated with
+      no address.</li>
+  <li>An integer constant other than zero or a pointer value returned
+      from a function not defined within LLVM may be associated with address
+      ranges allocated through mechanisms other than those provided by
+      LLVM. Such ranges shall not overlap with any ranges of addresses
+      allocated by mechanisms provided by LLVM.</li>
+</ul>
+
+<p>A pointer value is <i>based</i> on another pointer value according
+   to the following rules:</p>
+
+<ul>
+  <li>A pointer value formed from a
+      <tt><a href="#i_getelementptr">getelementptr</a></tt> operation
+      is <i>based</i> on the first operand of the <tt>getelementptr</tt>.</li>
+  <li>The result value of a
+      <tt><a href="#i_bitcast">bitcast</a></tt> is <i>based</i> on the operand
+      of the <tt>bitcast</tt>.</li>
+  <li>A pointer value formed by an
+      <tt><a href="#i_inttoptr">inttoptr</a></tt> is <i>based</i> on all
+      pointer values that contribute (directly or indirectly) to the
+      computation of the pointer's value.</li>
+  <li>The "<i>based</i> on" relationship is transitive.</li>
+</ul>
+
+<p>Note that this definition of <i>"based"</i> is intentionally
+   similar to the definition of <i>"based"</i> in C99, though it is
+   slightly weaker.</p>
+
+<p>LLVM IR does not associate types with memory. The result type of a
+<tt><a href="#i_load">load</a></tt> merely indicates the size and
+alignment of the memory from which to load, as well as the
+interpretation of the value. The first operand type of a
+<tt><a href="#i_store">store</a></tt> similarly only indicates the size
+and alignment of the store.</p>
+
+<p>Consequently, type-based alias analysis, aka TBAA, aka
+<tt>-fstrict-aliasing</tt>, is not applicable to general unadorned
+LLVM IR. <a href="#metadata">Metadata</a> may be used to encode
+additional information which specialized optimization passes may use
+to implement type-based alias analysis.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="volatile">Volatile Memory Accesses</a>
+</h3>
+
+<div>
+
+<p>Certain memory accesses, such as <a href="#i_load"><tt>load</tt></a>s, <a
+href="#i_store"><tt>store</tt></a>s, and <a
+href="#int_memcpy"><tt>llvm.memcpy</tt></a>s may be marked <tt>volatile</tt>.
+The optimizers must not change the number of volatile operations or change their
+order of execution relative to other volatile operations.  The optimizers
+<i>may</i> change the order of volatile operations relative to non-volatile
+operations.  This is not Java's "volatile" and has no cross-thread
+synchronization behavior.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="memmodel">Memory Model for Concurrent Operations</a>
+</h3>
+
+<div>
+
+<p>The LLVM IR does not define any way to start parallel threads of execution
+or to register signal handlers. Nonetheless, there are platform-specific
+ways to create them, and we define LLVM IR's behavior in their presence. This
+model is inspired by the C++0x memory model.</p>
+
+<p>For a more informal introduction to this model, see the
+<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.
+
+<p>We define a <i>happens-before</i> partial order as the least partial order
+that</p>
+<ul>
+  <li>Is a superset of single-thread program order, and</li>
+  <li>When a <i>synchronizes-with</i> <tt>b</tt>, includes an edge from
+      <tt>a</tt> to <tt>b</tt>. <i>Synchronizes-with</i> pairs are introduced
+      by platform-specific techniques, like pthread locks, thread
+      creation, thread joining, etc., and by atomic instructions.
+      (See also <a href="#ordering">Atomic Memory Ordering Constraints</a>).
+      </li>
+</ul>
+
+<p>Note that program order does not introduce <i>happens-before</i> edges
+between a thread and signals executing inside that thread.</p>
+
+<p>Every (defined) read operation (load instructions, memcpy, atomic
+loads/read-modify-writes, etc.) <var>R</var> reads a series of bytes written by
+(defined) write operations (store instructions, atomic
+stores/read-modify-writes, memcpy, etc.). For the purposes of this section,
+initialized globals are considered to have a write of the initializer which is
+atomic and happens before any other read or write of the memory in question.
+For each byte of a read <var>R</var>, <var>R<sub>byte</sub></var> may see
+any write to the same byte, except:</p>
+
+<ul>
+  <li>If <var>write<sub>1</sub></var> happens before
+      <var>write<sub>2</sub></var>, and <var>write<sub>2</sub></var> happens
+      before <var>R<sub>byte</sub></var>, then <var>R<sub>byte</sub></var>
+      does not see <var>write<sub>1</sub></var>.
+  <li>If <var>R<sub>byte</sub></var> happens before
+      <var>write<sub>3</sub></var>, then <var>R<sub>byte</sub></var> does not
+      see <var>write<sub>3</sub></var>.
+</ul>
+
+<p>Given that definition, <var>R<sub>byte</sub></var> is defined as follows:
+<ul>
+  <li>If <var>R</var> is volatile, the result is target-dependent. (Volatile
+      is supposed to give guarantees which can support
+      <code>sig_atomic_t</code> in C/C++, and may be used for accesses to
+      addresses which do not behave like normal memory.  It does not generally
+      provide cross-thread synchronization.)
+  <li>Otherwise, if there is no write to the same byte that happens before
+    <var>R<sub>byte</sub></var>, <var>R<sub>byte</sub></var> returns 
+    <tt>undef</tt> for that byte.
+  <li>Otherwise, if <var>R<sub>byte</sub></var> may see exactly one write,
+      <var>R<sub>byte</sub></var> returns the value written by that
+      write.</li>
+  <li>Otherwise, if <var>R</var> is atomic, and all the writes
+      <var>R<sub>byte</sub></var> may see are atomic, it chooses one of the
+      values written.  See the <a href="#ordering">Atomic Memory Ordering
+      Constraints</a> section for additional constraints on how the choice
+      is made.
+  <li>Otherwise <var>R<sub>byte</sub></var> returns <tt>undef</tt>.</li>
+</ul>
+
+<p><var>R</var> returns the value composed of the series of bytes it read.
+This implies that some bytes within the value may be <tt>undef</tt>
+<b>without</b> the entire value being <tt>undef</tt>. Note that this only
+defines the semantics of the operation; it doesn't mean that targets will
+emit more than one instruction to read the series of bytes.</p>
+
+<p>Note that in cases where none of the atomic intrinsics are used, this model
+places only one restriction on IR transformations on top of what is required
+for single-threaded execution: introducing a store to a byte which might not
+otherwise be stored is not allowed in general.  (Specifically, in the case
+where another thread might write to and read from an address, introducing a
+store can change a load that may see exactly one write into a load that may
+see multiple writes.)</p>
+
+<!-- FIXME: This model assumes all targets where concurrency is relevant have
+a byte-size store which doesn't affect adjacent bytes.  As far as I can tell,
+none of the backends currently in the tree fall into this category; however,
+there might be targets which care.  If there are, we want a paragraph
+like the following:
+
+Targets may specify that stores narrower than a certain width are not
+available; on such a target, for the purposes of this model, treat any
+non-atomic write with an alignment or width less than the minimum width
+as if it writes to the relevant surrounding bytes.
+-->
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+      <a name="ordering">Atomic Memory Ordering Constraints</a>
+</h3>
+
+<div>
+
+<p>Atomic instructions (<a href="#i_cmpxchg"><code>cmpxchg</code></a>,
+<a href="#i_atomicrmw"><code>atomicrmw</code></a>,
+<a href="#i_fence"><code>fence</code></a>,
+<a href="#i_load"><code>atomic load</code></a>, and
+<a href="#i_store"><code>atomic store</code></a>) take an ordering parameter
+that determines which other atomic instructions on the same address they
+<i>synchronize with</i>.  These semantics are borrowed from Java and C++0x,
+but are somewhat more colloquial. If these descriptions aren't precise enough,
+check those specs (see spec references in the
+<a href="Atomics.html#introduction">atomics guide</a>).
+<a href="#i_fence"><code>fence</code></a> instructions
+treat these orderings somewhat differently since they don't take an address.
+See that instruction's documentation for details.</p>
+
+<p>For a simpler introduction to the ordering constraints, see the
+<a href="Atomics.html">LLVM Atomic Instructions and Concurrency Guide</a>.</p>
+
+<dl>
+<dt><code>unordered</code></dt>
+<dd>The set of values that can be read is governed by the happens-before
+partial order. A value cannot be read unless some operation wrote it.
+This is intended to provide a guarantee strong enough to model Java's
+non-volatile shared variables.  This ordering cannot be specified for
+read-modify-write operations; it is not strong enough to make them atomic
+in any interesting way.</dd>
+<dt><code>monotonic</code></dt>
+<dd>In addition to the guarantees of <code>unordered</code>, there is a single
+total order for modifications by <code>monotonic</code> operations on each
+address. All modification orders must be compatible with the happens-before
+order. There is no guarantee that the modification orders can be combined to
+a global total order for the whole program (and this often will not be
+possible). The read in an atomic read-modify-write operation
+(<a href="#i_cmpxchg"><code>cmpxchg</code></a> and
+<a href="#i_atomicrmw"><code>atomicrmw</code></a>)
+reads the value in the modification order immediately before the value it
+writes. If one atomic read happens before another atomic read of the same
+address, the later read must see the same value or a later value in the
+address's modification order. This disallows reordering of
+<code>monotonic</code> (or stronger) operations on the same address. If an
+address is written <code>monotonic</code>ally by one thread, and other threads
+<code>monotonic</code>ally read that address repeatedly, the other threads must
+eventually see the write. This corresponds to the C++0x/C1x
+<code>memory_order_relaxed</code>.</dd>
+<dt><code>acquire</code></dt>
+<dd>In addition to the guarantees of <code>monotonic</code>,
+a <i>synchronizes-with</i> edge may be formed with a <code>release</code>
+operation. This is intended to model C++'s <code>memory_order_acquire</code>.</dd>
+<dt><code>release</code></dt>
+<dd>In addition to the guarantees of <code>monotonic</code>, if this operation
+writes a value which is subsequently read by an <code>acquire</code> operation,
+it <i>synchronizes-with</i> that operation.  (This isn't a complete
+description; see the C++0x definition of a release sequence.) This corresponds
+to the C++0x/C1x <code>memory_order_release</code>.</dd>
+<dt><code>acq_rel</code> (acquire+release)</dt><dd>Acts as both an
+<code>acquire</code> and <code>release</code> operation on its address.
+This corresponds to the C++0x/C1x <code>memory_order_acq_rel</code>.</dd>
+<dt><code>seq_cst</code> (sequentially consistent)</dt><dd>
+<dd>In addition to the guarantees of <code>acq_rel</code>
+(<code>acquire</code> for an operation which only reads, <code>release</code>
+for an operation which only writes), there is a global total order on all
+sequentially-consistent operations on all addresses, which is consistent with
+the <i>happens-before</i> partial order and with the modification orders of
+all the affected addresses. Each sequentially-consistent read sees the last
+preceding write to the same address in this global order. This corresponds
+to the C++0x/C1x <code>memory_order_seq_cst</code> and Java volatile.</dd>
+</dl>
+
+<p id="singlethread">If an atomic operation is marked <code>singlethread</code>,
+it only <i>synchronizes with</i> or participates in modification and seq_cst
+total orderings with other operations running in the same thread (for example,
+in signal handlers).</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="typesystem">Type System</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>The LLVM type system is one of the most important features of the
+   intermediate representation.  Being typed enables a number of optimizations
+   to be performed on the intermediate representation directly, without having
+   to do extra analyses on the side before the transformation.  A strong type
+   system makes it easier to read the generated code and enables novel analyses
+   and transformations that are not feasible to perform on normal three address
+   code representations.</p>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="t_classifications">Type Classifications</a>
+</h3>
+
+<div>
+
+<p>The types fall into a few useful classifications:</p>
+
+<table border="1" cellspacing="0" cellpadding="4">
+  <tbody>
+    <tr><th>Classification</th><th>Types</th></tr>
+    <tr>
+      <td><a href="#t_integer">integer</a></td>
+      <td><tt>i1, i2, i3, ... i8, ... i16, ... i32, ... i64, ... </tt></td>
+    </tr>
+    <tr>
+      <td><a href="#t_floating">floating point</a></td>
+      <td><tt>half, float, double, x86_fp80, fp128, ppc_fp128</tt></td>
+    </tr>
+    <tr>
+      <td><a name="t_firstclass">first class</a></td>
+      <td><a href="#t_integer">integer</a>,
+          <a href="#t_floating">floating point</a>,
+          <a href="#t_pointer">pointer</a>,
+          <a href="#t_vector">vector</a>,
+          <a href="#t_struct">structure</a>,
+          <a href="#t_array">array</a>,
+          <a href="#t_label">label</a>,
+          <a href="#t_metadata">metadata</a>.
+      </td>
+    </tr>
+    <tr>
+      <td><a href="#t_primitive">primitive</a></td>
+      <td><a href="#t_label">label</a>,
+          <a href="#t_void">void</a>,
+          <a href="#t_integer">integer</a>,
+          <a href="#t_floating">floating point</a>,
+          <a href="#t_x86mmx">x86mmx</a>,
+          <a href="#t_metadata">metadata</a>.</td>
+    </tr>
+    <tr>
+      <td><a href="#t_derived">derived</a></td>
+      <td><a href="#t_array">array</a>,
+          <a href="#t_function">function</a>,
+          <a href="#t_pointer">pointer</a>,
+          <a href="#t_struct">structure</a>,
+          <a href="#t_vector">vector</a>,
+          <a href="#t_opaque">opaque</a>.
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<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.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="t_primitive">Primitive Types</a>
+</h3>
+
+<div>
+
+<p>The primitive types are the fundamental building blocks of the LLVM
+   system.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_integer">Integer Type</a>
+</h4>
+
+<div>
+
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_floating">Floating Point Types</a>
+</h4>
+
+<div>
+
+<table>
+  <tbody>
+    <tr><th>Type</th><th>Description</th></tr>
+    <tr><td><tt>half</tt></td><td>16-bit floating point value</td></tr>
+    <tr><td><tt>float</tt></td><td>32-bit floating point value</td></tr>
+    <tr><td><tt>double</tt></td><td>64-bit floating point value</td></tr>
+    <tr><td><tt>fp128</tt></td><td>128-bit floating point value (112-bit mantissa)</td></tr>
+    <tr><td><tt>x86_fp80</tt></td><td>80-bit floating point value (X87)</td></tr>
+    <tr><td><tt>ppc_fp128</tt></td><td>128-bit floating point value (two 64-bits)</td></tr>
+  </tbody>
+</table>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_x86mmx">X86mmx Type</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<p>The x86mmx type represents a value held in an MMX register on an x86 machine.  The operations allowed on it are quite limited:  parameters and return values, load and store, and bitcast.  User-specified MMX instructions are represented as intrinsic or asm calls with arguments and/or results of this type.  There are no arrays, vectors or constants of this type.</p>
+
+<h5>Syntax:</h5>
+<pre>
+  x86mmx
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_void">Void Type</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<p>The void type does not represent any value and has no size.</p>
+
+<h5>Syntax:</h5>
+<pre>
+  void
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_label">Label Type</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<p>The label type represents code labels.</p>
+
+<h5>Syntax:</h5>
+<pre>
+  label
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_metadata">Metadata Type</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<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>
+  metadata
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="t_derived">Derived Types</a>
+</h3>
+
+<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.  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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_aggregate">Aggregate Types</a>
+</h4>
+
+<div>
+
+<p>Aggregate Types are a subset of derived types that can contain multiple
+  member types. <a href="#t_array">Arrays</a> and
+  <a href="#t_struct">structs</a> are aggregate types.
+  <a href="#t_vector">Vectors</a> are not considered to be aggregate types.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_array">Array Type</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<p>The array type is a very simple derived type that arranges elements
+   sequentially in memory.  The array type requires a size (number of elements)
+   and an underlying data type.</p>
+
+<h5>Syntax:</h5>
+<pre>
+  [<# elements> x <elementtype>]
+</pre>
+
+<p>The number of elements is a constant integer value; <tt>elementtype</tt> may
+   be any type with a size.</p>
+
+<h5>Examples:</h5>
+<table class="layout">
+  <tr class="layout">
+    <td class="left"><tt>[40 x i32]</tt></td>
+    <td class="left">Array of 40 32-bit integer values.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>[41 x i32]</tt></td>
+    <td class="left">Array of 41 32-bit integer values.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>[4 x i8]</tt></td>
+    <td class="left">Array of 4 8-bit integer values.</td>
+  </tr>
+</table>
+<p>Here are some examples of multidimensional arrays:</p>
+<table class="layout">
+  <tr class="layout">
+    <td class="left"><tt>[3 x [4 x i32]]</tt></td>
+    <td class="left">3x4 array of 32-bit integer values.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>[12 x [10 x float]]</tt></td>
+    <td class="left">12x10 array of single precision floating point values.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>[2 x [3 x [4 x i16]]]</tt></td>
+    <td class="left">2x3x4 array of 16-bit integer  values.</td>
+  </tr>
+</table>
+
+<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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_function">Function Type</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<p>The function type can be thought of as a function signature.  It consists of
+   a return type and a list of formal parameter types. The return type of a
+   function type is a first class type or a void type.</p>
+
+<h5>Syntax:</h5>
+<pre>
+  <returntype> (<parameter list>)
+</pre>
+
+<p>...where '<tt><parameter list></tt>' is a comma-separated list of type
+   specifiers.  Optionally, the parameter list may include a type <tt>...</tt>,
+   which indicates that the function takes a variable number of arguments.
+   Variable argument functions can access their arguments with
+   the <a href="#int_varargs">variable argument handling intrinsic</a>
+   functions.  '<tt><returntype></tt>' is any type except
+   <a href="#t_label">label</a>.</p>
+
+<h5>Examples:</h5>
+<table class="layout">
+  <tr class="layout">
+    <td class="left"><tt>i32 (i32)</tt></td>
+    <td class="left">function taking an <tt>i32</tt>, returning an <tt>i32</tt>
+    </td>
+  </tr><tr class="layout">
+    <td class="left"><tt>float (i16, i32 *) *
+    </tt></td>
+    <td class="left"><a href="#t_pointer">Pointer</a> to a function that takes
+      an <tt>i16</tt> 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
+      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 a
+        <a href="#t_struct">structure</a> containing two <tt>i32</tt> values
+    </td>
+  </tr>
+</table>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_struct">Structure Type</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<p>The structure type is used to represent a collection of data members together
+  in memory.  The elements of a structure may be any type that has a size.</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>
+  
+<p>Structures may optionally be "packed" structures, which indicate that the 
+  alignment of the struct is one byte, and that there is no padding between
+  the elements.  In non-packed structs, padding between field types is inserted
+  as defined by the DataLayout string in the module, which is required to match
+  what the underlying code generator expects.</p>
+
+<p>Structures can either be "literal" or "identified".  A literal structure is
+  defined inline with other types (e.g. <tt>{i32, i32}*</tt>) whereas identified
+  types are always defined at the top level with a name.  Literal types are
+  uniqued by their contents and can never be recursive or opaque since there is
+  no way to write one.  Identified types can be recursive, can be opaqued, and are
+  never uniqued.
+</p>
+  
+<h5>Syntax:</h5>
+<pre>
+  %T1 = type { <type list> }     <i>; Identified normal struct type</i>
+  %T2 = type <{ <type list> }>   <i>; Identified packed struct type</i>
+</pre>
+  
+<h5>Examples:</h5>
+<table class="layout">
+  <tr class="layout">
+    <td class="left"><tt>{ i32, i32, i32 }</tt></td>
+    <td class="left">A triple of three <tt>i32</tt> values</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>{ float, i32 (i32) * }</tt></td>
+    <td class="left">A pair, where the first element is a <tt>float</tt> and the
+      second element is a <a href="#t_pointer">pointer</a> to a
+      <a href="#t_function">function</a> that takes an <tt>i32</tt>, returning
+      an <tt>i32</tt>.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt><{ i8, i32 }></tt></td>
+    <td class="left">A packed struct known to be 5 bytes in size.</td>
+  </tr>
+</table>
+
+</div>
+  
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_opaque">Opaque Structure Types</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<p>Opaque structure types are used to represent named structure types that do
+   not have a body specified.  This corresponds (for example) to the C notion of
+   a forward declared structure.</p>
+
+<h5>Syntax:</h5>
+<pre>
+  %X = type opaque
+  %52 = type opaque
+</pre>
+
+<h5>Examples:</h5>
+<table class="layout">
+  <tr class="layout">
+    <td class="left"><tt>opaque</tt></td>
+    <td class="left">An opaque type.</td>
+  </tr>
+</table>
+
+</div>
+
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_pointer">Pointer Type</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<p>The pointer type is used to specify memory locations.
+   Pointers are commonly used to reference objects in memory.</p>
+   
+<p>Pointer types may have an optional address space attribute defining the
+   numbered address space where the pointed-to object resides. The default
+   address space is number zero. The semantics of non-zero address
+   spaces are target-specific.</p>
+
+<p>Note that LLVM does not permit pointers to void (<tt>void*</tt>) nor does it
+   permit pointers to labels (<tt>label*</tt>).  Use <tt>i8*</tt> instead.</p>
+
+<h5>Syntax:</h5>
+<pre>
+  <type> *
+</pre>
+
+<h5>Examples:</h5>
+<table class="layout">
+  <tr class="layout">
+    <td class="left"><tt>[4 x i32]*</tt></td>
+    <td class="left">A <a href="#t_pointer">pointer</a> to <a
+                    href="#t_array">array</a> of four <tt>i32</tt> values.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>i32 (i32*) *</tt></td>
+    <td class="left"> A <a href="#t_pointer">pointer</a> to a <a
+      href="#t_function">function</a> that takes an <tt>i32*</tt>, returning an
+      <tt>i32</tt>.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt>i32 addrspace(5)*</tt></td>
+    <td class="left">A <a href="#t_pointer">pointer</a> to an <tt>i32</tt> value
+     that resides in address space #5.</td>
+  </tr>
+</table>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="t_vector">Vector Type</a>
+</h4>
+
+<div>
+
+<h5>Overview:</h5>
+<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.  Vector types are considered
+   <a href="#t_firstclass">first class</a>.</p>
+
+<h5>Syntax:</h5>
+<pre>
+  < <# elements> x <elementtype> >
+</pre>
+
+<p>The number of elements is a constant integer value larger than 0; elementtype
+   may be any integer or floating point type, or a pointer to these types.
+   Vectors of size zero are not allowed. </p>
+
+<h5>Examples:</h5>
+<table class="layout">
+  <tr class="layout">
+    <td class="left"><tt><4 x i32></tt></td>
+    <td class="left">Vector of 4 32-bit integer values.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt><8 x float></tt></td>
+    <td class="left">Vector of 8 32-bit floating-point values.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt><2 x i64></tt></td>
+    <td class="left">Vector of 2 64-bit integer values.</td>
+  </tr>
+  <tr class="layout">
+    <td class="left"><tt><4 x i64*></tt></td>
+    <td class="left">Vector of 4 pointers to 64-bit integer values.</td>
+  </tr>
+</table>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="constants">Constants</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>LLVM has several different basic types of constants.  This section describes
+   them all and their syntax.</p>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="simpleconstants">Simple Constants</a>
+</h3>
+
+<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_integer">i1</a></tt> type.</dd>
+
+  <dt><b>Integer constants</b></dt>
+  <dd>Standard integers (such as '4') are constants of
+      the <a href="#t_integer">integer</a> type.  Negative numbers may be used
+      with integer types.</dd>
+
+  <dt><b>Floating point constants</b></dt>
+  <dd>Floating point constants use standard decimal notation (e.g. 123.421),
+      exponential notation (e.g. 1.23421e+2), or a more precise hexadecimal
+      notation (see below).  The assembler requires the exact decimal value of a
+      floating-point constant.  For example, the assembler accepts 1.25 but
+      rejects 1.3 because 1.3 is a repeating decimal in binary.  Floating point
+      constants must have a <a href="#t_floating">floating point</a> type. </dd>
+
+  <dt><b>Null pointer constants</b></dt>
+  <dd>The identifier '<tt>null</tt>' is recognized as a null pointer constant
+      and must be of <a href="#t_pointer">pointer type</a>.</dd>
+</dl>
+
+<p>The one non-intuitive notation for constants is the hexadecimal 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>'.  The only time hexadecimal floating point
+   constants are required (and the only time that they are generated by the
+   disassembler) is when a floating point constant must be emitted but it cannot
+   be represented as a decimal floating point number in a reasonable number of
+   digits.  For example, NaN's, infinities, and other special values are
+   represented in their IEEE hexadecimal format so that assembly and disassembly
+   do not cause any bits to change in the constants.</p>
+
+<p>When using the hexadecimal form, constants of types half, float, and double are
+   represented using the 16-digit form shown above (which matches the IEEE754
+   representation for double); half and float values must, however, be exactly
+   representable as IEE754 half and single precision, respectively.
+   Hexadecimal format is always used
+   for long double, and there are three forms of long double.  The 80-bit format
+   used by x86 is represented as <tt>0xK</tt> followed by 20 hexadecimal digits.
+   The 128-bit format used by PowerPC (two adjacent doubles) is represented
+   by <tt>0xM</tt> followed by 32 hexadecimal digits.  The IEEE 128-bit format
+   is represented by <tt>0xL</tt> followed by 32 hexadecimal digits; no
+   currently supported target uses this format.  Long doubles will only work if
+   they match the long double format on your target. The IEEE 16-bit format
+   (half precision) is represented by <tt>0xH</tt> followed by 4 hexadecimal
+   digits. All hexadecimal formats are big-endian (sign bit at the left).</p>
+
+<p>There are no constants of type x86mmx.</p>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+<a name="aggregateconstants"></a> <!-- old anchor -->
+<a name="complexconstants">Complex Constants</a>
+</h3>
+
+<div>
+
+<p>Complex constants are a (potentially recursive) combination of simple
+   constants and smaller complex constants.</p>
+
+<dl>
+  <dt><b>Structure constants</b></dt>
+  <dd>Structure constants are represented with notation similar to structure
+      type definitions (a comma separated list of elements, surrounded by braces
+      (<tt>{}</tt>)).  For example: "<tt>{ i32 4, float 17.0, i32* @G }</tt>",
+      where "<tt>@G</tt>" is declared as "<tt>@G = external global i32</tt>".
+      Structure constants must have <a href="#t_struct">structure type</a>, and
+      the number and types of elements must match those specified by the
+      type.</dd>
+
+  <dt><b>Array constants</b></dt>
+  <dd>Array constants are represented with notation similar to array type
+     definitions (a comma separated list of elements, surrounded by square
+     brackets (<tt>[]</tt>)).  For example: "<tt>[ i32 42, i32 11, i32 74
+     ]</tt>".  Array constants must have <a href="#t_array">array type</a>, and
+     the number and types of elements must match those specified by the
+     type.</dd>
+
+  <dt><b>Vector constants</b></dt>
+  <dd>Vector constants are represented with notation similar to vector type
+      definitions (a comma separated list of elements, surrounded by
+      less-than/greater-than's (<tt><></tt>)).  For example: "<tt>< i32
+      42, i32 11, i32 74, i32 100 ></tt>".  Vector constants must
+      have <a href="#t_vector">vector type</a>, and the number and types of
+      elements must match those specified by the type.</dd>
+
+  <dt><b>Zero initialization</b></dt>
+  <dd>The string '<tt>zeroinitializer</tt>' can be used to zero initialize a
+      value to zero of <em>any</em> type, including scalar and
+      <a href="#t_aggregate">aggregate</a> types.
+      This is often used to avoid having to print large zero initializers
+      (e.g. for large arrays) and is always exactly equivalent to using explicit
+      zero initializers.</dd>
+
+  <dt><b>Metadata node</b></dt>
+  <dd>A metadata node is a structure-like constant with
+      <a href="#t_metadata">metadata type</a>.  For example: "<tt>metadata !{
+      i32 0, metadata !"test" }</tt>".  Unlike other constants that are meant to
+      be interpreted as part of the instruction stream, metadata is a place to
+      attach additional information such as debug info.</dd>
+</dl>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="globalconstants">Global Variable and Function Addresses</a>
+</h3>
+
+<div>
+
+<p>The addresses of <a href="#globalvars">global variables</a>
+   and <a href="#functionstructure">functions</a> are always implicitly valid
+   (link-time) constants.  These constants are explicitly referenced when
+   the <a href="#identifiers">identifier for the global</a> is used and always
+   have <a href="#t_pointer">pointer</a> type. For example, the following is a
+   legal LLVM file:</p>
+
+<pre class="doc_code">
+ at X = global i32 17
+ at Y = global i32 42
+ at Z = global [2 x i32*] [ i32* @X, i32* @Y ]
+</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="undefvalues">Undefined Values</a>
+</h3>
+
+<div>
+
+<p>The string '<tt>undef</tt>' can be used anywhere a constant is expected, and
+   indicates that the user of the value may receive an unspecified bit-pattern.
+   Undefined values may be of any type (other than '<tt>label</tt>'
+   or '<tt>void</tt>') and be used anywhere a constant is permitted.</p>
+
+<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>
+
+
+<pre class="doc_code">
+  %A = add %X, undef
+  %B = sub %X, undef
+  %C = xor %X, undef
+Safe:
+  %A = undef
+  %B = undef
+  %C = undef
+</pre>
+
+<p>This is safe because all of the output bits are affected by the undef bits.
+   Any output bit can have a zero or one depending on the input bits.</p>
+
+<pre class="doc_code">
+  %A = or %X, undef
+  %B = and %X, undef
+Safe:
+  %A = -1
+  %B = 0
+Unsafe:
+  %A = undef
+  %B = undef
+</pre>
+
+<p>These logical operations have bits that are not always affected by the input.
+   For example, if <tt>%X</tt> has a zero bit, then the output of the
+   '<tt>and</tt>' operation will always be a zero for that bit, no matter what
+   the corresponding bit from the '<tt>undef</tt>' is. As such, it is unsafe to
+   optimize or assume that the result of the '<tt>and</tt>' is '<tt>undef</tt>'.
+   However, it is safe to assume that all bits of the '<tt>undef</tt>' could be
+   0, and optimize the '<tt>and</tt>' to 0. Likewise, it is safe to assume that
+   all the bits of the '<tt>undef</tt>' operand to the '<tt>or</tt>' could be
+   set, allowing the '<tt>or</tt>' to be folded to -1.</p>
+
+<pre class="doc_code">
+  %A = select undef, %X, %Y
+  %B = select undef, 42, %Y
+  %C = select %X, %Y, undef
+Safe:
+  %A = %X     (or %Y)
+  %B = 42     (or %Y)
+  %C = %Y
+Unsafe:
+  %A = undef
+  %B = undef
+  %C = undef
+</pre>
+
+<p>This set of examples shows that undefined '<tt>select</tt>' (and conditional
+   branch) conditions can go <em>either way</em>, but they have to come from one
+   of the two operands.  In the <tt>%A</tt> example, if <tt>%X</tt> and
+   <tt>%Y</tt> were both known to have a clear low bit, then <tt>%A</tt> would
+   have to have a cleared low bit. However, in the <tt>%C</tt> example, the
+   optimizer is allowed to assume that the '<tt>undef</tt>' operand could be the
+   same as <tt>%Y</tt>, allowing the whole '<tt>select</tt>' to be
+   eliminated.</p>
+
+<pre class="doc_code">
+  %A = xor undef, undef
+
+  %B = undef
+  %C = xor %B, %B
+
+  %D = undef
+  %E = icmp lt %D, 4
+  %F = icmp gte %D, 4
+
+Safe:
+  %A = undef
+  %B = undef
+  %C = undef
+  %D = undef
+  %E = undef
+  %F = undef
+</pre>
+
+<p>This example points out that two '<tt>undef</tt>' operands are not
+   necessarily the same. This can be surprising to people (and also matches C
+   semantics) where they assume that "<tt>X^X</tt>" is always zero, even
+   if <tt>X</tt> is undefined. This isn't true for a number of reasons, but the
+   short answer is that an '<tt>undef</tt>' "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 necessarily consistent over time. In fact, <tt>%A</tt> and <tt>%C</tt>
+   need to have the same semantics or the core LLVM "replace all uses with"
+   concept would not hold.</p>
+
+<pre class="doc_code">
+  %A = fdiv undef, %X
+  %B = fdiv %X, undef
+Safe:
+  %A = undef
+b: unreachable
+</pre>
+
+<p>These examples show the crucial difference between an <em>undefined
+  value</em> and <em>undefined behavior</em>. An undefined value (like
+  '<tt>undef</tt>') is allowed to have an arbitrary bit-pattern. This means that
+  the <tt>%A</tt> operation can be constant folded to '<tt>undef</tt>', because
+  the '<tt>undef</tt>' could be an SNaN, and <tt>fdiv</tt> is not (currently)
+  defined on SNaN's. However, in the second example, we can make a more
+  aggressive assumption: because the <tt>undef</tt> 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. Because the undefined operation "can't happen", the
+  optimizer can assume that it occurs in dead code.</p>
+
+<pre class="doc_code">
+a:  store undef -> %X
+b:  store %X -> undef
+Safe:
+a: <deleted>
+b: unreachable
+</pre>
+
+<p>These examples reiterate the <tt>fdiv</tt> example: a store <em>of</em> 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 <em>to</em> an undefined location could clobber arbitrary
+   memory, therefore, it has undefined behavior.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="poisonvalues">Poison Values</a>
+</h3>
+
+<div>
+
+<p>Poison values are similar to <a href="#undefvalues">undef values</a>, however
+   they also represent the fact that an instruction or constant expression which
+   cannot evoke side effects has nevertheless detected a condition which results
+   in undefined behavior.</p>
+
+<p>There is currently no way of representing a poison value in the IR; they
+   only exist when produced by operations such as
+   <a href="#i_add"><tt>add</tt></a> with the <tt>nsw</tt> flag.</p>
+
+<p>Poison value behavior is defined in terms of value <i>dependence</i>:</p>
+
+<ul>
+<li>Values other than <a href="#i_phi"><tt>phi</tt></a> nodes depend on
+    their operands.</li>
+
+<li><a href="#i_phi"><tt>Phi</tt></a> nodes depend on the operand corresponding
+    to their dynamic predecessor basic block.</li>
+
+<li>Function arguments depend on the corresponding actual argument values in
+    the dynamic callers of their functions.</li>
+
+<li><a href="#i_call"><tt>Call</tt></a> instructions depend on the
+    <a href="#i_ret"><tt>ret</tt></a> instructions that dynamically transfer
+    control back to them.</li>
+
+<li><a href="#i_invoke"><tt>Invoke</tt></a> instructions depend on the
+    <a href="#i_ret"><tt>ret</tt></a>, <a href="#i_resume"><tt>resume</tt></a>,
+    or exception-throwing call instructions that dynamically transfer control
+    back to them.</li>
+
+<li>Non-volatile loads and stores depend on the most recent stores to all of the
+    referenced memory addresses, following the order in the IR
+    (including loads and stores implied by intrinsics such as
+    <a href="#int_memcpy"><tt>@llvm.memcpy</tt></a>.)</li>
+
+<!-- TODO: In the case of multiple threads, this only applies if the store
+     "happens-before" the load or store. -->
+
+<!-- TODO: floating-point exception state -->
+
+<li>An instruction with externally visible side effects depends on the most
+    recent preceding instruction with externally visible side effects, following
+    the order in the IR. (This includes
+    <a href="#volatile">volatile operations</a>.)</li>
+
+<li>An instruction <i>control-depends</i> on a
+    <a href="#terminators">terminator instruction</a>
+    if the terminator instruction has multiple successors and the instruction
+    is always executed when control transfers to one of the successors, and
+    may not be executed when control is transferred to another.</li>
+
+<li>Additionally, an instruction also <i>control-depends</i> on a terminator
+    instruction if the set of instructions it otherwise depends on would be
+    different if the terminator had transferred control to a different
+    successor.</li>
+
+<li>Dependence is transitive.</li>
+
+</ul>
+
+<p>Poison Values have the same behavior as <a href="#undefvalues">undef values</a>,
+   with the additional affect that any instruction which has a <i>dependence</i>
+   on a poison value has undefined behavior.</p>
+
+<p>Here are some examples:</p>
+
+<pre class="doc_code">
+entry:
+  %poison = sub nuw i32 0, 1           ; Results in a poison value.
+  %still_poison = and i32 %poison, 0   ; 0, but also poison.
+  %poison_yet_again = getelementptr i32* @h, i32 %still_poison
+  store i32 0, i32* %poison_yet_again  ; memory at @h[0] is poisoned
+
+  store i32 %poison, i32* @g           ; Poison value stored to memory.
+  %poison2 = load i32* @g              ; Poison value loaded back from memory.
+
+  store volatile i32 %poison, i32* @g  ; External observation; undefined behavior.
+
+  %narrowaddr = bitcast i32* @g to i16*
+  %wideaddr = bitcast i32* @g to i64*
+  %poison3 = load i16* %narrowaddr     ; Returns a poison value.
+  %poison4 = load i64* %wideaddr       ; Returns a poison value.
+
+  %cmp = icmp slt i32 %poison, 0       ; Returns a poison value.
+  br i1 %cmp, label %true, label %end  ; Branch to either destination.
+
+true:
+  store volatile i32 0, i32* @g        ; This is control-dependent on %cmp, so
+                                       ; it has undefined behavior.
+  br label %end
+
+end:
+  %p = phi i32 [ 0, %entry ], [ 1, %true ]
+                                       ; Both edges into this PHI are
+                                       ; control-dependent on %cmp, so this
+                                       ; always results in a poison value.
+
+  store volatile i32 0, i32* @g        ; This would depend on the store in %true
+                                       ; if %cmp is true, or the store in %entry
+                                       ; otherwise, so this is undefined behavior.
+
+  br i1 %cmp, label %second_true, label %second_end
+                                       ; The same branch again, but this time the
+                                       ; true block doesn't have side effects.
+
+second_true:
+  ; No side effects!
+  ret void
+
+second_end:
+  store volatile i32 0, i32* @g        ; This time, the instruction always depends
+                                       ; on the store in %end. Also, it is
+                                       ; control-equivalent to %end, so this is
+                                       ; well-defined (ignoring earlier undefined
+                                       ; behavior in this example).
+</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="blockaddress">Addresses of Basic Blocks</a>
+</h3>
+
+<div>
+
+<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
+   results in undefined behavior — though, again, comparison against null
+   is ok, and no label is equal to the null pointer. This may 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>
+   instruction.</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>
+
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="constantexprs">Constant Expressions</a>
+</h3>
+
+<div>
+
+<p>Constant expressions are used to allow expressions involving other constants
+   to be used as constants.  Constant expressions may be of
+   any <a href="#t_firstclass">first class</a> type and may involve any LLVM
+   operation that does not have side effects (e.g. load and call are not
+   supported). The following is the syntax for constant expressions:</p>
+
+<dl>
+  <dt><b><tt>trunc (CST to TYPE)</tt></b></dt>
+  <dd>Truncate a constant to another type. The bit size of CST must be larger
+      than the bit size of TYPE. Both types must be integers.</dd>
+
+  <dt><b><tt>zext (CST to TYPE)</tt></b></dt>
+  <dd>Zero extend a constant to another type. The bit size of CST must be
+      smaller than the bit size of TYPE.  Both types must be integers.</dd>
+
+  <dt><b><tt>sext (CST to TYPE)</tt></b></dt>
+  <dd>Sign extend a constant to another type. The bit size of CST must be
+      smaller than the bit size of TYPE.  Both types must be integers.</dd>
+
+  <dt><b><tt>fptrunc (CST to TYPE)</tt></b></dt>
+  <dd>Truncate a floating point constant to another floating point type. The
+      size of CST must be larger than the size of TYPE. Both types must be
+      floating point.</dd>
+
+  <dt><b><tt>fpext (CST to TYPE)</tt></b></dt>
+  <dd>Floating point extend a constant to another type. The size of CST must be
+      smaller or equal to the size of TYPE. Both types must be floating
+      point.</dd>
+
+  <dt><b><tt>fptoui (CST to TYPE)</tt></b></dt>
+  <dd>Convert a floating point constant to the corresponding unsigned integer
+      constant. TYPE must be a scalar or vector integer type. CST must be of
+      scalar or vector floating point type. Both CST and TYPE must be scalars,
+      or vectors of the same number of elements. If the value won't fit in the
+      integer type, the results are undefined.</dd>
+
+  <dt><b><tt>fptosi (CST to TYPE)</tt></b></dt>
+  <dd>Convert a floating point constant to the corresponding signed integer
+      constant.  TYPE must be a scalar or vector integer type. CST must be of
+      scalar or vector floating point type. Both CST and TYPE must be scalars,
+      or vectors of the same number of elements. If the value won't fit in the
+      integer type, the results are undefined.</dd>
+
+  <dt><b><tt>uitofp (CST to TYPE)</tt></b></dt>
+  <dd>Convert an unsigned integer constant to the corresponding floating point
+      constant. TYPE must be a scalar or vector floating point type. CST must be
+      of scalar or vector integer type. Both CST and TYPE must be scalars, or
+      vectors of the same number of elements. If the value won't fit in the
+      floating point type, the results are undefined.</dd>
+
+  <dt><b><tt>sitofp (CST to TYPE)</tt></b></dt>
+  <dd>Convert a signed integer constant to the corresponding floating point
+      constant. TYPE must be a scalar or vector floating point type. CST must be
+      of scalar or vector integer type. Both CST and TYPE must be scalars, or
+      vectors of the same number of elements. If the value won't fit in the
+      floating point type, the results are undefined.</dd>
+
+  <dt><b><tt>ptrtoint (CST to TYPE)</tt></b></dt>
+  <dd>Convert a pointer typed constant to the corresponding integer constant
+      <tt>TYPE</tt> must be an integer type. <tt>CST</tt> must be of pointer
+      type. The <tt>CST</tt> value is zero extended, truncated, or unchanged to
+      make it fit in <tt>TYPE</tt>.</dd>
+
+  <dt><b><tt>inttoptr (CST to TYPE)</tt></b></dt>
+  <dd>Convert an integer constant to a pointer constant.  TYPE must be a pointer
+      type.  CST must be of integer type. The CST value is zero extended,
+      truncated, or unchanged to make it fit in a pointer size. This one is
+      <i>really</i> dangerous!</dd>
+
+  <dt><b><tt>bitcast (CST to TYPE)</tt></b></dt>
+  <dd>Convert a constant, CST, to another TYPE. The constraints of the operands
+      are the same as those for the <a href="#i_bitcast">bitcast
+      instruction</a>.</dd>
+
+  <dt><b><tt>getelementptr (CSTPTR, IDX0, IDX1, ...)</tt></b></dt>
+  <dt><b><tt>getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)</tt></b></dt>
+  <dd>Perform the <a href="#i_getelementptr">getelementptr operation</a> on
+      constants.  As with the <a href="#i_getelementptr">getelementptr</a>
+      instruction, the index list may have zero or more indexes, which are
+      required to make sense for the type of "CSTPTR".</dd>
+
+  <dt><b><tt>select (COND, VAL1, VAL2)</tt></b></dt>
+  <dd>Perform the <a href="#i_select">select operation</a> on constants.</dd>
+
+  <dt><b><tt>icmp COND (VAL1, VAL2)</tt></b></dt>
+  <dd>Performs the <a href="#i_icmp">icmp operation</a> on constants.</dd>
+
+  <dt><b><tt>fcmp COND (VAL1, VAL2)</tt></b></dt>
+  <dd>Performs the <a href="#i_fcmp">fcmp operation</a> on constants.</dd>
+
+  <dt><b><tt>extractelement (VAL, IDX)</tt></b></dt>
+  <dd>Perform the <a href="#i_extractelement">extractelement operation</a> on
+      constants.</dd>
+
+  <dt><b><tt>insertelement (VAL, ELT, IDX)</tt></b></dt>
+  <dd>Perform the <a href="#i_insertelement">insertelement operation</a> on
+    constants.</dd>
+
+  <dt><b><tt>shufflevector (VEC1, VEC2, IDXMASK)</tt></b></dt>
+  <dd>Perform the <a href="#i_shufflevector">shufflevector operation</a> on
+      constants.</dd>
+
+  <dt><b><tt>extractvalue (VAL, IDX0, IDX1, ...)</tt></b></dt>
+  <dd>Perform the <a href="#i_extractvalue">extractvalue operation</a> on
+    constants. The index list is interpreted in a similar manner as indices in
+    a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one
+    index value must be specified.</dd>
+
+  <dt><b><tt>insertvalue (VAL, ELT, IDX0, IDX1, ...)</tt></b></dt>
+  <dd>Perform the <a href="#i_insertvalue">insertvalue operation</a> on
+    constants. The index list is interpreted in a similar manner as indices in
+    a '<a href="#i_getelementptr">getelementptr</a>' operation. At least one
+    index value must be specified.</dd>
+
+  <dt><b><tt>OPCODE (LHS, RHS)</tt></b></dt>
+  <dd>Perform the specified operation of the LHS and RHS constants. OPCODE may
+      be any of the <a href="#binaryops">binary</a>
+      or <a href="#bitwiseops">bitwise binary</a> operations.  The constraints
+      on operands are the same as those for the corresponding instruction
+      (e.g. no bitwise operations on floating point values are allowed).</dd>
+</dl>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="othervalues">Other Values</a></h2>
+<!-- *********************************************************************** -->
+<div>
+<!-- ======================================================================= -->
+<h3>
+<a name="inlineasm">Inline Assembler Expressions</a>
+</h3>
+
+<div>
+
+<p>LLVM supports inline assembler expressions (as opposed
+   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), 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>
+
+<pre class="doc_code">
+i32 (i32) asm "bswap $0", "=r,r"
+</pre>
+
+<p>Inline assembler expressions may <b>only</b> be used as the callee operand of
+   a <a href="#i_call"><tt>call</tt></a> or an
+   <a href="#i_invoke"><tt>invoke</tt></a> instruction.
+   Thus, typically we have:</p>
+
+<pre class="doc_code">
+%X = call i32 asm "<a href="#int_bswap">bswap</a> $0", "=r,r"(i32 %Y)
+</pre>
+
+<p>Inline asms with side effects not visible in the constraint list must be
+   marked as having side effects.  This is done through the use of the
+   '<tt>sideeffect</tt>' keyword, like so:</p>
+
+<pre class="doc_code">
+call void asm sideeffect "eieio", ""()
+</pre>
+
+<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>
+
+<pre class="doc_code">
+call void asm alignstack "eieio", ""()
+</pre>
+
+<p>Inline asms also support using non-standard assembly dialects.  The assumed
+   dialect is ATT.  When the '<tt>inteldialect</tt>' keyword is present, the
+   inline asm is using the Intel dialect.  Currently, ATT and Intel are the
+   only supported dialects.  An example is:</p>
+
+<pre class="doc_code">
+call void asm inteldialect "eieio", ""()
+</pre>
+
+<p>If multiple keywords appear the '<tt>sideeffect</tt>' keyword must come
+   first, the '<tt>alignstack</tt>' keyword second and the
+   '<tt>inteldialect</tt>' keyword last.</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
+   another document that covers inline asm from a holistic perspective.</p>
+  -->
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="inlineasm_md">Inline Asm Metadata</a>
+</h4>
+
+<div>
+
+<p>The call instructions that wrap inline asm nodes may have a
+   "<tt>!srcloc</tt>" MDNode attached to it that contains a list of constant
+   integers.  If present, the code generator will use the integer as the
+   location cookie value when report errors through the <tt>LLVMContext</tt>
+   error reporting mechanisms.  This allows a front-end to correlate backend
+   errors that occur with inline asm back to the source code that produced it.
+   For example:</p>
+
+<pre class="doc_code">
+call void asm sideeffect "something bad", ""()<b>, !srcloc !42</b>
+...
+!42 = !{ i32 1234567 }
+</pre>
+
+<p>It is up to the front-end to make sense of the magic numbers it places in the
+   IR. If the MDNode contains multiple constants, the code generator will use
+   the one that corresponds to the line of the asm that the error occurs on.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="metadata">Metadata Nodes and Metadata Strings</a>
+</h3>
+
+<div>
+
+<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 "<tt>\xx</tt>" where
+   "<tt>xx</tt>" 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). Metadata nodes can have any values as their operand. For
+   example:</p>
+
+<div class="doc_code">
+<pre>
+!{ metadata !"test\00", i32 10}
+</pre>
+</div>
+
+<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:</p>
+
+<div class="doc_code">
+<pre>
+!foo =  metadata !{!4, !3}
+</pre>
+</div>
+
+<p>Metadata can be used as function arguments. Here <tt>llvm.dbg.value</tt> 
+   function is using two metadata arguments:</p>
+
+<div class="doc_code">
+<pre>
+call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
+</pre>
+</div>
+
+<p>Metadata can be attached with an instruction. Here metadata <tt>!21</tt> is
+   attached to the <tt>add</tt> instruction using the <tt>!dbg</tt>
+   identifier:</p>
+
+<div class="doc_code">
+<pre>
+%indvar.next = add i64 %indvar, 1, !dbg !21
+</pre>
+</div>
+
+<p>More information about specific metadata nodes recognized by the optimizers
+   and code generator is found below.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="tbaa">'<tt>tbaa</tt>' Metadata</a>
+</h4>
+
+<div>
+
+<p>In LLVM IR, memory does not have types, so LLVM's own type system is not
+   suitable for doing TBAA. Instead, metadata is added to the IR to describe
+   a type system of a higher level language. This can be used to implement
+   typical C/C++ TBAA, but it can also be used to implement custom alias
+   analysis behavior for other languages.</p>
+
+<p>The current metadata format is very simple. TBAA metadata nodes have up to
+   three fields, e.g.:</p>
+
+<div class="doc_code">
+<pre>
+!0 = metadata !{ metadata !"an example type tree" }
+!1 = metadata !{ metadata !"int", metadata !0 }
+!2 = metadata !{ metadata !"float", metadata !0 }
+!3 = metadata !{ metadata !"const float", metadata !2, i64 1 }
+</pre>
+</div>
+
+<p>The first field is an identity field. It can be any value, usually
+   a metadata string, which uniquely identifies the type. The most important
+   name in the tree is the name of the root node. Two trees with
+   different root node names are entirely disjoint, even if they
+   have leaves with common names.</p>
+
+<p>The second field identifies the type's parent node in the tree, or
+   is null or omitted for a root node. A type is considered to alias
+   all of its descendants and all of its ancestors in the tree. Also,
+   a type is considered to alias all types in other trees, so that
+   bitcode produced from multiple front-ends is handled conservatively.</p>
+
+<p>If the third field is present, it's an integer which if equal to 1
+   indicates that the type is "constant" (meaning
+   <tt>pointsToConstantMemory</tt> should return true; see
+   <a href="AliasAnalysis.html#OtherItfs">other useful
+   <tt>AliasAnalysis</tt> methods</a>).</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="tbaa.struct">'<tt>tbaa.struct</tt>' Metadata</a>
+</h4>
+
+<div>
+
+<p>The <a href="#int_memcpy"><tt>llvm.memcpy</tt></a> is often used to implement
+aggregate assignment operations in C and similar languages, however it is
+defined to copy a contiguous region of memory, which is more than strictly
+necessary for aggregate types which contain holes due to padding. Also, it
+doesn't contain any TBAA information about the fields of the aggregate.</p>
+
+<p><tt>!tbaa.struct</tt> metadata can describe which memory subregions in a memcpy
+are padding and what the TBAA tags of the struct are.</p>
+
+<p>The current metadata format is very simple. <tt>!tbaa.struct</tt> metadata nodes
+   are a list of operands which are in conceptual groups of three. For each
+   group of three, the first operand gives the byte offset of a field in bytes,
+   the second gives its size in bytes, and the third gives its
+   tbaa tag. e.g.:</p>
+
+<div class="doc_code">
+<pre>
+!4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 }
+</pre>
+</div>
+
+<p>This describes a struct with two fields. The first is at offset 0 bytes
+   with size 4 bytes, and has tbaa tag !1. The second is at offset 8 bytes
+   and has size 4 bytes and has tbaa tag !2.</p>
+
+<p>Note that the fields need not be contiguous. In this example, there is a
+   4 byte gap between the two fields. This gap represents padding which
+   does not carry useful data and need not be preserved.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="fpmath">'<tt>fpmath</tt>' Metadata</a>
+</h4>
+ 
+<div>
+
+<p><tt>fpmath</tt> metadata may be attached to any instruction of floating point
+  type.  It can be used to express the maximum acceptable error in the result of
+  that instruction, in ULPs, thus potentially allowing the compiler to use a
+  more efficient but less accurate method of computing it.  ULP is defined as
+  follows:</p>
+
+<blockquote>
+
+<p>If <tt>x</tt> is a real number that lies between two finite consecutive
+   floating-point numbers <tt>a</tt> and <tt>b</tt>, without being equal to one
+   of them, then <tt>ulp(x) = |b - a|</tt>, otherwise <tt>ulp(x)</tt> is the
+   distance between the two non-equal finite floating-point numbers nearest
+   <tt>x</tt>. Moreover, <tt>ulp(NaN)</tt> is <tt>NaN</tt>.</p>
+
+</blockquote>
+
+<p>The metadata node shall consist of a single positive floating point number
+   representing the maximum relative error, for example:</p>
+
+<div class="doc_code">
+<pre>
+!0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
+</pre>
+</div>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="range">'<tt>range</tt>' Metadata</a>
+</h4>
+
+<div>
+<p><tt>range</tt> metadata may be attached only to loads of integer types. It
+   expresses the possible ranges the loaded value is in. The ranges are
+   represented with a flattened list of integers. The loaded value is known to
+   be in the union of the ranges defined by each consecutive pair. Each pair
+   has the following properties:</p>
+<ul>
+   <li>The type must match the type loaded by the instruction.</li>
+   <li>The pair <tt>a,b</tt> represents the range <tt>[a,b)</tt>.</li>
+   <li>Both <tt>a</tt> and <tt>b</tt> are constants.</li>
+   <li>The range is allowed to wrap.</li>
+   <li>The range should not represent the full or empty set. That is,
+       <tt>a!=b</tt>. </li>
+</ul>
+<p> In addition, the pairs must be in signed order of the lower bound and
+  they must be non-contiguous.</p>
+
+<p>Examples:</p>
+<div class="doc_code">
+<pre>
+  %a = load i8* %x, align 1, !range !0 ; Can only be 0 or 1
+  %b = load i8* %y, align 1, !range !1 ; Can only be 255 (-1), 0 or 1
+  %c = load i8* %z, align 1, !range !2 ; Can only be 0, 1, 3, 4 or 5
+  %d = load i8* %z, align 1, !range !3 ; Can only be -2, -1, 3, 4 or 5
+...
+!0 = metadata !{ i8 0, i8 2 }
+!1 = metadata !{ i8 255, i8 2 }
+!2 = metadata !{ i8 0, i8 2, i8 3, i8 6 }
+!3 = metadata !{ i8 -2, i8 0, i8 3, i8 6 }
+</pre>
+</div>
+</div>
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="module_flags">Module Flags Metadata</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Information about the module as a whole is difficult to convey to LLVM's
+   subsystems. The LLVM IR isn't sufficient to transmit this
+   information. The <tt>llvm.module.flags</tt> named metadata exists in order to
+   facilitate this. These flags are in the form of key / value pairs —
+   much like a dictionary — making it easy for any subsystem who cares
+   about a flag to look it up.</p>
+
+<p>The <tt>llvm.module.flags</tt> metadata contains a list of metadata
+   triplets. Each triplet has the following form:</p>
+
+<ul>
+  <li>The first element is a <i>behavior</i> flag, which specifies the behavior
+      when two (or more) modules are merged together, and it encounters two (or
+      more) metadata with the same ID. The supported behaviors are described
+      below.</li>
+
+  <li>The second element is a metadata string that is a unique ID for the
+      metadata. How each ID is interpreted is documented below.</li>
+
+  <li>The third element is the value of the flag.</li>
+</ul>
+
+<p>When two (or more) modules are merged together, the resulting
+   <tt>llvm.module.flags</tt> metadata is the union of the
+   modules' <tt>llvm.module.flags</tt> metadata. The only exception being a flag
+   with the <i>Override</i> behavior, which may override another flag's value
+   (see below).</p>
+
+<p>The following behaviors are supported:</p>
+
+<table border="1" cellspacing="0" cellpadding="4">
+  <tbody>
+    <tr>
+      <th>Value</th>
+      <th>Behavior</th>
+    </tr>
+    <tr>
+      <td>1</td>
+      <td align="left">
+        <dl>
+          <dt><b>Error</b></dt>
+          <dd>Emits an error if two values disagree. It is an error to have an ID
+              with both an Error and a Warning behavior.</dd>
+        </dl>
+      </td>
+    </tr>
+    <tr>
+      <td>2</td>
+      <td align="left">
+        <dl>
+          <dt><b>Warning</b></dt>
+          <dd>Emits a warning if two values disagree.</dd>
+        </dl>
+      </td>
+    </tr>
+    <tr>
+      <td>3</td>
+      <td align="left">
+        <dl>
+          <dt><b>Require</b></dt>
+          <dd>Emits an error when the specified value is not present or doesn't
+              have the specified value. It is an error for two (or more)
+              <tt>llvm.module.flags</tt> with the same ID to have the Require
+              behavior but different values. There may be multiple Require flags
+              per ID.</dd>
+        </dl>
+      </td>
+    </tr>
+    <tr>
+      <td>4</td>
+      <td align="left">
+        <dl>
+          <dt><b>Override</b></dt>
+          <dd>Uses the specified value if the two values disagree. It is an
+              error for two (or more) <tt>llvm.module.flags</tt> with the same
+              ID to have the Override behavior but different values.</dd>
+        </dl>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<p>An example of module flags:</p>
+
+<pre class="doc_code">
+!0 = metadata !{ i32 1, metadata !"foo", i32 1 }
+!1 = metadata !{ i32 4, metadata !"bar", i32 37 }
+!2 = metadata !{ i32 2, metadata !"qux", i32 42 }
+!3 = metadata !{ i32 3, metadata !"qux",
+  metadata !{
+    metadata !"foo", i32 1
+  }
+}
+!llvm.module.flags = !{ !0, !1, !2, !3 }
+</pre>
+
+<ul>
+  <li><p>Metadata <tt>!0</tt> has the ID <tt>!"foo"</tt> and the value '1'. The
+         behavior if two or more <tt>!"foo"</tt> flags are seen is to emit an
+         error if their values are not equal.</p></li>
+
+  <li><p>Metadata <tt>!1</tt> has the ID <tt>!"bar"</tt> and the value '37'. The
+         behavior if two or more <tt>!"bar"</tt> flags are seen is to use the
+         value '37' if their values are not equal.</p></li>
+
+  <li><p>Metadata <tt>!2</tt> has the ID <tt>!"qux"</tt> and the value '42'. The
+         behavior if two or more <tt>!"qux"</tt> flags are seen is to emit a
+         warning if their values are not equal.</p></li>
+
+  <li><p>Metadata <tt>!3</tt> has the ID <tt>!"qux"</tt> and the value:</p>
+
+<pre class="doc_code">
+metadata !{ metadata !"foo", i32 1 }
+</pre>
+
+      <p>The behavior is to emit an error if the <tt>llvm.module.flags</tt> does
+         not contain a flag with the ID <tt>!"foo"</tt> that has the value
+         '1'. If two or more <tt>!"qux"</tt> flags exist, then they must have
+         the same value or an error will be issued.</p></li>
+</ul>
+
+
+<!-- ======================================================================= -->
+<h3>
+<a name="objc_gc_flags">Objective-C Garbage Collection Module Flags Metadata</a>
+</h3>
+
+<div>
+
+<p>On the Mach-O platform, Objective-C stores metadata about garbage collection
+   in a special section called "image info". The metadata consists of a version
+   number and a bitmask specifying what types of garbage collection are
+   supported (if any) by the file. If two or more modules are linked together
+   their garbage collection metadata needs to be merged rather than appended
+   together.</p>
+
+<p>The Objective-C garbage collection module flags metadata consists of the
+   following key-value pairs:</p>
+
+<table border="1" cellspacing="0" cellpadding="4">
+  <col width="30%">
+  <tbody>
+    <tr>
+      <th>Key</th>
+      <th>Value</th>
+    </tr>
+    <tr>
+      <td><tt>Objective-C Version</tt></td>
+      <td align="left"><b>[Required]</b> — The Objective-C ABI
+         version. Valid values are 1 and 2.</td>
+    </tr>
+    <tr>
+      <td><tt>Objective-C Image Info Version</tt></td>
+      <td align="left"><b>[Required]</b> — The version of the image info
+         section. Currently always 0.</td>
+    </tr>
+    <tr>
+      <td><tt>Objective-C Image Info Section</tt></td>
+      <td align="left"><b>[Required]</b> — The section to place the
+         metadata. Valid values are <tt>"__OBJC, __image_info, regular"</tt> for
+         Objective-C ABI version 1, and <tt>"__DATA,__objc_imageinfo, regular,
+         no_dead_strip"</tt> for Objective-C ABI version 2.</td>
+    </tr>
+    <tr>
+      <td><tt>Objective-C Garbage Collection</tt></td>
+      <td align="left"><b>[Required]</b> — Specifies whether garbage
+          collection is supported or not. Valid values are 0, for no garbage
+          collection, and 2, for garbage collection supported.</td>
+    </tr>
+    <tr>
+      <td><tt>Objective-C GC Only</tt></td>
+      <td align="left"><b>[Optional]</b> — Specifies that only garbage
+         collection is supported. If present, its value must be 6. This flag
+         requires that the <tt>Objective-C Garbage Collection</tt> flag have the
+         value 2.</td>
+    </tr>
+  </tbody>
+</table>
+
+<p>Some important flag interactions:</p>
+
+<ul>
+  <li>If a module with <tt>Objective-C Garbage Collection</tt> set to 0 is
+      merged with a module with <tt>Objective-C Garbage Collection</tt> set to
+      2, then the resulting module has the <tt>Objective-C Garbage
+      Collection</tt> flag set to 0.</li>
+
+  <li>A module with <tt>Objective-C Garbage Collection</tt> set to 0 cannot be
+      merged with a module with <tt>Objective-C GC Only</tt> set to 6.</li>
+</ul>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="intrinsic_globals">Intrinsic Global Variables</a>
+</h2>
+<!-- *********************************************************************** -->
+<div>
+<p>LLVM has a number of "magic" global variables that contain data that affect
+code generation or other IR semantics.  These are documented here.  All globals
+of this sort should have a section specified as "<tt>llvm.metadata</tt>".  This
+section and all globals that start with "<tt>llvm.</tt>" are reserved for use
+by LLVM.</p>
+
+<!-- ======================================================================= -->
+<h3>
+<a name="intg_used">The '<tt>llvm.used</tt>' Global Variable</a>
+</h3>
+
+<div>
+
+<p>The <tt>@llvm.used</tt> global is an array with i8* element type which has <a
+href="#linkage_appending">appending linkage</a>.  This array contains a list of
+pointers to global variables and functions which may optionally have a pointer
+cast formed of bitcast or getelementptr.  For example, a legal use of it is:</p>
+
+<div class="doc_code">
+<pre>
+ at X = global i8 4
+ at Y = global i32 123
+
+ at llvm.used = appending global [2 x i8*] [
+   i8* @X,
+   i8* bitcast (i32* @Y to i8*)
+], section "llvm.metadata"
+</pre>
+</div>
+
+<p>If a global variable appears in the <tt>@llvm.used</tt> list, then the
+   compiler, assembler, and linker are required to treat the symbol as if there
+   is a reference to the global that it cannot see.  For example, if a variable
+   has internal linkage and no references other than that from
+   the <tt>@llvm.used</tt> list, it cannot be deleted.  This is commonly used to
+   represent references from inline asms and other things the compiler cannot
+   "see", and corresponds to "<tt>attribute((used))</tt>" in GNU C.</p>
+
+<p>On some targets, the code generator must emit a directive to the assembler or
+   object file to prevent the assembler and linker from molesting the
+   symbol.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="intg_compiler_used">
+    The '<tt>llvm.compiler.used</tt>' Global Variable
+  </a>
+</h3>
+
+<div>
+
+<p>The <tt>@llvm.compiler.used</tt> directive is the same as the
+   <tt>@llvm.used</tt> directive, except that it only prevents the compiler from
+   touching the symbol.  On targets that support it, this allows an intelligent
+   linker to optimize references to the symbol without being impeded as it would
+   be by <tt>@llvm.used</tt>.</p>
+
+<p>This is a rare construct that should only be used in rare circumstances, and
+   should not be exposed to source languages.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+<a name="intg_global_ctors">The '<tt>llvm.global_ctors</tt>' Global Variable</a>
+</h3>
+
+<div>
+
+<div class="doc_code">
+<pre>
+%0 = type { i32, void ()* }
+ at llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor }]
+</pre>
+</div>
+
+<p>The <tt>@llvm.global_ctors</tt> array contains a list of constructor
+   functions and associated priorities.  The functions referenced by this array
+   will be called in ascending order of priority (i.e. lowest first) when the
+   module is loaded.  The order of functions with the same priority is not
+   defined.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+<a name="intg_global_dtors">The '<tt>llvm.global_dtors</tt>' Global Variable</a>
+</h3>
+
+<div>
+
+<div class="doc_code">
+<pre>
+%0 = type { i32, void ()* }
+ at llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor }]
+</pre>
+</div>
+
+<p>The <tt>@llvm.global_dtors</tt> array contains a list of destructor functions
+   and associated priorities.  The functions referenced by this array will be
+   called in descending order of priority (i.e. highest first) when the module
+   is loaded.  The order of functions with the same priority is not defined.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="instref">Instruction Reference</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>The LLVM instruction set consists of several different classifications of
+   instructions: <a href="#terminators">terminator
+   instructions</a>, <a href="#binaryops">binary instructions</a>,
+   <a href="#bitwiseops">bitwise binary instructions</a>,
+   <a href="#memoryops">memory instructions</a>, and
+   <a href="#otherops">other instructions</a>.</p>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="terminators">Terminator Instructions</a>
+</h3>
+
+<div>
+
+<p>As mentioned <a href="#functionstructure">previously</a>, every basic block
+   in a program ends with a "Terminator" instruction, which indicates which
+   block should be executed after the current block is finished. These
+   terminator instructions 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>
+
+<p>The terminator instructions are: 
+   '<a href="#i_ret"><tt>ret</tt></a>', 
+   '<a href="#i_br"><tt>br</tt></a>',
+   '<a href="#i_switch"><tt>switch</tt></a>', 
+   '<a href="#i_indirectbr"><tt>indirectbr</tt></a>',
+   '<a href="#i_invoke"><tt>invoke</tt></a>', 
+   '<a href="#i_resume"><tt>resume</tt></a>', and 
+   '<a href="#i_unreachable"><tt>unreachable</tt></a>'.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_ret">'<tt>ret</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  ret <type> <value>       <i>; Return a value from a non-void function</i>
+  ret void                 <i>; Return from void function</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>ret</tt>' instruction is used to return control flow (and optionally
+   a value) from a function back to the caller.</p>
+
+<p>There are two forms of the '<tt>ret</tt>' instruction: one that returns a
+   value and then causes control flow, and one that just causes control flow to
+   occur.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>ret</tt>' instruction optionally accepts a single argument, the
+   return value. The type of the return value must be a
+   '<a href="#t_firstclass">first class</a>' type.</p>
+
+<p>A function is not <a href="#wellformed">well formed</a> if it it has a
+   non-void return type and contains a '<tt>ret</tt>' instruction with no return
+   value or a return value with a type that does not match its type, or if it
+   has a void return type and contains a '<tt>ret</tt>' instruction with a
+   return value.</p>
+
+<h5>Semantics:</h5>
+<p>When the '<tt>ret</tt>' instruction is executed, control flow returns back to
+   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 of the "normal" 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>
+  ret i32 5                       <i>; Return an integer value of 5</i>
+  ret void                        <i>; Return from a void function</i>
+  ret { i32, i8 } { i32 4, i8 2 } <i>; Return a struct of values 4 and 2</i>
+</pre>
+
+</div>
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_br">'<tt>br</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  br i1 <cond>, label <iftrue>, label <iffalse>
+  br label <dest>          <i>; Unconditional branch</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>br</tt>' instruction is used to cause control flow to transfer to a
+   different basic block in the current function.  There are two forms of this
+   instruction, corresponding to a conditional branch and an unconditional
+   branch.</p>
+
+<h5>Arguments:</h5>
+<p>The conditional branch form of the '<tt>br</tt>' instruction takes a single
+   '<tt>i1</tt>' value and two '<tt>label</tt>' values.  The unconditional form
+   of the '<tt>br</tt>' instruction takes a single '<tt>label</tt>' value as a
+   target.</p>
+
+<h5>Semantics:</h5>
+<p>Upon execution of a conditional '<tt>br</tt>' instruction, the '<tt>i1</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>
+
+<h5>Example:</h5>
+<pre>
+Test:
+  %cond = <a href="#i_icmp">icmp</a> eq i32 %a, %b
+  br i1 %cond, label %IfEqual, label %IfUnequal
+IfEqual:
+  <a href="#i_ret">ret</a> i32 1
+IfUnequal:
+  <a href="#i_ret">ret</a> i32 0
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_switch">'<tt>switch</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
+</pre>
+
+<h5>Overview:</h5>
+<p>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>
+
+<h5>Arguments:</h5>
+<p>The '<tt>switch</tt>' instruction uses three parameters: an integer
+   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 table is not allowed to contain duplicate constant entries.</p>
+
+<h5>Semantics:</h5>
+<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
+   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
+   <tt>switch</tt> instruction, this instruction may be code generated in
+   different ways.  For example, it could be 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_zext">zext</a> i1 %value to i32
+ switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
+
+ <i>; Emulate an unconditional br instruction</i>
+ switch i32 0, label %dest [ ]
+
+ <i>; Implement a jump table:</i>
+ switch i32 %val, label %otherwise [ i32 0, label %onzero
+                                     i32 1, label %onone
+                                     i32 2, label %ontwo ]
+</pre>
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_indirectbr">'<tt>indirectbr</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]
+</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>
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_invoke">'<tt>invoke</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = invoke [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] <ptr to function ty> <function ptr val>(<function args>) [<a href="#fnattrs">fn attrs</a>]
+                to label <normal label> unwind label <exception label>
+</pre>
+
+<h5>Overview:</h5>
+<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>' label or the '<tt>exception</tt>' label.  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 via the "<a href="#i_resume"><tt>resume</tt></a>"
+   instruction or other exception handling mechanism, control is interrupted and
+   continued at the dynamically nearest "exception" label.</p>
+
+<p>The '<tt>exception</tt>' label is a
+   <i><a href="ExceptionHandling.html#overview">landing pad</a></i> for the
+   exception. As such, '<tt>exception</tt>' label is required to have the
+   "<a href="#i_landingpad"><tt>landingpad</tt></a>" instruction, which contains
+   the information about the behavior of the program after unwinding
+   happens, as its first non-PHI instruction. The restrictions on the
+   "<tt>landingpad</tt>" instruction's tightly couples it to the
+   "<tt>invoke</tt>" instruction, so that the important information contained
+   within the "<tt>landingpad</tt>" instruction can't be lost through normal
+   code motion.</p>
+
+<h5>Arguments:</h5>
+<p>This instruction requires several arguments:</p>
+
+<ol>
+  <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>
+
+  <li>The optional <a href="#paramattrs">Parameter Attributes</a> list for
+      return values. Only '<tt>zeroext</tt>', '<tt>signext</tt>', and
+      '<tt>inreg</tt>' attributes are valid here.</li>
+
+  <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.</li>
+
+  <li>'<tt>function ptr val</tt>': An LLVM value containing a pointer to a
+      function to be invoked. </li>
+
+  <li>'<tt>function args</tt>': argument list whose types match the function
+      signature argument types and parameter attributes. All arguments must be
+      of <a href="#t_firstclass">first class</a> type. If the function
+      signature indicates the function accepts a variable number of arguments,
+      the extra arguments can be specified.</li>
+
+  <li>'<tt>normal label</tt>': the label reached when the called function
+      executes a '<tt><a href="#i_ret">ret</a></tt>' instruction. </li>
+
+  <li>'<tt>exception label</tt>': the label reached when a callee returns via
+      the <a href="#i_resume"><tt>resume</tt></a> instruction or other exception
+      handling mechanism.</li>
+
+  <li>The optional <a href="#fnattrs">function attributes</a> list. Only
+      '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
+      '<tt>readnone</tt>' attributes are valid here.</li>
+</ol>
+
+<h5>Semantics:</h5>
+<p>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 establishes an association with a label, which
+   is used by the runtime library to unwind the stack.</p>
+
+<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>
+
+<p>For the purposes of the SSA form, the definition of the value returned by the
+   '<tt>invoke</tt>' instruction is deemed to occur on the edge from the current
+   block to the "normal" label. If the callee unwinds then no return value is
+   available.</p>
+
+<h5>Example:</h5>
+<pre>
+  %retval = invoke i32 @Test(i32 15) to label %Continue
+              unwind label %TestCleanup              <i>; {i32}:retval set</i>
+  %retval = invoke <a href="#callingconv">coldcc</a> i32 %Testfnptr(i32 15) to label %Continue
+              unwind label %TestCleanup              <i>; {i32}:retval set</i>
+</pre>
+
+</div>
+
+ <!-- _______________________________________________________________________ -->
+ 
+<h4>
+  <a name="i_resume">'<tt>resume</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  resume <type> <value>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>resume</tt>' instruction is a terminator instruction that has no
+   successors.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>resume</tt>' instruction requires one argument, which must have the
+   same type as the result of any '<tt>landingpad</tt>' instruction in the same
+   function.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>resume</tt>' instruction resumes propagation of an existing
+   (in-flight) exception whose unwinding was interrupted with
+   a <a href="#i_landingpad"><tt>landingpad</tt></a> instruction.</p>
+
+<h5>Example:</h5>
+<pre>
+  resume { i8*, i32 } %exn
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+
+<h4>
+  <a name="i_unreachable">'<tt>unreachable</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  unreachable
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>unreachable</tt>' instruction has no defined semantics.  This
+   instruction is used to inform the optimizer that a particular portion of the
+   code is not reachable.  This can be used to indicate that the code after a
+   no-return function cannot be reached, and other facts.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>unreachable</tt>' instruction has no defined semantics.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="binaryops">Binary Operations</a>
+</h3>
+
+<div>
+
+<p>Binary operators are used to do most of the computation in a program.  They
+   require two operands of the same type, execute an operation on them, and
+   produce a single value.  The operands might represent multiple data, as is
+   the case with the <a href="#t_vector">vector</a> data type.  The result value
+   has the same type as its operands.</p>
+
+<p>There are several different binary operators:</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_add">'<tt>add</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = add <ty> <op1>, <op2>          <i>; yields {ty}:result</i>
+  <result> = add nuw <ty> <op1>, <op2>      <i>; yields {ty}:result</i>
+  <result> = add nsw <ty> <op1>, <op2>      <i>; yields {ty}:result</i>
+  <result> = add nuw nsw <ty> <op1>, <op2>  <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>add</tt>' instruction returns the sum of its two operands.</p>
+
+<h5>Arguments:</h5>
+<p>The two arguments to the '<tt>add</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 sum of the two operands.</p>
+
+<p>If the sum has unsigned overflow, the result returned is the mathematical
+   result modulo 2<sup>n</sup>, where n is the bit width of the result.</p>
+
+<p>Because LLVM integers use a two's complement representation, this instruction
+   is appropriate for both signed and unsigned integers.</p>
+
+<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
+   and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
+   <tt>nsw</tt> keywords are present, the result value of the <tt>add</tt>
+   is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow,
+   respectively, occurs.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = add i32 4, %var          <i>; yields {i32}:result = 4 + %var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_fadd">'<tt>fadd</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = fadd <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fadd</tt>' instruction returns the sum of its two operands.</p>
+
+<h5>Arguments:</h5>
+<p>The two arguments to the '<tt>fadd</tt>' instruction must be
+   <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
+   floating point values. Both arguments must have identical types.</p>
+
+<h5>Semantics:</h5>
+<p>The value produced is the floating point sum of the two operands.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = fadd float 4.0, %var          <i>; yields {float}:result = 4.0 + %var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_sub">'<tt>sub</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = sub <ty> <op1>, <op2>          <i>; yields {ty}:result</i>
+  <result> = sub nuw <ty> <op1>, <op2>      <i>; yields {ty}:result</i>
+  <result> = sub nsw <ty> <op1>, <op2>      <i>; yields {ty}:result</i>
+  <result> = sub nuw nsw <ty> <op1>, <op2>  <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>sub</tt>' instruction returns the difference of its two
+   operands.</p>
+
+<p>Note that the '<tt>sub</tt>' instruction is used to represent the
+   '<tt>neg</tt>' instruction present in most other intermediate
+   representations.</p>
+
+<h5>Arguments:</h5>
+<p>The two arguments to the '<tt>sub</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 difference of the two operands.</p>
+
+<p>If the difference has unsigned overflow, the result returned is the
+   mathematical result modulo 2<sup>n</sup>, where n is the bit width of the
+   result.</p>
+
+<p>Because LLVM integers use a two's complement representation, this instruction
+   is appropriate for both signed and unsigned integers.</p>
+
+<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
+   and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
+   <tt>nsw</tt> keywords are present, the result value of the <tt>sub</tt>
+   is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow,
+   respectively, occurs.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = sub i32 4, %var          <i>; yields {i32}:result = 4 - %var</i>
+  <result> = sub i32 0, %val          <i>; yields {i32}:result = -%var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_fsub">'<tt>fsub</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = fsub <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fsub</tt>' instruction returns the difference of its two
+   operands.</p>
+
+<p>Note that the '<tt>fsub</tt>' instruction is used to represent the
+   '<tt>fneg</tt>' instruction present in most other intermediate
+   representations.</p>
+
+<h5>Arguments:</h5>
+<p>The two arguments to the '<tt>fsub</tt>' instruction must be
+   <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
+   floating point values.  Both arguments must have identical types.</p>
+
+<h5>Semantics:</h5>
+<p>The value produced is the floating point difference of the two operands.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = fsub float 4.0, %var           <i>; yields {float}:result = 4.0 - %var</i>
+  <result> = fsub float -0.0, %val          <i>; yields {float}:result = -%var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_mul">'<tt>mul</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = mul <ty> <op1>, <op2>          <i>; yields {ty}:result</i>
+  <result> = mul nuw <ty> <op1>, <op2>      <i>; yields {ty}:result</i>
+  <result> = mul nsw <ty> <op1>, <op2>      <i>; yields {ty}:result</i>
+  <result> = mul nuw nsw <ty> <op1>, <op2>  <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>mul</tt>' instruction returns the product of its two operands.</p>
+
+<h5>Arguments:</h5>
+<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>
+
+<p>If the result of the multiplication has unsigned overflow, the result
+   returned is the mathematical result modulo 2<sup>n</sup>, where n is the bit
+   width of the result.</p>
+
+<p>Because LLVM integers use a two's complement representation, and the result
+   is the same width as the operands, this instruction returns the correct
+   result for both signed and unsigned integers.  If a full product
+   (e.g. <tt>i32</tt>x<tt>i32</tt>-><tt>i64</tt>) is needed, the operands should
+   be sign-extended or zero-extended as appropriate to the width of the full
+   product.</p>
+
+<p><tt>nuw</tt> and <tt>nsw</tt> stand for "No Unsigned Wrap"
+   and "No Signed Wrap", respectively. If the <tt>nuw</tt> and/or
+   <tt>nsw</tt> keywords are present, the result value of the <tt>mul</tt>
+   is a <a href="#poisonvalues">poison value</a> if unsigned and/or signed overflow,
+   respectively, occurs.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = mul i32 4, %var          <i>; yields {i32}:result = 4 * %var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_fmul">'<tt>fmul</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = fmul <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fmul</tt>' instruction returns the product of its two operands.</p>
+
+<h5>Arguments:</h5>
+<p>The two arguments to the '<tt>fmul</tt>' instruction must be
+   <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
+   floating point values.  Both arguments must have identical types.</p>
+
+<h5>Semantics:</h5>
+<p>The value produced is the floating point product of the two operands.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = fmul float 4.0, %var          <i>; yields {float}:result = 4.0 * %var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_udiv">'<tt>udiv</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = udiv <ty> <op1>, <op2>         <i>; yields {ty}:result</i>
+  <result> = udiv exact <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<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
+   <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 unsigned integer quotient of the two operands.</p>
+
+<p>Note that unsigned integer division and signed integer division are distinct
+   operations; for signed integer division, use '<tt>sdiv</tt>'.</p>
+
+<p>Division by zero leads to undefined behavior.</p>
+
+<p>If the <tt>exact</tt> keyword is present, the result value of the
+   <tt>udiv</tt> is a <a href="#poisonvalues">poison value</a> if %op1 is not a
+  multiple of %op2 (as such, "((a udiv exact b) mul b) == a").</p>
+
+
+<h5>Example:</h5>
+<pre>
+  <result> = udiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_sdiv">'<tt>sdiv</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = sdiv <ty> <op1>, <op2>         <i>; yields {ty}:result</i>
+  <result> = sdiv exact <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<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
+   <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 signed integer quotient of the two operands rounded
+   towards zero.</p>
+
+<p>Note that signed integer division and unsigned integer division are distinct
+   operations; for unsigned integer division, use '<tt>udiv</tt>'.</p>
+
+<p>Division by zero leads to undefined behavior. Overflow also leads to
+   undefined behavior; this is a rare case, but can occur, for example, by doing
+   a 32-bit division of -2147483648 by -1.</p>
+
+<p>If the <tt>exact</tt> keyword is present, the result value of the
+   <tt>sdiv</tt> is a <a href="#poisonvalues">poison value</a> if the result would
+   be rounded.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = sdiv i32 4, %var          <i>; yields {i32}:result = 4 / %var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_fdiv">'<tt>fdiv</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = fdiv <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fdiv</tt>' instruction returns the quotient of its two operands.</p>
+
+<h5>Arguments:</h5>
+<p>The two arguments to the '<tt>fdiv</tt>' instruction must be
+   <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
+   floating point values.  Both arguments must have identical types.</p>
+
+<h5>Semantics:</h5>
+<p>The value produced is the floating point quotient of the two operands.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = fdiv float 4.0, %var          <i>; yields {float}:result = 4.0 / %var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_urem">'<tt>urem</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = urem <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>urem</tt>' instruction returns the remainder from the unsigned
+   division of its two arguments.</p>
+
+<h5>Arguments:</h5>
+<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>
+
+<h5>Semantics:</h5>
+<p>This instruction returns the unsigned integer <i>remainder</i> of a division.
+   This instruction always performs an unsigned division to get the
+   remainder.</p>
+
+<p>Note that unsigned integer remainder and signed integer remainder are
+   distinct operations; for signed integer remainder, use '<tt>srem</tt>'.</p>
+
+<p>Taking the remainder of a division by zero leads to undefined behavior.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = urem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_srem">'<tt>srem</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = srem <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>srem</tt>' instruction returns the remainder from the signed
+   division of its two operands. This instruction can also take
+   <a href="#t_vector">vector</a> versions of the values in which case the
+   elements must be integers.</p>
+
+<h5>Arguments:</h5>
+<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>
+
+<h5>Semantics:</h5>
+<p>This instruction returns the <i>remainder</i> of a division (where the result
+   is either zero or has the same sign as the dividend, <tt>op1</tt>), not the
+   <i>modulo</i> operator (where the result is either zero or has the same sign
+   as the divisor, <tt>op2</tt>) of a value.
+   For more information about the difference,
+   see <a href="http://mathforum.org/dr.math/problems/anne.4.28.99.html">The
+   Math Forum</a>. For a table of how this is implemented in various languages,
+   please see <a href="http://en.wikipedia.org/wiki/Modulo_operation">
+   Wikipedia: modulo operation</a>.</p>
+
+<p>Note that signed integer remainder and unsigned integer remainder are
+   distinct operations; for unsigned integer remainder, use '<tt>urem</tt>'.</p>
+
+<p>Taking the remainder of a division by zero leads to undefined behavior.
+   Overflow also leads to undefined behavior; this is a rare case, but can
+   occur, for example, by taking the remainder of a 32-bit division of
+   -2147483648 by -1.  (The remainder doesn't actually overflow, but this rule
+   lets srem be implemented using instructions that return both the result of
+   the division and the remainder.)</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = srem i32 4, %var          <i>; yields {i32}:result = 4 % %var</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_frem">'<tt>frem</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = frem <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>frem</tt>' instruction returns the remainder from the division of
+   its two operands.</p>
+
+<h5>Arguments:</h5>
+<p>The two arguments to the '<tt>frem</tt>' instruction must be
+   <a href="#t_floating">floating point</a> or <a href="#t_vector">vector</a> of
+   floating point values.  Both arguments must have identical types.</p>
+
+<h5>Semantics:</h5>
+<p>This instruction returns the <i>remainder</i> of a division.  The remainder
+   has the same sign as the dividend.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = frem float 4.0, %var          <i>; yields {float}:result = 4.0 % %var</i>
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="bitwiseops">Bitwise Binary Operations</a>
+</h3>
+
+<div>
+
+<p>Bitwise binary operators are used to do various forms of bit-twiddling in a
+   program.  They are generally very efficient instructions and can commonly be
+   strength reduced from other instructions.  They require two operands of the
+   same type, execute an operation on them, and produce a single value.  The
+   resulting value is the same type as its operands.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_shl">'<tt>shl</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = shl <ty> <op1>, <op2>           <i>; yields {ty}:result</i>
+  <result> = shl nuw <ty> <op1>, <op2>       <i>; yields {ty}:result</i>
+  <result> = shl nsw <ty> <op1>, <op2>       <i>; yields {ty}:result</i>
+  <result> = shl nuw nsw <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>shl</tt>' instruction returns the first operand shifted to the left
+   a specified number of bits.</p>
+
+<h5>Arguments:</h5>
+<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>
+   is (statically or dynamically) negative or equal to or larger than the number
+   of bits in <tt>op1</tt>, the result is undefined.  If the arguments are
+   vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
+   shift amount in <tt>op2</tt>.</p>
+
+<p>If the <tt>nuw</tt> keyword is present, then the shift produces a 
+   <a href="#poisonvalues">poison value</a> if it shifts out any non-zero bits.  If
+   the <tt>nsw</tt> keyword is present, then the shift produces a
+   <a href="#poisonvalues">poison value</a> if it shifts out any bits that disagree
+   with the resultant sign bit.  As such, NUW/NSW have the same semantics as
+   they would if the shift were expressed as a mul instruction with the same
+   nsw/nuw bits in (mul %op1, (shl 1, %op2)).</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = shl i32 4, %var   <i>; yields {i32}: 4 << %var</i>
+  <result> = shl i32 4, 2      <i>; yields {i32}: 16</i>
+  <result> = shl i32 1, 10     <i>; yields {i32}: 1024</i>
+  <result> = shl i32 1, 32     <i>; undefined</i>
+  <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2>   <i>; yields: result=<2 x i32> < i32 2, i32 4></i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_lshr">'<tt>lshr</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = lshr <ty> <op1>, <op2>         <i>; yields {ty}:result</i>
+  <result> = lshr exact <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>lshr</tt>' instruction (logical shift right) returns the first
+   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
+   <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>This instruction always performs a logical shift right operation. The most
+   significant bits of the result will be filled with zero bits after the shift.
+   If <tt>op2</tt> is (statically or dynamically) equal to or larger than the
+   number of bits in <tt>op1</tt>, the result is undefined. If the arguments are
+   vectors, each vector element of <tt>op1</tt> is shifted by the corresponding
+   shift amount in <tt>op2</tt>.</p>
+
+<p>If the <tt>exact</tt> keyword is present, the result value of the
+   <tt>lshr</tt> is a <a href="#poisonvalues">poison value</a> if any of the bits
+   shifted out are non-zero.</p>
+
+
+<h5>Example:</h5>
+<pre>
+  <result> = lshr i32 4, 1   <i>; yields {i32}:result = 2</i>
+  <result> = lshr i32 4, 2   <i>; yields {i32}:result = 1</i>
+  <result> = lshr i8  4, 3   <i>; yields {i8}:result = 0</i>
+  <result> = lshr i8 -2, 1   <i>; yields {i8}:result = 0x7FFFFFFF </i>
+  <result> = lshr i32 1, 32  <i>; undefined</i>
+  <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2>   <i>; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1></i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_ashr">'<tt>ashr</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = ashr <ty> <op1>, <op2>         <i>; yields {ty}:result</i>
+  <result> = ashr exact <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>ashr</tt>' instruction (arithmetic shift right) returns the first
+   operand shifted to the right a specified number of bits with sign
+   extension.</p>
+
+<h5>Arguments:</h5>
+<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>
+
+<h5>Semantics:</h5>
+<p>This instruction always performs an arithmetic shift right operation, The
+   most significant bits of the result will be filled with the sign bit
+   of <tt>op1</tt>.  If <tt>op2</tt> is (statically or dynamically) equal to or
+   larger than the number of bits in <tt>op1</tt>, the result is undefined. If
+   the arguments are vectors, each vector element of <tt>op1</tt> is shifted by
+   the corresponding shift amount in <tt>op2</tt>.</p>
+
+<p>If the <tt>exact</tt> keyword is present, the result value of the
+   <tt>ashr</tt> is a <a href="#poisonvalues">poison value</a> if any of the bits
+   shifted out are non-zero.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = ashr i32 4, 1   <i>; yields {i32}:result = 2</i>
+  <result> = ashr i32 4, 2   <i>; yields {i32}:result = 1</i>
+  <result> = ashr i8  4, 3   <i>; yields {i8}:result = 0</i>
+  <result> = ashr i8 -2, 1   <i>; yields {i8}:result = -1</i>
+  <result> = ashr i32 1, 32  <i>; undefined</i>
+  <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3>   <i>; yields: result=<2 x i32> < i32 -1, i32 0></i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_and">'<tt>and</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = and <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>and</tt>' instruction returns the bitwise logical and of its two
+   operands.</p>
+
+<h5>Arguments:</h5>
+<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>
+
+<h5>Semantics:</h5>
+<p>The truth table used for the '<tt>and</tt>' instruction is:</p>
+
+<table border="1" cellspacing="0" cellpadding="4">
+  <tbody>
+    <tr>
+      <th>In0</th>
+      <th>In1</th>
+      <th>Out</th>
+    </tr>
+    <tr>
+      <td>0</td>
+      <td>0</td>
+      <td>0</td>
+    </tr>
+    <tr>
+      <td>0</td>
+      <td>1</td>
+      <td>0</td>
+    </tr>
+    <tr>
+      <td>1</td>
+      <td>0</td>
+      <td>0</td>
+    </tr>
+    <tr>
+      <td>1</td>
+      <td>1</td>
+      <td>1</td>
+    </tr>
+  </tbody>
+</table>
+
+<h5>Example:</h5>
+<pre>
+  <result> = and i32 4, %var         <i>; yields {i32}:result = 4 & %var</i>
+  <result> = and i32 15, 40          <i>; yields {i32}:result = 8</i>
+  <result> = and i32 4, 8            <i>; yields {i32}:result = 0</i>
+</pre>
+</div>
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_or">'<tt>or</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = or <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>or</tt>' instruction returns the bitwise logical inclusive or of its
+   two operands.</p>
+
+<h5>Arguments:</h5>
+<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>
+
+<h5>Semantics:</h5>
+<p>The truth table used for the '<tt>or</tt>' instruction is:</p>
+
+<table border="1" cellspacing="0" cellpadding="4">
+  <tbody>
+    <tr>
+      <th>In0</th>
+      <th>In1</th>
+      <th>Out</th>
+    </tr>
+    <tr>
+      <td>0</td>
+      <td>0</td>
+      <td>0</td>
+    </tr>
+    <tr>
+      <td>0</td>
+      <td>1</td>
+      <td>1</td>
+    </tr>
+    <tr>
+      <td>1</td>
+      <td>0</td>
+      <td>1</td>
+    </tr>
+    <tr>
+      <td>1</td>
+      <td>1</td>
+      <td>1</td>
+    </tr>
+  </tbody>
+</table>
+
+<h5>Example:</h5>
+<pre>
+  <result> = or i32 4, %var         <i>; yields {i32}:result = 4 | %var</i>
+  <result> = or i32 15, 40          <i>; yields {i32}:result = 47</i>
+  <result> = or i32 4, 8            <i>; yields {i32}:result = 12</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_xor">'<tt>xor</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = xor <ty> <op1>, <op2>   <i>; yields {ty}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>xor</tt>' instruction returns the bitwise logical exclusive or of
+   its 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>
+<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>
+
+<h5>Semantics:</h5>
+<p>The truth table used for the '<tt>xor</tt>' instruction is:</p>
+
+<table border="1" cellspacing="0" cellpadding="4">
+  <tbody>
+    <tr>
+      <th>In0</th>
+      <th>In1</th>
+      <th>Out</th>
+    </tr>
+    <tr>
+      <td>0</td>
+      <td>0</td>
+      <td>0</td>
+    </tr>
+    <tr>
+      <td>0</td>
+      <td>1</td>
+      <td>1</td>
+    </tr>
+    <tr>
+      <td>1</td>
+      <td>0</td>
+      <td>1</td>
+    </tr>
+    <tr>
+      <td>1</td>
+      <td>1</td>
+      <td>0</td>
+    </tr>
+  </tbody>
+</table>
+
+<h5>Example:</h5>
+<pre>
+  <result> = xor i32 4, %var         <i>; yields {i32}:result = 4 ^ %var</i>
+  <result> = xor i32 15, 40          <i>; yields {i32}:result = 39</i>
+  <result> = xor i32 4, 8            <i>; yields {i32}:result = 12</i>
+  <result> = xor i32 %V, -1          <i>; yields {i32}:result = ~%V</i>
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="vectorops">Vector Operations</a>
+</h3>
+
+<div>
+
+<p>LLVM supports several instructions to represent vector operations in a
+   target-independent manner.  These instructions cover the element-access and
+   vector-specific operations needed to process vectors effectively.  While LLVM
+   does directly support these vector operations, many sophisticated algorithms
+   will want to use target-specific intrinsics to take full advantage of a
+   specific target.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_extractelement">'<tt>extractelement</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = extractelement <n x <ty>> <val>, i32 <idx>    <i>; yields <ty></i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>extractelement</tt>' instruction extracts a single scalar element
+   from a vector at a specified index.</p>
+
+
+<h5>Arguments:</h5>
+<p>The first operand of an '<tt>extractelement</tt>' instruction is a value
+   of <a href="#t_vector">vector</a> type.  The second operand is an index
+   indicating the position from which to extract the element.  The index may be
+   a variable.</p>
+
+<h5>Semantics:</h5>
+<p>The result is a scalar of the same type as the element type of
+   <tt>val</tt>.  Its value is the value at position <tt>idx</tt> of
+   <tt>val</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
+   results are undefined.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = extractelement <4 x i32> %vec, i32 0    <i>; yields i32</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_insertelement">'<tt>insertelement</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = insertelement <n x <ty>> <val>, <ty> <elt>, i32 <idx>    <i>; yields <n x <ty>></i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>insertelement</tt>' instruction inserts a scalar element into a
+   vector at a specified index.</p>
+
+<h5>Arguments:</h5>
+<p>The first operand of an '<tt>insertelement</tt>' instruction is a value
+   of <a href="#t_vector">vector</a> type.  The second operand is a scalar value
+   whose type must equal the element type of the first operand.  The third
+   operand is an index indicating the position at which to insert the value.
+   The index may be a variable.</p>
+
+<h5>Semantics:</h5>
+<p>The result is a vector of the same type as <tt>val</tt>.  Its element values
+   are those of <tt>val</tt> except at position <tt>idx</tt>, where it gets the
+   value <tt>elt</tt>.  If <tt>idx</tt> exceeds the length of <tt>val</tt>, the
+   results are undefined.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = insertelement <4 x i32> %vec, i32 1, i32 0    <i>; yields <4 x i32></i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_shufflevector">'<tt>shufflevector</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask>    <i>; yields <m x <ty>></i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>shufflevector</tt>' instruction constructs a permutation of elements
+   from two input vectors, returning a vector with the same element type as the
+   input and length that is the same as the shuffle mask.</p>
+
+<h5>Arguments:</h5>
+<p>The first two operands of a '<tt>shufflevector</tt>' instruction are vectors
+   with the same type.  The third argument is a shuffle mask whose
+   element type is always 'i32'.  The result of the instruction is a vector
+   whose length is the same as the shuffle mask and whose element type is the
+   same as the element type of the first two operands.</p>
+
+<p>The shuffle mask operand is required to be a constant vector with either
+   constant integer or undef values.</p>
+
+<h5>Semantics:</h5>
+<p>The elements of the two input vectors are numbered from left to right across
+   both of the vectors.  The shuffle mask operand specifies, for each element of
+   the result vector, which element of the two input vectors the result element
+   gets.  The element selector may be undef (meaning "don't care") and the
+   second operand may be undef if performing a shuffle from only one vector.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+                          <4 x i32> <i32 0, i32 4, i32 1, i32 5>  <i>; yields <4 x i32></i>
+  <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
+                          <4 x i32> <i32 0, i32 1, i32 2, i32 3>  <i>; yields <4 x i32></i> - Identity shuffle.
+  <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
+                          <4 x i32> <i32 0, i32 1, i32 2, i32 3>  <i>; yields <4 x i32></i>
+  <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+                          <8 x i32> <i32 0, i32 1, i32 2, i32 3, i32 4, i32 5, i32 6, i32 7 >  <i>; yields <8 x i32></i>
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="aggregateops">Aggregate Operations</a>
+</h3>
+
+<div>
+
+<p>LLVM supports several instructions for working with
+  <a href="#t_aggregate">aggregate</a> values.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_extractvalue">'<tt>extractvalue</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>extractvalue</tt>' instruction extracts the value of a member field
+   from an <a href="#t_aggregate">aggregate</a> value.</p>
+
+<h5>Arguments:</h5>
+<p>The first operand of an '<tt>extractvalue</tt>' instruction is a value
+   of <a href="#t_struct">struct</a> or
+   <a href="#t_array">array</a> type.  The operands are constant indices to
+   specify which value to extract in a similar manner as indices in a
+   '<tt><a href="#i_getelementptr">getelementptr</a></tt>' instruction.</p>
+   <p>The major differences to <tt>getelementptr</tt> indexing are:</p>
+     <ul>
+       <li>Since the value being indexed is not a pointer, the first index is
+           omitted and assumed to be zero.</li>
+       <li>At least one index must be specified.</li>
+       <li>Not only struct indices but also array indices must be in
+           bounds.</li>
+     </ul>
+
+<h5>Semantics:</h5>
+<p>The result is the value at the position in the aggregate specified by the
+   index operands.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = extractvalue {i32, float} %agg, 0    <i>; yields i32</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_insertvalue">'<tt>insertvalue</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}*    <i>; yields <aggregate type></i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>insertvalue</tt>' instruction inserts a value into a member field
+   in an <a href="#t_aggregate">aggregate</a> value.</p>
+
+<h5>Arguments:</h5>
+<p>The first operand of an '<tt>insertvalue</tt>' instruction is a value
+   of <a href="#t_struct">struct</a> or
+   <a href="#t_array">array</a> type.  The second operand is a first-class
+   value to insert.  The following operands are constant indices indicating
+   the position at which to insert the value in a similar manner as indices in a
+   '<tt><a href="#i_extractvalue">extractvalue</a></tt>' instruction.  The
+   value to insert must have the same type as the value identified by the
+   indices.</p>
+
+<h5>Semantics:</h5>
+<p>The result is an aggregate of the same type as <tt>val</tt>.  Its value is
+   that of <tt>val</tt> except that the value at the position specified by the
+   indices is that of <tt>elt</tt>.</p>
+
+<h5>Example:</h5>
+<pre>
+  %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>
+  %agg3 = insertvalue {i32, {float}} %agg1, float %val, 1, 0    <i>; yields {i32 1, float %val}</i>
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="memoryops">Memory Access and Addressing Operations</a>
+</h3>
+
+<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, and allocate
+   memory in LLVM.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_alloca">'<tt>alloca</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = alloca <type>[, <ty> <NumElements>][, align <alignment>]     <i>; yields {type*}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>alloca</tt>' instruction allocates memory on the stack frame of the
+   currently executing function, to be automatically released when this function
+   returns to its caller. The object is always allocated in the generic address
+   space (address space zero).</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>alloca</tt>' instruction
+   allocates <tt>sizeof(<type>)*NumElements</tt> bytes of memory on the
+   runtime stack, returning 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>' may be any sized type.</p>
+
+<h5>Semantics:</h5>
+<p>Memory is allocated; a pointer is returned.  The operation is undefined if
+   there is insufficient stack space for the allocation.  '<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.  When the function returns
+   (either with the <tt><a href="#i_ret">ret</a></tt>
+   or <tt><a href="#i_resume">resume</a></tt> instructions), the memory is
+   reclaimed.  Allocating zero bytes is legal, but the result is undefined.
+   The order in which memory is allocated (ie., which way the stack grows) is
+   not specified.</p>
+
+<p>
+
+<h5>Example:</h5>
+<pre>
+  %ptr = alloca i32                             <i>; yields {i32*}:ptr</i>
+  %ptr = alloca i32, i32 4                      <i>; yields {i32*}:ptr</i>
+  %ptr = alloca i32, i32 4, align 1024          <i>; yields {i32*}:ptr</i>
+  %ptr = alloca i32, align 1024                 <i>; yields {i32*}:ptr</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_load">'<tt>load</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = load [volatile] <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>][, !invariant.load !<index>]
+  <result> = load atomic [volatile] <ty>* <pointer> [singlethread] <ordering>, align <alignment>
+  !<index> = !{ i32 1 }
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>load</tt>' instruction is used to read from memory.</p>
+
+<h5>Arguments:</h5>
+<p>The argument to the '<tt>load</tt>' instruction specifies the memory address
+   from which to load.  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 <a
+   href="#volatile">volatile operations</a>.</p>
+
+<p>If the <code>load</code> is marked as <code>atomic</code>, it takes an extra
+   <a href="#ordering">ordering</a> and optional <code>singlethread</code>
+   argument.  The <code>release</code> and <code>acq_rel</code> orderings are
+   not valid on <code>load</code> instructions.  Atomic loads produce <a
+   href="#memorymodel">defined</a> results when they may see multiple atomic
+   stores.  The type of the pointee must be an integer type whose bit width
+   is a power of two greater than or equal to eight and less than or equal
+   to a target-specific size limit. <code>align</code> must be explicitly 
+   specified on atomic loads, and the load has undefined behavior if the
+   alignment is not set to a value which is at least the size in bytes of
+   the pointee. <code>!nontemporal</code> does not have any defined semantics
+   for atomic loads.</p>
+
+<p>The optional constant <tt>align</tt> argument specifies the alignment of the
+   operation (that is, the alignment of the memory address). A value of 0 or an
+   omitted <tt>align</tt> argument means that the operation has the abi
+   alignment for the target. It is the responsibility of the code emitter to
+   ensure that the alignment information is correct. Overestimating the
+   alignment results in undefined behavior. Underestimating the alignment may
+   produce less efficient code. An alignment of 1 is always safe.</p>
+
+<p>The optional <tt>!nontemporal</tt> metadata must reference a single
+   metatadata name <index> corresponding to a metadata node with
+   one <tt>i32</tt> entry of value 1.  The existence of
+   the <tt>!nontemporal</tt> metatadata on the instruction tells the optimizer
+   and code generator that this load is not expected to be reused in the cache.
+   The code generator may select special instructions to save cache bandwidth,
+   such as the <tt>MOVNT</tt> instruction on x86.</p>
+
+<p>The optional <tt>!invariant.load</tt> metadata must reference a single
+   metatadata name <index> corresponding to a metadata node with no
+   entries.  The existence of the <tt>!invariant.load</tt> metatadata on the
+   instruction tells the optimizer and code generator that this load address
+   points to memory which does not change value during program execution.
+   The optimizer may then move this load around, for example, by hoisting it
+   out of loops using loop invariant code motion.</p>
+
+<h5>Semantics:</h5>
+<p>The location of memory pointed to is loaded.  If the value being loaded is of
+   scalar type then the number of bytes read does not exceed the minimum number
+   of bytes needed to hold all bits of the type.  For example, loading an
+   <tt>i24</tt> reads at most three bytes.  When loading a value of a type like
+   <tt>i20</tt> with a size that is not an integral number of bytes, the result
+   is undefined if the value was not originally written using a store of the
+   same type.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
+  <a href="#i_store">store</a> i32 3, i32* %ptr                          <i>; yields {void}</i>
+  %val = load i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_store">'<tt>store</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>]        <i>; yields {void}</i>
+  store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment>  <i>; yields {void}</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>store</tt>' instruction is used to write to memory.</p>
+
+<h5>Arguments:</h5>
+<p>There are two arguments to the '<tt>store</tt>' instruction: a value to store
+   and an address at which to store it.  The type of the
+   '<tt><pointer></tt>' operand must be a pointer to
+   the <a href="#t_firstclass">first class</a> type of the
+   '<tt><value></tt>' operand. If the <tt>store</tt> is marked as
+   <tt>volatile</tt>, then the optimizer is not allowed to modify the number or
+   order of execution of this <tt>store</tt> with other <a
+   href="#volatile">volatile operations</a>.</p>
+
+<p>If the <code>store</code> is marked as <code>atomic</code>, it takes an extra
+   <a href="#ordering">ordering</a> and optional <code>singlethread</code>
+   argument.  The <code>acquire</code> and <code>acq_rel</code> orderings aren't
+   valid on <code>store</code> instructions.  Atomic loads produce <a
+   href="#memorymodel">defined</a> results when they may see multiple atomic
+   stores. The type of the pointee must be an integer type whose bit width
+   is a power of two greater than or equal to eight and less than or equal
+   to a target-specific size limit. <code>align</code> must be explicitly 
+   specified on atomic stores, and the store has undefined behavior if the
+   alignment is not set to a value which is at least the size in bytes of
+   the pointee. <code>!nontemporal</code> does not have any defined semantics
+   for atomic stores.</p>
+
+<p>The optional constant "align" argument specifies the alignment of the
+   operation (that is, the alignment of the memory address). A value of 0 or an
+   omitted "align" argument means that the operation has the abi
+   alignment for the target. It is the responsibility of the code emitter to
+   ensure that the alignment information is correct. Overestimating the
+   alignment results in an undefined behavior. Underestimating the alignment may
+   produce less efficient code. An alignment of 1 is always safe.</p>
+
+<p>The optional !nontemporal metadata must reference a single metatadata
+   name <index> corresponding to a metadata node with one i32 entry of
+   value 1.  The existence of the !nontemporal metatadata on the
+   instruction tells the optimizer and code generator that this load is
+   not expected to be reused in the cache.  The code generator may
+   select special instructions to save cache bandwidth, such as the
+   MOVNT instruction on x86.</p>
+
+
+<h5>Semantics:</h5>
+<p>The contents of memory are updated to contain '<tt><value></tt>' at the
+   location specified by the '<tt><pointer></tt>' operand.  If
+   '<tt><value></tt>' is of scalar type then the number of bytes written
+   does not exceed the minimum number of bytes needed to hold all bits of the
+   type.  For example, storing an <tt>i24</tt> writes at most three bytes.  When
+   writing a value of a type like <tt>i20</tt> with a size that is not an
+   integral number of bytes, it is unspecified what happens to the extra bits
+   that do not belong to the type, but they will typically be overwritten.</p>
+
+<h5>Example:</h5>
+<pre>
+  %ptr = <a href="#i_alloca">alloca</a> i32                               <i>; yields {i32*}:ptr</i>
+  store i32 3, i32* %ptr                          <i>; yields {void}</i>
+  %val = <a href="#i_load">load</a> i32* %ptr                           <i>; yields {i32}:val = i32 3</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+<a name="i_fence">'<tt>fence</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  fence [singlethread] <ordering>                   <i>; yields {void}</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fence</tt>' instruction is used to introduce happens-before edges
+between operations.</p>
+
+<h5>Arguments:</h5> <p>'<code>fence</code>' instructions take an <a
+href="#ordering">ordering</a> argument which defines what
+<i>synchronizes-with</i> edges they add.  They can only be given
+<code>acquire</code>, <code>release</code>, <code>acq_rel</code>, and
+<code>seq_cst</code> orderings.</p>
+
+<h5>Semantics:</h5>
+<p>A fence <var>A</var> which has (at least) <code>release</code> ordering
+semantics <i>synchronizes with</i> a fence <var>B</var> with (at least)
+<code>acquire</code> ordering semantics if and only if there exist atomic
+operations <var>X</var> and <var>Y</var>, both operating on some atomic object
+<var>M</var>, such that <var>A</var> is sequenced before <var>X</var>,
+<var>X</var> modifies <var>M</var> (either directly or through some side effect
+of a sequence headed by <var>X</var>), <var>Y</var> is sequenced before
+<var>B</var>, and <var>Y</var> observes <var>M</var>. This provides a
+<i>happens-before</i> dependency between <var>A</var> and <var>B</var>. Rather
+than an explicit <code>fence</code>, one (but not both) of the atomic operations
+<var>X</var> or <var>Y</var> might provide a <code>release</code> or
+<code>acquire</code> (resp.) ordering constraint and still
+<i>synchronize-with</i> the explicit <code>fence</code> and establish the
+<i>happens-before</i> edge.</p>
+
+<p>A <code>fence</code> which has <code>seq_cst</code> ordering, in addition to
+having both <code>acquire</code> and <code>release</code> semantics specified
+above, participates in the global program order of other <code>seq_cst</code>
+operations and/or fences.</p>
+
+<p>The optional "<a href="#singlethread"><code>singlethread</code></a>" argument
+specifies that the fence only synchronizes with other fences in the same
+thread.  (This is useful for interacting with signal handlers.)</p>
+
+<h5>Example:</h5>
+<pre>
+  fence acquire                          <i>; yields {void}</i>
+  fence singlethread seq_cst             <i>; yields {void}</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+<a name="i_cmpxchg">'<tt>cmpxchg</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  cmpxchg [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <ordering>  <i>; yields {ty}</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>cmpxchg</tt>' instruction is used to atomically modify memory.
+It loads a value in memory and compares it to a given value. If they are
+equal, it stores a new value into the memory.</p>
+
+<h5>Arguments:</h5>
+<p>There are three arguments to the '<code>cmpxchg</code>' instruction: an
+address to operate on, a value to compare to the value currently be at that
+address, and a new value to place at that address if the compared values are
+equal.  The type of '<var><cmp></var>' must be an integer type whose
+bit width is a power of two greater than or equal to eight and less than
+or equal to a target-specific size limit. '<var><cmp></var>' and
+'<var><new></var>' must have the same type, and the type of
+'<var><pointer></var>' must be a pointer to that type. If the
+<code>cmpxchg</code> is marked as <code>volatile</code>, then the
+optimizer is not allowed to modify the number or order of execution
+of this <code>cmpxchg</code> with other <a href="#volatile">volatile
+operations</a>.</p>
+
+<!-- FIXME: Extend allowed types. -->
+
+<p>The <a href="#ordering"><var>ordering</var></a> argument specifies how this
+<code>cmpxchg</code> synchronizes with other atomic operations.</p>
+
+<p>The optional "<code>singlethread</code>" argument declares that the
+<code>cmpxchg</code> is only atomic with respect to code (usually signal
+handlers) running in the same thread as the <code>cmpxchg</code>.  Otherwise the
+cmpxchg is atomic with respect to all other code in the system.</p>
+
+<p>The pointer passed into cmpxchg must have alignment greater than or equal to
+the size in memory of the operand.
+
+<h5>Semantics:</h5>
+<p>The contents of memory at the location specified by the
+'<tt><pointer></tt>' operand is read and compared to
+'<tt><cmp></tt>'; if the read value is the equal,
+'<tt><new></tt>' is written.  The original value at the location
+is returned.
+
+<p>A successful <code>cmpxchg</code> is a read-modify-write instruction for the
+purpose of identifying <a href="#release_sequence">release sequences</a>.  A
+failed <code>cmpxchg</code> is equivalent to an atomic load with an ordering
+parameter determined by dropping any <code>release</code> part of the
+<code>cmpxchg</code>'s ordering.</p>
+
+<!--
+FIXME: Is compare_exchange_weak() necessary?  (Consider after we've done
+optimization work on ARM.)
+
+FIXME: Is a weaker ordering constraint on failure helpful in practice?
+-->
+
+<h5>Example:</h5>
+<pre>
+entry:
+  %orig = atomic <a href="#i_load">load</a> i32* %ptr unordered                   <i>; yields {i32}</i>
+  <a href="#i_br">br</a> label %loop
+
+loop:
+  %cmp = <a href="#i_phi">phi</a> i32 [ %orig, %entry ], [%old, %loop]
+  %squared = <a href="#i_mul">mul</a> i32 %cmp, %cmp
+  %old = cmpxchg i32* %ptr, i32 %cmp, i32 %squared          <i>; yields {i32}</i>
+  %success = <a href="#i_icmp">icmp</a> eq i32 %cmp, %old
+  <a href="#i_br">br</a> i1 %success, label %done, label %loop
+
+done:
+  ...
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+<a name="i_atomicrmw">'<tt>atomicrmw</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering>                   <i>; yields {ty}</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>atomicrmw</tt>' instruction is used to atomically modify memory.</p>
+
+<h5>Arguments:</h5>
+<p>There are three arguments to the '<code>atomicrmw</code>' instruction: an
+operation to apply, an address whose value to modify, an argument to the
+operation.  The operation must be one of the following keywords:</p>
+<ul>
+  <li>xchg</li>
+  <li>add</li>
+  <li>sub</li>
+  <li>and</li>
+  <li>nand</li>
+  <li>or</li>
+  <li>xor</li>
+  <li>max</li>
+  <li>min</li>
+  <li>umax</li>
+  <li>umin</li>
+</ul>
+
+<p>The type of '<var><value></var>' must be an integer type whose
+bit width is a power of two greater than or equal to eight and less than
+or equal to a target-specific size limit.  The type of the
+'<code><pointer></code>' operand must be a pointer to that type.
+If the <code>atomicrmw</code> is marked as <code>volatile</code>, then the
+optimizer is not allowed to modify the number or order of execution of this
+<code>atomicrmw</code> with other <a href="#volatile">volatile
+  operations</a>.</p>
+
+<!-- FIXME: Extend allowed types. -->
+
+<h5>Semantics:</h5>
+<p>The contents of memory at the location specified by the
+'<tt><pointer></tt>' operand are atomically read, modified, and written
+back.  The original value at the location is returned.  The modification is
+specified by the <var>operation</var> argument:</p>
+
+<ul>
+  <li>xchg: <code>*ptr = val</code></li>
+  <li>add: <code>*ptr = *ptr + val</code></li>
+  <li>sub: <code>*ptr = *ptr - val</code></li>
+  <li>and: <code>*ptr = *ptr & val</code></li>
+  <li>nand: <code>*ptr = ~(*ptr & val)</code></li>
+  <li>or: <code>*ptr = *ptr | val</code></li>
+  <li>xor: <code>*ptr = *ptr ^ val</code></li>
+  <li>max: <code>*ptr = *ptr > val ? *ptr : val</code> (using a signed comparison)</li>
+  <li>min: <code>*ptr = *ptr < val ? *ptr : val</code> (using a signed comparison)</li>
+  <li>umax: <code>*ptr = *ptr > val ? *ptr : val</code> (using an unsigned comparison)</li>
+  <li>umin: <code>*ptr = *ptr < val ? *ptr : val</code> (using an unsigned comparison)</li>
+</ul>
+
+<h5>Example:</h5>
+<pre>
+  %old = atomicrmw add i32* %ptr, i32 1 acquire                        <i>; yields {i32}</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_getelementptr">'<tt>getelementptr</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}*
+  <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}*
+  <result> = getelementptr <ptr vector> ptrval, <vector index type> idx 
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>getelementptr</tt>' instruction is used to get the address of a
+   subelement of an <a href="#t_aggregate">aggregate</a> data structure.
+   It performs address calculation only and does not access memory.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is always a pointer or a vector of pointers,
+   and forms the basis of the
+   calculation. The remaining arguments are indices that indicate which of the
+   elements of the aggregate object are indexed. The interpretation of each
+   index is dependent on the type being indexed into. The first index always
+   indexes the pointer value given as the first argument, the second index
+   indexes a value of the type pointed to (not necessarily the value directly
+   pointed to, since the first index can be non-zero), etc. The first type
+   indexed into must be a pointer value, subsequent types can be arrays,
+   vectors, and structs. Note that subsequent types being indexed into
+   can never be pointers, since that would require loading the pointer before
+   continuing calculation.</p>
+
+<p>The type of each index argument depends on the type it is indexing into.
+   When indexing into a (optionally packed) structure, only <tt>i32</tt>
+   integer <b>constants</b> are allowed.  When indexing into an array, pointer
+   or vector, integers of any width are allowed, and they are not required to be
+   constant.  These integers are treated as signed values where relevant.</p>
+
+<p>For example, let's consider a C code fragment and how it gets compiled to
+   LLVM:</p>
+
+<pre class="doc_code">
+struct RT {
+  char A;
+  int B[10][20];
+  char C;
+};
+struct ST {
+  int X;
+  double Y;
+  struct RT Z;
+};
+
+int *foo(struct ST *s) {
+  return &s[1].Z.B[5][13];
+}
+</pre>
+
+<p>The LLVM code generated by Clang is:</p>
+
+<pre class="doc_code">
+%struct.RT = <a href="#namedtypes">type</a> { i8, [10 x [20 x i32]], i8 }
+%struct.ST = <a href="#namedtypes">type</a> { i32, double, %struct.RT }
+
+define i32* @foo(%struct.ST* %s) nounwind uwtable readnone optsize ssp {
+entry:
+  %arrayidx = getelementptr inbounds %struct.ST* %s, i64 1, i32 2, i32 1, i64 5, i64 13
+  ret i32* %arrayidx
+}
+</pre>
+
+<h5>Semantics:</h5>
+<p>In the example above, the first index is indexing into the
+   '<tt>%struct.ST*</tt>' type, which is a pointer, yielding a
+   '<tt>%struct.ST</tt>' = '<tt>{ i32, double, %struct.RT }</tt>' type, a
+   structure. The second index indexes into the third element of the structure,
+   yielding a '<tt>%struct.RT</tt>' = '<tt>{ i8 , [10 x [20 x i32]], i8 }</tt>'
+   type, another structure. The third index indexes into the second element of
+   the structure, yielding a '<tt>[10 x [20 x i32]]</tt>' type, an array. The
+   two dimensions of the array are subscripted into, yielding an '<tt>i32</tt>'
+   type. The '<tt>getelementptr</tt>' instruction returns a pointer to this
+   element, thus computing a value of '<tt>i32*</tt>' type.</p>
+
+<p>Note that it is perfectly legal to index partially through a structure,
+   returning a pointer to an inner element.  Because of this, the LLVM code for
+   the given testcase is equivalent to:</p>
+
+<pre class="doc_code">
+define i32* @foo(%struct.ST* %s) {
+  %t1 = getelementptr %struct.ST* %s, i32 1                 <i>; yields %struct.ST*:%t1</i>
+  %t2 = getelementptr %struct.ST* %t1, i32 0, i32 2         <i>; yields %struct.RT*:%t2</i>
+  %t3 = getelementptr %struct.RT* %t2, i32 0, i32 1         <i>; yields [10 x [20 x i32]]*:%t3</i>
+  %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5  <i>; yields [20 x i32]*:%t4</i>
+  %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13        <i>; yields i32*:%t5</i>
+  ret i32* %t5
+}
+</pre>
+
+<p>If the <tt>inbounds</tt> keyword is present, the result value of the
+   <tt>getelementptr</tt> is a <a href="#poisonvalues">poison value</a> if the
+   base pointer is not an <i>in bounds</i> address of an allocated object,
+   or if any of the addresses that would be formed by successive addition of
+   the offsets implied by the indices to the base address with infinitely
+   precise signed arithmetic are not an <i>in bounds</i> address of that
+   allocated object. The <i>in bounds</i> addresses for an allocated object
+   are all the addresses that point into the object, plus the address one
+   byte past the end.
+   In cases where the base is a vector of pointers the <tt>inbounds</tt> keyword
+   applies to each of the computations element-wise. </p>
+
+<p>If the <tt>inbounds</tt> keyword is not present, the offsets are added to
+   the base address with silently-wrapping two's complement arithmetic. If the
+   offsets have a different width from the pointer, they are sign-extended or
+   truncated to the width of the pointer. The result value of the
+   <tt>getelementptr</tt> may be outside the object pointed to by the base
+   pointer. The result value may not necessarily be used to access memory
+   though, even if it happens to point into allocated storage. See the
+   <a href="#pointeraliasing">Pointer Aliasing Rules</a> section for more
+   information.</p>
+
+<p>The getelementptr instruction is often confusing.  For some more insight into
+   how it works, see <a href="GetElementPtr.html">the getelementptr FAQ</a>.</p>
+
+<h5>Example:</h5>
+<pre>
+    <i>; yields [12 x i8]*:aptr</i>
+    %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1
+    <i>; yields i8*:vptr</i>
+    %vptr = getelementptr {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1
+    <i>; yields i8*:eptr</i>
+    %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1
+    <i>; yields i32*:iptr</i>
+    %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0
+</pre>
+
+<p>In cases where the pointer argument is a vector of pointers, only a
+   single index may be used, and the number of vector elements has to be
+   the same.  For example: </p>
+<pre class="doc_code">
+ %A = getelementptr <4 x i8*> %ptrs, <4 x i64> %offsets,
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="convertops">Conversion Operations</a>
+</h3>
+
+<div>
+
+<p>The instructions in this category are the conversion instructions (casting)
+   which all take a single operand and a type. They perform various bit
+   conversions on the operand.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_trunc">'<tt>trunc .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = trunc <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>trunc</tt>' instruction truncates its operand to the
+   type <tt>ty2</tt>.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>trunc</tt>' instruction takes a value to trunc, and a type to trunc it to.
+   Both types must be of <a href="#t_integer">integer</a> types, or vectors
+   of the same number of integers.
+   The bit size of the <tt>value</tt> must be larger than
+   the bit size of the destination type, <tt>ty2</tt>.
+   Equal sized types are not allowed.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>trunc</tt>' instruction truncates the high order bits
+   in <tt>value</tt> and converts the remaining bits to <tt>ty2</tt>. Since the
+   source size must be larger than the destination size, <tt>trunc</tt> cannot
+   be a <i>no-op cast</i>.  It will always truncate bits.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = trunc i32 257 to i8                        <i>; yields i8:1</i>
+  %Y = trunc i32 123 to i1                        <i>; yields i1:true</i>
+  %Z = trunc i32 122 to i1                        <i>; yields i1:false</i>
+  %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> <i>; yields <i8 8, i8 7></i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_zext">'<tt>zext .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = zext <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<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, and a type to cast it to.
+   Both types must be of <a href="#t_integer">integer</a> types, or vectors
+   of the same number of integers.
+   The bit size of the <tt>value</tt> must be smaller than
+   the bit size of the destination type,
+   <tt>ty2</tt>.</p>
+
+<h5>Semantics:</h5>
+<p>The <tt>zext</tt> fills the high order bits of the <tt>value</tt> with zero
+   bits until it reaches the size of the destination type, <tt>ty2</tt>.</p>
+
+<p>When zero extending from i1, the result will always be either 0 or 1.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = zext i32 257 to i64              <i>; yields i64:257</i>
+  %Y = zext i1 true to i32              <i>; yields i32:1</i>
+  %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> <i>; yields <i32 8, i32 7></i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_sext">'<tt>sext .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = sext <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<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, and a type to cast it to.
+   Both types must be of <a href="#t_integer">integer</a> types, or vectors
+   of the same number of integers.
+   The bit size of the <tt>value</tt> must be smaller than
+   the bit size of the destination type,
+   <tt>ty2</tt>.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>sext</tt>' instruction performs a sign extension by copying the sign
+   bit (highest order bit) of the <tt>value</tt> until it reaches the bit size
+   of the type <tt>ty2</tt>.</p>
+
+<p>When sign extending from i1, the extension always results in -1 or 0.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = sext i8  -1 to i16              <i>; yields i16   :65535</i>
+  %Y = sext i1 true to i32             <i>; yields i32:-1</i>
+  %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> <i>; yields <i32 8, i32 7></i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_fptrunc">'<tt>fptrunc .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = fptrunc <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fptrunc</tt>' instruction truncates <tt>value</tt> to type
+   <tt>ty2</tt>.</p>
+
+<h5>Arguments:</h5>
+<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
+   <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.  If the value cannot fit
+   within the destination type, <tt>ty2</tt>, then the results are
+   undefined.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = fptrunc double 123.0 to float         <i>; yields float:123.0</i>
+  %Y = fptrunc double 1.0E+300 to float      <i>; yields undefined</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_fpext">'<tt>fpext .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = fpext <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fpext</tt>' extends a floating point <tt>value</tt> to a larger
+   floating point value.</p>
+
+<h5>Arguments:</h5>
+<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>
+
+<h5>Semantics:</h5>
+<p>The '<tt>fpext</tt>' instruction extends the <tt>value</tt> from a smaller
+   <a href="#t_floating">floating point</a> type to a larger
+   <a href="#t_floating">floating point</a> type. The <tt>fpext</tt> cannot be
+   used to make a <i>no-op cast</i> because it always changes bits. Use
+   <tt>bitcast</tt> to make a <i>no-op cast</i> for a floating point cast.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = fpext float 3.125 to double         <i>; yields double:3.125000e+00</i>
+  %Y = fpext double %X to fp128            <i>; yields fp128:0xL00000000000000004000900000000000</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_fptoui">'<tt>fptoui .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = fptoui <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fptoui</tt>' converts a floating point <tt>value</tt> to its
+   unsigned integer equivalent of type <tt>ty2</tt>.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>fptoui</tt>' instruction takes a value to cast, which must be a
+   scalar or vector <a href="#t_floating">floating point</a> value, and a type
+   to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
+   type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
+   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
+   <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>
+
+<h5>Example:</h5>
+<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>
+  %Z = fptoui float 1.04E+17 to i8     <i>; yields undefined:1</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_fptosi">'<tt>fptosi .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = fptosi <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fptosi</tt>' instruction converts
+   <a href="#t_floating">floating point</a> <tt>value</tt> to
+   type <tt>ty2</tt>.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>fptosi</tt>' instruction takes a value to cast, which must be a
+   scalar or vector <a href="#t_floating">floating point</a> value, and a type
+   to cast it to <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a>
+   type. If <tt>ty</tt> is a vector floating point type, <tt>ty2</tt> must be a
+   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
+   <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>
+
+<h5>Example:</h5>
+<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>
+  %Z = fptosi float 1.04E+17 to i8      <i>; yields undefined:1</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_uitofp">'<tt>uitofp .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = uitofp <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>uitofp</tt>' instruction regards <tt>value</tt> as an unsigned
+   integer and converts that value to the <tt>ty2</tt> type.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>uitofp</tt>' instruction takes a value to cast, which must be a
+   scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
+   it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
+   type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
+   floating point type with the same number of elements as <tt>ty</tt></p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>uitofp</tt>' instruction interprets its operand as an unsigned
+   integer quantity and converts it to the corresponding floating point
+   value. If the value cannot fit in the floating point value, the results are
+   undefined.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = uitofp i32 257 to float         <i>; yields float:257.0</i>
+  %Y = uitofp i8 -1 to double          <i>; yields double:255.0</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_sitofp">'<tt>sitofp .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = sitofp <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>sitofp</tt>' instruction regards <tt>value</tt> as a signed integer
+   and converts that value to the <tt>ty2</tt> type.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>sitofp</tt>' instruction takes a value to cast, which must be a
+   scalar or vector <a href="#t_integer">integer</a> value, and a type to cast
+   it to <tt>ty2</tt>, which must be an <a href="#t_floating">floating point</a>
+   type. If <tt>ty</tt> is a vector integer type, <tt>ty2</tt> must be a vector
+   floating point type with the same number of elements as <tt>ty</tt></p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>sitofp</tt>' instruction interprets its operand as a signed integer
+   quantity and converts it to the corresponding floating point value. If the
+   value cannot fit in the floating point value, the results are undefined.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = sitofp i32 257 to float         <i>; yields float:257.0</i>
+  %Y = sitofp i8 -1 to double          <i>; yields double:-1.0</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_ptrtoint">'<tt>ptrtoint .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = ptrtoint <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>ptrtoint</tt>' instruction converts the pointer or a vector of
+   pointers <tt>value</tt> to
+   the integer (or vector of integers) type <tt>ty2</tt>.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>ptrtoint</tt>' instruction takes a <tt>value</tt> to cast, which
+   must be a a value of type <a href="#t_pointer">pointer</a> or a vector of
+    pointers, and a type to cast it to
+   <tt>ty2</tt>, which must be an <a href="#t_integer">integer</a> or a vector
+   of integers type.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>ptrtoint</tt>' instruction converts <tt>value</tt> to integer type
+   <tt>ty2</tt> by interpreting the pointer value as an integer and either
+   truncating or zero extending that value to the size of the integer type. If
+   <tt>value</tt> is smaller than <tt>ty2</tt> then a zero extension is done. If
+   <tt>value</tt> is larger than <tt>ty2</tt> then a truncation is done. If they
+   are the same size, then nothing is done (<i>no-op cast</i>) other than a type
+   change.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = ptrtoint i32* %P to i8                         <i>; yields truncation on 32-bit architecture</i>
+  %Y = ptrtoint i32* %P to i64                        <i>; yields zero extension on 32-bit architecture</i>
+  %Z = ptrtoint <4 x i32*> %P to <4 x i64><i>; yields vector zero extension for a vector of addresses on 32-bit architecture</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_inttoptr">'<tt>inttoptr .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = inttoptr <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>inttoptr</tt>' instruction converts an integer <tt>value</tt> to a
+   pointer type, <tt>ty2</tt>.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>inttoptr</tt>' instruction takes an <a href="#t_integer">integer</a>
+   value to cast, and a type to cast it to, which must be a
+   <a href="#t_pointer">pointer</a> type.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>inttoptr</tt>' instruction converts <tt>value</tt> to type
+   <tt>ty2</tt> by applying either a zero extension or a truncation depending on
+   the size of the integer <tt>value</tt>. If <tt>value</tt> is larger than the
+   size of a pointer then a truncation is done. If <tt>value</tt> is smaller
+   than the size of a pointer then a zero extension is done. If they are the
+   same size, nothing is done (<i>no-op cast</i>).</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = inttoptr i32 255 to i32*          <i>; yields zero extension on 64-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>
+  %Z = inttoptr <4 x i32> %G to <4 x i8*><i>; yields truncation of vector G to four pointers</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_bitcast">'<tt>bitcast .. to</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = bitcast <ty> <value> to <ty2>             <i>; yields ty2</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
+   <tt>ty2</tt> without changing any bits.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>bitcast</tt>' instruction takes a value to cast, which must be a
+   non-aggregate first class value, and a type to cast it to, which must also be
+   a non-aggregate <a href="#t_firstclass">first class</a> type. The bit sizes
+   of <tt>value</tt> and the destination type, <tt>ty2</tt>, must be
+   identical. If the source type is a pointer, the destination type must also be
+   a pointer.  This instruction supports bitwise conversion of vectors to
+   integers and to vectors of other types (as long as they have the same
+   size).</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>bitcast</tt>' instruction converts <tt>value</tt> to type
+   <tt>ty2</tt>. It is always a <i>no-op cast</i> because no bits change with
+   this conversion.  The conversion is done as if the <tt>value</tt> had been
+   stored to memory and read back as type <tt>ty2</tt>.
+   Pointer (or vector of pointers) types may only be converted to other pointer
+   (or vector of pointers) types with this instruction. To convert
+   pointers to other types, use the <a href="#i_inttoptr">inttoptr</a> or
+   <a href="#i_ptrtoint">ptrtoint</a> instructions first.</p>
+
+<h5>Example:</h5>
+<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 <2 x int> %V to i64;        <i>; yields i64: %V</i>
+  %Z = bitcast <2 x i32*> %V to <2 x i64*> <i>; yields <2 x i64*></i>
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="otherops">Other Operations</a>
+</h3>
+
+<div>
+
+<p>The instructions in this category are the "miscellaneous" instructions, which
+   defy better classification.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_icmp">'<tt>icmp</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = icmp <cond> <ty> <op1>, <op2>   <i>; yields {i1} or {<N x i1>}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>icmp</tt>' instruction returns a boolean value or a vector of
+   boolean values based on comparison of its two integer, integer vector,
+   pointer, or pointer vector operands.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>icmp</tt>' instruction takes three operands. The first operand is
+   the condition code indicating the kind of comparison to perform. It is not a
+   value, just a keyword. The possible condition code are:</p>
+
+<ol>
+  <li><tt>eq</tt>: equal</li>
+  <li><tt>ne</tt>: not equal </li>
+  <li><tt>ugt</tt>: unsigned greater than</li>
+  <li><tt>uge</tt>: unsigned greater or equal</li>
+  <li><tt>ult</tt>: unsigned less than</li>
+  <li><tt>ule</tt>: unsigned less or equal</li>
+  <li><tt>sgt</tt>: signed greater than</li>
+  <li><tt>sge</tt>: signed greater or equal</li>
+  <li><tt>slt</tt>: signed less than</li>
+  <li><tt>sle</tt>: signed less or equal</li>
+</ol>
+
+<p>The remaining two arguments must be <a href="#t_integer">integer</a> or
+   <a href="#t_pointer">pointer</a> or integer <a href="#t_vector">vector</a>
+   typed.  They must also be identical types.</p>
+
+<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_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,
+      <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,
+      <tt>false</tt> otherwise. No sign interpretation is necessary or
+      performed.</li>
+
+  <li><tt>ugt</tt>: interprets the operands as unsigned values and yields
+      <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
+
+  <li><tt>uge</tt>: interprets the operands as unsigned values and yields
+      <tt>true</tt> if <tt>op1</tt> is greater than or equal
+      to <tt>op2</tt>.</li>
+
+  <li><tt>ult</tt>: interprets the operands as unsigned values and yields
+      <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
+
+  <li><tt>ule</tt>: interprets the operands as unsigned values and yields
+      <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
+
+  <li><tt>sgt</tt>: interprets the operands as signed values and yields
+      <tt>true</tt> if <tt>op1</tt> is greater than <tt>op2</tt>.</li>
+
+  <li><tt>sge</tt>: interprets the operands as signed values and yields
+      <tt>true</tt> if <tt>op1</tt> is greater than or equal
+      to <tt>op2</tt>.</li>
+
+  <li><tt>slt</tt>: interprets the operands as signed values and yields
+      <tt>true</tt> if <tt>op1</tt> is less than <tt>op2</tt>.</li>
+
+  <li><tt>sle</tt>: interprets the operands as signed values and yields
+      <tt>true</tt> if <tt>op1</tt> is less than or equal to <tt>op2</tt>.</li>
+</ol>
+
+<p>If the operands are <a href="#t_pointer">pointer</a> typed, the pointer
+   values are compared as if they were integers.</p>
+
+<p>If the operands are integer vectors, then they are compared element by
+   element. The result is an <tt>i1</tt> vector with the same number of elements
+   as the values being compared.  Otherwise, the result is an <tt>i1</tt>.</p>
+
+<h5>Example:</h5>
+<pre>
+  <result> = icmp eq i32 4, 5          <i>; yields: result=false</i>
+  <result> = icmp ne float* %X, %X     <i>; yields: result=false</i>
+  <result> = icmp ult i16  4, 5        <i>; yields: result=true</i>
+  <result> = icmp sgt i16  4, 5        <i>; yields: result=false</i>
+  <result> = icmp ule i16 -4, 5        <i>; yields: result=false</i>
+  <result> = icmp sge i16  4, 5        <i>; yields: result=false</i>
+</pre>
+
+<p>Note that the code generator does not yet support vector types with
+   the <tt>icmp</tt> instruction.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_fcmp">'<tt>fcmp</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = fcmp <cond> <ty> <op1>, <op2>     <i>; yields {i1} or {<N x i1>}:result</i>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>fcmp</tt>' instruction returns a boolean value or vector of boolean
+   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_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
+   compared.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>fcmp</tt>' instruction takes three operands. The first operand is
+   the condition code indicating the kind of comparison to perform. It is not a
+   value, just a keyword. The possible condition code are:</p>
+
+<ol>
+  <li><tt>false</tt>: no comparison, always returns false</li>
+  <li><tt>oeq</tt>: ordered and equal</li>
+  <li><tt>ogt</tt>: ordered and greater than </li>
+  <li><tt>oge</tt>: ordered and greater than or equal</li>
+  <li><tt>olt</tt>: ordered and less than </li>
+  <li><tt>ole</tt>: ordered and less than or equal</li>
+  <li><tt>one</tt>: ordered and not equal</li>
+  <li><tt>ord</tt>: ordered (no nans)</li>
+  <li><tt>ueq</tt>: unordered or equal</li>
+  <li><tt>ugt</tt>: unordered or greater than </li>
+  <li><tt>uge</tt>: unordered or greater than or equal</li>
+  <li><tt>ult</tt>: unordered or less than </li>
+  <li><tt>ule</tt>: unordered or less than or equal</li>
+  <li><tt>une</tt>: unordered or not equal</li>
+  <li><tt>uno</tt>: unordered (either nans)</li>
+  <li><tt>true</tt>: no comparison, always returns true</li>
+</ol>
+
+<p><i>Ordered</i> means that neither operand is a QNAN while
+   <i>unordered</i> means that either operand may be a QNAN.</p>
+
+<p>Each of <tt>val1</tt> and <tt>val2</tt> arguments must be either
+   a <a href="#t_floating">floating point</a> type or
+   a <a href="#t_vector">vector</a> of floating point type.  They must have
+   identical types.</p>
+
+<h5>Semantics:</h5>
+<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_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
+      <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 greater than <tt>op2</tt>.</li>
+
+  <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
+      <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
+      <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
+      <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
+      <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
+      <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
+      <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
+      <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
+      <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
+      <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>
+
+  <li><tt>true</tt>: always yields <tt>true</tt>, regardless of operands.</li>
+</ol>
+
+<h5>Example:</h5>
+<pre>
+  <result> = fcmp oeq float 4.0, 5.0    <i>; yields: result=false</i>
+  <result> = fcmp one float 4.0, 5.0    <i>; yields: result=true</i>
+  <result> = fcmp olt float 4.0, 5.0    <i>; yields: result=true</i>
+  <result> = fcmp ueq double 1.0, 2.0   <i>; yields: result=false</i>
+</pre>
+
+<p>Note that the code generator does not yet support vector types with
+   the <tt>fcmp</tt> instruction.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_phi">'<tt>phi</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = phi <ty> [ <val0>, <label0>], ...
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>phi</tt>' instruction is used to implement the φ node in the
+   SSA graph representing the function.</p>
+
+<h5>Arguments:</h5>
+<p>The type of the incoming values is specified with the first type field. After
+   this, the '<tt>phi</tt>' instruction takes a list of pairs as arguments, with
+   one pair for each predecessor basic block of the current block.  Only values
+   of <a href="#t_firstclass">first class</a> type may be used as the value
+   arguments to the PHI node.  Only labels may be used as the label
+   arguments.</p>
+
+<p>There must be no non-phi instructions between the start of a basic block and
+   the PHI instructions: i.e. PHI instructions must be first in a basic
+   block.</p>
+
+<p>For the purposes of the SSA form, the use of each incoming value is deemed to
+   occur on the edge from the corresponding predecessor block to the current
+   block (but after any definition of an '<tt>invoke</tt>' instruction's return
+   value on the same edge).</p>
+
+<h5>Semantics:</h5>
+<p>At runtime, the '<tt>phi</tt>' instruction logically takes on the value
+   specified by the pair corresponding to the predecessor basic block that
+   executed just prior to the current block.</p>
+
+<h5>Example:</h5>
+<pre>
+Loop:       ; Infinite loop that counts from 0 on up...
+  %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
+  %nextindvar = add i32 %indvar, 1
+  br label %Loop
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+   <a name="i_select">'<tt>select</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = select <i>selty</i> <cond>, <ty> <val1>, <ty> <val2>             <i>; yields ty</i>
+
+  <i>selty</i> is either i1 or {<N x i1>}
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>select</tt>' instruction is used to choose one value based on a
+   condition, without branching.</p>
+
+
+<h5>Arguments:</h5>
+<p>The '<tt>select</tt>' instruction requires an 'i1' value or a vector of 'i1'
+   values indicating the condition, and two values of the
+   same <a href="#t_firstclass">first class</a> type.  If the val1/val2 are
+   vectors and the condition is a scalar, then entire vectors are selected, not
+   individual elements.</p>
+
+<h5>Semantics:</h5>
+<p>If the condition is an i1 and it evaluates to 1, the instruction returns the
+   first value argument; otherwise, it returns the second value argument.</p>
+
+<p>If the condition is a vector of i1, then the value arguments must be vectors
+   of the same size, and the selection is done element by element.</p>
+
+<h5>Example:</h5>
+<pre>
+  %X = select i1 true, i8 17, i8 42          <i>; yields i8:17</i>
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_call">'<tt>call</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <result> = [tail] call [<a href="#callingconv">cconv</a>] [<a href="#paramattrs">ret attrs</a>] <ty> [<fnty>*] <fnptrval>(<function args>) [<a href="#fnattrs">fn attrs</a>]
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>call</tt>' instruction represents a simple function call.</p>
+
+<h5>Arguments:</h5>
+<p>This instruction requires several arguments:</p>
+
+<ol>
+  <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>.  The code generator may optimize calls marked
+      "tail" with either 1) automatic <a href="CodeGenerator.html#sibcallopt">
+      sibling call optimization</a> when the caller and callee have
+      matching signatures, or 2) forced tail call optimization when the
+      following extra requirements are met:
+      <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::GuaranteedTailCallOpt</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.  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
+      '<tt>inreg</tt>' attributes are valid here.</li>
+
+  <li>'<tt>ty</tt>': the type of the call instruction itself which is also the
+      type of the return value.  Functions that return no value are marked
+      <tt><a href="#t_void">void</a></tt>.</li>
+
+  <li>'<tt>fnty</tt>': shall be the signature of the pointer to function value
+      being invoked.  The argument types must match the types implied by this
+      signature.  This type can be omitted if the function is not varargs and if
+      the function type does not return a pointer to a function.</li>
+
+  <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 value.</li>
+
+  <li>'<tt>function args</tt>': argument list whose types match the function
+      signature argument types and parameter attributes. All arguments must be
+      of <a href="#t_firstclass">first class</a> type. If the function
+      signature indicates the function accepts a variable number of arguments,
+      the extra arguments can be specified.</li>
+
+  <li>The optional <a href="#fnattrs">function attributes</a> list. Only
+      '<tt>noreturn</tt>', '<tt>nounwind</tt>', '<tt>readonly</tt>' and
+      '<tt>readnone</tt>' attributes are valid here.</li>
+</ol>
+
+<h5>Semantics:</h5>
+<p>The '<tt>call</tt>' instruction is used to cause control flow to transfer to
+   a specified function, with its incoming arguments bound to the specified
+   values. Upon a '<tt><a href="#i_ret">ret</a></tt>' instruction in the called
+   function, control flow continues with the instruction after the function
+   call, and the return value of the function is bound to the result
+   argument.</p>
+
+<h5>Example:</h5>
+<pre>
+  %retval = call i32 @test(i32 %argc)
+  call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42)        <i>; yields i32</i>
+  %X = tail call i32 @foo()                                    <i>; yields i32</i>
+  %Y = tail call <a href="#callingconv">fastcc</a> i32 @foo()  <i>; yields i32</i>
+  call void %foo(i8 97 signext)
+
+  %struct.A = type { i32, i8 }
+  %r = call %struct.A @foo()                        <i>; yields { 32, i8 }</i>
+  %gr = extractvalue %struct.A %r, 0                <i>; yields i32</i>
+  %gr1 = extractvalue %struct.A %r, 1               <i>; yields i8</i>
+  %Z = call void @foo() noreturn                    <i>; indicates that %foo never returns normally</i>
+  %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 languages.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_va_arg">'<tt>va_arg</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <resultval> = va_arg <va_list*> <arglist>, <argty>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>va_arg</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>
+<p>This instruction takes a <tt>va_list*</tt> value and the type of the
+   argument. It returns a value of the specified argument type and increments
+   the <tt>va_list</tt> to point to the next argument.  The actual type
+   of <tt>va_list</tt> is target specific.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>va_arg</tt>' instruction loads an argument of the specified type
+   from the specified <tt>va_list</tt> and causes the <tt>va_list</tt> to point
+   to the next argument.  For more information, see the variable argument
+   handling <a href="#int_varargs">Intrinsic Functions</a>.</p>
+
+<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>
+
+<p><tt>va_arg</tt> is an LLVM instruction instead of
+   an <a href="#intrinsics">intrinsic function</a> because it takes a type as an
+   argument.</p>
+
+<h5>Example:</h5>
+<p>See the <a href="#int_varargs">variable argument processing</a> section.</p>
+
+<p>Note that the code generator does not yet fully support va_arg on many
+   targets. Also, it does not currently support va_arg with aggregate types on
+   any target.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="i_landingpad">'<tt>landingpad</tt>' Instruction</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  <resultval> = landingpad <resultty> personality <type> <pers_fn> <clause>+
+  <resultval> = landingpad <resultty> personality <type> <pers_fn> cleanup <clause>*
+
+  <clause> := catch <type> <value>
+  <clause> := filter <array constant type> <array constant>
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>landingpad</tt>' instruction is used by
+   <a href="ExceptionHandling.html#overview">LLVM's exception handling
+   system</a> to specify that a basic block is a landing pad — one where
+   the exception lands, and corresponds to the code found in the
+   <i><tt>catch</tt></i> portion of a <i><tt>try/catch</tt></i> sequence. It
+   defines values supplied by the personality function (<tt>pers_fn</tt>) upon
+   re-entry to the function. The <tt>resultval</tt> has the
+   type <tt>resultty</tt>.</p>
+
+<h5>Arguments:</h5>
+<p>This instruction takes a <tt>pers_fn</tt> value. This is the personality
+   function associated with the unwinding mechanism. The optional
+   <tt>cleanup</tt> flag indicates that the landing pad block is a cleanup.</p>
+
+<p>A <tt>clause</tt> begins with the clause type — <tt>catch</tt>
+   or <tt>filter</tt> — and contains the global variable representing the
+   "type" that may be caught or filtered respectively. Unlike the
+   <tt>catch</tt> clause, the <tt>filter</tt> clause takes an array constant as
+   its argument. Use "<tt>[0 x i8**] undef</tt>" for a filter which cannot
+   throw. The '<tt>landingpad</tt>' instruction must contain <em>at least</em>
+   one <tt>clause</tt> or the <tt>cleanup</tt> flag.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>landingpad</tt>' instruction defines the values which are set by the
+   personality function (<tt>pers_fn</tt>) upon re-entry to the function, and
+   therefore the "result type" of the <tt>landingpad</tt> instruction. As with
+   calling conventions, how the personality function results are represented in
+   LLVM IR is target specific.</p>
+
+<p>The clauses are applied in order from top to bottom. If two
+   <tt>landingpad</tt> instructions are merged together through inlining, the
+   clauses from the calling function are appended to the list of clauses.
+   When the call stack is being unwound due to an exception being thrown, the
+   exception is compared against each <tt>clause</tt> in turn.  If it doesn't
+   match any of the clauses, and the <tt>cleanup</tt> flag is not set, then
+   unwinding continues further up the call stack.</p>
+
+<p>The <tt>landingpad</tt> instruction has several restrictions:</p>
+
+<ul>
+  <li>A landing pad block is a basic block which is the unwind destination of an
+      '<tt>invoke</tt>' instruction.</li>
+  <li>A landing pad block must have a '<tt>landingpad</tt>' instruction as its
+      first non-PHI instruction.</li>
+  <li>There can be only one '<tt>landingpad</tt>' instruction within the landing
+      pad block.</li>
+  <li>A basic block that is not a landing pad block may not include a
+      '<tt>landingpad</tt>' instruction.</li>
+  <li>All '<tt>landingpad</tt>' instructions in a function must have the same
+      personality function.</li>
+</ul>
+
+<h5>Example:</h5>
+<pre>
+  ;; A landing pad which can catch an integer.
+  %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
+           catch i8** @_ZTIi
+  ;; A landing pad that is a cleanup.
+  %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
+           cleanup
+  ;; A landing pad which can catch an integer and can only throw a double.
+  %res = landingpad { i8*, i32 } personality i32 (...)* @__gxx_personality_v0
+           catch i8** @_ZTIi
+           filter [1 x i8**] [@_ZTId]
+</pre>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2><a name="intrinsics">Intrinsic Functions</a></h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>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 intrinsics represent an extension mechanism for
+   the LLVM language that does not require changing all of the transformations
+   in LLVM when adding to the language (or the bitcode reader/writer, the
+   parser, etc...).</p>
+
+<p>Intrinsic function names must all start with an "<tt>llvm.</tt>" prefix. This
+   prefix is reserved in LLVM for intrinsic names; thus, function names may not
+   begin with this prefix.  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 if any are added that
+   they be documented here.</p>
+
+<p>Some intrinsic functions can be overloaded, i.e., the intrinsic represents a
+   family of functions that perform the same operation but on different data
+   types. Because LLVM can represent over 8 million different integer types,
+   overloading is used commonly to allow an intrinsic function to operate on any
+   integer type. One or more of the argument types or the result type can be
+   overloaded to accept any integer type. Argument types may also be defined as
+   exactly matching a previous argument's type or the result type. This allows
+   an intrinsic function which accepts multiple arguments, but needs all of them
+   to be of the same type, to only be overloaded with respect to a single
+   argument or the result.</p>
+
+<p>Overloaded intrinsics will have the names of its overloaded argument types
+   encoded into its function name, each preceded by a period. Only those types
+   which are overloaded result in a name suffix. Arguments whose type is matched
+   against another type do not. For example, the <tt>llvm.ctpop</tt> function
+   can take an integer of any width and returns an integer of exactly the same
+   integer width. This leads to a family of functions such as
+   <tt>i8 @llvm.ctpop.i8(i8 %val)</tt> and <tt>i29 @llvm.ctpop.i29(i29
+   %val)</tt>.  Only one type, the return type, is overloaded, and only one type
+   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
+   <a href="ExtendingLLVM.html">Extending LLVM Guide</a>.</p>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_varargs">Variable Argument Handling Intrinsics</a>
+</h3>
+
+<div>
+
+<p>Variable argument support is defined in LLVM with
+   the <a href="#i_va_arg"><tt>va_arg</tt></a> instruction and these three
+   intrinsic functions.  These functions are related to the similarly named
+   macros defined in the <tt><stdarg.h></tt> header file.</p>
+
+<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 these functions regardless of the type used.</p>
+
+<p>This example shows how the <a href="#i_va_arg"><tt>va_arg</tt></a>
+   instruction and the variable argument handling intrinsic functions are
+   used.</p>
+
+<pre class="doc_code">
+define i32 @test(i32 %X, ...) {
+  ; Initialize variable argument processing
+  %ap = alloca i8*
+  %ap2 = bitcast i8** %ap to i8*
+  call void @llvm.va_start(i8* %ap2)
+
+  ; Read a single integer argument
+  %tmp = va_arg i8** %ap, i32
+
+  ; Demonstrate usage of llvm.va_copy and llvm.va_end
+  %aq = alloca i8*
+  %aq2 = bitcast i8** %aq to i8*
+  call void @llvm.va_copy(i8* %aq2, i8* %ap2)
+  call void @llvm.va_end(i8* %aq2)
+
+  ; Stop processing of arguments.
+  call void @llvm.va_end(i8* %ap2)
+  ret i32 %tmp
+}
+
+declare void @llvm.va_start(i8*)
+declare void @llvm.va_copy(i8*, i8*)
+declare void @llvm.va_end(i8*)
+</pre>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_va_start">'<tt>llvm.va_start</tt>' Intrinsic</a>
+</h4>
+
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void %llvm.va_start(i8* <arglist>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.va_start</tt>' intrinsic initializes <tt>*<arglist></tt>
+   for subsequent use by <tt><a href="#i_va_arg">va_arg</a></tt>.</p>
+
+<h5>Arguments:</h5>
+<p>The argument is a pointer to a <tt>va_list</tt> element to initialize.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.va_start</tt>' intrinsic works just like the <tt>va_start</tt>
+   macro available in C.  In a target-dependent way, it initializes
+   the <tt>va_list</tt> element to which the argument points, so that the next
+   call to <tt>va_arg</tt> will produce the first variable argument passed to
+   the function.  Unlike the C <tt>va_start</tt> macro, this intrinsic does not
+   need to know the last argument of the function as the compiler can figure
+   that out.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+ <a name="int_va_end">'<tt>llvm.va_end</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.va_end(i8* <arglist>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.va_end</tt>' intrinsic destroys <tt>*<arglist></tt>,
+   which has been initialized previously
+   with <tt><a href="#int_va_start">llvm.va_start</a></tt>
+   or <tt><a href="#i_va_copy">llvm.va_copy</a></tt>.</p>
+
+<h5>Arguments:</h5>
+<p>The argument is a pointer to a <tt>va_list</tt> to destroy.</p>
+
+<h5>Semantics:</h5>
+<p>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> element to which the argument points.  Calls
+   to <a href="#int_va_start"><tt>llvm.va_start</tt></a>
+   and <a href="#int_va_copy"> <tt>llvm.va_copy</tt></a> must be matched exactly
+   with calls to <tt>llvm.va_end</tt>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_va_copy">'<tt>llvm.va_copy</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
+</pre>
+
+<h5>Overview:</h5>
+<p>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>
+<p>The first argument is a pointer to a <tt>va_list</tt> element to initialize.
+   The second argument is a pointer to a <tt>va_list</tt> element to copy
+   from.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.va_copy</tt>' intrinsic works just like the <tt>va_copy</tt>
+   macro available in C.  In a target-dependent way, it copies the
+   source <tt>va_list</tt> element into the destination <tt>va_list</tt>
+   element.  This intrinsic is necessary because
+   the <tt><a href="#int_va_start"> llvm.va_start</a></tt> intrinsic may be
+   arbitrarily complex and require, for example, memory allocation.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_gc">Accurate Garbage Collection Intrinsics</a>
+</h3>
+
+<div>
+
+<p>LLVM support for <a href="GarbageCollection.html">Accurate Garbage
+Collection</a> (GC) requires the implementation and generation of these
+intrinsics. These intrinsics allow identification of <a href="#int_gcroot">GC
+roots on the stack</a>, as well as garbage collector implementations that
+require <a href="#int_gcread">read</a> and <a href="#int_gcwrite">write</a>
+barriers.  Front-ends for type-safe garbage collected languages should generate
+these intrinsics to make use of the LLVM garbage collectors.  For more details,
+see <a href="GarbageCollection.html">Accurate Garbage Collection with
+LLVM</a>.</p>
+
+<p>The garbage collection intrinsics only operate on objects in the generic
+   address space (address space zero).</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_gcroot">'<tt>llvm.gcroot</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.gcroot</tt>' intrinsic declares the existence of a GC root to
+   the code generator, and allows some metadata to be associated with it.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument specifies the address of a stack object that contains the
+   root pointer.  The second pointer (which must be either a constant or a
+   global value address) contains the meta-data to be associated with the
+   root.</p>
+
+<h5>Semantics:</h5>
+<p>At runtime, a call to this intrinsic stores a null pointer into the "ptrloc"
+   location.  At compile-time, the code generator generates information to allow
+   the runtime to find the pointer at GC safe points. The '<tt>llvm.gcroot</tt>'
+   intrinsic may only be used in a function which <a href="#gc">specifies a GC
+   algorithm</a>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_gcread">'<tt>llvm.gcread</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.gcread</tt>' intrinsic identifies reads of references from heap
+   locations, allowing garbage collector implementations that require read
+   barriers.</p>
+
+<h5>Arguments:</h5>
+<p>The second argument is the address to read from, which should be an address
+   allocated from the garbage collector.  The first object is a pointer to the
+   start of the referenced object, if needed by the language runtime (otherwise
+   null).</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.gcread</tt>' intrinsic has the same semantics as a load
+   instruction, but may be replaced with substantially more complex code by the
+   garbage collector runtime, as needed. The '<tt>llvm.gcread</tt>' intrinsic
+   may only be used in a function which <a href="#gc">specifies a GC
+   algorithm</a>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_gcwrite">'<tt>llvm.gcwrite</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.gcwrite</tt>' intrinsic identifies writes of references to heap
+   locations, allowing garbage collector implementations that require write
+   barriers (such as generational or reference counting collectors).</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is the reference to store, the second is the start of the
+   object to store it to, and the third is the address of the field of Obj to
+   store to.  If the runtime does not require a pointer to the object, Obj may
+   be null.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.gcwrite</tt>' intrinsic has the same semantics as a store
+   instruction, but may be replaced with substantially more complex code by the
+   garbage collector runtime, as needed. The '<tt>llvm.gcwrite</tt>' intrinsic
+   may only be used in a function which <a href="#gc">specifies a GC
+   algorithm</a>.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_codegen">Code Generator Intrinsics</a>
+</h3>
+
+<div>
+
+<p>These intrinsics are provided by LLVM to expose special features that may
+   only be implemented with code generator support.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_returnaddress">'<tt>llvm.returnaddress</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare i8  *@llvm.returnaddress(i32 <level>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.returnaddress</tt>' intrinsic attempts to compute a
+   target-specific value indicating the return address of the current function
+   or one of its callers.</p>
+
+<h5>Arguments:</h5>
+<p>The argument to this intrinsic indicates which function to return the address
+   for.  Zero indicates the calling function, one indicates its caller, etc.
+   The argument is <b>required</b> to be a constant integer value.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.returnaddress</tt>' intrinsic either returns a pointer
+   indicating the return address of the specified call frame, or zero if it
+   cannot be identified.  The value returned by this intrinsic is likely to be
+   incorrect or 0 for arguments other than zero, so it should only be used for
+   debugging purposes.</p>
+
+<p>Note that calling this intrinsic does not prevent function inlining or other
+   aggressive transformations, so the value returned may not be that of the
+   obvious source-language caller.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_frameaddress">'<tt>llvm.frameaddress</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare i8* @llvm.frameaddress(i32 <level>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.frameaddress</tt>' intrinsic attempts to return the
+   target-specific frame pointer value for the specified stack frame.</p>
+
+<h5>Arguments:</h5>
+<p>The argument to this intrinsic indicates which function to return the frame
+   pointer for.  Zero indicates the calling function, one indicates its caller,
+   etc.  The argument is <b>required</b> to be a constant integer value.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.frameaddress</tt>' intrinsic either returns a pointer
+   indicating the frame address of the specified call frame, or zero if it
+   cannot be identified.  The value returned by this intrinsic is likely to be
+   incorrect or 0 for arguments other than zero, so it should only be used for
+   debugging purposes.</p>
+
+<p>Note that calling this intrinsic does not prevent function inlining or other
+   aggressive transformations, so the value returned may not be that of the
+   obvious source-language caller.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_stacksave">'<tt>llvm.stacksave</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare i8* @llvm.stacksave()
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.stacksave</tt>' intrinsic is used to remember the current state
+   of the function stack, for use
+   with <a href="#int_stackrestore"> <tt>llvm.stackrestore</tt></a>.  This is
+   useful for implementing language features like scoped automatic variable
+   sized arrays in C99.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic returns a opaque pointer value that can be passed
+   to <a href="#int_stackrestore"><tt>llvm.stackrestore</tt></a>.  When
+   an <tt>llvm.stackrestore</tt> intrinsic is executed with a value saved
+   from <tt>llvm.stacksave</tt>, it effectively restores the state of the stack
+   to the state it was in when the <tt>llvm.stacksave</tt> intrinsic executed.
+   In practice, this pops any <a href="#i_alloca">alloca</a> blocks from the
+   stack that were allocated after the <tt>llvm.stacksave</tt> was executed.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_stackrestore">'<tt>llvm.stackrestore</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.stackrestore(i8* %ptr)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.stackrestore</tt>' intrinsic is used to restore the state of
+   the function stack to the state it was in when the
+   corresponding <a href="#int_stacksave"><tt>llvm.stacksave</tt></a> intrinsic
+   executed.  This is useful for implementing language features like scoped
+   automatic variable sized arrays in C99.</p>
+
+<h5>Semantics:</h5>
+<p>See the description
+   for <a href="#int_stacksave"><tt>llvm.stacksave</tt></a>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_prefetch">'<tt>llvm.prefetch</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.prefetch</tt>' intrinsic is a hint to the code generator to
+   insert a prefetch instruction if supported; otherwise, it is a noop.
+   Prefetches have no effect on the behavior of the program but can change its
+   performance characteristics.</p>
+
+<h5>Arguments:</h5>
+<p><tt>address</tt> is the address to be prefetched, <tt>rw</tt> is the
+   specifier determining if the fetch should be for a read (0) or write (1),
+   and <tt>locality</tt> is a temporal locality specifier ranging from (0) - no
+   locality, to (3) - extremely local keep in cache. The <tt>cache type</tt>
+   specifies whether the prefetch is performed on the data (1) or instruction (0)
+   cache. The <tt>rw</tt>, <tt>locality</tt> and <tt>cache type</tt> arguments
+   must be constant integers.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic does not modify the behavior of the program.  In particular,
+   prefetches cannot trap and do not produce a value.  On targets that support
+   this intrinsic, the prefetch can provide hints to the processor cache for
+   better performance.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_pcmarker">'<tt>llvm.pcmarker</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.pcmarker(i32 <id>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.pcmarker</tt>' intrinsic is a method to export a Program
+   Counter (PC) in a region of code to simulators and other tools.  The method
+   is target specific, but it is expected that the marker will use exported
+   symbols to transmit the PC of the marker.  The marker makes no guarantees
+   that it will remain with any specific instruction after optimizations.  It is
+   possible that the presence of a marker will inhibit optimizations.  The
+   intended use is to be inserted after optimizations to allow correlations of
+   simulation runs.</p>
+
+<h5>Arguments:</h5>
+<p><tt>id</tt> is a numerical id identifying the marker.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic does not modify the behavior of the program.  Backends that do
+   not support this intrinsic may ignore it.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_readcyclecounter">'<tt>llvm.readcyclecounter</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare i64 @llvm.readcyclecounter()
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.readcyclecounter</tt>' intrinsic provides access to the cycle
+   counter register (or similar low latency, high accuracy clocks) on those
+   targets that support it.  On X86, it should map to RDTSC.  On Alpha, it
+   should map to RPCC.  As the backing counters overflow quickly (on the order
+   of 9 seconds on alpha), this should only be used for small timings.</p>
+
+<h5>Semantics:</h5>
+<p>When directly supported, reading the cycle counter should not modify any
+   memory.  Implementations are allowed to either return a application specific
+   value or a system wide value.  On backends without support, this is lowered
+   to a constant 0.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_libc">Standard C Library Intrinsics</a>
+</h3>
+
+<div>
+
+<p>LLVM provides intrinsics for a few important standard C library functions.
+   These intrinsics allow source-language front-ends to pass information about
+   the alignment of the pointer arguments to the code generator, providing
+   opportunity for more efficient code generation.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_memcpy">'<tt>llvm.memcpy</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.memcpy</tt> on any
+   integer bit width and for different address spaces. Not all targets support
+   all bit widths however.</p>
+
+<pre>
+  declare void @llvm.memcpy.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
+                                          i32 <len>, i32 <align>, i1 <isvolatile>)
+  declare void @llvm.memcpy.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
+                                          i64 <len>, i32 <align>, i1 <isvolatile>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
+   source location to the destination location.</p>
+
+<p>Note that, unlike the standard libc function, the <tt>llvm.memcpy.*</tt>
+   intrinsics do not return a value, takes extra alignment/isvolatile arguments
+   and the pointers can be in specified address spaces.</p>
+
+<h5>Arguments:</h5>
+
+<p>The first argument is a pointer to the destination, the second is a pointer
+   to the source.  The third argument is an integer argument specifying the
+   number of bytes to copy, the fourth argument is the alignment of the
+   source and destination locations, and the fifth is a boolean indicating a
+   volatile access.</p>
+
+<p>If the call to this intrinsic has an alignment value that is not 0 or 1,
+   then the caller guarantees that both the source and destination pointers are
+   aligned to that boundary.</p>
+
+<p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
+   <tt>llvm.memcpy</tt> call is a <a href="#volatile">volatile operation</a>.
+   The detailed access behavior is not very cleanly specified and it is unwise
+   to depend on it.</p>
+
+<h5>Semantics:</h5>
+
+<p>The '<tt>llvm.memcpy.*</tt>' intrinsics copy a block of memory from the
+   source location to the destination location, which are not allowed to
+   overlap.  It copies "len" bytes of memory over.  If the argument is known to
+   be aligned to some boundary, this can be specified as the fourth argument,
+   otherwise it should be set to 0 or 1.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_memmove">'<tt>llvm.memmove</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use llvm.memmove on any integer bit
+   width and for different address space. Not all targets support all bit
+   widths however.</p>
+
+<pre>
+  declare void @llvm.memmove.p0i8.p0i8.i32(i8* <dest>, i8* <src>,
+                                           i32 <len>, i32 <align>, i1 <isvolatile>)
+  declare void @llvm.memmove.p0i8.p0i8.i64(i8* <dest>, i8* <src>,
+                                           i64 <len>, i32 <align>, i1 <isvolatile>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.memmove.*</tt>' intrinsics move a block of memory from the
+   source location to the destination location. It is similar to the
+   '<tt>llvm.memcpy</tt>' intrinsic but allows the two memory locations to
+   overlap.</p>
+
+<p>Note that, unlike the standard libc function, the <tt>llvm.memmove.*</tt>
+   intrinsics do not return a value, takes extra alignment/isvolatile arguments
+   and the pointers can be in specified address spaces.</p>
+
+<h5>Arguments:</h5>
+
+<p>The first argument is a pointer to the destination, the second is a pointer
+   to the source.  The third argument is an integer argument specifying the
+   number of bytes to copy, the fourth argument is the alignment of the
+   source and destination locations, and the fifth is a boolean indicating a
+   volatile access.</p>
+
+<p>If the call to this intrinsic has an alignment value that is not 0 or 1,
+   then the caller guarantees that the source and destination pointers are
+   aligned to that boundary.</p>
+
+<p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
+   <tt>llvm.memmove</tt> call is a <a href="#volatile">volatile operation</a>.
+   The detailed access behavior is not very cleanly specified and it is unwise
+   to depend on it.</p>
+
+<h5>Semantics:</h5>
+
+<p>The '<tt>llvm.memmove.*</tt>' intrinsics copy a block of memory from the
+   source location to the destination location, which may overlap.  It copies
+   "len" bytes of memory over.  If the argument is known to be aligned to some
+   boundary, this can be specified as the fourth argument, otherwise it should
+   be set to 0 or 1.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_memset">'<tt>llvm.memset.*</tt>' Intrinsics</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use llvm.memset on any integer bit
+   width and for different address spaces. However, not all targets support all
+   bit widths.</p>
+
+<pre>
+  declare void @llvm.memset.p0i8.i32(i8* <dest>, i8 <val>,
+                                     i32 <len>, i32 <align>, i1 <isvolatile>)
+  declare void @llvm.memset.p0i8.i64(i8* <dest>, i8 <val>,
+                                     i64 <len>, i32 <align>, i1 <isvolatile>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.memset.*</tt>' intrinsics fill a block of memory with a
+   particular byte value.</p>
+
+<p>Note that, unlike the standard libc function, the <tt>llvm.memset</tt>
+   intrinsic does not return a value and takes extra alignment/volatile
+   arguments.  Also, the destination can be in an arbitrary address space.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is a pointer to the destination to fill, the second is the
+   byte value with which to fill it, the third argument is an integer argument
+   specifying the number of bytes to fill, and the fourth argument is the known
+   alignment of the destination location.</p>
+
+<p>If the call to this intrinsic has an alignment value that is not 0 or 1,
+   then the caller guarantees that the destination pointer is aligned to that
+   boundary.</p>
+
+<p>If the <tt>isvolatile</tt> parameter is <tt>true</tt>, the
+   <tt>llvm.memset</tt> call is a <a href="#volatile">volatile operation</a>.
+   The detailed access behavior is not very cleanly specified and it is unwise
+   to depend on it.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.memset.*</tt>' intrinsics fill "len" bytes of memory starting
+   at the destination location.  If the argument is known to be aligned to some
+   boundary, this can be specified as the fourth argument, otherwise it should
+   be set to 0 or 1.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_sqrt">'<tt>llvm.sqrt.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.sqrt</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.sqrt.f32(float %Val)
+  declare double    @llvm.sqrt.f64(double %Val)
+  declare x86_fp80  @llvm.sqrt.f80(x86_fp80 %Val)
+  declare fp128     @llvm.sqrt.f128(fp128 %Val)
+  declare ppc_fp128 @llvm.sqrt.ppcf128(ppc_fp128 %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.sqrt</tt>' intrinsics return the sqrt of the specified operand,
+   returning the same value as the libm '<tt>sqrt</tt>' functions would.
+   Unlike <tt>sqrt</tt> in libm, however, <tt>llvm.sqrt</tt> has undefined
+   behavior for negative numbers other than -0.0 (which allows for better
+   optimization, because there is no need to worry about errno being
+   set).  <tt>llvm.sqrt(-0.0)</tt> is defined to return -0.0 like IEEE sqrt.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+   type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the sqrt of the specified operand if it is a
+   nonnegative floating point number.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_powi">'<tt>llvm.powi.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.powi</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.powi.f32(float  %Val, i32 %power)
+  declare double    @llvm.powi.f64(double %Val, i32 %power)
+  declare x86_fp80  @llvm.powi.f80(x86_fp80  %Val, i32 %power)
+  declare fp128     @llvm.powi.f128(fp128 %Val, i32 %power)
+  declare ppc_fp128 @llvm.powi.ppcf128(ppc_fp128  %Val, i32 %power)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.powi.*</tt>' intrinsics return the first operand raised to the
+   specified (positive or negative) power.  The order of evaluation of
+   multiplications is not defined.  When a vector of floating point type is
+   used, the second argument remains a scalar integer value.</p>
+
+<h5>Arguments:</h5>
+<p>The second argument is an integer power, and the first is a value to raise to
+   that power.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the first value raised to the second power with an
+   unspecified sequence of rounding operations.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_sin">'<tt>llvm.sin.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.sin</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.sin.f32(float  %Val)
+  declare double    @llvm.sin.f64(double %Val)
+  declare x86_fp80  @llvm.sin.f80(x86_fp80  %Val)
+  declare fp128     @llvm.sin.f128(fp128 %Val)
+  declare ppc_fp128 @llvm.sin.ppcf128(ppc_fp128  %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.sin.*</tt>' intrinsics return the sine of the operand.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+   type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the sine of the specified operand, returning the same
+   values as the libm <tt>sin</tt> functions would, and handles error conditions
+   in the same way.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_cos">'<tt>llvm.cos.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.cos</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.cos.f32(float  %Val)
+  declare double    @llvm.cos.f64(double %Val)
+  declare x86_fp80  @llvm.cos.f80(x86_fp80  %Val)
+  declare fp128     @llvm.cos.f128(fp128 %Val)
+  declare ppc_fp128 @llvm.cos.ppcf128(ppc_fp128  %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.cos.*</tt>' intrinsics return the cosine of the operand.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+   type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the cosine of the specified operand, returning the same
+   values as the libm <tt>cos</tt> functions would, and handles error conditions
+   in the same way.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_pow">'<tt>llvm.pow.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.pow</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.pow.f32(float  %Val, float %Power)
+  declare double    @llvm.pow.f64(double %Val, double %Power)
+  declare x86_fp80  @llvm.pow.f80(x86_fp80  %Val, x86_fp80 %Power)
+  declare fp128     @llvm.pow.f128(fp128 %Val, fp128 %Power)
+  declare ppc_fp128 @llvm.pow.ppcf128(ppc_fp128  %Val, ppc_fp128 Power)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.pow.*</tt>' intrinsics return the first operand raised to the
+   specified (positive or negative) power.</p>
+
+<h5>Arguments:</h5>
+<p>The second argument is a floating point power, and the first is a value to
+   raise to that power.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the first value raised to the second power, returning
+   the same values as the libm <tt>pow</tt> functions would, and handles error
+   conditions in the same way.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_exp">'<tt>llvm.exp.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.exp</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.exp.f32(float  %Val)
+  declare double    @llvm.exp.f64(double %Val)
+  declare x86_fp80  @llvm.exp.f80(x86_fp80  %Val)
+  declare fp128     @llvm.exp.f128(fp128 %Val)
+  declare ppc_fp128 @llvm.exp.ppcf128(ppc_fp128  %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.exp.*</tt>' intrinsics perform the exp function.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+   type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the same values as the libm <tt>exp</tt> functions
+   would, and handles error conditions in the same way.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_log">'<tt>llvm.log.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.log</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.log.f32(float  %Val)
+  declare double    @llvm.log.f64(double %Val)
+  declare x86_fp80  @llvm.log.f80(x86_fp80  %Val)
+  declare fp128     @llvm.log.f128(fp128 %Val)
+  declare ppc_fp128 @llvm.log.ppcf128(ppc_fp128  %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.log.*</tt>' intrinsics perform the log function.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+   type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the same values as the libm <tt>log</tt> functions
+   would, and handles error conditions in the same way.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_fma">'<tt>llvm.fma.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.fma</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.fma.f32(float  %a, float  %b, float  %c)
+  declare double    @llvm.fma.f64(double %a, double %b, double %c)
+  declare x86_fp80  @llvm.fma.f80(x86_fp80 %a, x86_fp80 %b, x86_fp80 %c)
+  declare fp128     @llvm.fma.f128(fp128 %a, fp128 %b, fp128 %c)
+  declare ppc_fp128 @llvm.fma.ppcf128(ppc_fp128 %a, ppc_fp128 %b, ppc_fp128 %c)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.fma.*</tt>' intrinsics perform the fused multiply-add
+   operation.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+   type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the same values as the libm <tt>fma</tt> functions
+   would.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_fabs">'<tt>llvm.fabs.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.fabs</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.fabs.f32(float  %Val)
+  declare double    @llvm.fabs.f64(double %Val)
+  declare x86_fp80  @llvm.fabs.f80(x86_fp80  %Val)
+  declare fp128     @llvm.fabs.f128(fp128 %Val)
+  declare ppc_fp128 @llvm.fabs.ppcf128(ppc_fp128  %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.fabs.*</tt>' intrinsics return the absolute value of
+   the operand.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+   type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the same values as the libm <tt>fabs</tt> functions
+   would, and handles error conditions in the same way.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_floor">'<tt>llvm.floor.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.floor</tt> on any
+   floating point or vector of floating point type. Not all targets support all
+   types however.</p>
+
+<pre>
+  declare float     @llvm.floor.f32(float  %Val)
+  declare double    @llvm.floor.f64(double %Val)
+  declare x86_fp80  @llvm.floor.f80(x86_fp80  %Val)
+  declare fp128     @llvm.floor.f128(fp128 %Val)
+  declare ppc_fp128 @llvm.floor.ppcf128(ppc_fp128  %Val)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.floor.*</tt>' intrinsics return the floor of
+   the operand.</p>
+
+<h5>Arguments:</h5>
+<p>The argument and return value are floating point numbers of the same
+   type.</p>
+
+<h5>Semantics:</h5>
+<p>This function returns the same values as the libm <tt>floor</tt> functions
+   would, and handles error conditions in the same way.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_manip">Bit Manipulation Intrinsics</a>
+</h3>
+
+<div>
+
+<p>LLVM provides intrinsics for a few important bit manipulation operations.
+   These allow efficient code generation for some algorithms.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_bswap">'<tt>llvm.bswap.*</tt>' Intrinsics</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic function. You can use bswap on any integer
+   type that is an even number of bytes (i.e. BitWidth % 16 == 0).</p>
+
+<pre>
+  declare i16 @llvm.bswap.i16(i16 <id>)
+  declare i32 @llvm.bswap.i32(i32 <id>)
+  declare i64 @llvm.bswap.i64(i64 <id>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.bswap</tt>' family of intrinsics is used to byte swap integer
+   values with an even number of bytes (positive multiple of 16 bits).  These
+   are useful for performing operations on data that is not in the target's
+   native byte order.</p>
+
+<h5>Semantics:</h5>
+<p>The <tt>llvm.bswap.i16</tt> intrinsic returns an i16 value that has the high
+   and low byte of the input i16 swapped.  Similarly,
+   the <tt>llvm.bswap.i32</tt> intrinsic returns an i32 value that has the four
+   bytes of the input i32 swapped, so that if the input bytes are numbered 0, 1,
+   2, 3 then the returned i32 will have its bytes in 3, 2, 1, 0 order.
+   The <tt>llvm.bswap.i48</tt>, <tt>llvm.bswap.i64</tt> and other intrinsics
+   extend this concept to additional even-byte lengths (6 bytes, 8 bytes and
+   more, respectively).</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_ctpop">'<tt>llvm.ctpop.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use llvm.ctpop on any integer bit
+   width, or on any vector with integer elements. Not all targets support all
+  bit widths or vector types, however.</p>
+
+<pre>
+  declare i8 @llvm.ctpop.i8(i8  <src>)
+  declare i16 @llvm.ctpop.i16(i16 <src>)
+  declare i32 @llvm.ctpop.i32(i32 <src>)
+  declare i64 @llvm.ctpop.i64(i64 <src>)
+  declare i256 @llvm.ctpop.i256(i256 <src>)
+  declare <2 x i32> @llvm.ctpop.v2i32(<2 x i32> <src>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.ctpop</tt>' family of intrinsics counts the number of bits set
+   in a value.</p>
+
+<h5>Arguments:</h5>
+<p>The only argument is the value to be counted.  The argument may be of any
+   integer type, or a vector with integer elements.
+   The return type must match the argument type.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.ctpop</tt>' intrinsic counts the 1's in a variable, or within each
+   element of a vector.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_ctlz">'<tt>llvm.ctlz.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.ctlz</tt> on any
+   integer bit width, or any vector whose elements are integers. Not all
+   targets support all bit widths or vector types, however.</p>
+
+<pre>
+  declare i8   @llvm.ctlz.i8  (i8   <src>, i1 <is_zero_undef>)
+  declare i16  @llvm.ctlz.i16 (i16  <src>, i1 <is_zero_undef>)
+  declare i32  @llvm.ctlz.i32 (i32  <src>, i1 <is_zero_undef>)
+  declare i64  @llvm.ctlz.i64 (i64  <src>, i1 <is_zero_undef>)
+  declare i256 @llvm.ctlz.i256(i256 <src>, i1 <is_zero_undef>)
+  declase <2 x i32> @llvm.ctlz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.ctlz</tt>' family of intrinsic functions counts the number of
+   leading zeros in a variable.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is the value to be counted. This argument may be of any
+   integer type, or a vectory with integer element type. The return type
+   must match the first argument type.</p>
+
+<p>The second argument must be a constant and is a flag to indicate whether the
+   intrinsic should ensure that a zero as the first argument produces a defined
+   result. Historically some architectures did not provide a defined result for
+   zero values as efficiently, and many algorithms are now predicated on
+   avoiding zero-value inputs.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.ctlz</tt>' intrinsic counts the leading (most significant)
+   zeros in a variable, or within each element of the vector.
+   If <tt>src == 0</tt> then the result is the size in bits of the type of
+   <tt>src</tt> if <tt>is_zero_undef == 0</tt> and <tt>undef</tt> otherwise.
+   For example, <tt>llvm.ctlz(i32 2) = 30</tt>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_cttz">'<tt>llvm.cttz.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.cttz</tt> on any
+   integer bit width, or any vector of integer elements. Not all targets
+   support all bit widths or vector types, however.</p>
+
+<pre>
+  declare i8   @llvm.cttz.i8  (i8   <src>, i1 <is_zero_undef>)
+  declare i16  @llvm.cttz.i16 (i16  <src>, i1 <is_zero_undef>)
+  declare i32  @llvm.cttz.i32 (i32  <src>, i1 <is_zero_undef>)
+  declare i64  @llvm.cttz.i64 (i64  <src>, i1 <is_zero_undef>)
+  declare i256 @llvm.cttz.i256(i256 <src>, i1 <is_zero_undef>)
+  declase <2 x i32> @llvm.cttz.v2i32(<2 x i32> <src>, i1 <is_zero_undef>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.cttz</tt>' family of intrinsic functions counts the number of
+   trailing zeros.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is the value to be counted. This argument may be of any
+   integer type, or a vectory with integer element type. The return type
+   must match the first argument type.</p>
+
+<p>The second argument must be a constant and is a flag to indicate whether the
+   intrinsic should ensure that a zero as the first argument produces a defined
+   result. Historically some architectures did not provide a defined result for
+   zero values as efficiently, and many algorithms are now predicated on
+   avoiding zero-value inputs.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.cttz</tt>' intrinsic counts the trailing (least significant)
+   zeros in a variable, or within each element of a vector.
+   If <tt>src == 0</tt> then the result is the size in bits of the type of
+   <tt>src</tt> if <tt>is_zero_undef == 0</tt> and <tt>undef</tt> otherwise.
+   For example, <tt>llvm.cttz(2) = 1</tt>.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_overflow">Arithmetic with Overflow Intrinsics</a>
+</h3>
+
+<div>
+
+<p>LLVM provides intrinsics for some arithmetic with overflow operations.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_sadd_overflow">
+    '<tt>llvm.sadd.with.overflow.*</tt>' Intrinsics
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.sadd.with.overflow</tt>
+   on any integer bit width.</p>
+
+<pre>
+  declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
+  declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
+  declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
+   a signed addition of the two arguments, and indicate whether an overflow
+   occurred during the signed summation.</p>
+
+<h5>Arguments:</h5>
+<p>The arguments (%a and %b) and the first element of the result structure may
+   be of integer types of any bit width, but they must have the same bit
+   width. The second element of the result structure must be of
+   type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
+   undergo signed addition.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.sadd.with.overflow</tt>' family of intrinsic functions perform
+   a signed addition of the two variables. They return a structure — the
+   first element of which is the signed summation, and the second element of
+   which is a bit specifying if the signed summation resulted in an
+   overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %res = call {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
+  %sum = extractvalue {i32, i1} %res, 0
+  %obit = extractvalue {i32, i1} %res, 1
+  br i1 %obit, label %overflow, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_uadd_overflow">
+    '<tt>llvm.uadd.with.overflow.*</tt>' Intrinsics
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.uadd.with.overflow</tt>
+   on any integer bit width.</p>
+
+<pre>
+  declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
+  declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
+  declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
+   an unsigned addition of the two arguments, and indicate whether a carry
+   occurred during the unsigned summation.</p>
+
+<h5>Arguments:</h5>
+<p>The arguments (%a and %b) and the first element of the result structure may
+   be of integer types of any bit width, but they must have the same bit
+   width. The second element of the result structure must be of
+   type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
+   undergo unsigned addition.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.uadd.with.overflow</tt>' family of intrinsic functions perform
+   an unsigned addition of the two arguments. They return a structure —
+   the first element of which is the sum, and the second element of which is a
+   bit specifying if the unsigned summation resulted in a carry.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %res = call {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
+  %sum = extractvalue {i32, i1} %res, 0
+  %obit = extractvalue {i32, i1} %res, 1
+  br i1 %obit, label %carry, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_ssub_overflow">
+    '<tt>llvm.ssub.with.overflow.*</tt>' Intrinsics
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.ssub.with.overflow</tt>
+   on any integer bit width.</p>
+
+<pre>
+  declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
+  declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
+  declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
+   a signed subtraction of the two arguments, and indicate whether an overflow
+   occurred during the signed subtraction.</p>
+
+<h5>Arguments:</h5>
+<p>The arguments (%a and %b) and the first element of the result structure may
+   be of integer types of any bit width, but they must have the same bit
+   width. The second element of the result structure must be of
+   type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
+   undergo signed subtraction.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.ssub.with.overflow</tt>' family of intrinsic functions perform
+   a signed subtraction of the two arguments. They return a structure —
+   the first element of which is the subtraction, and the second element of
+   which is a bit specifying if the signed subtraction resulted in an
+   overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %res = call {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
+  %sum = extractvalue {i32, i1} %res, 0
+  %obit = extractvalue {i32, i1} %res, 1
+  br i1 %obit, label %overflow, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_usub_overflow">
+    '<tt>llvm.usub.with.overflow.*</tt>' Intrinsics
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.usub.with.overflow</tt>
+   on any integer bit width.</p>
+
+<pre>
+  declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
+  declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
+  declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
+   an unsigned subtraction of the two arguments, and indicate whether an
+   overflow occurred during the unsigned subtraction.</p>
+
+<h5>Arguments:</h5>
+<p>The arguments (%a and %b) and the first element of the result structure may
+   be of integer types of any bit width, but they must have the same bit
+   width. The second element of the result structure must be of
+   type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
+   undergo unsigned subtraction.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.usub.with.overflow</tt>' family of intrinsic functions perform
+   an unsigned subtraction of the two arguments. They return a structure —
+   the first element of which is the subtraction, and the second element of
+   which is a bit specifying if the unsigned subtraction resulted in an
+   overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %res = call {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
+  %sum = extractvalue {i32, i1} %res, 0
+  %obit = extractvalue {i32, i1} %res, 1
+  br i1 %obit, label %overflow, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_smul_overflow">
+    '<tt>llvm.smul.with.overflow.*</tt>' Intrinsics
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.smul.with.overflow</tt>
+   on any integer bit width.</p>
+
+<pre>
+  declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
+  declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
+  declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+
+<p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
+   a signed multiplication of the two arguments, and indicate whether an
+   overflow occurred during the signed multiplication.</p>
+
+<h5>Arguments:</h5>
+<p>The arguments (%a and %b) and the first element of the result structure may
+   be of integer types of any bit width, but they must have the same bit
+   width. The second element of the result structure must be of
+   type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
+   undergo signed multiplication.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.smul.with.overflow</tt>' family of intrinsic functions perform
+   a signed multiplication of the two arguments. They return a structure —
+   the first element of which is the multiplication, and the second element of
+   which is a bit specifying if the signed multiplication resulted in an
+   overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %res = call {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
+  %sum = extractvalue {i32, i1} %res, 0
+  %obit = extractvalue {i32, i1} %res, 1
+  br i1 %obit, label %overflow, label %normal
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_umul_overflow">
+    '<tt>llvm.umul.with.overflow.*</tt>' Intrinsics
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use <tt>llvm.umul.with.overflow</tt>
+   on any integer bit width.</p>
+
+<pre>
+  declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
+  declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
+  declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
+   a unsigned multiplication of the two arguments, and indicate whether an
+   overflow occurred during the unsigned multiplication.</p>
+
+<h5>Arguments:</h5>
+<p>The arguments (%a and %b) and the first element of the result structure may
+   be of integer types of any bit width, but they must have the same bit
+   width. The second element of the result structure must be of
+   type <tt>i1</tt>. <tt>%a</tt> and <tt>%b</tt> are the two values that will
+   undergo unsigned multiplication.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.umul.with.overflow</tt>' family of intrinsic functions perform
+   an unsigned multiplication of the two arguments. They return a structure
+   — the first element of which is the multiplication, and the second
+   element of which is a bit specifying if the unsigned multiplication resulted
+   in an overflow.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %res = call {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
+  %sum = extractvalue {i32, i1} %res, 0
+  %obit = extractvalue {i32, i1} %res, 1
+  br i1 %obit, label %overflow, label %normal
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="spec_arithmetic">Specialised Arithmetic Intrinsics</a>
+</h3>
+
+<!-- _______________________________________________________________________ -->
+
+<h4>
+  <a name="fmuladd">'<tt>llvm.fmuladd.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare float @llvm.fmuladd.f32(float %a, float %b, float %c)
+  declare double @llvm.fmuladd.f64(double %a, double %b, double %c)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.fmuladd.*</tt>' intrinsic functions represent multiply-add
+expressions that can be fused if the code generator determines that the fused
+expression would be legal and efficient.</p>
+
+<h5>Arguments:</h5>
+<p>The '<tt>llvm.fmuladd.*</tt>' intrinsics each take three arguments: two
+multiplicands, a and b, and an addend c.</p>
+
+<h5>Semantics:</h5>
+<p>The expression:</p>
+<pre>
+  %0 = call float @llvm.fmuladd.f32(%a, %b, %c)
+</pre>
+<p>is equivalent to the expression a * b + c, except that rounding will not be
+performed between the multiplication and addition steps if the code generator
+fuses the operations. Fusion is not guaranteed, even if the target platform
+supports it. If a fused multiply-add is required the corresponding llvm.fma.*
+intrinsic function should be used instead.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields {float}:r2 = (a * b) + c
+</pre>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_fp16">Half Precision Floating Point Intrinsics</a>
+</h3>
+
+<div>
+
+<p>For most target platforms, half precision floating point is a storage-only
+   format. This means that it is
+   a dense encoding (in memory) but does not support computation in the
+   format.</p>
+   
+<p>This means that code must first load the half-precision floating point
+   value as an i16, then convert it to float with <a
+   href="#int_convert_from_fp16"><tt>llvm.convert.from.fp16</tt></a>.
+   Computation can then be performed on the float value (including extending to
+   double etc).  To store the value back to memory, it is first converted to
+   float if needed, then converted to i16 with
+   <a href="#int_convert_to_fp16"><tt>llvm.convert.to.fp16</tt></a>, then
+   storing as an i16 value.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_convert_to_fp16">
+    '<tt>llvm.convert.to.fp16</tt>' Intrinsic
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare i16 @llvm.convert.to.fp16(f32 %a)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
+   a conversion from single precision floating point format to half precision
+   floating point format.</p>
+
+<h5>Arguments:</h5>
+<p>The intrinsic function contains single argument - the value to be
+   converted.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.convert.to.fp16</tt>' intrinsic function performs
+   a conversion from single precision floating point format to half precision
+   floating point format. The return value is an <tt>i16</tt> which
+   contains the converted number.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %res = call i16 @llvm.convert.to.fp16(f32 %a)
+  store i16 %res, i16* @x, align 2
+</pre>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_convert_from_fp16">
+    '<tt>llvm.convert.from.fp16</tt>' Intrinsic
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare f32 @llvm.convert.from.fp16(i16 %a)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs
+   a conversion from half precision floating point format to single precision
+   floating point format.</p>
+
+<h5>Arguments:</h5>
+<p>The intrinsic function contains single argument - the value to be
+   converted.</p>
+
+<h5>Semantics:</h5>
+<p>The '<tt>llvm.convert.from.fp16</tt>' intrinsic function performs a
+   conversion from half single precision floating point format to single
+   precision floating point format. The input half-float value is represented by
+   an <tt>i16</tt> value.</p>
+
+<h5>Examples:</h5>
+<pre>
+  %a = load i16* @x, align 2
+  %res = call f32 @llvm.convert.from.fp16(i16 %a)
+</pre>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_debugger">Debugger Intrinsics</a>
+</h3>
+
+<div>
+
+<p>The LLVM debugger intrinsics (which all start with <tt>llvm.dbg.</tt>
+   prefix), are described in
+   the <a href="SourceLevelDebugging.html#format_common_intrinsics">LLVM Source
+   Level Debugging</a> document.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_eh">Exception Handling Intrinsics</a>
+</h3>
+
+<div>
+
+<p>The LLVM exception handling intrinsics (which all start with
+   <tt>llvm.eh.</tt> prefix), are described in
+   the <a href="ExceptionHandling.html#format_common_intrinsics">LLVM Exception
+   Handling</a> document.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_trampoline">Trampoline Intrinsics</a>
+</h3>
+
+<div>
+
+<p>These intrinsics make it possible to excise one parameter, marked with
+   the <a href="#nest"><tt>nest</tt></a> attribute, from a function.
+   The result is a callable
+   function pointer lacking the nest parameter - the caller does not need to
+   provide a value for it.  Instead, the value to use is stored in advance in a
+   "trampoline", a block of memory usually allocated on the stack, which also
+   contains code to splice the nest value into the argument list.  This is used
+   to implement the GCC nested function address extension.</p>
+
+<p>For example, if the function is
+   <tt>i32 f(i8* nest %c, i32 %x, i32 %y)</tt> then the resulting function
+   pointer has signature <tt>i32 (i32, i32)*</tt>.  It can be created as
+   follows:</p>
+
+<pre class="doc_code">
+  %tramp = alloca [10 x i8], align 4 ; size and alignment only correct for X86
+  %tramp1 = getelementptr [10 x i8]* %tramp, i32 0, i32 0
+  call i8* @llvm.init.trampoline(i8* %tramp1, i8* bitcast (i32 (i8*, i32, i32)* @f to i8*), i8* %nval)
+  %p = call i8* @llvm.adjust.trampoline(i8* %tramp1)
+  %fp = bitcast i8* %p to i32 (i32, i32)*
+</pre>
+
+<p>The call <tt>%val = call i32 %fp(i32 %x, i32 %y)</tt> is then equivalent
+   to <tt>%val = call i32 %f(i8* %nval, i32 %x, i32 %y)</tt>.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_it">
+    '<tt>llvm.init.trampoline</tt>' Intrinsic
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
+</pre>
+
+<h5>Overview:</h5>
+<p>This fills the memory pointed to by <tt>tramp</tt> with executable code,
+   turning it into a trampoline.</p>
+
+<h5>Arguments:</h5>
+<p>The <tt>llvm.init.trampoline</tt> intrinsic takes three arguments, all
+   pointers.  The <tt>tramp</tt> argument must point to a sufficiently large and
+   sufficiently aligned block of memory; this memory is written to by the
+   intrinsic.  Note that the size and the alignment are target-specific - LLVM
+   currently provides no portable way of determining them, so a front-end that
+   generates this intrinsic needs to have some target-specific knowledge.
+   The <tt>func</tt> argument must hold a function bitcast to
+   an <tt>i8*</tt>.</p>
+
+<h5>Semantics:</h5>
+<p>The block of memory pointed to by <tt>tramp</tt> is filled with target
+   dependent code, turning it into a function.  Then <tt>tramp</tt> needs to be
+   passed to <a href="#int_at">llvm.adjust.trampoline</a> to get a pointer
+   which can be <a href="#int_trampoline">bitcast (to a new function) and
+   called</a>.  The new function's signature is the same as that of
+   <tt>func</tt> with any arguments marked with the <tt>nest</tt> attribute
+   removed.  At most one such <tt>nest</tt> argument is allowed, and it must be of
+   pointer type.  Calling the new function is equivalent to calling <tt>func</tt>
+   with the same argument list, but with <tt>nval</tt> used for the missing
+   <tt>nest</tt> argument.  If, after calling <tt>llvm.init.trampoline</tt>, the
+   memory pointed to by <tt>tramp</tt> is modified, then the effect of any later call
+   to the returned function pointer is undefined.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_at">
+    '<tt>llvm.adjust.trampoline</tt>' Intrinsic
+  </a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare i8* @llvm.adjust.trampoline(i8* <tramp>)
+</pre>
+
+<h5>Overview:</h5>
+<p>This performs any required machine-specific adjustment to the address of a
+   trampoline (passed as <tt>tramp</tt>).</p>
+
+<h5>Arguments:</h5>
+<p><tt>tramp</tt> must point to a block of memory which already has trampoline code
+   filled in by a previous call to <a href="#int_it"><tt>llvm.init.trampoline</tt>
+   </a>.</p>
+
+<h5>Semantics:</h5>
+<p>On some architectures the address of the code to be executed needs to be
+   different to the address where the trampoline is actually stored.  This
+   intrinsic returns the executable address corresponding to <tt>tramp</tt>
+   after performing the required machine specific adjustments.
+   The pointer returned can then be <a href="#int_trampoline"> bitcast and
+   executed</a>.
+</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_memorymarkers">Memory Use Markers</a>
+</h3>
+
+<div>
+
+<p>This class of intrinsics exists to information about the lifetime of memory
+   objects and ranges where variables are immutable.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_lifetime_start">'<tt>llvm.lifetime.start</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>)
+</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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_lifetime_end">'<tt>llvm.lifetime.end</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)
+</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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_invariant_start">'<tt>llvm.invariant.start</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)
+</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>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_invariant_end">'<tt>llvm.invariant.end</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>)
+</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>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="int_general">General Intrinsics</a>
+</h3>
+
+<div>
+
+<p>This class of intrinsics is designed to be generic and has no specific
+   purpose.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_var_annotation">'<tt>llvm.var.annotation</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32  <int>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.var.annotation</tt>' intrinsic.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is a pointer to a value, the second is a pointer to a
+   global string, the third is a pointer to a global string which is the source
+   file name, and the last argument is the line number.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic allows annotation of local variables with arbitrary strings.
+   This can be useful for special purpose optimizations that want to look for
+   these annotations.  These have no other defined use; they are ignored by code
+   generation and optimization.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_annotation">'<tt>llvm.annotation.*</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<p>This is an overloaded intrinsic. You can use '<tt>llvm.annotation</tt>' on
+   any integer bit width.</p>
+
+<pre>
+  declare i8 @llvm.annotation.i8(i8 <val>, i8* <str>, i8* <str>, i32  <int>)
+  declare i16 @llvm.annotation.i16(i16 <val>, i8* <str>, i8* <str>, i32  <int>)
+  declare i32 @llvm.annotation.i32(i32 <val>, i8* <str>, i8* <str>, i32  <int>)
+  declare i64 @llvm.annotation.i64(i64 <val>, i8* <str>, i8* <str>, i32  <int>)
+  declare i256 @llvm.annotation.i256(i256 <val>, i8* <str>, i8* <str>, i32  <int>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.annotation</tt>' intrinsic.</p>
+
+<h5>Arguments:</h5>
+<p>The first argument is an integer value (result of some expression), the
+   second is a pointer to a global string, the third is a pointer to a global
+   string which is the source file name, and the last argument is the line
+   number.  It returns the value of the first argument.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic allows annotations to be put on arbitrary expressions with
+   arbitrary strings.  This can be useful for special purpose optimizations that
+   want to look for these annotations.  These have no other defined use; they
+   are ignored by code generation and optimization.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_trap">'<tt>llvm.trap</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.trap() noreturn nounwind
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.trap</tt>' intrinsic.</p>
+
+<h5>Arguments:</h5>
+<p>None.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic is lowered to the target dependent trap instruction. If the
+   target does not have a trap instruction, this intrinsic will be lowered to
+   a call of the <tt>abort()</tt> function.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_debugtrap">'<tt>llvm.debugtrap</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.debugtrap() nounwind
+</pre>
+
+<h5>Overview:</h5>
+<p>The '<tt>llvm.debugtrap</tt>' intrinsic.</p>
+
+<h5>Arguments:</h5>
+<p>None.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic is lowered to code which is intended to cause an execution
+   trap with the intention of requesting the attention of a debugger.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_stackprotector">'<tt>llvm.stackprotector</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.stackprotector(i8* <guard>, i8** <slot>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The <tt>llvm.stackprotector</tt> intrinsic takes the <tt>guard</tt> and
+   stores it onto the stack at <tt>slot</tt>. The stack slot is adjusted to
+   ensure that it is placed on the stack before local variables.</p>
+
+<h5>Arguments:</h5>
+<p>The <tt>llvm.stackprotector</tt> intrinsic requires two pointer
+   arguments. The first argument is the value loaded from the stack
+   guard <tt>@__stack_chk_guard</tt>. The second variable is an <tt>alloca</tt>
+   that has enough space to hold the value of the guard.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic causes the prologue/epilogue inserter to force the position of
+   the <tt>AllocaInst</tt> stack slot to be before local variables on the
+   stack. This is to ensure that if a local variable on the stack is
+   overwritten, it will destroy the value of the guard. When the function exits,
+   the guard on the stack is checked against the original guard. If they are
+   different, then the program aborts by calling the <tt>__stack_chk_fail()</tt>
+   function.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_objectsize">'<tt>llvm.objectsize</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>)
+  declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The <tt>llvm.objectsize</tt> intrinsic is designed to provide information to
+   the optimizers to determine at compile time whether a) an operation (like
+   memcpy) will overflow a buffer that corresponds to an object, or b) 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 and determines whether <tt>llvm.objectsize</tt> returns 0 (if
+   true) or -1 (if false) when the object size is unknown.
+   The second argument only accepts constants.</p>
+   
+<h5>Semantics:</h5>
+<p>The <tt>llvm.objectsize</tt> intrinsic is lowered to a constant representing
+   the size of the object concerned. If the size cannot be determined at compile
+   time, <tt>llvm.objectsize</tt> returns <tt>i32/i64 -1 or 0</tt>
+   (depending on the <tt>min</tt> argument).</p>
+
+</div>
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_expect">'<tt>llvm.expect</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>)
+  declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>)
+</pre>
+
+<h5>Overview:</h5>
+<p>The <tt>llvm.expect</tt> intrinsic provides information about expected (the
+   most probable) value of <tt>val</tt>, which can be used by optimizers.</p>
+
+<h5>Arguments:</h5>
+<p>The <tt>llvm.expect</tt> intrinsic takes two arguments. The first
+   argument is a value. The second argument is an expected value, this needs to
+   be a constant value, variables are not allowed.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic is lowered to the <tt>val</tt>.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="int_donothing">'<tt>llvm.donothing</tt>' Intrinsic</a>
+</h4>
+
+<div>
+
+<h5>Syntax:</h5>
+<pre>
+  declare void @llvm.donothing() nounwind readnone
+</pre>
+
+<h5>Overview:</h5>
+<p>The <tt>llvm.donothing</tt> intrinsic doesn't perform any operation. It's the
+only intrinsic that can be called with an invoke instruction.</p>
+
+<h5>Arguments:</h5>
+<p>None.</p>
+
+<h5>Semantics:</h5>
+<p>This intrinsic does nothing, and it's removed by optimizers and ignored by
+codegen.</p>
+</div>
+
+</div>
+
+</div>
+<!-- *********************************************************************** -->
+<hr>
+<address>
+  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+  <a href="http://validator.w3.org/check/referer"><img
+  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+  <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+  <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+  Last modified: $Date: 2012-10-29 09:12:44 -0500 (Mon, 29 Oct 2012) $
+</address>
+
+</body>
+</html>

Added: www-releases/trunk/3.2/docs/Lexicon.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/Lexicon.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/Lexicon.rst (added)
+++ www-releases/trunk/3.2/docs/Lexicon.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,203 @@
+.. _lexicon:
+
+================
+The LLVM Lexicon
+================
+
+.. note::
+
+    This document is a work in progress!
+
+Definitions
+===========
+
+A
+-
+
+**ADCE**
+    Aggressive Dead Code Elimination
+
+B
+-
+
+**BB Vectorization**
+    Basic Block Vectorization
+
+**BURS**
+    Bottom Up Rewriting System --- A method of instruction selection for code
+    generation.  An example is the `BURG
+    <http://www.program-transformation.org/Transform/BURG>`_ tool.
+
+C
+-
+
+**CSE**
+    Common Subexpression Elimination. An optimization that removes common
+    subexpression compuation. For example ``(a+b)*(a+b)`` has two subexpressions
+    that are the same: ``(a+b)``. This optimization would perform the addition
+    only once and then perform the multiply (but only if it's compulationally
+    correct/safe).
+
+D
+-
+
+**DAG**
+    Directed Acyclic Graph
+
+.. _derived pointer:
+.. _derived pointers:
+
+**Derived Pointer**
+    A pointer to the interior of an object, such that a garbage collector is
+    unable to use the pointer for reachability analysis. While a derived pointer
+    is live, the corresponding object pointer must be kept in a root, otherwise
+    the collector might free the referenced object. With copying collectors,
+    derived pointers pose an additional hazard that they may be invalidated at
+    any `safe point`_. This term is used in opposition to `object pointer`_.
+
+**DSA**
+    Data Structure Analysis
+
+**DSE**
+    Dead Store Elimination
+
+F
+-
+
+**FCA**
+    First Class Aggregate
+
+G
+-
+
+**GC**
+    Garbage Collection. The practice of using reachability analysis instead of
+    explicit memory management to reclaim unused memory.
+
+H
+-
+
+.. _heap:
+
+**Heap**
+    In garbage collection, the region of memory which is managed using
+    reachability analysis.
+
+I
+-
+
+**IPA**
+    Inter-Procedural Analysis. Refers to any variety of code analysis that
+    occurs between procedures, functions or compilation units (modules).
+
+**IPO**
+    Inter-Procedural Optimization. Refers to any variety of code optimization
+    that occurs between procedures, functions or compilation units (modules).
+
+**ISel**
+    Instruction Selection
+
+L
+-
+
+**LCSSA**
+    Loop-Closed Static Single Assignment Form
+
+**LICM**
+    Loop Invariant Code Motion
+
+**Load-VN**
+    Load Value Numbering
+
+**LTO**
+    Link-Time Optimization
+
+M
+-
+
+**MC**
+    Machine Code
+
+O
+-
+.. _object pointer:
+.. _object pointers:
+
+**Object Pointer**
+    A pointer to an object such that the garbage collector is able to trace
+    references contained within the object. This term is used in opposition to
+    `derived pointer`_.
+
+P
+-
+
+**PRE**
+    Partial Redundancy Elimination
+
+R
+-
+
+**RAUW**
+
+    Replace All Uses With. The functions ``User::replaceUsesOfWith()``,
+    ``Value::replaceAllUsesWith()``, and
+    ``Constant::replaceUsesOfWithOnConstant()`` implement the replacement of one
+    Value with another by iterating over its def/use chain and fixing up all of
+    the pointers to point to the new value.  See
+    also `def/use chains <ProgrammersManual.html#iterate_chains>`_.
+
+**Reassociation**
+    Rearranging associative expressions to promote better redundancy elimination
+    and other optimization.  For example, changing ``(A+B-A)`` into ``(B+A-A)``,
+    permitting it to be optimized into ``(B+0)`` then ``(B)``.
+
+.. _roots:
+.. _stack roots:
+
+**Root**
+    In garbage collection, a pointer variable lying outside of the `heap`_ from
+    which the collector begins its reachability analysis. In the context of code
+    generation, "root" almost always refers to a "stack root" --- a local or
+    temporary variable within an executing function.
+
+**RPO**
+    Reverse postorder
+
+S
+-
+
+.. _safe point:
+
+**Safe Point**
+    In garbage collection, it is necessary to identify `stack roots`_ so that
+    reachability analysis may proceed. It may be infeasible to provide this
+    information for every instruction, so instead the information may is
+    calculated only at designated safe points. With a copying collector,
+    `derived pointers`_ must not be retained across safe points and `object
+    pointers`_ must be reloaded from stack roots.
+
+**SDISel**
+    Selection DAG Instruction Selection.
+
+**SCC**
+    Strongly Connected Component
+
+**SCCP**
+    Sparse Conditional Constant Propagation
+
+**SRoA**
+    Scalar Replacement of Aggregates
+
+**SSA**
+    Static Single Assignment
+
+**Stack Map**
+    In garbage collection, metadata emitted by the code generator which
+    identifies `roots`_ within the stack frame of an executing function.
+
+T
+-
+
+**TBAA**
+    Type-Based Alias Analysis
+

Added: www-releases/trunk/3.2/docs/LinkTimeOptimization.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/LinkTimeOptimization.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/LinkTimeOptimization.rst (added)
+++ www-releases/trunk/3.2/docs/LinkTimeOptimization.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,300 @@
+.. _lto:
+
+======================================================
+LLVM Link Time Optimization: Design and Implementation
+======================================================
+
+.. contents::
+   :local:
+
+Description
+===========
+
+LLVM features powerful intermodular optimizations which can be used at link
+time.  Link Time Optimization (LTO) is another name for intermodular
+optimization when performed during the link stage. This document describes the
+interface and design between the LTO optimizer and the linker.
+
+Design Philosophy
+=================
+
+The LLVM Link Time Optimizer provides complete transparency, while doing
+intermodular optimization, in the compiler tool chain. Its main goal is to let
+the developer take advantage of intermodular optimizations without making any
+significant changes to the developer's makefiles or build system. This is
+achieved through tight integration with the linker. In this model, the linker
+treates LLVM bitcode files like native object files and allows mixing and
+matching among them. The linker uses `libLTO`_, a shared object, to handle LLVM
+bitcode files. This tight integration between the linker and LLVM optimizer
+helps to do optimizations that are not possible in other models. The linker
+input allows the optimizer to avoid relying on conservative escape analysis.
+
+.. _libLTO-example:
+
+Example of link time optimization
+---------------------------------
+
+The following example illustrates the advantages of LTO's integrated approach
+and clean interface. This example requires a system linker which supports LTO
+through the interface described in this document.  Here, clang transparently
+invokes system linker.
+
+* Input source file ``a.c`` is compiled into LLVM bitcode form.
+* Input source file ``main.c`` is compiled into native object code.
+
+.. code-block:: c++
+
+  --- a.h ---
+  extern int foo1(void);
+  extern void foo2(void);
+  extern void foo4(void);
+
+  --- a.c ---
+  #include "a.h"
+
+  static signed int i = 0;
+
+  void foo2(void) {
+    i = -1;
+  }
+
+  static int foo3() {
+    foo4();
+    return 10;
+  }
+
+  int foo1(void) {
+    int data = 0;
+
+    if (i < 0) 
+      data = foo3();
+
+    data = data + 42;
+    return data;
+  }
+
+  --- main.c ---
+  #include <stdio.h>
+  #include "a.h"
+
+  void foo4(void) {
+    printf("Hi\n");
+  }
+
+  int main() {
+    return foo1();
+  }
+
+.. code-block:: bash
+
+  --- command lines ---
+  % clang -emit-llvm -c a.c -o a.o   # <-- a.o is LLVM bitcode file
+  % clang -c main.c -o main.o        # <-- main.o is native object file
+  % clang a.o main.o -o main         # <-- standard link command without modifications
+
+* In this example, the linker recognizes that ``foo2()`` is an externally
+  visible symbol defined in LLVM bitcode file. The linker completes its usual
+  symbol resolution pass and finds that ``foo2()`` is not used
+  anywhere. This information is used by the LLVM optimizer and it
+  removes ``foo2()``.</li>
+
+* As soon as ``foo2()`` is removed, the optimizer recognizes that condition ``i
+  < 0`` is always false, which means ``foo3()`` is never used. Hence, the
+  optimizer also removes ``foo3()``.
+
+* And this in turn, enables linker to remove ``foo4()``.
+
+This example illustrates the advantage of tight integration with the
+linker. Here, the optimizer can not remove ``foo3()`` without the linker's
+input.
+
+Alternative Approaches
+----------------------
+
+**Compiler driver invokes link time optimizer separately.**
+    In this model the link time optimizer is not able to take advantage of
+    information collected during the linker's normal symbol resolution phase.
+    In the above example, the optimizer can not remove ``foo2()`` without the
+    linker's input because it is externally visible. This in turn prohibits the
+    optimizer from removing ``foo3()``.
+
+**Use separate tool to collect symbol information from all object files.**
+    In this model, a new, separate, tool or library replicates the linker's
+    capability to collect information for link time optimization. Not only is
+    this code duplication difficult to justify, but it also has several other
+    disadvantages.  For example, the linking semantics and the features provided
+    by the linker on various platform are not unique. This means, this new tool
+    needs to support all such features and platforms in one super tool or a
+    separate tool per platform is required. This increases maintenance cost for
+    link time optimizer significantly, which is not necessary. This approach
+    also requires staying synchronized with linker developements on various
+    platforms, which is not the main focus of the link time optimizer. Finally,
+    this approach increases end user's build time due to the duplication of work
+    done by this separate tool and the linker itself.
+
+Multi-phase communication between ``libLTO`` and linker
+=======================================================
+
+The linker collects information about symbol defininitions and uses in various
+link objects which is more accurate than any information collected by other
+tools during typical build cycles.  The linker collects this information by
+looking at the definitions and uses of symbols in native .o files and using
+symbol visibility information. The linker also uses user-supplied information,
+such as a list of exported symbols. LLVM optimizer collects control flow
+information, data flow information and knows much more about program structure
+from the optimizer's point of view.  Our goal is to take advantage of tight
+integration between the linker and the optimizer by sharing this information
+during various linking phases.
+
+Phase 1 : Read LLVM Bitcode Files
+---------------------------------
+
+The linker first reads all object files in natural order and collects symbol
+information. This includes native object files as well as LLVM bitcode files.
+To minimize the cost to the linker in the case that all .o files are native
+object files, the linker only calls ``lto_module_create()`` when a supplied
+object file is found to not be a native object file.  If ``lto_module_create()``
+returns that the file is an LLVM bitcode file, the linker then iterates over the
+module using ``lto_module_get_symbol_name()`` and
+``lto_module_get_symbol_attribute()`` to get all symbols defined and referenced.
+This information is added to the linker's global symbol table.
+
+
+The lto* functions are all implemented in a shared object libLTO.  This allows
+the LLVM LTO code to be updated independently of the linker tool.  On platforms
+that support it, the shared object is lazily loaded.
+
+Phase 2 : Symbol Resolution
+---------------------------
+
+In this stage, the linker resolves symbols using global symbol table.  It may
+report undefined symbol errors, read archive members, replace weak symbols, etc.
+The linker is able to do this seamlessly even though it does not know the exact
+content of input LLVM bitcode files.  If dead code stripping is enabled then the
+linker collects the list of live symbols.
+
+Phase 3 : Optimize Bitcode Files
+--------------------------------
+
+After symbol resolution, the linker tells the LTO shared object which symbols
+are needed by native object files.  In the example above, the linker reports
+that only ``foo1()`` is used by native object files using
+``lto_codegen_add_must_preserve_symbol()``.  Next the linker invokes the LLVM
+optimizer and code generators using ``lto_codegen_compile()`` which returns a
+native object file creating by merging the LLVM bitcode files and applying
+various optimization passes.
+
+Phase 4 : Symbol Resolution after optimization
+----------------------------------------------
+
+In this phase, the linker reads optimized a native object file and updates the
+internal global symbol table to reflect any changes. The linker also collects
+information about any changes in use of external symbols by LLVM bitcode
+files. In the example above, the linker notes that ``foo4()`` is not used any
+more. If dead code stripping is enabled then the linker refreshes the live
+symbol information appropriately and performs dead code stripping.
+
+After this phase, the linker continues linking as if it never saw LLVM bitcode
+files.
+
+.. _libLTO:
+
+``libLTO``
+==========
+
+``libLTO`` is a shared object that is part of the LLVM tools, and is intended
+for use by a linker. ``libLTO`` provides an abstract C interface to use the LLVM
+interprocedural optimizer without exposing details of LLVM's internals. The
+intention is to keep the interface as stable as possible even when the LLVM
+optimizer continues to evolve. It should even be possible for a completely
+different compilation technology to provide a different libLTO that works with
+their object files and the standard linker tool.
+
+``lto_module_t``
+----------------
+
+A non-native object file is handled via an ``lto_module_t``.  The following
+functions allow the linker to check if a file (on disk or in a memory buffer) is
+a file which libLTO can process:
+
+.. code-block:: c
+
+  lto_module_is_object_file(const char*)
+  lto_module_is_object_file_for_target(const char*, const char*)
+  lto_module_is_object_file_in_memory(const void*, size_t)
+  lto_module_is_object_file_in_memory_for_target(const void*, size_t, const char*)
+
+If the object file can be processed by ``libLTO``, the linker creates a
+``lto_module_t`` by using one of:
+
+.. code-block:: c
+
+  lto_module_create(const char*)
+  lto_module_create_from_memory(const void*, size_t)
+
+and when done, the handle is released via
+
+.. code-block:: c
+
+  lto_module_dispose(lto_module_t)
+
+
+The linker can introspect the non-native object file by getting the number of
+symbols and getting the name and attributes of each symbol via:
+
+.. code-block:: c
+
+  lto_module_get_num_symbols(lto_module_t)
+  lto_module_get_symbol_name(lto_module_t, unsigned int)
+  lto_module_get_symbol_attribute(lto_module_t, unsigned int)
+
+The attributes of a symbol include the alignment, visibility, and kind.
+
+``lto_code_gen_t``
+------------------
+
+Once the linker has loaded each non-native object files into an
+``lto_module_t``, it can request ``libLTO`` to process them all and generate a
+native object file.  This is done in a couple of steps.  First, a code generator
+is created with:
+
+.. code-block:: c
+
+  lto_codegen_create()
+
+Then, each non-native object file is added to the code generator with:
+
+.. code-block:: c
+
+  lto_codegen_add_module(lto_code_gen_t, lto_module_t)
+
+The linker then has the option of setting some codegen options.  Whether or not
+to generate DWARF debug info is set with:
+  
+.. code-block:: c
+
+  lto_codegen_set_debug_model(lto_code_gen_t)
+
+Which kind of position independence is set with:
+
+.. code-block:: c
+
+  lto_codegen_set_pic_model(lto_code_gen_t)
+  
+And each symbol that is referenced by a native object file or otherwise must not
+be optimized away is set with:
+
+.. code-block:: c
+
+  lto_codegen_add_must_preserve_symbol(lto_code_gen_t, const char*)
+
+After all these settings are done, the linker requests that a native object file
+be created from the modules with the settings using:
+
+.. code-block:: c
+
+  lto_codegen_compile(lto_code_gen_t, size*)
+
+which returns a pointer to a buffer containing the generated native object file.
+The linker then parses that and links it with the rest of the native object
+files.

Added: www-releases/trunk/3.2/docs/Makefile
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/Makefile?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/Makefile (added)
+++ www-releases/trunk/3.2/docs/Makefile Fri Dec 21 00:57:24 2012
@@ -0,0 +1,127 @@
+##===- docs/Makefile ---------------------------------------*- Makefile -*-===##
+# 
+#                     The LLVM Compiler Infrastructure
+#
+# This file is distributed under the University of Illinois Open Source
+# License. See LICENSE.TXT for details.
+# 
+##===----------------------------------------------------------------------===##
+
+LEVEL      := ..
+DIRS       :=
+
+ifdef BUILD_FOR_WEBSITE
+PROJ_OBJ_DIR = .
+DOXYGEN = doxygen
+
+$(PROJ_OBJ_DIR)/doxygen.cfg: doxygen.cfg.in
+	cat $< | sed \
+	  -e 's/@abs_top_srcdir@/../g' \
+	  -e 's/@DOT@/dot/g' \
+	  -e 's/@PACKAGE_VERSION@/mainline/' \
+	  -e 's/@abs_top_builddir@/../g' > $@
+endif
+
+include $(LEVEL)/Makefile.common
+
+HTML       := $(wildcard $(PROJ_SRC_DIR)/*.html) \
+              $(wildcard $(PROJ_SRC_DIR)/*.css)
+DOXYFILES  := doxygen.cfg.in doxygen.css doxygen.footer doxygen.header \
+              doxygen.intro
+EXTRA_DIST := $(HTML) $(DOXYFILES) llvm.css CommandGuide
+
+.PHONY: install-html install-doxygen doxygen install-ocamldoc ocamldoc generated
+
+install_targets := install-html
+ifeq ($(ENABLE_DOXYGEN),1)
+install_targets += install-doxygen
+endif
+ifdef OCAMLDOC
+ifneq (,$(filter ocaml,$(BINDINGS_TO_BUILD)))
+install_targets += install-ocamldoc
+endif
+endif
+install-local:: $(install_targets)
+
+generated_targets := doxygen
+ifdef OCAMLDOC
+generated_targets += ocamldoc
+endif
+
+# Live documentation is generated for the web site using this target:
+# 'make generated BUILD_FOR_WEBSITE=1'
+generated:: $(generated_targets)
+
+install-html: $(PROJ_OBJ_DIR)/html.tar.gz
+	$(Echo) Installing HTML documentation
+	$(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html
+	$(Verb) $(DataInstall) $(HTML) $(DESTDIR)$(PROJ_docsdir)/html
+	$(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/html.tar.gz $(DESTDIR)$(PROJ_docsdir)
+
+$(PROJ_OBJ_DIR)/html.tar.gz: $(HTML)
+	$(Echo) Packaging HTML documentation
+	$(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/html.tar
+	$(Verb) cd $(PROJ_SRC_DIR) && \
+	  $(TAR) cf $(PROJ_OBJ_DIR)/html.tar *.html
+	$(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/html.tar
+
+install-doxygen: doxygen
+	$(Echo) Installing doxygen documentation
+	$(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/html/doxygen
+	$(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(DESTDIR)$(PROJ_docsdir)
+	$(Verb) cd $(PROJ_OBJ_DIR)/doxygen && \
+	  $(FIND) . -type f -exec \
+	    $(DataInstall) {} $(DESTDIR)$(PROJ_docsdir)/html/doxygen \;
+
+doxygen: regendoc $(PROJ_OBJ_DIR)/doxygen.tar.gz
+
+regendoc:
+	$(Echo) Building doxygen documentation
+	$(Verb) if test -e $(PROJ_OBJ_DIR)/doxygen ; then \
+	  $(RM) -rf $(PROJ_OBJ_DIR)/doxygen ; \
+	fi
+	$(Verb) $(DOXYGEN) $(PROJ_OBJ_DIR)/doxygen.cfg
+
+$(PROJ_OBJ_DIR)/doxygen.tar.gz: $(DOXYFILES) $(PROJ_OBJ_DIR)/doxygen.cfg
+	$(Echo) Packaging doxygen documentation
+	$(Verb) $(RM) -rf $@ $(PROJ_OBJ_DIR)/doxygen.tar
+	$(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/doxygen.tar doxygen
+	$(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/doxygen.tar
+	$(Verb) $(CP) $(PROJ_OBJ_DIR)/doxygen.tar.gz $(PROJ_OBJ_DIR)/doxygen/html/
+
+userloc: $(LLVM_SRC_ROOT)/docs/userloc.html
+
+$(LLVM_SRC_ROOT)/docs/userloc.html:
+	$(Echo) Making User LOC Table
+	$(Verb) cd $(LLVM_SRC_ROOT) ; ./utils/userloc.pl -details -recurse \
+	  -html lib include tools runtime utils examples autoconf test > docs/userloc.html
+
+install-ocamldoc: ocamldoc
+	$(Echo) Installing ocamldoc documentation
+	$(Verb) $(MKDIR) $(DESTDIR)$(PROJ_docsdir)/ocamldoc/html
+	$(Verb) $(DataInstall) $(PROJ_OBJ_DIR)/ocamldoc.tar.gz $(DESTDIR)$(PROJ_docsdir)
+	$(Verb) cd $(PROJ_OBJ_DIR)/ocamldoc && \
+	  $(FIND) . -type f -exec \
+	    $(DataInstall) {} $(DESTDIR)$(PROJ_docsdir)/ocamldoc/html \;
+
+ocamldoc: regen-ocamldoc
+	$(Echo) Packaging ocamldoc documentation
+	$(Verb) $(RM) -rf $(PROJ_OBJ_DIR)/ocamldoc.tar*
+	$(Verb) $(TAR) cf $(PROJ_OBJ_DIR)/ocamldoc.tar ocamldoc
+	$(Verb) $(GZIPBIN) $(PROJ_OBJ_DIR)/ocamldoc.tar
+	$(Verb) $(CP) $(PROJ_OBJ_DIR)/ocamldoc.tar.gz $(PROJ_OBJ_DIR)/ocamldoc/html/
+
+regen-ocamldoc:
+	$(Echo) Building ocamldoc documentation
+	$(Verb) if test -e $(PROJ_OBJ_DIR)/ocamldoc ; then \
+		$(RM) -rf $(PROJ_OBJ_DIR)/ocamldoc ; \
+	fi
+	$(Verb) $(MAKE) -C $(LEVEL)/bindings/ocaml ocamldoc
+	$(Verb) $(MKDIR) $(PROJ_OBJ_DIR)/ocamldoc/html
+	$(Verb) \
+		$(OCAMLDOC) -d $(PROJ_OBJ_DIR)/ocamldoc/html -sort -colorize-code -html \
+		`$(FIND) $(LEVEL)/bindings/ocaml -name "*.odoc" -exec echo -load '{}' ';'`
+
+uninstall-local::
+	$(Echo) Uninstalling Documentation
+	$(Verb) $(RM) -rf $(DESTDIR)$(PROJ_docsdir)

Added: www-releases/trunk/3.2/docs/Makefile.sphinx
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/Makefile.sphinx?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/Makefile.sphinx (added)
+++ www-releases/trunk/3.2/docs/Makefile.sphinx Fri Dec 21 00:57:24 2012
@@ -0,0 +1,159 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+all:	html
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@# FIXME: Remove this `cp` once HTML->Sphinx transition is completed.
+	@# Kind of a hack, but HTML-formatted docs are on the way out anyway.
+	@echo "Copying legacy HTML-formatted docs into $(BUILDDIR)/html"
+	@cp -a *.html tutorial $(BUILDDIR)/html
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/llvm.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/llvm.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/llvm"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/llvm"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

Added: www-releases/trunk/3.2/docs/MakefileGuide.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/MakefileGuide.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/MakefileGuide.rst (added)
+++ www-releases/trunk/3.2/docs/MakefileGuide.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,956 @@
+.. _makefile_guide:
+
+===================
+LLVM Makefile Guide
+===================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+This document provides *usage* information about the LLVM makefile system. While
+loosely patterned after the BSD makefile system, LLVM has taken a departure from
+BSD in order to implement additional features needed by LLVM.  Although makefile
+systems, such as ``automake``, were attempted at one point, it has become clear
+that the features needed by LLVM and the ``Makefile`` norm are too great to use
+a more limited tool. Consequently, LLVM requires simply GNU Make 3.79, a widely
+portable makefile processor. LLVM unabashedly makes heavy use of the features of
+GNU Make so the dependency on GNU Make is firm. If you're not familiar with
+``make``, it is recommended that you read the `GNU Makefile Manual
+<http://www.gnu.org/software/make/manual/make.html>`_.
+
+While this document is rightly part of the `LLVM Programmer's
+Manual <ProgrammersManual.html>`_, it is treated separately here because of the
+volume of content and because it is often an early source of bewilderment for
+new developers.
+
+General Concepts
+================
+
+The LLVM Makefile System is the component of LLVM that is responsible for
+building the software, testing it, generating distributions, checking those
+distributions, installing and uninstalling, etc. It consists of a several files
+throughout the source tree. These files and other general concepts are described
+in this section.
+
+Projects
+--------
+
+The LLVM Makefile System is quite generous. It not only builds its own software,
+but it can build yours too. Built into the system is knowledge of the
+``llvm/projects`` directory. Any directory under ``projects`` that has both a
+``configure`` script and a ``Makefile`` is assumed to be a project that uses the
+LLVM Makefile system.  Building software that uses LLVM does not require the
+LLVM Makefile System nor even placement in the ``llvm/projects``
+directory. However, doing so will allow your project to get up and running
+quickly by utilizing the built-in features that are used to compile LLVM. LLVM
+compiles itself using the same features of the makefile system as used for
+projects.
+
+For complete details on setting up your projects configuration, simply mimic the
+``llvm/projects/sample`` project. Or for further details, consult the
+`Projects <Projects.html>`_ page.
+
+Variable Values
+---------------
+
+To use the makefile system, you simply create a file named ``Makefile`` in your
+directory and declare values for certain variables.  The variables and values
+that you select determine what the makefile system will do. These variables
+enable rules and processing in the makefile system that automatically Do The
+Right Thing™.
+
+Including Makefiles
+-------------------
+
+Setting variables alone is not enough. You must include into your Makefile
+additional files that provide the rules of the LLVM Makefile system. The various
+files involved are described in the sections that follow.
+
+``Makefile``
+^^^^^^^^^^^^
+
+Each directory to participate in the build needs to have a file named
+``Makefile``. This is the file first read by ``make``. It has three
+sections:
+
+#. Settable Variables --- Required that must be set first.
+#. ``include $(LEVEL)/Makefile.common`` --- include the LLVM Makefile system.
+#. Override Variables --- Override variables set by the LLVM Makefile system.
+
+.. _$(LEVEL)/Makefile.common:
+
+``Makefile.common``
+^^^^^^^^^^^^^^^^^^^
+
+Every project must have a ``Makefile.common`` file at its top source
+directory. This file serves three purposes:
+
+#. It includes the project's configuration makefile to obtain values determined
+   by the ``configure`` script. This is done by including the
+   `$(LEVEL)/Makefile.config`_ file.
+
+#. It specifies any other (static) values that are needed throughout the
+   project. Only values that are used in all or a large proportion of the
+   project's directories should be placed here.
+
+#. It includes the standard rules for the LLVM Makefile system,
+   `$(LLVM_SRC_ROOT)/Makefile.rules`_.  This file is the *guts* of the LLVM
+   ``Makefile`` system.
+
+.. _$(LEVEL)/Makefile.config:
+
+``Makefile.config``
+^^^^^^^^^^^^^^^^^^^
+
+Every project must have a ``Makefile.config`` at the top of its *build*
+directory. This file is **generated** by the ``configure`` script from the
+pattern provided by the ``Makefile.config.in`` file located at the top of the
+project's *source* directory. The contents of this file depend largely on what
+configuration items the project uses, however most projects can get what they
+need by just relying on LLVM's configuration found in
+``$(LLVM_OBJ_ROOT)/Makefile.config``.
+
+.. _$(LLVM_SRC_ROOT)/Makefile.rules:
+
+``Makefile.rules``
+^^^^^^^^^^^^^^^^^^
+
+This file, located at ``$(LLVM_SRC_ROOT)/Makefile.rules`` is the heart of the
+LLVM Makefile System. It provides all the logic, dependencies, and rules for
+building the targets supported by the system. What it does largely depends on
+the values of ``make`` `variables`_ that have been set *before*
+``Makefile.rules`` is included.
+
+Comments
+^^^^^^^^
+
+User ``Makefile``\s need not have comments in them unless the construction is
+unusual or it does not strictly follow the rules and patterns of the LLVM
+makefile system. Makefile comments are invoked with the pound (``#``) character.
+The ``#`` character and any text following it, to the end of the line, are
+ignored by ``make``.
+
+Tutorial
+========
+
+This section provides some examples of the different kinds of modules you can
+build with the LLVM makefile system. In general, each directory you provide will
+build a single object although that object may be composed of additionally
+compiled components.
+
+Libraries
+---------
+
+Only a few variable definitions are needed to build a regular library.
+Normally, the makefile system will build all the software into a single
+``libname.o`` (pre-linked) object. This means the library is not searchable and
+that the distinction between compilation units has been dissolved. Optionally,
+you can ask for a shared library (.so) or archive library (.a) built.  Archive
+libraries are the default. For example:
+
+.. code-block:: makefile
+
+  LIBRARYNAME = mylib
+  SHARED_LIBRARY = 1
+  ARCHIVE_LIBRARY = 1
+
+says to build a library named ``mylib`` with both a shared library
+(``mylib.so``) and an archive library (``mylib.a``) version. The contents of all
+the libraries produced will be the same, they are just constructed differently.
+Note that you normally do not need to specify the sources involved. The LLVM
+Makefile system will infer the source files from the contents of the source
+directory.
+
+The ``LOADABLE_MODULE=1`` directive can be used in conjunction with
+``SHARED_LIBRARY=1`` to indicate that the resulting shared library should be
+openable with the ``dlopen`` function and searchable with the ``dlsym`` function
+(or your operating system's equivalents). While this isn't strictly necessary on
+Linux and a few other platforms, it is required on systems like HP-UX and
+Darwin. You should use ``LOADABLE_MODULE`` for any shared library that you
+intend to be loaded into an tool via the ``-load`` option. See the
+`WritingAnLLVMPass.html <WritingAnLLVMPass.html#makefile>`_ document for an
+example of why you might want to do this.
+
+Bitcode Modules
+^^^^^^^^^^^^^^^
+
+In some situations, it is desirable to build a single bitcode module from a
+variety of sources, instead of an archive, shared library, or bitcode
+library. Bitcode modules can be specified in addition to any of the other types
+of libraries by defining the `MODULE_NAME`_ variable. For example:
+
+.. code-block:: makefile
+
+  LIBRARYNAME = mylib
+  BYTECODE_LIBRARY = 1
+  MODULE_NAME = mymod
+
+will build a module named ``mymod.bc`` from the sources in the directory. This
+module will be an aggregation of all the bitcode modules derived from the
+sources. The example will also build a bitcode archive containing a bitcode
+module for each compiled source file. The difference is subtle, but important
+depending on how the module or library is to be linked.
+
+Loadable Modules
+^^^^^^^^^^^^^^^^
+
+In some situations, you need to create a loadable module. Loadable modules can
+be loaded into programs like ``opt`` or ``llc`` to specify additional passes to
+run or targets to support.  Loadable modules are also useful for debugging a
+pass or providing a pass with another package if that pass can't be included in
+LLVM.
+
+LLVM provides complete support for building such a module. All you need to do is
+use the ``LOADABLE_MODULE`` variable in your ``Makefile``. For example, to build
+a loadable module named ``MyMod`` that uses the LLVM libraries ``LLVMSupport.a``
+and ``LLVMSystem.a``, you would specify:
+
+.. code-block:: makefile
+
+  LIBRARYNAME := MyMod
+  LOADABLE_MODULE := 1
+  LINK_COMPONENTS := support system
+
+Use of the ``LOADABLE_MODULE`` facility implies several things:
+
+#. There will be no "``lib``" prefix on the module. This differentiates it from
+    a standard shared library of the same name.
+
+#. The `SHARED_LIBRARY`_ variable is turned on.
+
+#. The `LINK_LIBS_IN_SHARED`_ variable is turned on.
+
+A loadable module is loaded by LLVM via the facilities of libtool's libltdl
+library which is part of ``lib/System`` implementation.
+
+Tools
+-----
+
+For building executable programs (tools), you must provide the name of the tool
+and the names of the libraries you wish to link with the tool. For example:
+
+.. code-block:: makefile
+
+  TOOLNAME = mytool
+  USEDLIBS = mylib
+  LINK_COMPONENTS = support system
+
+says that we are to build a tool name ``mytool`` and that it requires three
+libraries: ``mylib``, ``LLVMSupport.a`` and ``LLVMSystem.a``.
+
+Note that two different variables are use to indicate which libraries are
+linked: ``USEDLIBS`` and ``LLVMLIBS``. This distinction is necessary to support
+projects. ``LLVMLIBS`` refers to the LLVM libraries found in the LLVM object
+directory. ``USEDLIBS`` refers to the libraries built by your project. In the
+case of building LLVM tools, ``USEDLIBS`` and ``LLVMLIBS`` can be used
+interchangeably since the "project" is LLVM itself and ``USEDLIBS`` refers to
+the same place as ``LLVMLIBS``.
+
+Also note that there are two different ways of specifying a library: with a
+``.a`` suffix and without. Without the suffix, the entry refers to the re-linked
+(.o) file which will include *all* symbols of the library.  This is
+useful, for example, to include all passes from a library of passes.  If the
+``.a`` suffix is used then the library is linked as a searchable library (with
+the ``-l`` option). In this case, only the symbols that are unresolved *at
+that point* will be resolved from the library, if they exist. Other
+(unreferenced) symbols will not be included when the ``.a`` syntax is used. Note
+that in order to use the ``.a`` suffix, the library in question must have been
+built with the ``ARCHIVE_LIBRARY`` option set.
+
+JIT Tools
+^^^^^^^^^
+
+Many tools will want to use the JIT features of LLVM.  To do this, you simply
+specify that you want an execution 'engine', and the makefiles will
+automatically link in the appropriate JIT for the host or an interpreter if none
+is available:
+
+.. code-block:: makefile
+
+  TOOLNAME = my_jit_tool
+  USEDLIBS = mylib
+  LINK_COMPONENTS = engine
+
+Of course, any additional libraries may be listed as other components.  To get a
+full understanding of how this changes the linker command, it is recommended
+that you:
+
+.. code-block:: bash
+
+  % cd examples/Fibonacci
+  % make VERBOSE=1
+
+Targets Supported
+=================
+
+This section describes each of the targets that can be built using the LLVM
+Makefile system. Any target can be invoked from any directory but not all are
+applicable to a given directory (e.g. "check", "dist" and "install" will always
+operate as if invoked from the top level directory).
+
+================= ===============      ==================
+Target Name       Implied Targets      Target Description
+================= ===============      ==================
+``all``           \                    Compile the software recursively. Default target.
+``all-local``     \                    Compile the software in the local directory only.
+``check``         \                    Change to the ``test`` directory in a project and run the test suite there.
+``check-local``   \                    Run a local test suite. Generally this is only defined in the  ``Makefile`` of the project's ``test`` directory.
+``clean``         \                    Remove built objects recursively.
+``clean-local``   \                    Remove built objects from the local directory only.
+``dist``          ``all``              Prepare a source distribution tarball.
+``dist-check``    ``all``              Prepare a source distribution tarball and check that it builds.
+``dist-clean``    ``clean``            Clean source distribution tarball temporary files.
+``install``       ``all``              Copy built objects to installation directory.
+``preconditions`` ``all``              Check to make sure configuration and makefiles are up to date.
+``printvars``     ``all``              Prints variables defined by the makefile system (for debugging).
+``tags``          \                    Make C and C++ tags files for emacs and vi.
+``uninstall``     \                    Remove built objects from installation directory.
+================= ===============      ==================
+
+.. _all:
+
+``all`` (default)
+-----------------
+
+When you invoke ``make`` with no arguments, you are implicitly instructing it to
+seek the ``all`` target (goal). This target is used for building the software
+recursively and will do different things in different directories.  For example,
+in a ``lib`` directory, the ``all`` target will compile source files and
+generate libraries. But, in a ``tools`` directory, it will link libraries and
+generate executables.
+
+``all-local``
+-------------
+
+This target is the same as `all`_ but it operates only on the current directory
+instead of recursively.
+
+``check``
+---------
+
+This target can be invoked from anywhere within a project's directories but
+always invokes the `check-local`_ target in the project's ``test`` directory, if
+it exists and has a ``Makefile``. A warning is produced otherwise.  If
+`TESTSUITE`_ is defined on the ``make`` command line, it will be passed down to
+the invocation of ``make check-local`` in the ``test`` directory. The intended
+usage for this is to assist in running specific suites of tests. If
+``TESTSUITE`` is not set, the implementation of ``check-local`` should run all
+normal tests.  It is up to the project to define what different values for
+``TESTSUTE`` will do. See the `Testing Guide <TestingGuide.html>`_ for further
+details.
+
+``check-local``
+---------------
+
+This target should be implemented by the ``Makefile`` in the project's ``test``
+directory. It is invoked by the ``check`` target elsewhere.  Each project is
+free to define the actions of ``check-local`` as appropriate for that
+project. The LLVM project itself uses dejagnu to run a suite of feature and
+regresson tests. Other projects may choose to use dejagnu or any other testing
+mechanism.
+
+``clean``
+---------
+
+This target cleans the build directory, recursively removing all things that the
+Makefile builds. The cleaning rules have been made guarded so they shouldn't go
+awry (via ``rm -f $(UNSET_VARIABLE)/*`` which will attempt to erase the entire
+directory structure.
+
+``clean-local``
+---------------
+
+This target does the same thing as ``clean`` but only for the current (local)
+directory.
+
+``dist``
+--------
+
+This target builds a distribution tarball. It first builds the entire project
+using the ``all`` target and then tars up the necessary files and compresses
+it. The generated tarball is sufficient for a casual source distribution, but
+probably not for a release (see ``dist-check``).
+
+``dist-check``
+--------------
+
+This target does the same thing as the ``dist`` target but also checks the
+distribution tarball. The check is made by unpacking the tarball to a new
+directory, configuring it, building it, installing it, and then verifying that
+the installation results are correct (by comparing to the original build).  This
+target can take a long time to run but should be done before a release goes out
+to make sure that the distributed tarball can actually be built into a working
+release.
+
+``dist-clean``
+--------------
+
+This is a special form of the ``clean`` clean target. It performs a normal
+``clean`` but also removes things pertaining to building the distribution.
+
+``install``
+-----------
+
+This target finalizes shared objects and executables and copies all libraries,
+headers, executables and documentation to the directory given with the
+``--prefix`` option to ``configure``.  When completed, the prefix directory will
+have everything needed to **use** LLVM.
+
+The LLVM makefiles can generate complete **internal** documentation for all the
+classes by using ``doxygen``. By default, this feature is **not** enabled
+because it takes a long time and generates a massive amount of data (>100MB). If
+you want this feature, you must configure LLVM with the --enable-doxygen switch
+and ensure that a modern version of doxygen (1.3.7 or later) is available in
+your ``PATH``. You can download doxygen from `here
+<http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc>`_.
+
+``preconditions``
+-----------------
+
+This utility target checks to see if the ``Makefile`` in the object directory is
+older than the ``Makefile`` in the source directory and copies it if so. It also
+reruns the ``configure`` script if that needs to be done and rebuilds the
+``Makefile.config`` file similarly. Users may overload this target to ensure
+that sanity checks are run *before* any building of targets as all the targets
+depend on ``preconditions``.
+
+``printvars``
+-------------
+
+This utility target just causes the LLVM makefiles to print out some of the
+makefile variables so that you can double check how things are set.
+
+``reconfigure``
+---------------
+
+This utility target will force a reconfigure of LLVM or your project. It simply
+runs ``$(PROJ_OBJ_ROOT)/config.status --recheck`` to rerun the configuration
+tests and rebuild the configured files. This isn't generally useful as the
+makefiles will reconfigure themselves whenever its necessary.
+
+``spotless``
+------------
+
+.. warning::
+
+  Use with caution!
+
+This utility target, only available when ``$(PROJ_OBJ_ROOT)`` is not the same as
+``$(PROJ_SRC_ROOT)``, will completely clean the ``$(PROJ_OBJ_ROOT)`` directory
+by removing its content entirely and reconfiguring the directory. This returns
+the ``$(PROJ_OBJ_ROOT)`` directory to a completely fresh state. All content in
+the directory except configured files and top-level makefiles will be lost.
+
+``tags``
+--------
+
+This target will generate a ``TAGS`` file in the top-level source directory. It
+is meant for use with emacs, XEmacs, or ViM. The TAGS file provides an index of
+symbol definitions so that the editor can jump you to the definition
+quickly.
+
+``uninstall``
+-------------
+
+This target is the opposite of the ``install`` target. It removes the header,
+library and executable files from the installation directories. Note that the
+directories themselves are not removed because it is not guaranteed that LLVM is
+the only thing installing there (e.g. ``--prefix=/usr``).
+
+.. _variables:
+
+Variables
+=========
+
+Variables are used to tell the LLVM Makefile System what to do and to obtain
+information from it. Variables are also used internally by the LLVM Makefile
+System. Variable names that contain only the upper case alphabetic letters and
+underscore are intended for use by the end user. All other variables are
+internal to the LLVM Makefile System and should not be relied upon nor
+modified. The sections below describe how to use the LLVM Makefile
+variables.
+
+Control Variables
+-----------------
+
+Variables listed in the table below should be set *before* the inclusion of
+`$(LEVEL)/Makefile.common`_.  These variables provide input to the LLVM make
+system that tell it what to do for the current directory.
+
+``BUILD_ARCHIVE``
+    If set to any value, causes an archive (.a) library to be built.
+
+``BUILT_SOURCES``
+    Specifies a set of source files that are generated from other source
+    files. These sources will be built before any other target processing to
+    ensure they are present.
+
+``BYTECODE_LIBRARY``
+    If set to any value, causes a bitcode library (.bc) to be built.
+
+``CONFIG_FILES``
+    Specifies a set of configuration files to be installed.
+
+``DEBUG_SYMBOLS``
+    If set to any value, causes the build to include debugging symbols even in
+    optimized objects, libraries and executables. This alters the flags
+    specified to the compilers and linkers. Debugging isn't fun in an optimized
+    build, but it is possible.
+
+``DIRS``
+    Specifies a set of directories, usually children of the current directory,
+    that should also be made using the same goal. These directories will be
+    built serially.
+
+``DISABLE_AUTO_DEPENDENCIES``
+    If set to any value, causes the makefiles to **not** automatically generate
+    dependencies when running the compiler. Use of this feature is discouraged
+    and it may be removed at a later date.
+
+``ENABLE_OPTIMIZED``
+    If set to 1, causes the build to generate optimized objects, libraries and
+    executables. This alters the flags specified to the compilers and
+    linkers. Generally debugging won't be a fun experience with an optimized
+    build.
+
+``ENABLE_PROFILING``
+    If set to 1, causes the build to generate both optimized and profiled
+    objects, libraries and executables. This alters the flags specified to the
+    compilers and linkers to ensure that profile data can be collected from the
+    tools built. Use the ``gprof`` tool to analyze the output from the profiled
+    tools (``gmon.out``).
+
+``DISABLE_ASSERTIONS``
+    If set to 1, causes the build to disable assertions, even if building a
+    debug or profile build.  This will exclude all assertion check code from the
+    build. LLVM will execute faster, but with little help when things go
+    wrong.
+
+``EXPERIMENTAL_DIRS``
+    Specify a set of directories that should be built, but if they fail, it
+    should not cause the build to fail. Note that this should only be used
+    temporarily while code is being written.
+
+``EXPORTED_SYMBOL_FILE``
+    Specifies the name of a single file that contains a list of the symbols to
+    be exported by the linker. One symbol per line.
+
+``EXPORTED_SYMBOL_LIST``
+    Specifies a set of symbols to be exported by the linker.
+
+``EXTRA_DIST``
+    Specifies additional files that should be distributed with LLVM. All source
+    files, all built sources, all Makefiles, and most documentation files will
+    be automatically distributed. Use this variable to distribute any files that
+    are not automatically distributed.
+
+``KEEP_SYMBOLS``
+    If set to any value, specifies that when linking executables the makefiles
+    should retain debug symbols in the executable. Normally, symbols are
+    stripped from the executable.
+
+``LEVEL`` (required)
+    Specify the level of nesting from the top level. This variable must be set
+    in each makefile as it is used to find the top level and thus the other
+    makefiles.
+
+``LIBRARYNAME``
+    Specify the name of the library to be built. (Required For Libraries)
+
+``LINK_COMPONENTS``
+    When specified for building a tool, the value of this variable will be
+    passed to the ``llvm-config`` tool to generate a link line for the
+    tool. Unlike ``USEDLIBS`` and ``LLVMLIBS``, not all libraries need to be
+    specified. The ``llvm-config`` tool will figure out the library dependencies
+    and add any libraries that are needed. The ``USEDLIBS`` variable can still
+    be used in conjunction with ``LINK_COMPONENTS`` so that additional
+    project-specific libraries can be linked with the LLVM libraries specified
+    by ``LINK_COMPONENTS``.
+
+.. _LINK_LIBS_IN_SHARED:
+
+``LINK_LIBS_IN_SHARED``
+    By default, shared library linking will ignore any libraries specified with
+    the `LLVMLIBS`_ or `USEDLIBS`_. This prevents shared libs from including
+    things that will be in the LLVM tool the shared library will be loaded
+    into. However, sometimes it is useful to link certain libraries into your
+    shared library and this option enables that feature.
+
+.. _LLVMLIBS:
+
+``LLVMLIBS``
+    Specifies the set of libraries from the LLVM ``$(ObjDir)`` that will be
+    linked into the tool or library.
+
+``LOADABLE_MODULE``
+    If set to any value, causes the shared library being built to also be a
+    loadable module. Loadable modules can be opened with the dlopen() function
+    and searched with dlsym (or the operating system's equivalent). Note that
+    setting this variable without also setting ``SHARED_LIBRARY`` will have no
+    effect.
+
+.. _MODULE_NAME:
+
+``MODULE_NAME``
+    Specifies the name of a bitcode module to be created. A bitcode module can
+    be specified in conjunction with other kinds of library builds or by
+    itself. It constructs from the sources a single linked bitcode file.
+
+``NO_INSTALL``
+    Specifies that the build products of the directory should not be installed
+    but should be built even if the ``install`` target is given.  This is handy
+    for directories that build libraries or tools that are only used as part of
+    the build process, such as code generators (e.g.  ``tblgen``).
+
+``OPTIONAL_DIRS``
+    Specify a set of directories that may be built, if they exist, but its not
+    an error for them not to exist.
+
+``PARALLEL_DIRS``
+    Specify a set of directories to build recursively and in parallel if the
+    ``-j`` option was used with ``make``.
+
+.. _SHARED_LIBRARY:
+
+``SHARED_LIBRARY``
+    If set to any value, causes a shared library (``.so``) to be built in
+    addition to any other kinds of libraries. Note that this option will cause
+    all source files to be built twice: once with options for position
+    independent code and once without. Use it only where you really need a
+    shared library.
+
+``SOURCES`` (optional)
+    Specifies the list of source files in the current directory to be
+    built. Source files of any type may be specified (programs, documentation,
+    config files, etc.). If not specified, the makefile system will infer the
+    set of source files from the files present in the current directory.
+
+``SUFFIXES``
+    Specifies a set of filename suffixes that occur in suffix match rules.  Only
+    set this if your local ``Makefile`` specifies additional suffix match
+    rules.
+
+``TARGET``
+    Specifies the name of the LLVM code generation target that the current
+    directory builds. Setting this variable enables additional rules to build
+    ``.inc`` files from ``.td`` files. 
+
+.. _TESTSUITE:
+
+``TESTSUITE``
+    Specifies the directory of tests to run in ``llvm/test``.
+
+``TOOLNAME``
+    Specifies the name of the tool that the current directory should build.
+
+``TOOL_VERBOSE``
+    Implies ``VERBOSE`` and also tells each tool invoked to be verbose. This is
+    handy when you're trying to see the sub-tools invoked by each tool invoked
+    by the makefile. For example, this will pass ``-v`` to the GCC compilers
+    which causes it to print out the command lines it uses to invoke sub-tools
+    (compiler, assembler, linker).
+
+.. _USEDLIBS:
+
+``USEDLIBS``
+    Specifies the list of project libraries that will be linked into the tool or
+    library.
+
+``VERBOSE``
+    Tells the Makefile system to produce detailed output of what it is doing
+    instead of just summary comments. This will generate a LOT of output.
+
+Override Variables
+------------------
+
+Override variables can be used to override the default values provided by the
+LLVM makefile system. These variables can be set in several ways:
+
+* In the environment (e.g. setenv, export) --- not recommended.
+* On the ``make`` command line --- recommended.
+* On the ``configure`` command line.
+* In the Makefile (only *after* the inclusion of `$(LEVEL)/Makefile.common`_).
+
+The override variables are given below:
+
+``AR`` (defaulted)
+    Specifies the path to the ``ar`` tool.
+
+``PROJ_OBJ_DIR``
+    The directory into which the products of build rules will be placed.  This
+    might be the same as `PROJ_SRC_DIR`_ but typically is not.
+
+.. _PROJ_SRC_DIR:
+
+``PROJ_SRC_DIR``
+    The directory which contains the source files to be built.
+
+``BUILD_EXAMPLES``
+    If set to 1, build examples in ``examples`` and (if building Clang)
+    ``tools/clang/examples`` directories.
+
+``BZIP2`` (configured)
+    The path to the ``bzip2`` tool.
+
+``CC`` (configured)
+    The path to the 'C' compiler.
+
+``CFLAGS``
+    Additional flags to be passed to the 'C' compiler.
+
+``CXX``
+    Specifies the path to the C++ compiler.
+
+``CXXFLAGS``
+    Additional flags to be passed to the C++ compiler.
+
+``DATE`` (configured)
+    Specifies the path to the ``date`` program or any program that can generate
+    the current date and time on its standard output.
+
+``DOT`` (configured)
+    Specifies the path to the ``dot`` tool or ``false`` if there isn't one.
+
+``ECHO`` (configured)
+    Specifies the path to the ``echo`` tool for printing output.
+
+``EXEEXT`` (configured)
+    Provides the extension to be used on executables built by the makefiles.
+    The value may be empty on platforms that do not use file extensions for
+    executables (e.g. Unix).
+
+``INSTALL`` (configured)
+    Specifies the path to the ``install`` tool.
+
+``LDFLAGS`` (configured)
+    Allows users to specify additional flags to pass to the linker.
+
+``LIBS`` (configured)
+    The list of libraries that should be linked with each tool.
+
+``LIBTOOL`` (configured)
+    Specifies the path to the ``libtool`` tool. This tool is renamed ``mklib``
+    by the ``configure`` script.
+
+``LLVMAS`` (defaulted)
+    Specifies the path to the ``llvm-as`` tool.
+
+``LLVMCC``
+    Specifies the path to the LLVM capable compiler.
+
+``LLVMCXX``
+    Specifies the path to the LLVM C++ capable compiler.
+
+``LLVMGCC`` (defaulted)
+    Specifies the path to the LLVM version of the GCC 'C' Compiler.
+
+``LLVMGXX`` (defaulted)
+    Specifies the path to the LLVM version of the GCC C++ Compiler.
+
+``LLVMLD`` (defaulted)
+    Specifies the path to the LLVM bitcode linker tool
+
+``LLVM_OBJ_ROOT`` (configured)
+    Specifies the top directory into which the output of the build is placed.
+
+``LLVM_SRC_ROOT`` (configured)
+    Specifies the top directory in which the sources are found.
+
+``LLVM_TARBALL_NAME`` (configured)
+    Specifies the name of the distribution tarball to create. This is configured
+    from the name of the project and its version number.
+
+``MKDIR`` (defaulted)
+    Specifies the path to the ``mkdir`` tool that creates directories.
+
+``ONLY_TOOLS``
+    If set, specifies the list of tools to build.
+
+``PLATFORMSTRIPOPTS``
+    The options to provide to the linker to specify that a stripped (no symbols)
+    executable should be built.
+
+``RANLIB`` (defaulted)
+    Specifies the path to the ``ranlib`` tool.
+
+``RM`` (defaulted)
+    Specifies the path to the ``rm`` tool.
+
+``SED`` (defaulted)
+    Specifies the path to the ``sed`` tool.
+
+``SHLIBEXT`` (configured)
+    Provides the filename extension to use for shared libraries.
+
+``TBLGEN`` (defaulted)
+    Specifies the path to the ``tblgen`` tool.
+
+``TAR`` (defaulted)
+    Specifies the path to the ``tar`` tool.
+
+``ZIP`` (defaulted)
+    Specifies the path to the ``zip`` tool.
+
+Readable Variables
+------------------
+
+Variables listed in the table below can be used by the user's Makefile but
+should not be changed. Changing the value will generally cause the build to go
+wrong, so don't do it.
+
+``bindir``
+    The directory into which executables will ultimately be installed. This
+    value is derived from the ``--prefix`` option given to ``configure``.
+
+``BuildMode``
+    The name of the type of build being performed: Debug, Release, or
+    Profile.
+
+``bytecode_libdir``
+    The directory into which bitcode libraries will ultimately be installed.
+    This value is derived from the ``--prefix`` option given to ``configure``.
+
+``ConfigureScriptFLAGS``
+    Additional flags given to the ``configure`` script when reconfiguring.
+
+``DistDir``
+    The *current* directory for which a distribution copy is being made.
+
+.. _Echo:
+
+``Echo``
+    The LLVM Makefile System output command. This provides the ``llvm[n]``
+    prefix and starts with ``@`` so the command itself is not printed by
+    ``make``.
+
+``EchoCmd``
+    Same as `Echo`_ but without the leading ``@``.
+
+``includedir``
+    The directory into which include files will ultimately be installed.  This
+    value is derived from the ``--prefix`` option given to ``configure``.
+
+``libdir``
+    The directory into which native libraries will ultimately be installed.
+    This value is derived from the ``--prefix`` option given to
+    ``configure``.
+
+``LibDir``
+    The configuration specific directory into which libraries are placed before
+    installation.
+
+``MakefileConfig``
+    Full path of the ``Makefile.config`` file.
+
+``MakefileConfigIn``
+    Full path of the ``Makefile.config.in`` file.
+
+``ObjDir``
+    The configuration and directory specific directory where build objects
+    (compilation results) are placed.
+
+``SubDirs``
+    The complete list of sub-directories of the current directory as
+    specified by other variables.
+
+``Sources``
+    The complete list of source files.
+
+``sysconfdir``
+    The directory into which configuration files will ultimately be
+    installed. This value is derived from the ``--prefix`` option given to
+    ``configure``.
+
+``ToolDir``
+    The configuration specific directory into which executables are placed
+    before they are installed.
+
+``TopDistDir``
+    The top most directory into which the distribution files are copied.
+
+``Verb``
+    Use this as the first thing on your build script lines to enable or disable
+    verbose mode. It expands to either an ``@`` (quiet mode) or nothing (verbose
+    mode).
+
+Internal Variables
+------------------
+
+Variables listed below are used by the LLVM Makefile System and considered
+internal. You should not use these variables under any circumstances.
+
+.. code-block:: makefile
+
+    Archive
+    AR.Flags
+    BaseNameSources
+    BCCompile.C
+    BCCompile.CXX
+    BCLinkLib
+    C.Flags
+    Compile.C
+    CompileCommonOpts
+    Compile.CXX
+    ConfigStatusScript
+    ConfigureScript
+    CPP.Flags
+    CPP.Flags 
+    CXX.Flags
+    DependFiles
+    DestArchiveLib
+    DestBitcodeLib
+    DestModule
+    DestSharedLib
+    DestTool
+    DistAlways
+    DistCheckDir
+    DistCheckTop
+    DistFiles
+    DistName
+    DistOther
+    DistSources
+    DistSubDirs
+    DistTarBZ2
+    DistTarGZip
+    DistZip
+    ExtraLibs
+    FakeSources
+    INCFiles
+    InternalTargets
+    LD.Flags
+    LibName.A
+    LibName.BC
+    LibName.LA
+    LibName.O
+    LibTool.Flags
+    Link
+    LinkModule
+    LLVMLibDir
+    LLVMLibsOptions
+    LLVMLibsPaths
+    LLVMToolDir
+    LLVMUsedLibs
+    LocalTargets
+    Module
+    ObjectsBC
+    ObjectsLO
+    ObjectsO
+    ObjMakefiles
+    ParallelTargets
+    PreConditions
+    ProjLibsOptions
+    ProjLibsPaths
+    ProjUsedLibs
+    Ranlib
+    RecursiveTargets
+    SrcMakefiles
+    Strip
+    StripWarnMsg
+    TableGen
+    TDFiles
+    ToolBuildPath
+    TopLevelTargets
+    UserTargets

Added: www-releases/trunk/3.2/docs/MarkedUpDisassembly.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/MarkedUpDisassembly.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/MarkedUpDisassembly.rst (added)
+++ www-releases/trunk/3.2/docs/MarkedUpDisassembly.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,88 @@
+.. _marked_up_disassembly:
+
+=======================================
+LLVM's Optional Rich Disassembly Output
+=======================================
+
+.. contents::
+   :local:
+
+Introduction
+============
+
+LLVM's default disassembly output is raw text. To allow consumers more ability
+to introspect the instructions' textual representation or to reformat for a more
+user friendly display there is an optional rich disassembly output.
+
+This optional output is sufficient to reference into individual portions of the
+instruction text. This is intended for clients like disassemblers, list file
+generators, and pretty-printers, which need more than the raw instructions and
+the ability to print them.
+
+To provide this functionality the assembly text is marked up with annotations.
+The markup is simple enough in syntax to be robust even in the case of version
+mismatches between consumers and producers. That is, the syntax generally does
+not carry semantics beyond "this text has an annotation," so consumers can
+simply ignore annotations they do not understand or do not care about.
+
+After calling ``LLVMCreateDisasm()`` to create a disassembler context the
+optional output is enable with this call:
+
+.. code-block:: c
+
+    LLVMSetDisasmOptions(DC, LLVMDisassembler_Option_UseMarkup);
+
+Then subsequent calls to ``LLVMDisasmInstruction()`` will return output strings
+with the marked up annotations.
+
+Instruction Annotations
+=======================
+
+.. _contextual markups:
+
+Contextual markups
+------------------
+
+Annoated assembly display will supply contextual markup to help clients more
+efficiently implement things like pretty printers. Most markup will be target
+independent, so clients can effectively provide good display without any target
+specific knowledge.
+
+Annotated assembly goes through the normal instruction printer, but optionally
+includes contextual tags on portions of the instruction string. An annotation
+is any '<' '>' delimited section of text(1).
+
+.. code-block:: bat
+
+    annotation: '<' tag-name tag-modifier-list ':' annotated-text '>'
+    tag-name: identifier
+    tag-modifier-list: comma delimited identifier list
+
+The tag-name is an identifier which gives the type of the annotation. For the
+first pass, this will be very simple, with memory references, registers, and
+immediates having the tag names "mem", "reg", and "imm", respectively.
+
+The tag-modifier-list is typically additional target-specific context, such as
+register class.
+
+Clients should accept and ignore any tag-names or tag-modifiers they do not
+understand, allowing the annotations to grow in richness without breaking older
+clients.
+
+For example, a possible annotation of an ARM load of a stack-relative location
+might be annotated as:
+
+.. code-block:: nasm
+
+   ldr <reg gpr:r0>, <mem regoffset:[<reg gpr:sp>, <imm:#4>]>
+
+
+1: For assembly dialects in which '<' and/or '>' are legal tokens, a literal token is escaped by following immediately with a repeat of the character.  For example, a literal '<' character is output as '<<' in an annotated assembly string.
+
+C API Details
+-------------
+
+The intended consumers of this information use the C API, therefore the new C
+API function for the disassembler will be added to provide an option to produce
+disassembled instructions with annotations, ``LLVMSetDisasmOptions()`` and the
+``LLVMDisassembler_Option_UseMarkup`` option (see above).

Added: www-releases/trunk/3.2/docs/Packaging.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/Packaging.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/Packaging.rst (added)
+++ www-releases/trunk/3.2/docs/Packaging.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,75 @@
+.. _packaging:
+
+========================
+Advice on Packaging LLVM
+========================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+LLVM sets certain default configure options to make sure our developers don't
+break things for constrained platforms.  These settings are not optimal for most
+desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts,
+etc.) will tweak them.  This document lists settings we suggest you tweak.
+
+LLVM's API changes with each release, so users are likely to want, for example,
+both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps developed
+against each.
+
+Compile Flags
+=============
+
+LLVM runs much more quickly when it's optimized and assertions are removed.
+However, such a build is currently incompatible with users who build without
+defining ``NDEBUG``, and the lack of assertions makes it hard to debug problems
+in user code.  We recommend allowing users to install both optimized and debug
+versions of LLVM in parallel.  The following configure flags are relevant:
+
+``--disable-assertions``
+    Builds LLVM with ``NDEBUG`` defined.  Changes the LLVM ABI.  Also available
+    by setting ``DISABLE_ASSERTIONS=0|1`` in ``make``'s environment.  This
+    defaults to enabled regardless of the optimization setting, but it slows
+    things down.
+
+``--enable-debug-symbols``
+    Builds LLVM with ``-g``.  Also available by setting ``DEBUG_SYMBOLS=0|1`` in
+    ``make``'s environment.  This defaults to disabled when optimizing, so you
+    should turn it back on to let users debug their programs.
+
+``--enable-optimized``
+    (For svn checkouts) Builds LLVM with ``-O2`` and, by default, turns off
+    debug symbols.  Also available by setting ``ENABLE_OPTIMIZED=0|1`` in
+    ``make``'s environment.  This defaults to enabled when not in a
+    checkout.
+
+C++ Features
+============
+
+RTTI
+    LLVM disables RTTI by default.  Add ``REQUIRES_RTTI=1`` to your environment
+    while running ``make`` to re-enable it.  This will allow users to build with
+    RTTI enabled and still inherit from LLVM classes.
+
+Shared Library
+==============
+
+Configure with ``--enable-shared`` to build
+``libLLVM-<major>.<minor>.(so|dylib)`` and link the tools against it.  This
+saves lots of binary size at the cost of some startup time.
+
+Dependencies
+============
+
+``--enable-libffi``
+    Depend on `libffi <http://sources.redhat.com/libffi/>`_ to allow the LLVM
+    interpreter to call external functions.
+
+``--with-oprofile``
+
+    Depend on `libopagent
+    <http://oprofile.sourceforge.net/doc/devel/index.html>`_ (>=version 0.9.4)
+    to let the LLVM JIT tell oprofile about function addresses and line
+    numbers.

Added: www-releases/trunk/3.2/docs/Passes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/Passes.html?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/Passes.html (added)
+++ www-releases/trunk/3.2/docs/Passes.html Fri Dec 21 00:57:24 2012
@@ -0,0 +1,2049 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                      "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+  <title>LLVM's Analysis and Transform Passes</title>
+  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
+  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+</head>
+<body>
+
+<!--
+
+If Passes.html is up to date, the following "one-liner" should print
+an empty diff.
+
+egrep -e '^<tr><td><a href="#.*">-.*</a></td><td>.*</td></tr>$' \
+      -e '^  <a name=".*">.*</a>$' < Passes.html >html; \
+perl >help <<'EOT' && diff -u help html; rm -f help html
+open HTML, "<Passes.html" or die "open: Passes.html: $!\n";
+while (<HTML>) {
+  m:^<tr><td><a href="#(.*)">-.*</a></td><td>.*</td></tr>$: or next;
+  $order{$1} = sprintf("%03d", 1 + int %order);
+}
+open HELP, "../Release/bin/opt -help|" or die "open: opt -help: $!\n";
+while (<HELP>) {
+  m:^    -([^ ]+) +- (.*)$: or next;
+  my $o = $order{$1};
+  $o = "000" unless defined $o;
+  push @x, "$o<tr><td><a href=\"#$1\">-$1</a></td><td>$2</td></tr>\n";
+  push @y, "$o  <a name=\"$1\">-$1: $2</a>\n";
+}
+ at x = map { s/^\d\d\d//; $_ } sort @x;
+ at y = map { s/^\d\d\d//; $_ } sort @y;
+print @x, @y;
+EOT
+
+This (real) one-liner can also be helpful when converting comments to HTML:
+
+perl -e '$/ = undef; for (split(/\n/, <>)) { s:^ *///? ?::; print "  <p>\n" if !$on && $_ =~ /\S/; print "  </p>\n" if $on && $_ =~ /^\s*$/; print "  $_\n"; $on = ($_ =~ /\S/); } print "  </p>\n" if $on'
+
+  -->
+
+<h1>LLVM's Analysis and Transform Passes</h1>
+
+<ol>
+  <li><a href="#intro">Introduction</a></li>
+  <li><a href="#analyses">Analysis Passes</a>
+  <li><a href="#transforms">Transform Passes</a></li>
+  <li><a href="#utilities">Utility Passes</a></li>
+</ol>
+
+<div class="doc_author">
+  <p>Written by <a href="mailto:rspencer at x10sys.com">Reid Spencer</a>
+            and Gordon Henriksen</p>
+</div>
+
+<!-- ======================================================================= -->
+<h2><a name="intro">Introduction</a></h2>
+<div>
+  <p>This document serves as a high level summary of the optimization features 
+  that LLVM provides. Optimizations are implemented as Passes that traverse some
+  portion of a program to either collect information or transform the program.
+  The table below divides the passes that LLVM provides into three categories.
+  Analysis passes compute information that other passes can use or for debugging
+  or program visualization purposes. Transform passes can use (or invalidate)
+  the analysis passes. Transform passes all mutate the program in some way. 
+  Utility passes provides some utility but don't otherwise fit categorization.
+  For example passes to extract functions to bitcode or write a module to
+  bitcode are neither analysis nor transform passes.
+  <p>The table below provides a quick summary of each pass and links to the more
+  complete pass description later in the document.</p>
+
+<table>
+<tr><th colspan="2"><b>ANALYSIS PASSES</b></th></tr>
+<tr><th>Option</th><th>Name</th></tr>
+<tr><td><a href="#aa-eval">-aa-eval</a></td><td>Exhaustive Alias Analysis Precision Evaluator</td></tr>
+<tr><td><a href="#basicaa">-basicaa</a></td><td>Basic Alias Analysis (stateless AA impl)</td></tr>
+<tr><td><a href="#basiccg">-basiccg</a></td><td>Basic CallGraph Construction</td></tr>
+<tr><td><a href="#count-aa">-count-aa</a></td><td>Count Alias Analysis Query Responses</td></tr>
+<tr><td><a href="#da">-da</a></td><td>Dependence Analysis</td></tr>
+<tr><td><a href="#debug-aa">-debug-aa</a></td><td>AA use debugger</td></tr>
+<tr><td><a href="#domfrontier">-domfrontier</a></td><td>Dominance Frontier Construction</td></tr>
+<tr><td><a href="#domtree">-domtree</a></td><td>Dominator Tree Construction</td></tr>
+<tr><td><a href="#dot-callgraph">-dot-callgraph</a></td><td>Print Call Graph to 'dot' file</td></tr>
+<tr><td><a href="#dot-cfg">-dot-cfg</a></td><td>Print CFG of function to 'dot' file</td></tr>
+<tr><td><a href="#dot-cfg-only">-dot-cfg-only</a></td><td>Print CFG of function to 'dot' file (with no function bodies)</td></tr>
+<tr><td><a href="#dot-dom">-dot-dom</a></td><td>Print dominance tree of function to 'dot' file</td></tr>
+<tr><td><a href="#dot-dom-only">-dot-dom-only</a></td><td>Print dominance tree of function to 'dot' file (with no function bodies)</td></tr>
+<tr><td><a href="#dot-postdom">-dot-postdom</a></td><td>Print postdominance tree of function to 'dot' file</td></tr>
+<tr><td><a href="#dot-postdom-only">-dot-postdom-only</a></td><td>Print postdominance tree of function to 'dot' file (with no function bodies)</td></tr>
+<tr><td><a href="#globalsmodref-aa">-globalsmodref-aa</a></td><td>Simple mod/ref analysis for globals</td></tr>
+<tr><td><a href="#instcount">-instcount</a></td><td>Counts the various types of Instructions</td></tr>
+<tr><td><a href="#intervals">-intervals</a></td><td>Interval Partition Construction</td></tr>
+<tr><td><a href="#iv-users">-iv-users</a></td><td>Induction Variable Users</td></tr>
+<tr><td><a href="#lazy-value-info">-lazy-value-info</a></td><td>Lazy Value Information Analysis</td></tr>
+<tr><td><a href="#libcall-aa">-libcall-aa</a></td><td>LibCall Alias Analysis</td></tr>
+<tr><td><a href="#lint">-lint</a></td><td>Statically lint-checks LLVM IR</td></tr>
+<tr><td><a href="#loops">-loops</a></td><td>Natural Loop Information</td></tr>
+<tr><td><a href="#memdep">-memdep</a></td><td>Memory Dependence Analysis</td></tr>
+<tr><td><a href="#module-debuginfo">-module-debuginfo</a></td><td>Decodes module-level debug info</td></tr>
+<tr><td><a href="#no-aa">-no-aa</a></td><td>No Alias Analysis (always returns 'may' alias)</td></tr>
+<tr><td><a href="#no-profile">-no-profile</a></td><td>No Profile Information</td></tr>
+<tr><td><a href="#postdomtree">-postdomtree</a></td><td>Post-Dominator Tree Construction</td></tr>
+<tr><td><a href="#print-alias-sets">-print-alias-sets</a></td><td>Alias Set Printer</td></tr>
+<tr><td><a href="#print-callgraph">-print-callgraph</a></td><td>Print a call graph</td></tr>
+<tr><td><a href="#print-callgraph-sccs">-print-callgraph-sccs</a></td><td>Print SCCs of the Call Graph</td></tr>
+<tr><td><a href="#print-cfg-sccs">-print-cfg-sccs</a></td><td>Print SCCs of each function CFG</td></tr>
+<tr><td><a href="#print-dbginfo">-print-dbginfo</a></td><td>Print debug info in human readable form</td></tr>
+<tr><td><a href="#print-dom-info">-print-dom-info</a></td><td>Dominator Info Printer</td></tr>
+<tr><td><a href="#print-externalfnconstants">-print-externalfnconstants</a></td><td>Print external fn callsites passed constants</td></tr>
+<tr><td><a href="#print-function">-print-function</a></td><td>Print function to stderr</td></tr>
+<tr><td><a href="#print-module">-print-module</a></td><td>Print module to stderr</td></tr>
+<tr><td><a href="#print-used-types">-print-used-types</a></td><td>Find Used Types</td></tr>
+<tr><td><a href="#profile-estimator">-profile-estimator</a></td><td>Estimate profiling information</td></tr>
+<tr><td><a href="#profile-loader">-profile-loader</a></td><td>Load profile information from llvmprof.out</td></tr>
+<tr><td><a href="#profile-verifier">-profile-verifier</a></td><td>Verify profiling information</td></tr>
+<tr><td><a href="#regions">-regions</a></td><td>Detect single entry single exit regions</td></tr>
+<tr><td><a href="#scalar-evolution">-scalar-evolution</a></td><td>Scalar Evolution Analysis</td></tr>
+<tr><td><a href="#scev-aa">-scev-aa</a></td><td>ScalarEvolution-based Alias Analysis</td></tr>
+<tr><td><a href="#targetdata">-targetdata</a></td><td>Target Data Layout</td></tr>
+
+
+<tr><th colspan="2"><b>TRANSFORM PASSES</b></th></tr>
+<tr><th>Option</th><th>Name</th></tr>
+<tr><td><a href="#adce">-adce</a></td><td>Aggressive Dead Code Elimination</td></tr>
+<tr><td><a href="#always-inline">-always-inline</a></td><td>Inliner for always_inline functions</td></tr>
+<tr><td><a href="#argpromotion">-argpromotion</a></td><td>Promote 'by reference' arguments to scalars</td></tr>
+<tr><td><a href="#bb-vectorize">-bb-vectorize</a></td><td>Combine instructions to form vector instructions within basic blocks</td></tr>
+<tr><td><a href="#block-placement">-block-placement</a></td><td>Profile Guided Basic Block Placement</td></tr>
+<tr><td><a href="#break-crit-edges">-break-crit-edges</a></td><td>Break critical edges in CFG</td></tr>
+<tr><td><a href="#codegenprepare">-codegenprepare</a></td><td>Optimize for code generation</td></tr>
+<tr><td><a href="#constmerge">-constmerge</a></td><td>Merge Duplicate Global Constants</td></tr>
+<tr><td><a href="#constprop">-constprop</a></td><td>Simple constant propagation</td></tr>
+<tr><td><a href="#dce">-dce</a></td><td>Dead Code Elimination</td></tr>
+<tr><td><a href="#deadargelim">-deadargelim</a></td><td>Dead Argument Elimination</td></tr>
+<tr><td><a href="#deadtypeelim">-deadtypeelim</a></td><td>Dead Type Elimination</td></tr>
+<tr><td><a href="#die">-die</a></td><td>Dead Instruction Elimination</td></tr>
+<tr><td><a href="#dse">-dse</a></td><td>Dead Store Elimination</td></tr>
+<tr><td><a href="#functionattrs">-functionattrs</a></td><td>Deduce function attributes</td></tr>
+<tr><td><a href="#globaldce">-globaldce</a></td><td>Dead Global Elimination</td></tr>
+<tr><td><a href="#globalopt">-globalopt</a></td><td>Global Variable Optimizer</td></tr>
+<tr><td><a href="#gvn">-gvn</a></td><td>Global Value Numbering</td></tr>
+<tr><td><a href="#indvars">-indvars</a></td><td>Canonicalize Induction Variables</td></tr>
+<tr><td><a href="#inline">-inline</a></td><td>Function Integration/Inlining</td></tr>
+<tr><td><a href="#insert-edge-profiling">-insert-edge-profiling</a></td><td>Insert instrumentation for edge profiling</td></tr>
+<tr><td><a href="#insert-optimal-edge-profiling">-insert-optimal-edge-profiling</a></td><td>Insert optimal instrumentation for edge profiling</td></tr>
+<tr><td><a href="#instcombine">-instcombine</a></td><td>Combine redundant instructions</td></tr>
+<tr><td><a href="#internalize">-internalize</a></td><td>Internalize Global Symbols</td></tr>
+<tr><td><a href="#ipconstprop">-ipconstprop</a></td><td>Interprocedural constant propagation</td></tr>
+<tr><td><a href="#ipsccp">-ipsccp</a></td><td>Interprocedural Sparse Conditional Constant Propagation</td></tr>
+<tr><td><a href="#jump-threading">-jump-threading</a></td><td>Jump Threading</td></tr>
+<tr><td><a href="#lcssa">-lcssa</a></td><td>Loop-Closed SSA Form Pass</td></tr>
+<tr><td><a href="#licm">-licm</a></td><td>Loop Invariant Code Motion</td></tr>
+<tr><td><a href="#loop-deletion">-loop-deletion</a></td><td>Delete dead loops</td></tr>
+<tr><td><a href="#loop-extract">-loop-extract</a></td><td>Extract loops into new functions</td></tr>
+<tr><td><a href="#loop-extract-single">-loop-extract-single</a></td><td>Extract at most one loop into a new function</td></tr>
+<tr><td><a href="#loop-reduce">-loop-reduce</a></td><td>Loop Strength Reduction</td></tr>
+<tr><td><a href="#loop-rotate">-loop-rotate</a></td><td>Rotate Loops</td></tr>
+<tr><td><a href="#loop-simplify">-loop-simplify</a></td><td>Canonicalize natural loops</td></tr>
+<tr><td><a href="#loop-unroll">-loop-unroll</a></td><td>Unroll loops</td></tr>
+<tr><td><a href="#loop-unswitch">-loop-unswitch</a></td><td>Unswitch loops</td></tr>
+<tr><td><a href="#loweratomic">-loweratomic</a></td><td>Lower atomic intrinsics to non-atomic form</td></tr>
+<tr><td><a href="#lowerinvoke">-lowerinvoke</a></td><td>Lower invoke and unwind, for unwindless code generators</td></tr>
+<tr><td><a href="#lowerswitch">-lowerswitch</a></td><td>Lower SwitchInst's to branches</td></tr>
+<tr><td><a href="#mem2reg">-mem2reg</a></td><td>Promote Memory to Register</td></tr>
+<tr><td><a href="#memcpyopt">-memcpyopt</a></td><td>MemCpy Optimization</td></tr>
+<tr><td><a href="#mergefunc">-mergefunc</a></td><td>Merge Functions</td></tr>
+<tr><td><a href="#mergereturn">-mergereturn</a></td><td>Unify function exit nodes</td></tr>
+<tr><td><a href="#partial-inliner">-partial-inliner</a></td><td>Partial Inliner</td></tr>
+<tr><td><a href="#prune-eh">-prune-eh</a></td><td>Remove unused exception handling info</td></tr>
+<tr><td><a href="#reassociate">-reassociate</a></td><td>Reassociate expressions</td></tr>
+<tr><td><a href="#reg2mem">-reg2mem</a></td><td>Demote all values to stack slots</td></tr>
+<tr><td><a href="#scalarrepl">-scalarrepl</a></td><td>Scalar Replacement of Aggregates (DT)</td></tr>
+<tr><td><a href="#sccp">-sccp</a></td><td>Sparse Conditional Constant Propagation</td></tr>
+<tr><td><a href="#simplify-libcalls">-simplify-libcalls</a></td><td>Simplify well-known library calls</td></tr>
+<tr><td><a href="#simplifycfg">-simplifycfg</a></td><td>Simplify the CFG</td></tr>
+<tr><td><a href="#sink">-sink</a></td><td>Code sinking</td></tr>
+<tr><td><a href="#sretpromotion">-sretpromotion</a></td><td>Promote sret arguments to multiple ret values</td></tr>
+<tr><td><a href="#strip">-strip</a></td><td>Strip all symbols from a module</td></tr>
+<tr><td><a href="#strip-dead-debug-info">-strip-dead-debug-info</a></td><td>Strip debug info for unused symbols</td></tr>
+<tr><td><a href="#strip-dead-prototypes">-strip-dead-prototypes</a></td><td>Strip Unused Function Prototypes</td></tr>
+<tr><td><a href="#strip-debug-declare">-strip-debug-declare</a></td><td>Strip all llvm.dbg.declare intrinsics</td></tr>
+<tr><td><a href="#strip-nondebug">-strip-nondebug</a></td><td>Strip all symbols, except dbg symbols, from a module</td></tr>
+<tr><td><a href="#tailcallelim">-tailcallelim</a></td><td>Tail Call Elimination</td></tr>
+
+
+<tr><th colspan="2"><b>UTILITY PASSES</b></th></tr>
+<tr><th>Option</th><th>Name</th></tr>
+<tr><td><a href="#deadarghaX0r">-deadarghaX0r</a></td><td>Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)</td></tr>
+<tr><td><a href="#extract-blocks">-extract-blocks</a></td><td>Extract Basic Blocks From Module (for bugpoint use)</td></tr>
+<tr><td><a href="#instnamer">-instnamer</a></td><td>Assign names to anonymous instructions</td></tr>
+<tr><td><a href="#preverify">-preverify</a></td><td>Preliminary module verification</td></tr>
+<tr><td><a href="#verify">-verify</a></td><td>Module Verifier</td></tr>
+<tr><td><a href="#view-cfg">-view-cfg</a></td><td>View CFG of function</td></tr>
+<tr><td><a href="#view-cfg-only">-view-cfg-only</a></td><td>View CFG of function (with no function bodies)</td></tr>
+<tr><td><a href="#view-dom">-view-dom</a></td><td>View dominance tree of function</td></tr>
+<tr><td><a href="#view-dom-only">-view-dom-only</a></td><td>View dominance tree of function (with no function bodies)</td></tr>
+<tr><td><a href="#view-postdom">-view-postdom</a></td><td>View postdominance tree of function</td></tr>
+<tr><td><a href="#view-postdom-only">-view-postdom-only</a></td><td>View postdominance tree of function (with no function bodies)</td></tr>
+</table>
+
+</div>
+
+<!-- ======================================================================= -->
+<h2><a name="analyses">Analysis Passes</a></h2>
+<div>
+  <p>This section describes the LLVM Analysis Passes.</p>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="aa-eval">-aa-eval: Exhaustive Alias Analysis Precision Evaluator</a>
+</h3>
+<div>
+  <p>This is a simple N^2 alias analysis accuracy evaluator.
+  Basically, for each function in the program, it simply queries to see how the
+  alias analysis implementation answers alias queries between each pair of
+  pointers in the function.</p>
+
+  <p>This is inspired and adapted from code by: Naveen Neelakantam, Francesco
+  Spadini, and Wojciech Stryjewski.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="basicaa">-basicaa: Basic Alias Analysis (stateless AA impl)</a>
+</h3>
+<div>
+  <p>A basic alias analysis pass that implements identities (two different
+  globals cannot alias, etc), but does no stateful analysis.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="basiccg">-basiccg: Basic CallGraph Construction</a>
+</h3>
+<div>
+  <p>Yet to be written.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="count-aa">-count-aa: Count Alias Analysis Query Responses</a>
+</h3>
+<div>
+  <p>
+  A pass which can be used to count how many alias queries
+  are being made and how the alias analysis implementation being used responds.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="da">-da: Dependence Analysis</a>
+</h3>
+<div>
+  <p>Dependence analysis framework, which is used to detect dependences in
+  memory accesses.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="debug-aa">-debug-aa: AA use debugger</a>
+</h3>
+<div>
+  <p>
+  This simple pass checks alias analysis users to ensure that if they
+  create a new value, they do not query AA without informing it of the value.
+  It acts as a shim over any other AA pass you want.
+  </p>
+  
+  <p>
+  Yes keeping track of every value in the program is expensive, but this is 
+  a debugging pass.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="domfrontier">-domfrontier: Dominance Frontier Construction</a>
+</h3>
+<div>
+  <p>
+  This pass is a simple dominator construction algorithm for finding forward
+  dominator frontiers.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="domtree">-domtree: Dominator Tree Construction</a>
+</h3>
+<div>
+  <p>
+  This pass is a simple dominator construction algorithm for finding forward
+  dominators.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="dot-callgraph">-dot-callgraph: Print Call Graph to 'dot' file</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the call graph into a
+  <code>.dot</code> graph.  This graph can then be processed with the "dot" tool
+  to convert it to postscript or some other suitable format.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="dot-cfg">-dot-cfg: Print CFG of function to 'dot' file</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the control flow graph
+  into a <code>.dot</code> graph.  This graph can then be processed with the
+  "dot" tool to convert it to postscript or some other suitable format.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="dot-cfg-only">-dot-cfg-only: Print CFG of function to 'dot' file (with no function bodies)</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the control flow graph
+  into a <code>.dot</code> graph, omitting the function bodies.  This graph can
+  then be processed with the "dot" tool to convert it to postscript or some
+  other suitable format.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="dot-dom">-dot-dom: Print dominance tree of function to 'dot' file</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the dominator tree
+  into a <code>.dot</code> graph.  This graph can then be processed with the
+  "dot" tool to convert it to postscript or some other suitable format.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="dot-dom-only">-dot-dom-only: Print dominance tree of function to 'dot' file (with no function bodies)</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the dominator tree
+  into a <code>.dot</code> graph, omitting the function bodies.  This graph can
+  then be processed with the "dot" tool to convert it to postscript or some
+  other suitable format.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="dot-postdom">-dot-postdom: Print postdominance tree of function to 'dot' file</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the post dominator tree
+  into a <code>.dot</code> graph.  This graph can then be processed with the
+  "dot" tool to convert it to postscript or some other suitable format.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="dot-postdom-only">-dot-postdom-only: Print postdominance tree of function to 'dot' file (with no function bodies)</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the post dominator tree
+  into a <code>.dot</code> graph, omitting the function bodies.  This graph can
+  then be processed with the "dot" tool to convert it to postscript or some
+  other suitable format.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="globalsmodref-aa">-globalsmodref-aa: Simple mod/ref analysis for globals</a>
+</h3>
+<div>
+  <p>
+  This simple pass provides alias and mod/ref information for global values
+  that do not have their address taken, and keeps track of whether functions
+  read or write memory (are "pure").  For this simple (but very common) case,
+  we can provide pretty accurate and useful information.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="instcount">-instcount: Counts the various types of Instructions</a>
+</h3>
+<div>
+  <p>
+  This pass collects the count of all instructions and reports them
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="intervals">-intervals: Interval Partition Construction</a>
+</h3>
+<div>
+  <p>
+  This analysis calculates and represents the interval partition of a function,
+  or a preexisting interval partition.
+  </p>
+  
+  <p>
+  In this way, the interval partition may be used to reduce a flow graph down
+  to its degenerate single node interval partition (unless it is irreducible).
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="iv-users">-iv-users: Induction Variable Users</a>
+</h3>
+<div>
+  <p>Bookkeeping for "interesting" users of expressions computed from 
+  induction variables.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="lazy-value-info">-lazy-value-info: Lazy Value Information Analysis</a>
+</h3>
+<div>
+  <p>Interface for lazy computation of value constraint information.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="libcall-aa">-libcall-aa: LibCall Alias Analysis</a>
+</h3>
+<div>
+  <p>LibCall Alias Analysis.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="lint">-lint: Statically lint-checks LLVM IR</a>
+</h3>
+<div>
+  <p>This pass statically checks for common and easily-identified constructs
+  which produce undefined or likely unintended behavior in LLVM IR.</p>
+ 
+  <p>It is not a guarantee of correctness, in two ways. First, it isn't
+  comprehensive. There are checks which could be done statically which are
+  not yet implemented. Some of these are indicated by TODO comments, but
+  those aren't comprehensive either. Second, many conditions cannot be
+  checked statically. This pass does no dynamic instrumentation, so it
+  can't check for all possible problems.</p>
+  
+  <p>Another limitation is that it assumes all code will be executed. A store
+  through a null pointer in a basic block which is never reached is harmless,
+  but this pass will warn about it anyway.</p>
+ 
+  <p>Optimization passes may make conditions that this pass checks for more or
+  less obvious. If an optimization pass appears to be introducing a warning,
+  it may be that the optimization pass is merely exposing an existing
+  condition in the code.</p>
+  
+  <p>This code may be run before instcombine. In many cases, instcombine checks
+  for the same kinds of things and turns instructions with undefined behavior
+  into unreachable (or equivalent). Because of this, this pass makes some
+  effort to look through bitcasts and so on.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loops">-loops: Natural Loop Information</a>
+</h3>
+<div>
+  <p>
+  This analysis is used to identify natural loops and determine the loop depth
+  of various nodes of the CFG.  Note that the loops identified may actually be
+  several natural loops that share the same header node... not just a single
+  natural loop.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="memdep">-memdep: Memory Dependence Analysis</a>
+</h3>
+<div>
+  <p>
+  An analysis that determines, for a given memory operation, what preceding 
+  memory operations it depends on.  It builds on alias analysis information, and 
+  tries to provide a lazy, caching interface to a common kind of alias 
+  information query.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="module-debuginfo">-module-debuginfo: Decodes module-level debug info</a>
+</h3>
+<div>
+  <p>This pass decodes the debug info metadata in a module and prints in a
+ (sufficiently-prepared-) human-readable form.
+
+ For example, run this pass from opt along with the -analyze option, and
+ it'll print to standard output.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="no-aa">-no-aa: No Alias Analysis (always returns 'may' alias)</a>
+</h3>
+<div>
+  <p>
+  This is the default implementation of the Alias Analysis interface. It always
+  returns "I don't know" for alias queries.  NoAA is unlike other alias analysis
+  implementations, in that it does not chain to a previous analysis. As such it
+  doesn't follow many of the rules that other alias analyses must.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="no-profile">-no-profile: No Profile Information</a>
+</h3>
+<div>
+  <p>
+  The default "no profile" implementation of the abstract
+  <code>ProfileInfo</code> interface.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="postdomfrontier">-postdomfrontier: Post-Dominance Frontier Construction</a>
+</h3>
+<div>
+  <p>
+  This pass is a simple post-dominator construction algorithm for finding
+  post-dominator frontiers.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="postdomtree">-postdomtree: Post-Dominator Tree Construction</a>
+</h3>
+<div>
+  <p>
+  This pass is a simple post-dominator construction algorithm for finding
+  post-dominators.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-alias-sets">-print-alias-sets: Alias Set Printer</a>
+</h3>
+<div>
+  <p>Yet to be written.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-callgraph">-print-callgraph: Print a call graph</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the call graph to
+  standard error in a human-readable form.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-callgraph-sccs">-print-callgraph-sccs: Print SCCs of the Call Graph</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the SCCs of the call
+  graph to standard error in a human-readable form.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-cfg-sccs">-print-cfg-sccs: Print SCCs of each function CFG</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints the SCCs of each
+  function CFG to standard error in a human-readable form.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-dbginfo">-print-dbginfo: Print debug info in human readable form</a>
+</h3>
+<div>
+  <p>Pass that prints instructions, and associated debug info:</p>
+  <ul>
+  
+  <li>source/line/col information</li>
+  <li>original variable name</li>
+  <li>original type name</li>
+  </ul>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-dom-info">-print-dom-info: Dominator Info Printer</a>
+</h3>
+<div>
+  <p>Dominator Info Printer.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-externalfnconstants">-print-externalfnconstants: Print external fn callsites passed constants</a>
+</h3>
+<div>
+  <p>
+  This pass, only available in <code>opt</code>, prints out call sites to
+  external functions that are called with constant arguments.  This can be
+  useful when looking for standard library functions we should constant fold
+  or handle in alias analyses.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-function">-print-function: Print function to stderr</a>
+</h3>
+<div>
+  <p>
+  The <code>PrintFunctionPass</code> class is designed to be pipelined with
+  other <code>FunctionPass</code>es, and prints out the functions of the module
+  as they are processed.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-module">-print-module: Print module to stderr</a>
+</h3>
+<div>
+  <p>
+  This pass simply prints out the entire module when it is executed.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="print-used-types">-print-used-types: Find Used Types</a>
+</h3>
+<div>
+  <p>
+  This pass is used to seek out all of the types in use by the program.  Note
+  that this analysis explicitly does not include types only used by the symbol
+  table.
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="profile-estimator">-profile-estimator: Estimate profiling information</a>
+</h3>
+<div>
+  <p>Profiling information that estimates the profiling information 
+  in a very crude and unimaginative way.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="profile-loader">-profile-loader: Load profile information from llvmprof.out</a>
+</h3>
+<div>
+  <p>
+  A concrete implementation of profiling information that loads the information
+  from a profile dump file.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="profile-verifier">-profile-verifier: Verify profiling information</a>
+</h3>
+<div>
+  <p>Pass that checks profiling information for plausibility.</p>
+</div>
+<h3>
+  <a name="regions">-regions: Detect single entry single exit regions</a>
+</h3>
+<div>
+  <p>
+  The <code>RegionInfo</code> pass detects single entry single exit regions in a
+  function, where a region is defined as any subgraph that is connected to the
+  remaining graph at only two spots. Furthermore, an hierarchical region tree is
+  built.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="scalar-evolution">-scalar-evolution: Scalar Evolution Analysis</a>
+</h3>
+<div>
+  <p>
+  The <code>ScalarEvolution</code> analysis can be used to analyze and
+  catagorize scalar expressions in loops.  It specializes in recognizing general
+  induction variables, representing them with the abstract and opaque
+  <code>SCEV</code> class.  Given this analysis, trip counts of loops and other
+  important properties can be obtained.
+  </p>
+  
+  <p>
+  This analysis is primarily useful for induction variable substitution and
+  strength reduction.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="scev-aa">-scev-aa: ScalarEvolution-based Alias Analysis</a>
+</h3>
+<div>
+  <p>Simple alias analysis implemented in terms of ScalarEvolution queries.
+ 
+  This differs from traditional loop dependence analysis in that it tests
+  for dependencies within a single iteration of a loop, rather than
+  dependencies between different iterations.
+ 
+  ScalarEvolution has a more complete understanding of pointer arithmetic
+  than BasicAliasAnalysis' collection of ad-hoc analyses.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="targetdata">-targetdata: Target Data Layout</a>
+</h3>
+<div>
+  <p>Provides other passes access to information on how the size and alignment
+  required by the target ABI for various data types.</p>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h2><a name="transforms">Transform Passes</a></h2>
+<div>
+  <p>This section describes the LLVM Transform Passes.</p>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="adce">-adce: Aggressive Dead Code Elimination</a>
+</h3>
+<div>
+  <p>ADCE aggressively tries to eliminate code. This pass is similar to
+  <a href="#dce">DCE</a> but it assumes that values are dead until proven 
+  otherwise. This is similar to <a href="#sccp">SCCP</a>, except applied to 
+  the liveness of values.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="always-inline">-always-inline: Inliner for always_inline functions</a>
+</h3>
+<div>
+  <p>A custom inliner that handles only functions that are marked as 
+  "always inline".</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="argpromotion">-argpromotion: Promote 'by reference' arguments to scalars</a>
+</h3>
+<div>
+  <p>
+  This pass promotes "by reference" arguments to be "by value" arguments.  In
+  practice, this means looking for internal functions that have pointer
+  arguments.  If it can prove, through the use of alias analysis, that an
+  argument is *only* loaded, then it can pass the value into the function
+  instead of the address of the value.  This can cause recursive simplification
+  of code and lead to the elimination of allocas (especially in C++ template
+  code like the STL).
+  </p>
+  
+  <p>
+  This pass also handles aggregate arguments that are passed into a function,
+  scalarizing them if the elements of the aggregate are only loaded.  Note that
+  it refuses to scalarize aggregates which would require passing in more than
+  three operands to the function, because passing thousands of operands for a
+  large array or structure is unprofitable!
+  </p>
+  
+  <p>
+  Note that this transformation could also be done for arguments that are only
+  stored to (returning the value instead), but does not currently.  This case
+  would be best handled when and if LLVM starts supporting multiple return
+  values from functions.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="bb-vectorize">-bb-vectorize: Basic-Block Vectorization</a>
+</h3>
+<div>
+  <p>This pass combines instructions inside basic blocks to form vector
+  instructions. It iterates over each basic block, attempting to pair
+  compatible instructions, repeating this process until no additional
+  pairs are selected for vectorization. When the outputs of some pair
+  of compatible instructions are used as inputs by some other pair of
+  compatible instructions, those pairs are part of a potential
+  vectorization chain. Instruction pairs are only fused into vector
+  instructions when they are part of a chain longer than some
+  threshold length. Moreover, the pass attempts to find the best
+  possible chain for each pair of compatible instructions. These
+  heuristics are intended to prevent vectorization in cases where
+  it would not yield a performance increase of the resulting code.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="block-placement">-block-placement: Profile Guided Basic Block Placement</a>
+</h3>
+<div>
+  <p>This pass is a very simple profile guided basic block placement algorithm.
+  The idea is to put frequently executed blocks together at the start of the
+  function and hopefully increase the number of fall-through conditional
+  branches.  If there is no profile information for a particular function, this
+  pass basically orders blocks in depth-first order.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="break-crit-edges">-break-crit-edges: Break critical edges in CFG</a>
+</h3>
+<div>
+  <p>
+  Break all of the critical edges in the CFG by inserting a dummy basic block.
+  It may be "required" by passes that cannot deal with critical edges. This
+  transformation obviously invalidates the CFG, but can update forward dominator
+  (set, immediate dominators, tree, and frontier) information.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="codegenprepare">-codegenprepare: Optimize for code generation</a>
+</h3>
+<div>
+  This pass munges the code in the input function to better prepare it for
+  SelectionDAG-based code generation. This works around limitations in it's
+  basic-block-at-a-time approach. It should eventually be removed.
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="constmerge">-constmerge: Merge Duplicate Global Constants</a>
+</h3>
+<div>
+  <p>
+  Merges duplicate global constants together into a single constant that is
+  shared.  This is useful because some passes (ie TraceValues) insert a lot of
+  string constants into the program, regardless of whether or not an existing
+  string is available.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="constprop">-constprop: Simple constant propagation</a>
+</h3>
+<div>
+  <p>This file implements constant propagation and merging. It looks for
+  instructions involving only constant operands and replaces them with a
+  constant value instead of an instruction. For example:</p>
+  <blockquote><pre>add i32 1, 2</pre></blockquote>
+  <p>becomes</p>
+  <blockquote><pre>i32 3</pre></blockquote>
+  <p>NOTE: this pass has a habit of making definitions be dead.  It is a good 
+  idea to to run a <a href="#die">DIE</a> (Dead Instruction Elimination) pass 
+  sometime after running this pass.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="dce">-dce: Dead Code Elimination</a>
+</h3>
+<div>
+  <p>
+  Dead code elimination is similar to <a href="#die">dead instruction
+  elimination</a>, but it rechecks instructions that were used by removed
+  instructions to see if they are newly dead.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="deadargelim">-deadargelim: Dead Argument Elimination</a>
+</h3>
+<div>
+  <p>
+  This pass deletes dead arguments from internal functions.  Dead argument
+  elimination removes arguments which are directly dead, as well as arguments
+  only passed into function calls as dead arguments of other functions.  This
+  pass also deletes dead arguments in a similar way.
+  </p>
+  
+  <p>
+  This pass is often useful as a cleanup pass to run after aggressive
+  interprocedural passes, which add possibly-dead arguments.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="deadtypeelim">-deadtypeelim: Dead Type Elimination</a>
+</h3>
+<div>
+  <p>
+  This pass is used to cleanup the output of GCC.  It eliminate names for types
+  that are unused in the entire translation unit, using the <a
+  href="#findusedtypes">find used types</a> pass.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="die">-die: Dead Instruction Elimination</a>
+</h3>
+<div>
+  <p>
+  Dead instruction elimination performs a single pass over the function,
+  removing instructions that are obviously dead.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="dse">-dse: Dead Store Elimination</a>
+</h3>
+<div>
+  <p>
+  A trivial dead store elimination that only considers basic-block local
+  redundant stores.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="functionattrs">-functionattrs: Deduce function attributes</a>
+</h3>
+<div>
+  <p>A simple interprocedural pass which walks the call-graph, looking for 
+  functions which do not access or only read non-local memory, and marking them 
+  readnone/readonly.  In addition, it marks function arguments (of pointer type) 
+  'nocapture' if a call to the function does not create any copies of the pointer 
+  value that outlive the call. This more or less means that the pointer is only
+  dereferenced, and not returned from the function or stored in a global.
+  This pass is implemented as a bottom-up traversal of the call-graph.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="globaldce">-globaldce: Dead Global Elimination</a>
+</h3>
+<div>
+  <p>
+  This transform is designed to eliminate unreachable internal globals from the
+  program.  It uses an aggressive algorithm, searching out globals that are
+  known to be alive.  After it finds all of the globals which are needed, it
+  deletes whatever is left over.  This allows it to delete recursive chunks of
+  the program which are unreachable.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="globalopt">-globalopt: Global Variable Optimizer</a>
+</h3>
+<div>
+  <p>
+  This pass transforms simple global variables that never have their address
+  taken.  If obviously true, it marks read/write globals as constant, deletes
+  variables only stored to, etc.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="gvn">-gvn: Global Value Numbering</a>
+</h3>
+<div>
+  <p>
+  This pass performs global value numbering to eliminate fully and partially
+  redundant instructions.  It also performs redundant load elimination.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="indvars">-indvars: Canonicalize Induction Variables</a>
+</h3>
+<div>
+  <p>
+  This transformation analyzes and transforms the induction variables (and
+  computations derived from them) into simpler forms suitable for subsequent
+  analysis and transformation.
+  </p>
+  
+  <p>
+  This transformation makes the following changes to each loop with an
+  identifiable induction variable:
+  </p>
+  
+  <ol>
+    <li>All loops are transformed to have a <em>single</em> canonical
+        induction variable which starts at zero and steps by one.</li>
+    <li>The canonical induction variable is guaranteed to be the first PHI node
+        in the loop header block.</li>
+    <li>Any pointer arithmetic recurrences are raised to use array
+        subscripts.</li>
+  </ol>
+  
+  <p>
+  If the trip count of a loop is computable, this pass also makes the following
+  changes:
+  </p>
+  
+  <ol>
+    <li>The exit condition for the loop is canonicalized to compare the
+        induction value against the exit value.  This turns loops like:
+        <blockquote><pre>for (i = 7; i*i < 1000; ++i)</pre></blockquote>
+        into
+        <blockquote><pre>for (i = 0; i != 25; ++i)</pre></blockquote></li>
+    <li>Any use outside of the loop of an expression derived from the indvar
+        is changed to compute the derived value outside of the loop, eliminating
+        the dependence on the exit value of the induction variable.  If the only
+        purpose of the loop is to compute the exit value of some derived
+        expression, this transformation will make the loop dead.</li>
+  </ol>
+  
+  <p>
+  This transformation should be followed by strength reduction after all of the
+  desired loop transformations have been performed.  Additionally, on targets
+  where it is profitable, the loop could be transformed to count down to zero
+  (the "do loop" optimization).
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="inline">-inline: Function Integration/Inlining</a>
+</h3>
+<div>
+  <p>
+  Bottom-up inlining of functions into callees.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="insert-edge-profiling">-insert-edge-profiling: Insert instrumentation for edge profiling</a>
+</h3>
+<div>
+  <p>
+  This pass instruments the specified program with counters for edge profiling.
+  Edge profiling can give a reasonable approximation of the hot paths through a
+  program, and is used for a wide variety of program transformations.
+  </p>
+  
+  <p>
+  Note that this implementation is very naïve.  It inserts a counter for
+  <em>every</em> edge in the program, instead of using control flow information
+  to prune the number of counters inserted.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="insert-optimal-edge-profiling">-insert-optimal-edge-profiling: Insert optimal instrumentation for edge profiling</a>
+</h3>
+<div>
+  <p>This pass instruments the specified program with counters for edge profiling.
+  Edge profiling can give a reasonable approximation of the hot paths through a
+  program, and is used for a wide variety of program transformations.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="instcombine">-instcombine: Combine redundant instructions</a>
+</h3>
+<div>
+  <p>
+  Combine instructions to form fewer, simple
+  instructions.  This pass does not modify the CFG This pass is where algebraic
+  simplification happens.
+  </p>
+  
+  <p>
+  This pass combines things like:
+  </p>
+  
+<blockquote><pre
+>%Y = add i32 %X, 1
+%Z = add i32 %Y, 1</pre></blockquote>
+  
+  <p>
+  into:
+  </p>
+
+<blockquote><pre
+>%Z = add i32 %X, 2</pre></blockquote>
+  
+  <p>
+  This is a simple worklist driven algorithm.
+  </p>
+  
+  <p>
+  This pass guarantees that the following canonicalizations are performed on
+  the program:
+  </p>
+
+  <ul>
+    <li>If a binary operator has a constant operand, it is moved to the right-
+        hand side.</li>
+    <li>Bitwise operators with constant operands are always grouped so that
+        shifts are performed first, then <code>or</code>s, then
+        <code>and</code>s, then <code>xor</code>s.</li>
+    <li>Compare instructions are converted from <code><</code>,
+        <code>></code>, <code>≤</code>, or <code>≥</code> to
+        <code>=</code> or <code>≠</code> if possible.</li>
+    <li>All <code>cmp</code> instructions on boolean values are replaced with
+        logical operations.</li>
+    <li><code>add <var>X</var>, <var>X</var></code> is represented as
+        <code>mul <var>X</var>, 2</code> ⇒ <code>shl <var>X</var>, 1</code></li>
+    <li>Multiplies with a constant power-of-two argument are transformed into
+        shifts.</li>
+    <li>… etc.</li>
+  </ul>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="internalize">-internalize: Internalize Global Symbols</a>
+</h3>
+<div>
+  <p>
+  This pass loops over all of the functions in the input module, looking for a
+  main function.  If a main function is found, all other functions and all
+  global variables with initializers are marked as internal.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="ipconstprop">-ipconstprop: Interprocedural constant propagation</a>
+</h3>
+<div>
+  <p>
+  This pass implements an <em>extremely</em> simple interprocedural constant
+  propagation pass.  It could certainly be improved in many different ways,
+  like using a worklist.  This pass makes arguments dead, but does not remove
+  them.  The existing dead argument elimination pass should be run after this
+  to clean up the mess.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="ipsccp">-ipsccp: Interprocedural Sparse Conditional Constant Propagation</a>
+</h3>
+<div>
+  <p>
+  An interprocedural variant of <a href="#sccp">Sparse Conditional Constant 
+  Propagation</a>.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="jump-threading">-jump-threading: Jump Threading</a>
+</h3>
+<div>
+  <p>
+  Jump threading tries to find distinct threads of control flow running through
+  a basic block. This pass looks at blocks that have multiple predecessors and
+  multiple successors.  If one or more of the predecessors of the block can be
+  proven to always cause a jump to one of the successors, we forward the edge
+  from the predecessor to the successor by duplicating the contents of this
+  block.
+  </p>
+  <p>
+  An example of when this can occur is code like this:
+  </p>
+
+  <pre
+>if () { ...
+  X = 4;
+}
+if (X < 3) {</pre>
+
+  <p>
+  In this case, the unconditional branch at the end of the first if can be
+  revectored to the false side of the second if.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="lcssa">-lcssa: Loop-Closed SSA Form Pass</a>
+</h3>
+<div>
+  <p>
+  This pass transforms loops by placing phi nodes at the end of the loops for
+  all values that are live across the loop boundary.  For example, it turns
+  the left into the right code:
+  </p>
+  
+  <pre
+>for (...)                for (...)
+  if (c)                   if (c)
+    X1 = ...                 X1 = ...
+  else                     else
+    X2 = ...                 X2 = ...
+  X3 = phi(X1, X2)         X3 = phi(X1, X2)
+... = X3 + 4              X4 = phi(X3)
+                          ... = X4 + 4</pre>
+  
+  <p>
+  This is still valid LLVM; the extra phi nodes are purely redundant, and will
+  be trivially eliminated by <code>InstCombine</code>.  The major benefit of
+  this transformation is that it makes many other loop optimizations, such as 
+  LoopUnswitching, simpler.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="licm">-licm: Loop Invariant Code Motion</a>
+</h3>
+<div>
+  <p>
+  This pass performs loop invariant code motion, attempting to remove as much
+  code from the body of a loop as possible.  It does this by either hoisting
+  code into the preheader block, or by sinking code to the exit blocks if it is
+  safe.  This pass also promotes must-aliased memory locations in the loop to
+  live in registers, thus hoisting and sinking "invariant" loads and stores.
+  </p>
+  
+  <p>
+  This pass uses alias analysis for two purposes:
+  </p>
+  
+  <ul>
+    <li>Moving loop invariant loads and calls out of loops.  If we can determine
+        that a load or call inside of a loop never aliases anything stored to,
+        we can hoist it or sink it like any other instruction.</li>
+    <li>Scalar Promotion of Memory - If there is a store instruction inside of
+        the loop, we try to move the store to happen AFTER the loop instead of
+        inside of the loop.  This can only happen if a few conditions are true:
+        <ul>
+          <li>The pointer stored through is loop invariant.</li>
+          <li>There are no stores or loads in the loop which <em>may</em> alias
+              the pointer.  There are no calls in the loop which mod/ref the
+              pointer.</li>
+        </ul>
+        If these conditions are true, we can promote the loads and stores in the
+        loop of the pointer to use a temporary alloca'd variable.  We then use
+        the mem2reg functionality to construct the appropriate SSA form for the
+        variable.</li>
+  </ul>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loop-deletion">-loop-deletion: Delete dead loops</a>
+</h3>
+<div>
+  <p>
+  This file implements the Dead Loop Deletion Pass.  This pass is responsible
+  for eliminating loops with non-infinite computable trip counts that have no
+  side effects or volatile instructions, and do not contribute to the
+  computation of the function's return value.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loop-extract">-loop-extract: Extract loops into new functions</a>
+</h3>
+<div>
+  <p>
+  A pass wrapper around the <code>ExtractLoop()</code> scalar transformation to 
+  extract each top-level loop into its own new function. If the loop is the
+  <em>only</em> loop in a given function, it is not touched. This is a pass most
+  useful for debugging via bugpoint.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loop-extract-single">-loop-extract-single: Extract at most one loop into a new function</a>
+</h3>
+<div>
+  <p>
+  Similar to <a href="#loop-extract">Extract loops into new functions</a>,
+  this pass extracts one natural loop from the program into a function if it
+  can. This is used by bugpoint.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loop-reduce">-loop-reduce: Loop Strength Reduction</a>
+</h3>
+<div>
+  <p>
+  This pass performs a strength reduction on array references inside loops that
+  have as one or more of their components the loop induction variable.  This is
+  accomplished by creating a new value to hold the initial value of the array
+  access for the first iteration, and then creating a new GEP instruction in
+  the loop to increment the value by the appropriate amount.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loop-rotate">-loop-rotate: Rotate Loops</a>
+</h3>
+<div>
+  <p>A simple loop rotation transformation.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loop-simplify">-loop-simplify: Canonicalize natural loops</a>
+</h3>
+<div>
+  <p>
+  This pass performs several transformations to transform natural loops into a
+  simpler form, which makes subsequent analyses and transformations simpler and
+  more effective.
+  </p>
+  
+  <p>
+  Loop pre-header insertion guarantees that there is a single, non-critical
+  entry edge from outside of the loop to the loop header.  This simplifies a
+  number of analyses and transformations, such as LICM.
+  </p>
+  
+  <p>
+  Loop exit-block insertion guarantees that all exit blocks from the loop
+  (blocks which are outside of the loop that have predecessors inside of the
+  loop) only have predecessors from inside of the loop (and are thus dominated
+  by the loop header).  This simplifies transformations such as store-sinking
+  that are built into LICM.
+  </p>
+  
+  <p>
+  This pass also guarantees that loops will have exactly one backedge.
+  </p>
+  
+  <p>
+  Note that the simplifycfg pass will clean up blocks which are split out but
+  end up being unnecessary, so usage of this pass should not pessimize
+  generated code.
+  </p>
+  
+  <p>
+  This pass obviously modifies the CFG, but updates loop information and
+  dominator information.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loop-unroll">-loop-unroll: Unroll loops</a>
+</h3>
+<div>
+  <p>
+  This pass implements a simple loop unroller.  It works best when loops have
+  been canonicalized by the <a href="#indvars"><tt>-indvars</tt></a> pass,
+  allowing it to determine the trip counts of loops easily.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loop-unswitch">-loop-unswitch: Unswitch loops</a>
+</h3>
+<div>
+  <p>
+  This pass transforms loops that contain branches on loop-invariant conditions
+  to have multiple loops.  For example, it turns the left into the right code:
+  </p>
+  
+  <pre
+>for (...)                  if (lic)
+  A                          for (...)
+  if (lic)                     A; B; C
+    B                      else
+  C                          for (...)
+                               A; C</pre>
+  
+  <p>
+  This can increase the size of the code exponentially (doubling it every time
+  a loop is unswitched) so we only unswitch if the resultant code will be
+  smaller than a threshold.
+  </p>
+  
+  <p>
+  This pass expects LICM to be run before it to hoist invariant conditions out
+  of the loop, to make the unswitching opportunity obvious.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="loweratomic">-loweratomic: Lower atomic intrinsics to non-atomic form</a>
+</h3>
+<div>
+  <p>
+  This pass lowers atomic intrinsics to non-atomic form for use in a known
+  non-preemptible environment.
+  </p>
+
+  <p>
+  The pass does not verify that the environment is non-preemptible (in
+  general this would require knowledge of the entire call graph of the
+  program including any libraries which may not be available in bitcode form);
+  it simply lowers every atomic intrinsic.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="lowerinvoke">-lowerinvoke: Lower invoke and unwind, for unwindless code generators</a>
+</h3>
+<div>
+  <p>
+  This transformation is designed for use by code generators which do not yet
+  support stack unwinding.  This pass supports two models of exception handling
+  lowering, the 'cheap' support and the 'expensive' support.
+  </p>
+  
+  <p>
+  'Cheap' exception handling support gives the program the ability to execute
+  any program which does not "throw an exception", by turning 'invoke'
+  instructions into calls and by turning 'unwind' instructions into calls to
+  abort().  If the program does dynamically use the unwind instruction, the
+  program will print a message then abort.
+  </p>
+  
+  <p>
+  'Expensive' exception handling support gives the full exception handling
+  support to the program at the cost of making the 'invoke' instruction
+  really expensive.  It basically inserts setjmp/longjmp calls to emulate the
+  exception handling as necessary.
+  </p>
+  
+  <p>
+  Because the 'expensive' support slows down programs a lot, and EH is only
+  used for a subset of the programs, it must be specifically enabled by the
+  <tt>-enable-correct-eh-support</tt> option.
+  </p>
+  
+  <p>
+  Note that after this pass runs the CFG is not entirely accurate (exceptional
+  control flow edges are not correct anymore) so only very simple things should
+  be done after the lowerinvoke pass has run (like generation of native code).
+  This should not be used as a general purpose "my LLVM-to-LLVM pass doesn't
+  support the invoke instruction yet" lowering pass.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="lowerswitch">-lowerswitch: Lower SwitchInst's to branches</a>
+</h3>
+<div>
+  <p>
+  Rewrites <tt>switch</tt> instructions with a sequence of branches, which
+  allows targets to get away with not implementing the switch instruction until
+  it is convenient.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="mem2reg">-mem2reg: Promote Memory to Register</a>
+</h3>
+<div>
+  <p>
+  This file promotes memory references to be register references.  It promotes
+  <tt>alloca</tt> instructions which only have <tt>load</tt>s and
+  <tt>store</tt>s as uses.  An <tt>alloca</tt> is transformed by using dominator
+  frontiers to place <tt>phi</tt> nodes, then traversing the function in
+  depth-first order to rewrite <tt>load</tt>s and <tt>store</tt>s as
+  appropriate. This is just the standard SSA construction algorithm to construct
+  "pruned" SSA form.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="memcpyopt">-memcpyopt: MemCpy Optimization</a>
+</h3>
+<div>
+  <p>
+  This pass performs various transformations related to eliminating memcpy
+  calls, or transforming sets of stores into memset's.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="mergefunc">-mergefunc: Merge Functions</a>
+</h3>
+<div>
+  <p>This pass looks for equivalent functions that are mergable and folds them.
+ 
+  A hash is computed from the function, based on its type and number of
+  basic blocks.
+ 
+  Once all hashes are computed, we perform an expensive equality comparison
+  on each function pair. This takes n^2/2 comparisons per bucket, so it's
+  important that the hash function be high quality. The equality comparison
+  iterates through each instruction in each basic block.
+ 
+  When a match is found the functions are folded. If both functions are
+  overridable, we move the functionality into a new internal function and
+  leave two overridable thunks to it.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="mergereturn">-mergereturn: Unify function exit nodes</a>
+</h3>
+<div>
+  <p>
+  Ensure that functions have at most one <tt>ret</tt> instruction in them.
+  Additionally, it keeps track of which node is the new exit node of the CFG.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="partial-inliner">-partial-inliner: Partial Inliner</a>
+</h3>
+<div>
+  <p>This pass performs partial inlining, typically by inlining an if 
+  statement that surrounds the body of the function.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="prune-eh">-prune-eh: Remove unused exception handling info</a>
+</h3>
+<div>
+  <p>
+  This file implements a simple interprocedural pass which walks the call-graph,
+  turning <tt>invoke</tt> instructions into <tt>call</tt> instructions if and
+  only if the callee cannot throw an exception. It implements this as a
+  bottom-up traversal of the call-graph.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="reassociate">-reassociate: Reassociate expressions</a>
+</h3>
+<div>
+  <p>
+  This pass reassociates commutative expressions in an order that is designed
+  to promote better constant propagation, GCSE, LICM, PRE, etc.
+  </p>
+  
+  <p>
+  For example: 4 + (<var>x</var> + 5) ⇒ <var>x</var> + (4 + 5)
+  </p>
+  
+  <p>
+  In the implementation of this algorithm, constants are assigned rank = 0,
+  function arguments are rank = 1, and other values are assigned ranks
+  corresponding to the reverse post order traversal of current function
+  (starting at 2), which effectively gives values in deep loops higher rank
+  than values not in loops.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="reg2mem">-reg2mem: Demote all values to stack slots</a>
+</h3>
+<div>
+  <p>
+  This file demotes all registers to memory references.  It is intended to be
+  the inverse of <a href="#mem2reg"><tt>-mem2reg</tt></a>.  By converting to
+  <tt>load</tt> instructions, the only values live across basic blocks are
+  <tt>alloca</tt> instructions and <tt>load</tt> instructions before
+  <tt>phi</tt> nodes. It is intended that this should make CFG hacking much 
+  easier. To make later hacking easier, the entry block is split into two, such
+  that all introduced <tt>alloca</tt> instructions (and nothing else) are in the
+  entry block.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="scalarrepl">-scalarrepl: Scalar Replacement of Aggregates (DT)</a>
+</h3>
+<div>
+  <p>
+  The well-known scalar replacement of aggregates transformation.  This
+  transform breaks up <tt>alloca</tt> instructions of aggregate type (structure
+  or array) into individual <tt>alloca</tt> instructions for each member if
+  possible.  Then, if possible, it transforms the individual <tt>alloca</tt>
+  instructions into nice clean scalar SSA form.
+  </p>
+  
+  <p>
+  This combines a simple scalar replacement of aggregates algorithm with the <a
+  href="#mem2reg"><tt>mem2reg</tt></a> algorithm because often interact, 
+  especially for C++ programs.  As such, iterating between <tt>scalarrepl</tt>, 
+  then <a href="#mem2reg"><tt>mem2reg</tt></a> until we run out of things to 
+  promote works well.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="sccp">-sccp: Sparse Conditional Constant Propagation</a>
+</h3>
+<div>
+  <p>
+  Sparse conditional constant propagation and merging, which can be summarized
+  as:
+  </p>
+  
+  <ol>
+    <li>Assumes values are constant unless proven otherwise</li>
+    <li>Assumes BasicBlocks are dead unless proven otherwise</li>
+    <li>Proves values to be constant, and replaces them with constants</li>
+    <li>Proves conditional branches to be unconditional</li>
+  </ol>
+  
+  <p>
+  Note that this pass has a habit of making definitions be dead.  It is a good
+  idea to to run a DCE pass sometime after running this pass.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="simplify-libcalls">-simplify-libcalls: Simplify well-known library calls</a>
+</h3>
+<div>
+  <p>
+  Applies a variety of small optimizations for calls to specific well-known 
+  function calls (e.g. runtime library functions). For example, a call
+   <tt>exit(3)</tt> that occurs within the <tt>main()</tt> function can be 
+   transformed into simply <tt>return 3</tt>.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="simplifycfg">-simplifycfg: Simplify the CFG</a>
+</h3>
+<div>
+  <p>
+  Performs dead code elimination and basic block merging. Specifically:
+  </p>
+  
+  <ol>
+    <li>Removes basic blocks with no predecessors.</li>
+    <li>Merges a basic block into its predecessor if there is only one and the
+        predecessor only has one successor.</li>
+    <li>Eliminates PHI nodes for basic blocks with a single predecessor.</li>
+    <li>Eliminates a basic block that only contains an unconditional
+        branch.</li>
+  </ol>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="sink">-sink: Code sinking</a>
+</h3>
+<div>
+  <p>This pass moves instructions into successor blocks, when possible, so that
+ they aren't executed on paths where their results aren't needed.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="sretpromotion">-sretpromotion: Promote sret arguments to multiple ret values</a>
+</h3>
+<div>
+  <p>
+  This pass finds functions that return a struct (using a pointer to the struct
+  as the first argument of the function, marked with the '<tt>sret</tt>' attribute) and
+  replaces them with a new function that simply returns each of the elements of
+  that struct (using multiple return values).
+  </p>
+
+  <p>
+  This pass works under a number of conditions:
+  </p>
+
+  <ul>
+  <li>The returned struct must not contain other structs</li>
+  <li>The returned struct must only be used to load values from</li>
+  <li>The placeholder struct passed in is the result of an <tt>alloca</tt></li>
+  </ul>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="strip">-strip: Strip all symbols from a module</a>
+</h3>
+<div>
+  <p>
+  performs code stripping. this transformation can delete:
+  </p>
+  
+  <ol>
+    <li>names for virtual registers</li>
+    <li>symbols for internal globals and functions</li>
+    <li>debug information</li>
+  </ol>
+  
+  <p>
+  note that this transformation makes code much less readable, so it should
+  only be used in situations where the <tt>strip</tt> utility would be used,
+  such as reducing code size or making it harder to reverse engineer code.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="strip-dead-debug-info">-strip-dead-debug-info: Strip debug info for unused symbols</a>
+</h3>
+<div>
+  <p>
+  performs code stripping. this transformation can delete:
+  </p>
+  
+  <ol>
+    <li>names for virtual registers</li>
+    <li>symbols for internal globals and functions</li>
+    <li>debug information</li>
+  </ol>
+  
+  <p>
+  note that this transformation makes code much less readable, so it should
+  only be used in situations where the <tt>strip</tt> utility would be used,
+  such as reducing code size or making it harder to reverse engineer code.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="strip-dead-prototypes">-strip-dead-prototypes: Strip Unused Function Prototypes</a>
+</h3>
+<div>
+  <p>
+  This pass loops over all of the functions in the input module, looking for
+  dead declarations and removes them. Dead declarations are declarations of
+  functions for which no implementation is available (i.e., declarations for
+  unused library functions).
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="strip-debug-declare">-strip-debug-declare: Strip all llvm.dbg.declare intrinsics</a>
+</h3>
+<div>
+  <p>This pass implements code stripping. Specifically, it can delete:</p>
+  <ul>
+  <li>names for virtual registers</li>
+  <li>symbols for internal globals and functions</li>
+  <li>debug information</li>
+  </ul>
+  <p>
+  Note that this transformation makes code much less readable, so it should
+  only be used in situations where the 'strip' utility would be used, such as
+  reducing code size or making it harder to reverse engineer code.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="strip-nondebug">-strip-nondebug: Strip all symbols, except dbg symbols, from a module</a>
+</h3>
+<div>
+  <p>This pass implements code stripping. Specifically, it can delete:</p>
+  <ul>
+  <li>names for virtual registers</li>
+  <li>symbols for internal globals and functions</li>
+  <li>debug information</li>
+  </ul>
+  <p>
+  Note that this transformation makes code much less readable, so it should
+  only be used in situations where the 'strip' utility would be used, such as
+  reducing code size or making it harder to reverse engineer code.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="tailcallelim">-tailcallelim: Tail Call Elimination</a>
+</h3>
+<div>
+  <p>
+  This file transforms calls of the current function (self recursion) followed
+  by a return instruction with a branch to the entry of the function, creating
+  a loop.  This pass also implements the following extensions to the basic
+  algorithm:
+  </p>
+  
+  <ul>
+  <li>Trivial instructions between the call and return do not prevent the
+      transformation from taking place, though currently the analysis cannot
+      support moving any really useful instructions (only dead ones).
+  <li>This pass transforms functions that are prevented from being tail
+      recursive by an associative expression to use an accumulator variable,
+      thus compiling the typical naive factorial or <tt>fib</tt> implementation
+      into efficient code.
+  <li>TRE is performed if the function returns void, if the return
+      returns the result returned by the call, or if the function returns a
+      run-time constant on all exits from the function.  It is possible, though
+      unlikely, that the return returns something else (like constant 0), and
+      can still be TRE'd.  It can be TRE'd if <em>all other</em> return 
+      instructions in the function return the exact same value.
+  <li>If it can prove that callees do not access theier caller stack frame,
+      they are marked as eligible for tail call elimination (by the code
+      generator).
+  </ul>
+</div>
+
+<!-- ======================================================================= -->
+<h2><a name="utilities">Utility Passes</a></h2>
+<div>
+  <p>This section describes the LLVM Utility Passes.</p>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="deadarghaX0r">-deadarghaX0r: Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)</a>
+</h3>
+<div>
+  <p>
+  Same as dead argument elimination, but deletes arguments to functions which
+  are external.  This is only for use by <a
+  href="Bugpoint.html">bugpoint</a>.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="extract-blocks">-extract-blocks: Extract Basic Blocks From Module (for bugpoint use)</a>
+</h3>
+<div>
+  <p>
+  This pass is used by bugpoint to extract all blocks from the module into their
+  own functions.</p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="instnamer">-instnamer: Assign names to anonymous instructions</a>
+</h3>
+<div>
+  <p>This is a little utility pass that gives instructions names, this is mostly
+ useful when diffing the effect of an optimization because deleting an
+ unnamed instruction can change all other instruction numbering, making the
+ diff very noisy.  
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="preverify">-preverify: Preliminary module verification</a>
+</h3>
+<div>
+  <p>
+  Ensures that the module is in the form required by the <a
+  href="#verifier">Module Verifier</a> pass.
+  </p>
+  
+  <p>
+  Running the verifier runs this pass automatically, so there should be no need
+  to use it directly.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="verify">-verify: Module Verifier</a>
+</h3>
+<div>
+  <p>
+  Verifies an LLVM IR code. This is useful to run after an optimization which is
+  undergoing testing. Note that <tt>llvm-as</tt> verifies its input before
+  emitting bitcode, and also that malformed bitcode is likely to make LLVM
+  crash. All language front-ends are therefore encouraged to verify their output
+  before performing optimizing transformations.
+  </p>
+
+  <ul>
+    <li>Both of a binary operator's parameters are of the same type.</li>
+    <li>Verify that the indices of mem access instructions match other
+        operands.</li>
+    <li>Verify that arithmetic and other things are only performed on
+        first-class types.  Verify that shifts and logicals only happen on
+        integrals f.e.</li>
+    <li>All of the constants in a switch statement are of the correct type.</li>
+    <li>The code is in valid SSA form.</li>
+    <li>It is illegal to put a label into any other type (like a structure) or 
+        to return one.</li>
+    <li>Only phi nodes can be self referential: <tt>%x = add i32 %x, %x</tt> is
+        invalid.</li>
+    <li>PHI nodes must have an entry for each predecessor, with no extras.</li>
+    <li>PHI nodes must be the first thing in a basic block, all grouped
+        together.</li>
+    <li>PHI nodes must have at least one entry.</li>
+    <li>All basic blocks should only end with terminator insts, not contain
+        them.</li>
+    <li>The entry node to a function must not have predecessors.</li>
+    <li>All Instructions must be embedded into a basic block.</li>
+    <li>Functions cannot take a void-typed parameter.</li>
+    <li>Verify that a function's argument list agrees with its declared
+        type.</li>
+    <li>It is illegal to specify a name for a void value.</li>
+    <li>It is illegal to have an internal global value with no initializer.</li>
+    <li>It is illegal to have a ret instruction that returns a value that does
+        not agree with the function return value type.</li>
+    <li>Function call argument types match the function prototype.</li>
+    <li>All other things that are tested by asserts spread about the code.</li>
+  </ul>
+  
+  <p>
+  Note that this does not provide full security verification (like Java), but
+  instead just tries to ensure that code is well-formed.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="view-cfg">-view-cfg: View CFG of function</a>
+</h3>
+<div>
+  <p>
+  Displays the control flow graph using the GraphViz tool.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="view-cfg-only">-view-cfg-only: View CFG of function (with no function bodies)</a>
+</h3>
+<div>
+  <p>
+  Displays the control flow graph using the GraphViz tool, but omitting function
+  bodies.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="view-dom">-view-dom: View dominance tree of function</a>
+</h3>
+<div>
+  <p>
+  Displays the dominator tree using the GraphViz tool.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="view-dom-only">-view-dom-only: View dominance tree of function (with no function bodies)</a>
+</h3>
+<div>
+  <p>
+  Displays the dominator tree using the GraphViz tool, but omitting function
+  bodies.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="view-postdom">-view-postdom: View postdominance tree of function</a>
+</h3>
+<div>
+  <p>
+  Displays the post dominator tree using the GraphViz tool.
+  </p>
+</div>
+
+<!-------------------------------------------------------------------------- -->
+<h3>
+  <a name="view-postdom-only">-view-postdom-only: View postdominance tree of function (with no function bodies)</a>
+</h3>
+<div>
+  <p>
+  Displays the post dominator tree using the GraphViz tool, but omitting
+  function bodies.
+  </p>
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+  <a href="http://validator.w3.org/check/referer"><img
+  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
+
+  <a href="mailto:rspencer at x10sys.com">Reid Spencer</a><br>
+  <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
+  Last modified: $Date: 2012-10-31 12:25:31 -0500 (Wed, 31 Oct 2012) $
+</address>
+
+</body>
+</html>

Added: www-releases/trunk/3.2/docs/Phabricator.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/Phabricator.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/Phabricator.rst (added)
+++ www-releases/trunk/3.2/docs/Phabricator.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,100 @@
+=============================
+Code Reviews with Phabricator
+=============================
+
+.. contents::
+  :local:
+
+If you prefer to use a web user interface for code reviews,
+you can now submit your patches for Clang and LLVM at
+`LLVM's Phabricator`_.
+
+Sign up
+-------
+
+There are two options to get an account on Phabricator. You can sign up
+immediately with one of the supported OAuth account types if you're comfortable
+with OAuth, but you can also email chandlerc at gmail.com to request an account to
+be created manually without using OAuth. We're working to get support in
+Phabricator to directly create new accounts, but currently this is a manual
+process.
+
+Note that if you use your Subversion user name as Phabricator user name,
+Phabricator will automatically connect your submits to your Phabricator user in
+the `Code Repository Browser`_.
+
+
+Requesting a review via the command line
+----------------------------------------
+
+Phabricator has a tool called *Arcanist* to upload patches from
+the command line. To get you set up, follow the
+`Arcanist Quick Start`_ instructions.
+
+You can learn more about how to use arc to interact with
+Phabricator in the `Arcanist User Guide`_.
+
+Requesting a review via the web interface
+-----------------------------------------
+
+The tool to create and review patches in Phabricator is called
+*Differential*.
+
+Note that you can upload patches created through various diff tools,
+including git and svn. To make reviews easier, please always include
+**as much context as possible** with your diff! Don't worry, Phabricator
+will automatically send a diff with a smaller context in the review
+email, but having the full file in the web interface will help the
+reviewer understand your code.
+
+To get a full diff, use one of the following commands (or just use Arcanist
+to upload your patch):
+
+* ``git diff -U999999 other-branch``
+* ``svn diff --diff-cmd=diff -x -U999999``
+
+To upload a new patch:
+
+* Click *Differential*.
+* Click *Create Revision*.
+* Paste the text diff or upload the patch file.
+  Note that TODO
+* Leave the drop down on *Create a new Revision...* and click *Continue*.
+* Enter a descriptive title and summary; add reviewers and mailing
+  lists that you want to be included in the review. If your patch is
+  for LLVM, cc llvm-commits; if your patch is for Clang, cc cfe-commits.
+* Click *Save*.
+
+To submit an updated patch:
+
+* Click *Differential*.
+* Click *Create Revision*.
+* Paste the updated diff.
+* Select the review you want to from the *Attach To* dropdown and click
+  *Continue*.
+* Click *Save*.
+
+Reviewing code with Phabricator
+-------------------------------
+
+Phabricator allows you to add inline comments as well as overall comments
+to a revision. To add an inline comment, select the lines of code you want
+to comment on by clicking and dragging the line numbers in the diff pane.
+
+You can add overall comments or submit your comments at the bottom of the page.
+
+Phabricator has many useful features, for example allowing you to select
+diffs between different versions of the patch as it was reviewed in the
+*Revision Update History*. Most features are self descriptive - explore, and
+if you have a question, drop by on #llvm in IRC to get help.
+
+Status
+------
+
+Currently, we're testing Phabricator for use with Clang/LLVM. Please let us
+know whether you like it and what could be improved!
+
+.. _LLVM's Phabricator: http://llvm-reviews.chandlerc.com
+.. _Code Repository Browser: http://llvm-reviews.chandlerc.com/diffusion/
+.. _Arcanist Quick Start: http://www.phabricator.com/docs/phabricator/article/Arcanist_Quick_Start.html
+.. _Arcanist User Guide: http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide.html

Added: www-releases/trunk/3.2/docs/ProgrammersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/ProgrammersManual.html?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/ProgrammersManual.html (added)
+++ www-releases/trunk/3.2/docs/ProgrammersManual.html Fri Dec 21 00:57:24 2012
@@ -0,0 +1,4156 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+                      "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+  <meta http-equiv="Content-type" content="text/html;charset=UTF-8">
+  <title>LLVM Programmer's Manual</title>
+  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
+</head>
+<body>
+
+<h1>
+  LLVM Programmer's Manual
+</h1>
+
+<ol>
+  <li><a href="#introduction">Introduction</a></li>
+  <li><a href="#general">General Information</a>
+    <ul>
+      <li><a href="#stl">The C++ Standard Template Library</a></li>
+<!--
+      <li>The <tt>-time-passes</tt> option</li>
+      <li>How to use the LLVM Makefile system</li>
+      <li>How to write a regression test</li>
+
+--> 
+    </ul>
+  </li>
+  <li><a href="#apis">Important and useful LLVM APIs</a>
+    <ul>
+      <li><a href="#isa">The <tt>isa<></tt>, <tt>cast<></tt>
+and <tt>dyn_cast<></tt> templates</a> </li>
+      <li><a href="#string_apis">Passing strings (the <tt>StringRef</tt>
+and <tt>Twine</tt> classes)</a>
+        <ul>
+          <li><a href="#StringRef">The <tt>StringRef</tt> class</a> </li>
+          <li><a href="#Twine">The <tt>Twine</tt> class</a> </li>
+        </ul>
+      </li>
+      <li><a href="#DEBUG">The <tt>DEBUG()</tt> macro and <tt>-debug</tt>
+option</a>
+        <ul>
+          <li><a href="#DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE</tt>
+and the <tt>-debug-only</tt> option</a> </li>
+        </ul>
+      </li>
+      <li><a href="#Statistic">The <tt>Statistic</tt> class & <tt>-stats</tt>
+option</a></li>
+<!--
+      <li>The <tt>InstVisitor</tt> template
+      <li>The general graph API
+--> 
+      <li><a href="#ViewGraph">Viewing graphs while debugging code</a></li>
+    </ul>
+  </li>
+  <li><a href="#datastructure">Picking the Right Data Structure for a Task</a>
+    <ul>
+    <li><a href="#ds_sequential">Sequential Containers (std::vector, std::list, etc)</a>
+    <ul>
+      <li><a href="#dss_arrayref">llvm/ADT/ArrayRef.h</a></li>
+      <li><a href="#dss_fixedarrays">Fixed Size Arrays</a></li>
+      <li><a href="#dss_heaparrays">Heap Allocated Arrays</a></li>
+      <li><a href="#dss_tinyptrvector">"llvm/ADT/TinyPtrVector.h"</a></li>
+      <li><a href="#dss_smallvector">"llvm/ADT/SmallVector.h"</a></li>
+      <li><a href="#dss_vector"><vector></a></li>
+      <li><a href="#dss_deque"><deque></a></li>
+      <li><a href="#dss_list"><list></a></li>
+      <li><a href="#dss_ilist">llvm/ADT/ilist.h</a></li>
+      <li><a href="#dss_packedvector">llvm/ADT/PackedVector.h</a></li>
+      <li><a href="#dss_other">Other Sequential Container Options</a></li>
+    </ul></li>
+    <li><a href="#ds_string">String-like containers</a>
+    <ul>
+      <li><a href="#dss_stringref">llvm/ADT/StringRef.h</a></li>
+      <li><a href="#dss_twine">llvm/ADT/Twine.h</a></li>
+      <li><a href="#dss_smallstring">llvm/ADT/SmallString.h</a></li>
+      <li><a href="#dss_stdstring">std::string</a></li>
+    </ul></li>
+    <li><a href="#ds_set">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a>
+    <ul>
+      <li><a href="#dss_sortedvectorset">A sorted 'vector'</a></li>
+      <li><a href="#dss_smallset">"llvm/ADT/SmallSet.h"</a></li>
+      <li><a href="#dss_smallptrset">"llvm/ADT/SmallPtrSet.h"</a></li>
+      <li><a href="#dss_denseset">"llvm/ADT/DenseSet.h"</a></li>
+      <li><a href="#dss_sparseset">"llvm/ADT/SparseSet.h"</a></li>
+      <li><a href="#dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a></li>
+      <li><a href="#dss_set"><set></a></li>
+      <li><a href="#dss_setvector">"llvm/ADT/SetVector.h"</a></li>
+      <li><a href="#dss_uniquevector">"llvm/ADT/UniqueVector.h"</a></li>
+      <li><a href="#dss_immutableset">"llvm/ADT/ImmutableSet.h"</a></li>
+      <li><a href="#dss_otherset">Other Set-Like Container Options</a></li>
+    </ul></li>
+    <li><a href="#ds_map">Map-Like Containers (std::map, DenseMap, etc)</a>
+    <ul>
+      <li><a href="#dss_sortedvectormap">A sorted 'vector'</a></li>
+      <li><a href="#dss_stringmap">"llvm/ADT/StringMap.h"</a></li>
+      <li><a href="#dss_indexedmap">"llvm/ADT/IndexedMap.h"</a></li>
+      <li><a href="#dss_densemap">"llvm/ADT/DenseMap.h"</a></li>
+      <li><a href="#dss_valuemap">"llvm/ADT/ValueMap.h"</a></li>
+      <li><a href="#dss_intervalmap">"llvm/ADT/IntervalMap.h"</a></li>
+      <li><a href="#dss_map"><map></a></li>
+      <li><a href="#dss_mapvector">"llvm/ADT/MapVector.h"</a></li>
+      <li><a href="#dss_inteqclasses">"llvm/ADT/IntEqClasses.h"</a></li>
+      <li><a href="#dss_immutablemap">"llvm/ADT/ImmutableMap.h"</a></li>
+      <li><a href="#dss_othermap">Other Map-Like Container Options</a></li>
+    </ul></li>
+    <li><a href="#ds_bit">BitVector-like containers</a>
+    <ul>
+      <li><a href="#dss_bitvector">A dense bitvector</a></li>
+      <li><a href="#dss_smallbitvector">A "small" dense bitvector</a></li>
+      <li><a href="#dss_sparsebitvector">A sparse bitvector</a></li>
+    </ul></li>
+  </ul>
+  </li>
+  <li><a href="#common">Helpful Hints for Common Operations</a>
+    <ul>
+      <li><a href="#inspection">Basic Inspection and Traversal Routines</a>
+        <ul>
+          <li><a href="#iterate_function">Iterating over the <tt>BasicBlock</tt>s
+in a <tt>Function</tt></a> </li>
+          <li><a href="#iterate_basicblock">Iterating over the <tt>Instruction</tt>s
+in a <tt>BasicBlock</tt></a> </li>
+          <li><a href="#iterate_institer">Iterating over the <tt>Instruction</tt>s
+in a <tt>Function</tt></a> </li>
+          <li><a href="#iterate_convert">Turning an iterator into a
+class pointer</a> </li>
+          <li><a href="#iterate_complex">Finding call sites: a more
+complex example</a> </li>
+          <li><a href="#calls_and_invokes">Treating calls and invokes
+the same way</a> </li>
+          <li><a href="#iterate_chains">Iterating over def-use &
+use-def chains</a> </li>
+          <li><a href="#iterate_preds">Iterating over predecessors &
+successors of blocks</a></li>
+        </ul>
+      </li>
+      <li><a href="#simplechanges">Making simple changes</a>
+        <ul>
+          <li><a href="#schanges_creating">Creating and inserting new
+		 <tt>Instruction</tt>s</a> </li>
+          <li><a href="#schanges_deleting">Deleting 		 <tt>Instruction</tt>s</a> </li>
+          <li><a href="#schanges_replacing">Replacing an 		 <tt>Instruction</tt>
+with another <tt>Value</tt></a> </li>
+          <li><a href="#schanges_deletingGV">Deleting <tt>GlobalVariable</tt>s</a> </li>  
+        </ul>
+      </li>
+      <li><a href="#create_types">How to Create Types</a></li>
+<!--
+    <li>Working with the Control Flow Graph
+    <ul>
+      <li>Accessing predecessors and successors of a <tt>BasicBlock</tt>
+      <li>
+      <li>
+    </ul>
+--> 
+    </ul>
+  </li>
+
+  <li><a href="#threading">Threads and LLVM</a>
+  <ul>
+    <li><a href="#startmultithreaded">Entering and Exiting Multithreaded Mode
+        </a></li>
+    <li><a href="#shutdown">Ending execution with <tt>llvm_shutdown()</tt></a></li>
+    <li><a href="#managedstatic">Lazy initialization with <tt>ManagedStatic</tt></a></li>
+    <li><a href="#llvmcontext">Achieving Isolation with <tt>LLVMContext</tt></a></li>
+    <li><a href="#jitthreading">Threads and the JIT</a></li>
+  </ul>
+  </li>
+
+  <li><a href="#advanced">Advanced Topics</a>
+  <ul>
+
+  <li><a href="#SymbolTable">The <tt>ValueSymbolTable</tt> class</a></li>
+  <li><a href="#UserLayout">The <tt>User</tt> and owned <tt>Use</tt> classes' memory layout</a></li>
+  </ul></li>
+
+  <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
+    <ul>
+      <li><a href="#Type">The <tt>Type</tt> class</a> </li>
+      <li><a href="#Module">The <tt>Module</tt> class</a></li>
+      <li><a href="#Value">The <tt>Value</tt> class</a>
+      <ul>
+        <li><a href="#User">The <tt>User</tt> class</a>
+        <ul>
+          <li><a href="#Instruction">The <tt>Instruction</tt> class</a></li>
+          <li><a href="#Constant">The <tt>Constant</tt> class</a>
+          <ul>
+            <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a>
+            <ul>
+              <li><a href="#Function">The <tt>Function</tt> class</a></li>
+              <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> class</a></li>
+            </ul>
+            </li>
+          </ul>
+          </li>
+        </ul>
+        </li>
+        <li><a href="#BasicBlock">The <tt>BasicBlock</tt> class</a></li>
+        <li><a href="#Argument">The <tt>Argument</tt> class</a></li>
+      </ul>
+      </li>
+    </ul>
+  </li>
+</ol>
+
+<div class="doc_author">    
+  <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a>, 
+                <a href="mailto:dhurjati at cs.uiuc.edu">Dinakar Dhurjati</a>, 
+                <a href="mailto:ggreif at gmail.com">Gabor Greif</a>, 
+                <a href="mailto:jstanley at cs.uiuc.edu">Joel Stanley</a>,
+                <a href="mailto:rspencer at x10sys.com">Reid Spencer</a> and
+                <a href="mailto:owen at apple.com">Owen Anderson</a></p>
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="introduction">Introduction </a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This document is meant to highlight some of the important classes and
+interfaces available in the LLVM source-base.  This manual is not
+intended to explain what LLVM is, how it works, and what LLVM code looks
+like.  It assumes that you know the basics of LLVM and are interested
+in writing transformations or otherwise analyzing or manipulating the
+code.</p>
+
+<p>This document should get you oriented so that you can find your
+way in the continuously growing source code that makes up the LLVM
+infrastructure. Note that this manual is not intended to serve as a
+replacement for reading the source code, so if you think there should be
+a method in one of these classes to do something, but it's not listed,
+check the source.  Links to the <a href="/doxygen/">doxygen</a> sources
+are provided to make this as easy as possible.</p>
+
+<p>The first section of this document describes general information that is
+useful to know when working in the LLVM infrastructure, and the second describes
+the Core LLVM classes.  In the future this manual will be extended with
+information describing how to use extension libraries, such as dominator
+information, CFG traversal routines, and useful utilities like the <tt><a
+href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt> template.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="general">General Information</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This section contains general information that is useful if you are working
+in the LLVM source-base, but that isn't specific to any particular API.</p>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="stl">The C++ Standard Template Library</a>
+</h3>
+
+<div>
+
+<p>LLVM makes heavy use of the C++ Standard Template Library (STL),
+perhaps much more than you are used to, or have seen before.  Because of
+this, you might want to do a little background reading in the
+techniques used and capabilities of the library.  There are many good
+pages that discuss the STL, and several books on the subject that you
+can get, so it will not be discussed in this document.</p>
+
+<p>Here are some useful links:</p>
+
+<ol>
+
+<li><a href="http://www.dinkumware.com/manuals/#Standard C++ Library">Dinkumware
+C++ Library reference</a> - an excellent reference for the STL and other parts
+of the standard C++ library.</li>
+
+<li><a href="http://www.tempest-sw.com/cpp/">C++ In a Nutshell</a> - This is an
+O'Reilly book in the making.  It has a decent Standard Library
+Reference that rivals Dinkumware's, and is unfortunately no longer free since the
+book has been published.</li>
+
+<li><a href="http://www.parashift.com/c++-faq-lite/">C++ Frequently Asked
+Questions</a></li>
+
+<li><a href="http://www.sgi.com/tech/stl/">SGI's STL Programmer's Guide</a> -
+Contains a useful <a
+href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction to the
+STL</a>.</li>
+
+<li><a href="http://www.research.att.com/%7Ebs/C++.html">Bjarne Stroustrup's C++
+Page</a></li>
+
+<li><a href="http://64.78.49.204/">
+Bruce Eckel's Thinking in C++, 2nd ed. Volume 2 Revision 4.0 (even better, get
+the book).</a></li>
+
+</ol>
+  
+<p>You are also encouraged to take a look at the <a
+href="CodingStandards.html">LLVM Coding Standards</a> guide which focuses on how
+to write maintainable code more than where to put your curly braces.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="stl">Other useful references</a>
+</h3>
+
+<div>
+
+<ol>
+<li><a href="http://www.fortran-2000.com/ArnaudRecipes/sharedlib.html">Using
+static and shared libraries across platforms</a></li>
+</ol>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="apis">Important and useful LLVM APIs</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Here we highlight some LLVM APIs that are generally useful and good to
+know about when writing transformations.</p>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="isa">The <tt>isa<></tt>, <tt>cast<></tt> and
+  <tt>dyn_cast<></tt> templates</a>
+</h3>
+
+<div>
+
+<p>The LLVM source-base makes extensive use of a custom form of RTTI.
+These templates have many similarities to the C++ <tt>dynamic_cast<></tt>
+operator, but they don't have some drawbacks (primarily stemming from
+the fact that <tt>dynamic_cast<></tt> only works on classes that
+have a v-table). Because they are used so often, you must know what they
+do and how they work. All of these templates are defined in the <a
+ href="/doxygen/Casting_8h-source.html"><tt>llvm/Support/Casting.h</tt></a>
+file (note that you very rarely have to include this file directly).</p>
+
+<dl>
+  <dt><tt>isa<></tt>: </dt>
+
+  <dd><p>The <tt>isa<></tt> operator works exactly like the Java
+  "<tt>instanceof</tt>" operator.  It returns true or false depending on whether
+  a reference or pointer points to an instance of the specified class.  This can
+  be very useful for constraint checking of various sorts (example below).</p>
+  </dd>
+
+  <dt><tt>cast<></tt>: </dt>
+
+  <dd><p>The <tt>cast<></tt> operator is a "checked cast" operation. It
+  converts a pointer or reference from a base class to a derived class, causing
+  an assertion failure if it is not really an instance of the right type.  This
+  should be used in cases where you have some information that makes you believe
+  that something is of the right type.  An example of the <tt>isa<></tt>
+  and <tt>cast<></tt> template is:</p>
+
+<div class="doc_code">
+<pre>
+static bool isLoopInvariant(const <a href="#Value">Value</a> *V, const Loop *L) {
+  if (isa<<a href="#Constant">Constant</a>>(V) || isa<<a href="#Argument">Argument</a>>(V) || isa<<a href="#GlobalValue">GlobalValue</a>>(V))
+    return true;
+
+  // <i>Otherwise, it must be an instruction...</i>
+  return !L->contains(cast<<a href="#Instruction">Instruction</a>>(V)->getParent());
+}
+</pre>
+</div>
+
+  <p>Note that you should <b>not</b> use an <tt>isa<></tt> test followed
+  by a <tt>cast<></tt>, for that use the <tt>dyn_cast<></tt>
+  operator.</p>
+
+  </dd>
+
+  <dt><tt>dyn_cast<></tt>:</dt>
+
+  <dd><p>The <tt>dyn_cast<></tt> operator is a "checking cast" operation.
+  It checks to see if the operand is of the specified type, and if so, returns a
+  pointer to it (this operator does not work with references). If the operand is
+  not of the correct type, a null pointer is returned.  Thus, this works very
+  much like the <tt>dynamic_cast<></tt> operator in C++, and should be
+  used in the same circumstances.  Typically, the <tt>dyn_cast<></tt>
+  operator is used in an <tt>if</tt> statement or some other flow control
+  statement like this:</p>
+
+<div class="doc_code">
+<pre>
+if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a href="#AllocationInst">AllocationInst</a>>(Val)) {
+  // <i>...</i>
+}
+</pre>
+</div>
+   
+  <p>This form of the <tt>if</tt> statement effectively combines together a call
+  to <tt>isa<></tt> and a call to <tt>cast<></tt> into one
+  statement, which is very convenient.</p>
+
+  <p>Note that the <tt>dyn_cast<></tt> operator, like C++'s
+  <tt>dynamic_cast<></tt> or Java's <tt>instanceof</tt> operator, can be
+  abused.  In particular, you should not use big chained <tt>if/then/else</tt>
+  blocks to check for lots of different variants of classes.  If you find
+  yourself wanting to do this, it is much cleaner and more efficient to use the
+  <tt>InstVisitor</tt> class to dispatch over the instruction type directly.</p>
+
+  </dd>
+
+  <dt><tt>cast_or_null<></tt>: </dt>
+  
+  <dd><p>The <tt>cast_or_null<></tt> operator works just like the
+  <tt>cast<></tt> operator, except that it allows for a null pointer as an
+  argument (which it then propagates).  This can sometimes be useful, allowing
+  you to combine several null checks into one.</p></dd>
+
+  <dt><tt>dyn_cast_or_null<></tt>: </dt>
+
+  <dd><p>The <tt>dyn_cast_or_null<></tt> operator works just like the
+  <tt>dyn_cast<></tt> operator, except that it allows for a null pointer
+  as an argument (which it then propagates).  This can sometimes be useful,
+  allowing you to combine several null checks into one.</p></dd>
+
+</dl>
+
+<p>These five templates can be used with any classes, whether they have a
+v-table or not. If you want to add support for these templates, see the
+document <a href="HowToSetUpLLVMStyleRTTI.html">How to set up LLVM-style
+RTTI for your class hierarchy </a>.
+</p>
+
+</div>
+
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="string_apis">Passing strings (the <tt>StringRef</tt>
+and <tt>Twine</tt> classes)</a>
+</h3>
+
+<div>
+
+<p>Although LLVM generally does not do much string manipulation, we do have
+several important APIs which take strings.  Two important examples are the
+Value class -- which has names for instructions, functions, etc. -- and the
+StringMap class which is used extensively in LLVM and Clang.</p>
+
+<p>These are generic classes, and they need to be able to accept strings which
+may have embedded null characters.  Therefore, they cannot simply take
+a <tt>const char *</tt>, and taking a <tt>const std::string&</tt> requires
+clients to perform a heap allocation which is usually unnecessary.  Instead,
+many LLVM APIs use a <tt>StringRef</tt> or a <tt>const Twine&</tt> for
+passing strings efficiently.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="StringRef">The <tt>StringRef</tt> class</a>
+</h4>
+
+<div>
+
+<p>The <tt>StringRef</tt> data type represents a reference to a constant string
+(a character array and a length) and supports the common operations available
+on <tt>std:string</tt>, but does not require heap allocation.</p>
+
+<p>It can be implicitly constructed using a C style null-terminated string,
+an <tt>std::string</tt>, or explicitly with a character pointer and length.
+For example, the <tt>StringRef</tt> find function is declared as:</p>
+
+<pre class="doc_code">
+  iterator find(StringRef Key);
+</pre>
+
+<p>and clients can call it using any one of:</p>
+
+<pre class="doc_code">
+  Map.find("foo");                 <i>// Lookup "foo"</i>
+  Map.find(std::string("bar"));    <i>// Lookup "bar"</i>
+  Map.find(StringRef("\0baz", 4)); <i>// Lookup "\0baz"</i>
+</pre>
+
+<p>Similarly, APIs which need to return a string may return a <tt>StringRef</tt>
+instance, which can be used directly or converted to an <tt>std::string</tt>
+using the <tt>str</tt> member function.  See 
+"<tt><a href="/doxygen/classllvm_1_1StringRef_8h-source.html">llvm/ADT/StringRef.h</a></tt>"
+for more information.</p>
+
+<p>You should rarely use the <tt>StringRef</tt> class directly, because it contains
+pointers to external memory it is not generally safe to store an instance of the
+class (unless you know that the external storage will not be freed). StringRef is
+small and pervasive enough in LLVM that it should always be passed by value.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="Twine">The <tt>Twine</tt> class</a>
+</h4>
+
+<div>
+
+<p>The <tt><a href="/doxygen/classllvm_1_1Twine.html">Twine</a></tt> class is an
+efficient way for APIs to accept concatenated strings.  For example, a common
+LLVM paradigm is to name one instruction based on
+the name of another instruction with a suffix, for example:</p>
+
+<div class="doc_code">
+<pre>
+    New = CmpInst::Create(<i>...</i>, SO->getName() + ".cmp");
+</pre>
+</div>
+
+<p>The <tt>Twine</tt> class is effectively a lightweight
+<a href="http://en.wikipedia.org/wiki/Rope_(computer_science)">rope</a>
+which points to temporary (stack allocated) objects.  Twines can be implicitly
+constructed as the result of the plus operator applied to strings (i.e., a C
+strings, an <tt>std::string</tt>, or a <tt>StringRef</tt>).  The twine delays
+the actual concatenation of strings until it is actually required, at which
+point it can be efficiently rendered directly into a character array.  This
+avoids unnecessary heap allocation involved in constructing the temporary
+results of string concatenation. See
+"<tt><a href="/doxygen/Twine_8h_source.html">llvm/ADT/Twine.h</a></tt>"
+and <a href="#dss_twine">here</a> for more information.</p>
+
+<p>As with a <tt>StringRef</tt>, <tt>Twine</tt> objects point to external memory
+and should almost never be stored or mentioned directly.  They are intended
+solely for use when defining a function which should be able to efficiently
+accept concatenated strings.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="DEBUG">The <tt>DEBUG()</tt> macro and <tt>-debug</tt> option</a>
+</h3>
+
+<div>
+
+<p>Often when working on your pass you will put a bunch of debugging printouts
+and other code into your pass.  After you get it working, you want to remove
+it, but you may need it again in the future (to work out new bugs that you run
+across).</p>
+
+<p> Naturally, because of this, you don't want to delete the debug printouts,
+but you don't want them to always be noisy.  A standard compromise is to comment
+them out, allowing you to enable them if you need them in the future.</p>
+
+<p>The "<tt><a href="/doxygen/Debug_8h-source.html">llvm/Support/Debug.h</a></tt>"
+file provides a macro named <tt>DEBUG()</tt> that is a much nicer solution to
+this problem.  Basically, you can put arbitrary code into the argument of the
+<tt>DEBUG</tt> macro, and it is only executed if '<tt>opt</tt>' (or any other
+tool) is run with the '<tt>-debug</tt>' command line argument:</p>
+
+<div class="doc_code">
+<pre>
+DEBUG(errs() << "I am here!\n");
+</pre>
+</div>
+
+<p>Then you can run your pass like this:</p>
+
+<div class="doc_code">
+<pre>
+$ opt < a.bc > /dev/null -mypass
+<i><no output></i>
+$ opt < a.bc > /dev/null -mypass -debug
+I am here!
+</pre>
+</div>
+
+<p>Using the <tt>DEBUG()</tt> macro instead of a home-brewed solution allows you
+to not have to create "yet another" command line option for the debug output for
+your pass.  Note that <tt>DEBUG()</tt> macros are disabled for optimized builds,
+so they do not cause a performance impact at all (for the same reason, they
+should also not contain side-effects!).</p>
+
+<p>One additional nice thing about the <tt>DEBUG()</tt> macro is that you can
+enable or disable it directly in gdb.  Just use "<tt>set DebugFlag=0</tt>" or
+"<tt>set DebugFlag=1</tt>" from the gdb if the program is running.  If the
+program hasn't been started yet, you can always just run it with
+<tt>-debug</tt>.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE</tt> and
+  the <tt>-debug-only</tt> option</a>
+</h4>
+
+<div>
+
+<p>Sometimes you may find yourself in a situation where enabling <tt>-debug</tt>
+just turns on <b>too much</b> information (such as when working on the code
+generator).  If you want to enable debug information with more fine-grained
+control, you define the <tt>DEBUG_TYPE</tt> macro and the <tt>-debug</tt> only
+option as follows:</p>
+
+<div class="doc_code">
+<pre>
+#undef  DEBUG_TYPE
+DEBUG(errs() << "No debug type\n");
+#define DEBUG_TYPE "foo"
+DEBUG(errs() << "'foo' debug type\n");
+#undef  DEBUG_TYPE
+#define DEBUG_TYPE "bar"
+DEBUG(errs() << "'bar' debug type\n"));
+#undef  DEBUG_TYPE
+#define DEBUG_TYPE ""
+DEBUG(errs() << "No debug type (2)\n");
+</pre>
+</div>
+
+<p>Then you can run your pass like this:</p>
+
+<div class="doc_code">
+<pre>
+$ opt < a.bc > /dev/null -mypass
+<i><no output></i>
+$ opt < a.bc > /dev/null -mypass -debug
+No debug type
+'foo' debug type
+'bar' debug type
+No debug type (2)
+$ opt < a.bc > /dev/null -mypass -debug-only=foo
+'foo' debug type
+$ opt < a.bc > /dev/null -mypass -debug-only=bar
+'bar' debug type
+</pre>
+</div>
+
+<p>Of course, in practice, you should only set <tt>DEBUG_TYPE</tt> at the top of
+a file, to specify the debug type for the entire module (if you do this before
+you <tt>#include "llvm/Support/Debug.h"</tt>, you don't have to insert the ugly
+<tt>#undef</tt>'s).  Also, you should use names more meaningful than "foo" and
+"bar", because there is no system in place to ensure that names do not
+conflict. If two different modules use the same string, they will all be turned
+on when the name is specified. This allows, for example, all debug information
+for instruction scheduling to be enabled with <tt>-debug-type=InstrSched</tt>,
+even if the source lives in multiple files.</p>
+
+<p>The <tt>DEBUG_WITH_TYPE</tt> macro is also available for situations where you
+would like to set <tt>DEBUG_TYPE</tt>, but only for one specific <tt>DEBUG</tt>
+statement. It takes an additional first parameter, which is the type to use. For
+example, the preceding example could be written as:</p>
+
+
+<div class="doc_code">
+<pre>
+DEBUG_WITH_TYPE("", errs() << "No debug type\n");
+DEBUG_WITH_TYPE("foo", errs() << "'foo' debug type\n");
+DEBUG_WITH_TYPE("bar", errs() << "'bar' debug type\n"));
+DEBUG_WITH_TYPE("", errs() << "No debug type (2)\n");
+</pre>
+</div>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="Statistic">The <tt>Statistic</tt> class & <tt>-stats</tt>
+  option</a>
+</h3>
+
+<div>
+
+<p>The "<tt><a
+href="/doxygen/Statistic_8h-source.html">llvm/ADT/Statistic.h</a></tt>" file
+provides a class named <tt>Statistic</tt> that is used as a unified way to
+keep track of what the LLVM compiler is doing and how effective various
+optimizations are.  It is useful to see what optimizations are contributing to
+making a particular program run faster.</p>
+
+<p>Often you may run your pass on some big program, and you're interested to see
+how many times it makes a certain transformation.  Although you can do this with
+hand inspection, or some ad-hoc method, this is a real pain and not very useful
+for big programs.  Using the <tt>Statistic</tt> class makes it very easy to
+keep track of this information, and the calculated information is presented in a
+uniform manner with the rest of the passes being executed.</p>
+
+<p>There are many examples of <tt>Statistic</tt> uses, but the basics of using
+it are as follows:</p>
+
+<ol>
+    <li><p>Define your statistic like this:</p>
+
+<div class="doc_code">
+<pre>
+#define <a href="#DEBUG_TYPE">DEBUG_TYPE</a> "mypassname"   <i>// This goes before any #includes.</i>
+STATISTIC(NumXForms, "The # of times I did stuff");
+</pre>
+</div>
+
+  <p>The <tt>STATISTIC</tt> macro defines a static variable, whose name is
+    specified by the first argument.  The pass name is taken from the DEBUG_TYPE
+    macro, and the description is taken from the second argument.  The variable
+    defined ("NumXForms" in this case) acts like an unsigned integer.</p></li>
+
+    <li><p>Whenever you make a transformation, bump the counter:</p>
+
+<div class="doc_code">
+<pre>
+++NumXForms;   // <i>I did stuff!</i>
+</pre>
+</div>
+
+    </li>
+  </ol>
+
+  <p>That's all you have to do.  To get '<tt>opt</tt>' to print out the
+  statistics gathered, use the '<tt>-stats</tt>' option:</p>
+
+<div class="doc_code">
+<pre>
+$ opt -stats -mypassname < program.bc > /dev/null
+<i>... statistics output ...</i>
+</pre>
+</div>
+
+  <p> When running <tt>opt</tt> on a C file from the SPEC benchmark
+suite, it gives a report that looks like this:</p>
+
+<div class="doc_code">
+<pre>
+   7646 bitcodewriter   - Number of normal instructions
+    725 bitcodewriter   - Number of oversized instructions
+ 129996 bitcodewriter   - Number of bitcode bytes written
+   2817 raise           - Number of insts DCEd or constprop'd
+   3213 raise           - Number of cast-of-self removed
+   5046 raise           - Number of expression trees converted
+     75 raise           - Number of other getelementptr's formed
+    138 raise           - Number of load/store peepholes
+     42 deadtypeelim    - Number of unused typenames removed from symtab
+    392 funcresolve     - Number of varargs functions resolved
+     27 globaldce       - Number of global variables removed
+      2 adce            - Number of basic blocks removed
+    134 cee             - Number of branches revectored
+     49 cee             - Number of setcc instruction eliminated
+    532 gcse            - Number of loads removed
+   2919 gcse            - Number of instructions removed
+     86 indvars         - Number of canonical indvars added
+     87 indvars         - Number of aux indvars removed
+     25 instcombine     - Number of dead inst eliminate
+    434 instcombine     - Number of insts combined
+    248 licm            - Number of load insts hoisted
+   1298 licm            - Number of insts hoisted to a loop pre-header
+      3 licm            - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)
+     75 mem2reg         - Number of alloca's promoted
+   1444 cfgsimplify     - Number of blocks simplified
+</pre>
+</div>
+
+<p>Obviously, with so many optimizations, having a unified framework for this
+stuff is very nice.  Making your pass fit well into the framework makes it more
+maintainable and useful.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="ViewGraph">Viewing graphs while debugging code</a>
+</h3>
+
+<div>
+
+<p>Several of the important data structures in LLVM are graphs: for example
+CFGs made out of LLVM <a href="#BasicBlock">BasicBlock</a>s, CFGs made out of
+LLVM <a href="CodeGenerator.html#machinebasicblock">MachineBasicBlock</a>s, and
+<a href="CodeGenerator.html#selectiondag_intro">Instruction Selection
+DAGs</a>.  In many cases, while debugging various parts of the compiler, it is
+nice to instantly visualize these graphs.</p>
+
+<p>LLVM provides several callbacks that are available in a debug build to do
+exactly that.  If you call the <tt>Function::viewCFG()</tt> method, for example,
+the current LLVM tool will pop up a window containing the CFG for the function
+where each basic block is a node in the graph, and each node contains the
+instructions in the block.  Similarly, there also exists 
+<tt>Function::viewCFGOnly()</tt> (does not include the instructions), the
+<tt>MachineFunction::viewCFG()</tt> and <tt>MachineFunction::viewCFGOnly()</tt>,
+and the <tt>SelectionDAG::viewGraph()</tt> methods.  Within GDB, for example,
+you can usually use something like <tt>call DAG.viewGraph()</tt> to pop
+up a window.  Alternatively, you can sprinkle calls to these functions in your
+code in places you want to debug.</p>
+
+<p>Getting this to work requires a small amount of configuration.  On Unix
+systems with X11, install the <a href="http://www.graphviz.org">graphviz</a>
+toolkit, and make sure 'dot' and 'gv' are in your path.  If you are running on
+Mac OS/X, download and install the Mac OS/X <a 
+href="http://www.pixelglow.com/graphviz/">Graphviz program</a>, and add
+<tt>/Applications/Graphviz.app/Contents/MacOS/</tt> (or wherever you install
+it) to your path.  Once in your system and path are set up, rerun the LLVM
+configure script and rebuild LLVM to enable this functionality.</p>
+
+<p><tt>SelectionDAG</tt> has been extended to make it easier to locate
+<i>interesting</i> nodes in large complex graphs.  From gdb, if you
+<tt>call DAG.setGraphColor(<i>node</i>, "<i>color</i>")</tt>, then the
+next <tt>call DAG.viewGraph()</tt> would highlight the node in the
+specified color (choices of colors can be found at <a
+href="http://www.graphviz.org/doc/info/colors.html">colors</a>.) More
+complex node attributes can be provided with <tt>call
+DAG.setGraphAttrs(<i>node</i>, "<i>attributes</i>")</tt> (choices can be
+found at <a href="http://www.graphviz.org/doc/info/attrs.html">Graph
+Attributes</a>.)  If you want to restart and clear all the current graph
+attributes, then you can <tt>call DAG.clearGraphAttrs()</tt>. </p>
+
+<p>Note that graph visualization features are compiled out of Release builds
+to reduce file size.  This means that you need a Debug+Asserts or 
+Release+Asserts build to use these features.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="datastructure">Picking the Right Data Structure for a Task</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>LLVM has a plethora of data structures in the <tt>llvm/ADT/</tt> directory,
+ and we commonly use STL data structures.  This section describes the trade-offs
+ you should consider when you pick one.</p>
+
+<p>
+The first step is a choose your own adventure: do you want a sequential
+container, a set-like container, or a map-like container?  The most important
+thing when choosing a container is the algorithmic properties of how you plan to
+access the container.  Based on that, you should use:</p>
+
+<ul>
+<li>a <a href="#ds_map">map-like</a> container if you need efficient look-up
+    of an value based on another value.  Map-like containers also support
+    efficient queries for containment (whether a key is in the map).  Map-like
+    containers generally do not support efficient reverse mapping (values to
+    keys).  If you need that, use two maps.  Some map-like containers also
+    support efficient iteration through the keys in sorted order.  Map-like
+    containers are the most expensive sort, only use them if you need one of
+    these capabilities.</li>
+
+<li>a <a href="#ds_set">set-like</a> container if you need to put a bunch of
+    stuff into a container that automatically eliminates duplicates.  Some
+    set-like containers support efficient iteration through the elements in
+    sorted order.  Set-like containers are more expensive than sequential
+    containers.
+</li>
+
+<li>a <a href="#ds_sequential">sequential</a> container provides
+    the most efficient way to add elements and keeps track of the order they are
+    added to the collection.  They permit duplicates and support efficient
+    iteration, but do not support efficient look-up based on a key.
+</li>
+
+<li>a <a href="#ds_string">string</a> container is a specialized sequential
+    container or reference structure that is used for character or byte
+    arrays.</li>
+
+<li>a <a href="#ds_bit">bit</a> container provides an efficient way to store and
+    perform set operations on sets of numeric id's, while automatically
+    eliminating duplicates.  Bit containers require a maximum of 1 bit for each
+    identifier you want to store.
+</li>
+</ul>
+
+<p>
+Once the proper category of container is determined, you can fine tune the
+memory use, constant factors, and cache behaviors of access by intelligently
+picking a member of the category.  Note that constant factors and cache behavior
+can be a big deal.  If you have a vector that usually only contains a few
+elements (but could contain many), for example, it's much better to use
+<a href="#dss_smallvector">SmallVector</a> than <a href="#dss_vector">vector</a>
+.  Doing so avoids (relatively) expensive malloc/free calls, which dwarf the
+cost of adding the elements to the container. </p>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="ds_sequential">Sequential Containers (std::vector, std::list, etc)</a>
+</h3>
+
+<div>
+There are a variety of sequential containers available for you, based on your
+needs.  Pick the first in this section that will do what you want.
+  
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_arrayref">llvm/ADT/ArrayRef.h</a>
+</h4>
+
+<div>
+<p>The llvm::ArrayRef class is the preferred class to use in an interface that
+   accepts a sequential list of elements in memory and just reads from them.  By
+   taking an ArrayRef, the API can be passed a fixed size array, an std::vector,
+   an llvm::SmallVector and anything else that is contiguous in memory.
+</p>
+</div>
+
+
+  
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_fixedarrays">Fixed Size Arrays</a>
+</h4>
+
+<div>
+<p>Fixed size arrays are very simple and very fast.  They are good if you know
+exactly how many elements you have, or you have a (low) upper bound on how many
+you have.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_heaparrays">Heap Allocated Arrays</a>
+</h4>
+
+<div>
+<p>Heap allocated arrays (new[] + delete[]) are also simple.  They are good if
+the number of elements is variable, if you know how many elements you will need
+before the array is allocated, and if the array is usually large (if not,
+consider a <a href="#dss_smallvector">SmallVector</a>).  The cost of a heap
+allocated array is the cost of the new/delete (aka malloc/free).  Also note that
+if you are allocating an array of a type with a constructor, the constructor and
+destructors will be run for every element in the array (re-sizable vectors only
+construct those elements actually used).</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_tinyptrvector">"llvm/ADT/TinyPtrVector.h"</a>
+</h4>
+
+
+<div>
+<p><tt>TinyPtrVector<Type></tt> is a highly specialized collection class
+that is optimized to avoid allocation in the case when a vector has zero or one
+elements.  It has two major restrictions: 1) it can only hold values of pointer
+type, and 2) it cannot hold a null pointer.</p>
+  
+<p>Since this container is highly specialized, it is rarely used.</p>
+  
+</div>
+    
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_smallvector">"llvm/ADT/SmallVector.h"</a>
+</h4>
+
+<div>
+<p><tt>SmallVector<Type, N></tt> is a simple class that looks and smells
+just like <tt>vector<Type></tt>:
+it supports efficient iteration, lays out elements in memory order (so you can
+do pointer arithmetic between elements), supports efficient push_back/pop_back
+operations, supports efficient random access to its elements, etc.</p>
+
+<p>The advantage of SmallVector is that it allocates space for
+some number of elements (N) <b>in the object itself</b>.  Because of this, if
+the SmallVector is dynamically smaller than N, no malloc is performed.  This can
+be a big win in cases where the malloc/free call is far more expensive than the
+code that fiddles around with the elements.</p>
+
+<p>This is good for vectors that are "usually small" (e.g. the number of
+predecessors/successors of a block is usually less than 8).  On the other hand,
+this makes the size of the SmallVector itself large, so you don't want to
+allocate lots of them (doing so will waste a lot of space).  As such,
+SmallVectors are most useful when on the stack.</p>
+
+<p>SmallVector also provides a nice portable and efficient replacement for
+<tt>alloca</tt>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_vector"><vector></a>
+</h4>
+
+<div>
+<p>
+std::vector is well loved and respected.  It is useful when SmallVector isn't:
+when the size of the vector is often large (thus the small optimization will
+rarely be a benefit) or if you will be allocating many instances of the vector
+itself (which would waste space for elements that aren't in the container).
+vector is also useful when interfacing with code that expects vectors :).
+</p>
+
+<p>One worthwhile note about std::vector: avoid code like this:</p>
+
+<div class="doc_code">
+<pre>
+for ( ... ) {
+   std::vector<foo> V;
+   // make use of V.
+}
+</pre>
+</div>
+
+<p>Instead, write this as:</p>
+
+<div class="doc_code">
+<pre>
+std::vector<foo> V;
+for ( ... ) {
+   // make use of V.
+   V.clear();
+}
+</pre>
+</div>
+
+<p>Doing so will save (at least) one heap allocation and free per iteration of
+the loop.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_deque"><deque></a>
+</h4>
+
+<div>
+<p>std::deque is, in some senses, a generalized version of std::vector.  Like
+std::vector, it provides constant time random access and other similar
+properties, but it also provides efficient access to the front of the list.  It
+does not guarantee continuity of elements within memory.</p>
+
+<p>In exchange for this extra flexibility, std::deque has significantly higher
+constant factor costs than std::vector.  If possible, use std::vector or
+something cheaper.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_list"><list></a>
+</h4>
+
+<div>
+<p>std::list is an extremely inefficient class that is rarely useful.
+It performs a heap allocation for every element inserted into it, thus having an
+extremely high constant factor, particularly for small data types.  std::list
+also only supports bidirectional iteration, not random access iteration.</p>
+
+<p>In exchange for this high cost, std::list supports efficient access to both
+ends of the list (like std::deque, but unlike std::vector or SmallVector).  In
+addition, the iterator invalidation characteristics of std::list are stronger
+than that of a vector class: inserting or removing an element into the list does
+not invalidate iterator or pointers to other elements in the list.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_ilist">llvm/ADT/ilist.h</a>
+</h4>
+
+<div>
+<p><tt>ilist<T></tt> implements an 'intrusive' doubly-linked list.  It is
+intrusive, because it requires the element to store and provide access to the
+prev/next pointers for the list.</p>
+
+<p><tt>ilist</tt> has the same drawbacks as <tt>std::list</tt>, and additionally
+requires an <tt>ilist_traits</tt> implementation for the element type, but it
+provides some novel characteristics.  In particular, it can efficiently store
+polymorphic objects, the traits class is informed when an element is inserted or
+removed from the list, and <tt>ilist</tt>s are guaranteed to support a
+constant-time splice operation.</p>
+
+<p>These properties are exactly what we want for things like
+<tt>Instruction</tt>s and basic blocks, which is why these are implemented with
+<tt>ilist</tt>s.</p>
+
+Related classes of interest are explained in the following subsections:
+    <ul>
+      <li><a href="#dss_ilist_traits">ilist_traits</a></li>
+      <li><a href="#dss_iplist">iplist</a></li>
+      <li><a href="#dss_ilist_node">llvm/ADT/ilist_node.h</a></li>
+      <li><a href="#dss_ilist_sentinel">Sentinels</a></li>
+    </ul>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_packedvector">llvm/ADT/PackedVector.h</a>
+</h4>
+
+<div>
+<p>
+Useful for storing a vector of values using only a few number of bits for each
+value. Apart from the standard operations of a vector-like container, it can
+also perform an 'or' set operation. 
+</p>
+
+<p>For example:</p>
+
+<div class="doc_code">
+<pre>
+enum State {
+    None = 0x0,
+    FirstCondition = 0x1,
+    SecondCondition = 0x2,
+    Both = 0x3
+};
+
+State get() {
+    PackedVector<State, 2> Vec1;
+    Vec1.push_back(FirstCondition);
+
+    PackedVector<State, 2> Vec2;
+    Vec2.push_back(SecondCondition);
+
+    Vec1 |= Vec2;
+    return Vec1[0]; // returns 'Both'.
+}
+</pre>
+</div>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_ilist_traits">ilist_traits</a>
+</h4>
+
+<div>
+<p><tt>ilist_traits<T></tt> is <tt>ilist<T></tt>'s customization
+mechanism. <tt>iplist<T></tt> (and consequently <tt>ilist<T></tt>)
+publicly derive from this traits class.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_iplist">iplist</a>
+</h4>
+
+<div>
+<p><tt>iplist<T></tt> is <tt>ilist<T></tt>'s base and as such
+supports a slightly narrower interface. Notably, inserters from
+<tt>T&</tt> are absent.</p>
+
+<p><tt>ilist_traits<T></tt> is a public base of this class and can be
+used for a wide variety of customizations.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_ilist_node">llvm/ADT/ilist_node.h</a>
+</h4>
+
+<div>
+<p><tt>ilist_node<T></tt> implements a the forward and backward links
+that are expected by the <tt>ilist<T></tt> (and analogous containers)
+in the default manner.</p>
+
+<p><tt>ilist_node<T></tt>s are meant to be embedded in the node type
+<tt>T</tt>, usually <tt>T</tt> publicly derives from
+<tt>ilist_node<T></tt>.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_ilist_sentinel">Sentinels</a>
+</h4>
+
+<div>
+<p><tt>ilist</tt>s have another specialty that must be considered. To be a good
+citizen in the C++ ecosystem, it needs to support the standard container
+operations, such as <tt>begin</tt> and <tt>end</tt> iterators, etc. Also, the
+<tt>operator--</tt> must work correctly on the <tt>end</tt> iterator in the
+case of non-empty <tt>ilist</tt>s.</p>
+
+<p>The only sensible solution to this problem is to allocate a so-called
+<i>sentinel</i> along with the intrusive list, which serves as the <tt>end</tt>
+iterator, providing the back-link to the last element. However conforming to the
+C++ convention it is illegal to <tt>operator++</tt> beyond the sentinel and it
+also must not be dereferenced.</p>
+
+<p>These constraints allow for some implementation freedom to the <tt>ilist</tt>
+how to allocate and store the sentinel. The corresponding policy is dictated
+by <tt>ilist_traits<T></tt>. By default a <tt>T</tt> gets heap-allocated
+whenever the need for a sentinel arises.</p>
+
+<p>While the default policy is sufficient in most cases, it may break down when
+<tt>T</tt> does not provide a default constructor. Also, in the case of many
+instances of <tt>ilist</tt>s, the memory overhead of the associated sentinels
+is wasted. To alleviate the situation with numerous and voluminous
+<tt>T</tt>-sentinels, sometimes a trick is employed, leading to <i>ghostly
+sentinels</i>.</p>
+
+<p>Ghostly sentinels are obtained by specially-crafted <tt>ilist_traits<T></tt>
+which superpose the sentinel with the <tt>ilist</tt> instance in memory. Pointer
+arithmetic is used to obtain the sentinel, which is relative to the
+<tt>ilist</tt>'s <tt>this</tt> pointer. The <tt>ilist</tt> is augmented by an
+extra pointer, which serves as the back-link of the sentinel. This is the only
+field in the ghostly sentinel which can be legally accessed.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_other">Other Sequential Container options</a>
+</h4>
+
+<div>
+<p>Other STL containers are available, such as std::string.</p>
+
+<p>There are also various STL adapter classes such as std::queue,
+std::priority_queue, std::stack, etc.  These provide simplified access to an
+underlying container but don't affect the cost of the container itself.</p>
+
+</div>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="ds_string">String-like containers</a>
+</h3>
+
+<div>
+
+<p>
+There are a variety of ways to pass around and use strings in C and C++, and
+LLVM adds a few new options to choose from.  Pick the first option on this list
+that will do what you need, they are ordered according to their relative cost.
+</p>
+<p>
+Note that is is generally preferred to <em>not</em> pass strings around as 
+"<tt>const char*</tt>"'s.  These have a number of problems, including the fact
+that they cannot represent embedded nul ("\0") characters, and do not have a
+length available efficiently.  The general replacement for '<tt>const 
+char*</tt>' is StringRef.
+</p>
+  
+<p>For more information on choosing string containers for APIs, please see
+<a href="#string_apis">Passing strings</a>.</p>
+  
+  
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_stringref">llvm/ADT/StringRef.h</a>
+</h4>
+
+<div>
+<p>
+The StringRef class is a simple value class that contains a pointer to a
+character and a length, and is quite related to the <a 
+href="#dss_arrayref">ArrayRef</a> class (but specialized for arrays of
+characters).  Because StringRef carries a length with it, it safely handles
+strings with embedded nul characters in it, getting the length does not require
+a strlen call, and it even has very convenient APIs for slicing and dicing the
+character range that it represents.
+</p>
+  
+<p>
+StringRef is ideal for passing simple strings around that are known to be live,
+either because they are C string literals, std::string, a C array, or a
+SmallVector.  Each of these cases has an efficient implicit conversion to
+StringRef, which doesn't result in a dynamic strlen being executed.
+</p>
+  
+<p>StringRef has a few major limitations which make more powerful string
+containers useful:</p>
+  
+<ol>
+<li>You cannot directly convert a StringRef to a 'const char*' because there is
+no way to add a trailing nul (unlike the .c_str() method on various stronger
+classes).</li>
+
+  
+<li>StringRef doesn't own or keep alive the underlying string bytes.
+As such it can easily lead to dangling pointers, and is not suitable for
+embedding in datastructures in most cases (instead, use an std::string or
+something like that).</li>
+  
+<li>For the same reason, StringRef cannot be used as the return value of a
+method if the method "computes" the result string.  Instead, use
+std::string.</li>
+    
+<li>StringRef's do not allow you to mutate the pointed-to string bytes and it
+doesn't allow you to insert or remove bytes from the range.  For editing 
+operations like this, it interoperates with the <a 
+href="#dss_twine">Twine</a> class.</li>
+</ol>
+  
+<p>Because of its strengths and limitations, it is very common for a function to
+take a StringRef and for a method on an object to return a StringRef that
+points into some string that it owns.</p>
+  
+</div>
+  
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_twine">llvm/ADT/Twine.h</a>
+</h4>
+
+<div>
+  <p>
+  The Twine class is used as an intermediary datatype for APIs that want to take
+  a string that can be constructed inline with a series of concatenations.
+  Twine works by forming recursive instances of the Twine datatype (a simple
+  value object) on the stack as temporary objects, linking them together into a
+  tree which is then linearized when the Twine is consumed.  Twine is only safe
+  to use as the argument to a function, and should always be a const reference,
+  e.g.:
+  </p>
+  
+  <pre>
+    void foo(const Twine &T);
+    ...
+    StringRef X = ...
+    unsigned i = ...
+    foo(X + "." + Twine(i));
+  </pre>
+  
+  <p>This example forms a string like "blarg.42" by concatenating the values
+  together, and does not form intermediate strings containing "blarg" or
+  "blarg.".
+  </p>
+  
+  <p>Because Twine is constructed with temporary objects on the stack, and
+  because these instances are destroyed at the end of the current statement,
+  it is an inherently dangerous API.  For example, this simple variant contains
+  undefined behavior and will probably crash:</p>
+  
+  <pre>
+    void foo(const Twine &T);
+    ...
+    StringRef X = ...
+    unsigned i = ...
+    const Twine &Tmp = X + "." + Twine(i);
+    foo(Tmp);
+  </pre>
+
+  <p>... because the temporaries are destroyed before the call.  That said,
+  Twine's are much more efficient than intermediate std::string temporaries, and
+  they work really well with StringRef.  Just be aware of their limitations.</p>
+  
+</div>
+
+  
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_smallstring">llvm/ADT/SmallString.h</a>
+</h4>
+
+<div>
+  
+<p>SmallString is a subclass of <a href="#dss_smallvector">SmallVector</a> that
+adds some convenience APIs like += that takes StringRef's.  SmallString avoids
+allocating memory in the case when the preallocated space is enough to hold its
+data, and it calls back to general heap allocation when required.  Since it owns
+its data, it is very safe to use and supports full mutation of the string.</p>
+  
+<p>Like SmallVector's, the big downside to SmallString is their sizeof.  While
+they are optimized for small strings, they themselves are not particularly
+small.  This means that they work great for temporary scratch buffers on the
+stack, but should not generally be put into the heap: it is very rare to 
+see a SmallString as the member of a frequently-allocated heap data structure
+or returned by-value.
+</p>
+
+</div>
+  
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_stdstring">std::string</a>
+</h4>
+
+<div>
+  
+  <p>The standard C++ std::string class is a very general class that (like
+  SmallString) owns its underlying data.  sizeof(std::string) is very reasonable
+  so it can be embedded into heap data structures and returned by-value.
+  On the other hand, std::string is highly inefficient for inline editing (e.g.
+  concatenating a bunch of stuff together) and because it is provided by the
+  standard library, its performance characteristics depend a lot of the host
+  standard library (e.g. libc++ and MSVC provide a highly optimized string
+  class, GCC contains a really slow implementation).
+  </p>
+
+  <p>The major disadvantage of std::string is that almost every operation that
+  makes them larger can allocate memory, which is slow.  As such, it is better
+  to use SmallVector or Twine as a scratch buffer, but then use std::string to
+  persist the result.</p>
+
+  
+</div>
+  
+<!-- end of strings -->
+</div>
+
+  
+<!-- ======================================================================= -->
+<h3>
+  <a name="ds_set">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a>
+</h3>
+
+<div>
+
+<p>Set-like containers are useful when you need to canonicalize multiple values
+into a single representation.  There are several different choices for how to do
+this, providing various trade-offs.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_sortedvectorset">A sorted 'vector'</a>
+</h4>
+
+<div>
+
+<p>If you intend to insert a lot of elements, then do a lot of queries, a
+great approach is to use a vector (or other sequential container) with
+std::sort+std::unique to remove duplicates.  This approach works really well if
+your usage pattern has these two distinct phases (insert then query), and can be
+coupled with a good choice of <a href="#ds_sequential">sequential container</a>.
+</p>
+
+<p>
+This combination provides the several nice properties: the result data is
+contiguous in memory (good for cache locality), has few allocations, is easy to
+address (iterators in the final vector are just indices or pointers), and can be
+efficiently queried with a standard binary or radix search.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_smallset">"llvm/ADT/SmallSet.h"</a>
+</h4>
+
+<div>
+
+<p>If you have a set-like data structure that is usually small and whose elements
+are reasonably small, a <tt>SmallSet<Type, N></tt> is a good choice.  This set
+has space for N elements in place (thus, if the set is dynamically smaller than
+N, no malloc traffic is required) and accesses them with a simple linear search.
+When the set grows beyond 'N' elements, it allocates a more expensive representation that
+guarantees efficient access (for most types, it falls back to std::set, but for
+pointers it uses something far better, <a
+href="#dss_smallptrset">SmallPtrSet</a>).</p>
+
+<p>The magic of this class is that it handles small sets extremely efficiently,
+but gracefully handles extremely large sets without loss of efficiency.  The
+drawback is that the interface is quite small: it supports insertion, queries
+and erasing, but does not support iteration.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_smallptrset">"llvm/ADT/SmallPtrSet.h"</a>
+</h4>
+
+<div>
+
+<p>SmallPtrSet has all the advantages of <tt>SmallSet</tt> (and a <tt>SmallSet</tt> of pointers is 
+transparently implemented with a <tt>SmallPtrSet</tt>), but also supports iterators.  If
+more than 'N' insertions are performed, a single quadratically
+probed hash table is allocated and grows as needed, providing extremely
+efficient access (constant time insertion/deleting/queries with low constant
+factors) and is very stingy with malloc traffic.</p>
+
+<p>Note that, unlike <tt>std::set</tt>, the iterators of <tt>SmallPtrSet</tt> are invalidated
+whenever an insertion occurs.  Also, the values visited by the iterators are not
+visited in sorted order.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_denseset">"llvm/ADT/DenseSet.h"</a>
+</h4>
+
+<div>
+
+<p>
+DenseSet is a simple quadratically probed hash table.  It excels at supporting
+small values: it uses a single allocation to hold all of the pairs that
+are currently inserted in the set.  DenseSet is a great way to unique small
+values that are not simple pointers (use <a 
+href="#dss_smallptrset">SmallPtrSet</a> for pointers).  Note that DenseSet has
+the same requirements for the value type that <a 
+href="#dss_densemap">DenseMap</a> has.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_sparseset">"llvm/ADT/SparseSet.h"</a>
+</h4>
+
+<div>
+
+<p>SparseSet holds a small number of objects identified by unsigned keys of
+moderate size. It uses a lot of memory, but provides operations that are
+almost as fast as a vector. Typical keys are physical registers, virtual
+registers, or numbered basic blocks.</p>
+
+<p>SparseSet is useful for algorithms that need very fast clear/find/insert/erase
+and fast iteration over small sets.  It is not intended for building composite
+data structures.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_FoldingSet">"llvm/ADT/FoldingSet.h"</a>
+</h4>
+
+<div>
+
+<p>
+FoldingSet is an aggregate class that is really good at uniquing
+expensive-to-create or polymorphic objects.  It is a combination of a chained
+hash table with intrusive links (uniqued objects are required to inherit from
+FoldingSetNode) that uses <a href="#dss_smallvector">SmallVector</a> as part of
+its ID process.</p>
+
+<p>Consider a case where you want to implement a "getOrCreateFoo" method for
+a complex object (for example, a node in the code generator).  The client has a
+description of *what* it wants to generate (it knows the opcode and all the
+operands), but we don't want to 'new' a node, then try inserting it into a set
+only to find out it already exists, at which point we would have to delete it
+and return the node that already exists.
+</p>
+
+<p>To support this style of client, FoldingSet perform a query with a
+FoldingSetNodeID (which wraps SmallVector) that can be used to describe the
+element that we want to query for.  The query either returns the element
+matching the ID or it returns an opaque ID that indicates where insertion should
+take place.  Construction of the ID usually does not require heap traffic.</p>
+
+<p>Because FoldingSet uses intrusive links, it can support polymorphic objects
+in the set (for example, you can have SDNode instances mixed with LoadSDNodes).
+Because the elements are individually allocated, pointers to the elements are
+stable: inserting or removing elements does not invalidate any pointers to other
+elements.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_set"><set></a>
+</h4>
+
+<div>
+
+<p><tt>std::set</tt> is a reasonable all-around set class, which is decent at
+many things but great at nothing.  std::set allocates memory for each element
+inserted (thus it is very malloc intensive) and typically stores three pointers
+per element in the set (thus adding a large amount of per-element space
+overhead).  It offers guaranteed log(n) performance, which is not particularly
+fast from a complexity standpoint (particularly if the elements of the set are
+expensive to compare, like strings), and has extremely high constant factors for
+lookup, insertion and removal.</p>
+
+<p>The advantages of std::set are that its iterators are stable (deleting or
+inserting an element from the set does not affect iterators or pointers to other
+elements) and that iteration over the set is guaranteed to be in sorted order.
+If the elements in the set are large, then the relative overhead of the pointers
+and malloc traffic is not a big deal, but if the elements of the set are small,
+std::set is almost never a good choice.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_setvector">"llvm/ADT/SetVector.h"</a>
+</h4>
+
+<div>
+<p>LLVM's SetVector<Type> is an adapter class that combines your choice of
+a set-like container along with a <a href="#ds_sequential">Sequential 
+Container</a>.  The important property
+that this provides is efficient insertion with uniquing (duplicate elements are
+ignored) with iteration support.  It implements this by inserting elements into
+both a set-like container and the sequential container, using the set-like
+container for uniquing and the sequential container for iteration.
+</p>
+
+<p>The difference between SetVector and other sets is that the order of
+iteration is guaranteed to match the order of insertion into the SetVector.
+This property is really important for things like sets of pointers.  Because
+pointer values are non-deterministic (e.g. vary across runs of the program on
+different machines), iterating over the pointers in the set will
+not be in a well-defined order.</p>
+
+<p>
+The drawback of SetVector is that it requires twice as much space as a normal
+set and has the sum of constant factors from the set-like container and the 
+sequential container that it uses.  Use it *only* if you need to iterate over 
+the elements in a deterministic order.  SetVector is also expensive to delete
+elements out of (linear time), unless you use it's "pop_back" method, which is
+faster.
+</p>
+
+<p><tt>SetVector</tt> is an adapter class that defaults to
+   using <tt>std::vector</tt> and a size 16 <tt>SmallSet</tt> for the underlying
+   containers, so it is quite expensive. However,
+   <tt>"llvm/ADT/SetVector.h"</tt> also provides a <tt>SmallSetVector</tt>
+   class, which defaults to using a <tt>SmallVector</tt> and <tt>SmallSet</tt>
+   of a specified size. If you use this, and if your sets are dynamically
+   smaller than <tt>N</tt>, you will save a lot of heap traffic.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_uniquevector">"llvm/ADT/UniqueVector.h"</a>
+</h4>
+
+<div>
+
+<p>
+UniqueVector is similar to <a href="#dss_setvector">SetVector</a>, but it
+retains a unique ID for each element inserted into the set.  It internally
+contains a map and a vector, and it assigns a unique ID for each value inserted
+into the set.</p>
+
+<p>UniqueVector is very expensive: its cost is the sum of the cost of
+maintaining both the map and vector, it has high complexity, high constant
+factors, and produces a lot of malloc traffic.  It should be avoided.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_immutableset">"llvm/ADT/ImmutableSet.h"</a>
+</h4>
+
+<div>
+
+<p>
+ImmutableSet is an immutable (functional) set implementation based on an AVL
+tree.
+Adding or removing elements is done through a Factory object and results in the
+creation of a new ImmutableSet object.
+If an ImmutableSet already exists with the given contents, then the existing one
+is returned; equality is compared with a FoldingSetNodeID.
+The time and space complexity of add or remove operations is logarithmic in the
+size of the original set.
+
+<p>
+There is no method for returning an element of the set, you can only check for
+membership.
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_otherset">Other Set-Like Container Options</a>
+</h4>
+
+<div>
+
+<p>
+The STL provides several other options, such as std::multiset and the various 
+"hash_set" like containers (whether from C++ TR1 or from the SGI library). We
+never use hash_set and unordered_set because they are generally very expensive 
+(each insertion requires a malloc) and very non-portable.
+</p>
+
+<p>std::multiset is useful if you're not interested in elimination of
+duplicates, but has all the drawbacks of std::set.  A sorted vector (where you 
+don't delete duplicate entries) or some other approach is almost always
+better.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="ds_map">Map-Like Containers (std::map, DenseMap, etc)</a>
+</h3>
+
+<div>
+Map-like containers are useful when you want to associate data to a key.  As
+usual, there are a lot of different ways to do this. :)
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_sortedvectormap">A sorted 'vector'</a>
+</h4>
+
+<div>
+
+<p>
+If your usage pattern follows a strict insert-then-query approach, you can
+trivially use the same approach as <a href="#dss_sortedvectorset">sorted vectors
+for set-like containers</a>.  The only difference is that your query function
+(which uses std::lower_bound to get efficient log(n) lookup) should only compare
+the key, not both the key and value.  This yields the same advantages as sorted
+vectors for sets.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_stringmap">"llvm/ADT/StringMap.h"</a>
+</h4>
+
+<div>
+
+<p>
+Strings are commonly used as keys in maps, and they are difficult to support
+efficiently: they are variable length, inefficient to hash and compare when
+long, expensive to copy, etc.  StringMap is a specialized container designed to
+cope with these issues.  It supports mapping an arbitrary range of bytes to an
+arbitrary other object.</p>
+
+<p>The StringMap implementation uses a quadratically-probed hash table, where
+the buckets store a pointer to the heap allocated entries (and some other
+stuff).  The entries in the map must be heap allocated because the strings are
+variable length.  The string data (key) and the element object (value) are
+stored in the same allocation with the string data immediately after the element
+object.  This container guarantees the "<tt>(char*)(&Value+1)</tt>" points
+to the key string for a value.</p>
+
+<p>The StringMap is very fast for several reasons: quadratic probing is very
+cache efficient for lookups, the hash value of strings in buckets is not
+recomputed when looking up an element, StringMap rarely has to touch the
+memory for unrelated objects when looking up a value (even when hash collisions
+happen), hash table growth does not recompute the hash values for strings
+already in the table, and each pair in the map is store in a single allocation
+(the string data is stored in the same allocation as the Value of a pair).</p>
+
+<p>StringMap also provides query methods that take byte ranges, so it only ever
+copies a string if a value is inserted into the table.</p>
+
+<p>StringMap iteratation order, however, is not guaranteed to be deterministic,
+so any uses which require that should instead use a std::map.</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_indexedmap">"llvm/ADT/IndexedMap.h"</a>
+</h4>
+
+<div>
+<p>
+IndexedMap is a specialized container for mapping small dense integers (or
+values that can be mapped to small dense integers) to some other type.  It is
+internally implemented as a vector with a mapping function that maps the keys to
+the dense integer range.
+</p>
+
+<p>
+This is useful for cases like virtual registers in the LLVM code generator: they
+have a dense mapping that is offset by a compile-time constant (the first
+virtual register ID).</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_densemap">"llvm/ADT/DenseMap.h"</a>
+</h4>
+
+<div>
+
+<p>
+DenseMap is a simple quadratically probed hash table.  It excels at supporting
+small keys and values: it uses a single allocation to hold all of the pairs that
+are currently inserted in the map.  DenseMap is a great way to map pointers to
+pointers, or map other small types to each other.
+</p>
+
+<p>
+There are several aspects of DenseMap that you should be aware of, however.  The
+iterators in a DenseMap are invalidated whenever an insertion occurs, unlike
+map.  Also, because DenseMap allocates space for a large number of key/value
+pairs (it starts with 64 by default), it will waste a lot of space if your keys
+or values are large.  Finally, you must implement a partial specialization of
+DenseMapInfo for the key that you want, if it isn't already supported.  This
+is required to tell DenseMap about two special marker values (which can never be
+inserted into the map) that it needs internally.</p>
+
+<p>
+DenseMap's find_as() method supports lookup operations using an alternate key
+type. This is useful in cases where the normal key type is expensive to
+construct, but cheap to compare against. The DenseMapInfo is responsible for
+defining the appropriate comparison and hashing methods for each alternate
+key type used.
+</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_valuemap">"llvm/ADT/ValueMap.h"</a>
+</h4>
+
+<div>
+
+<p>
+ValueMap is a wrapper around a <a href="#dss_densemap">DenseMap</a> mapping
+Value*s (or subclasses) to another type.  When a Value is deleted or RAUW'ed,
+ValueMap will update itself so the new version of the key is mapped to the same
+value, just as if the key were a WeakVH.  You can configure exactly how this
+happens, and what else happens on these two events, by passing
+a <code>Config</code> parameter to the ValueMap template.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_intervalmap">"llvm/ADT/IntervalMap.h"</a>
+</h4>
+
+<div>
+
+<p> IntervalMap is a compact map for small keys and values. It maps key
+intervals instead of single keys, and it will automatically coalesce adjacent
+intervals. When then map only contains a few intervals, they are stored in the
+map object itself to avoid allocations.</p>
+
+<p> The IntervalMap iterators are quite big, so they should not be passed around
+as STL iterators. The heavyweight iterators allow a smaller data structure.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_map"><map></a>
+</h4>
+
+<div>
+
+<p>
+std::map has similar characteristics to <a href="#dss_set">std::set</a>: it uses
+a single allocation per pair inserted into the map, it offers log(n) lookup with
+an extremely large constant factor, imposes a space penalty of 3 pointers per
+pair in the map, etc.</p>
+
+<p>std::map is most useful when your keys or values are very large, if you need
+to iterate over the collection in sorted order, or if you need stable iterators
+into the map (i.e. they don't get invalidated if an insertion or deletion of
+another element takes place).</p>
+
+</div>
+
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_mapvector">"llvm/ADT/MapVector.h"</a>
+</h4>
+<div>
+
+<p> MapVector<KeyT,ValueT&gt provides a subset of the DenseMap interface.
+  The main difference is that the iteration order is guaranteed to be
+  the insertion order, making it an easy (but somewhat expensive) solution
+  for non-deterministic iteration over maps of pointers. </p>
+
+<p> It is implemented by mapping from key to an index in a vector of key,value
+  pairs. This provides fast lookup and iteration, but has two main drawbacks:
+  The key is stored twice and it doesn't support removing elements. </p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_inteqclasses">"llvm/ADT/IntEqClasses.h"</a>
+</h4>
+
+<div>
+
+<p>IntEqClasses provides a compact representation of equivalence classes of
+small integers. Initially, each integer in the range 0..n-1 has its own
+equivalence class. Classes can be joined by passing two class representatives to
+the join(a, b) method. Two integers are in the same class when findLeader()
+returns the same representative.</p>
+
+<p>Once all equivalence classes are formed, the map can be compressed so each
+integer 0..n-1 maps to an equivalence class number in the range 0..m-1, where m
+is the total number of equivalence classes. The map must be uncompressed before
+it can be edited again.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_immutablemap">"llvm/ADT/ImmutableMap.h"</a>
+</h4>
+
+<div>
+
+<p>
+ImmutableMap is an immutable (functional) map implementation based on an AVL
+tree.
+Adding or removing elements is done through a Factory object and results in the
+creation of a new ImmutableMap object.
+If an ImmutableMap already exists with the given key set, then the existing one
+is returned; equality is compared with a FoldingSetNodeID.
+The time and space complexity of add or remove operations is logarithmic in the
+size of the original map.
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_othermap">Other Map-Like Container Options</a>
+</h4>
+
+<div>
+
+<p>
+The STL provides several other options, such as std::multimap and the various 
+"hash_map" like containers (whether from C++ TR1 or from the SGI library). We
+never use hash_set and unordered_set because they are generally very expensive 
+(each insertion requires a malloc) and very non-portable.</p>
+
+<p>std::multimap is useful if you want to map a key to multiple values, but has
+all the drawbacks of std::map.  A sorted vector or some other approach is almost
+always better.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="ds_bit">Bit storage containers (BitVector, SparseBitVector)</a>
+</h3>
+
+<div>
+<p>Unlike the other containers, there are only two bit storage containers, and 
+choosing when to use each is relatively straightforward.</p>
+
+<p>One additional option is 
+<tt>std::vector<bool></tt>: we discourage its use for two reasons 1) the
+implementation in many common compilers (e.g. commonly available versions of 
+GCC) is extremely inefficient and 2) the C++ standards committee is likely to
+deprecate this container and/or change it significantly somehow.  In any case,
+please don't use it.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_bitvector">BitVector</a>
+</h4>
+
+<div>
+<p> The BitVector container provides a dynamic size set of bits for manipulation.
+It supports individual bit setting/testing, as well as set operations.  The set
+operations take time O(size of bitvector), but operations are performed one word
+at a time, instead of one bit at a time.  This makes the BitVector very fast for
+set operations compared to other containers.  Use the BitVector when you expect
+the number of set bits to be high (IE a dense set).
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_smallbitvector">SmallBitVector</a>
+</h4>
+
+<div>
+<p> The SmallBitVector container provides the same interface as BitVector, but
+it is optimized for the case where only a small number of bits, less than
+25 or so, are needed. It also transparently supports larger bit counts, but
+slightly less efficiently than a plain BitVector, so SmallBitVector should
+only be used when larger counts are rare.
+</p>
+
+<p>
+At this time, SmallBitVector does not support set operations (and, or, xor),
+and its operator[] does not provide an assignable lvalue.
+</p>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="dss_sparsebitvector">SparseBitVector</a>
+</h4>
+
+<div>
+<p> The SparseBitVector container is much like BitVector, with one major
+difference: Only the bits that are set, are stored.  This makes the
+SparseBitVector much more space efficient than BitVector when the set is sparse,
+as well as making set operations O(number of set bits) instead of O(size of
+universe).  The downside to the SparseBitVector is that setting and testing of random bits is O(N), and on large SparseBitVectors, this can be slower than BitVector. In our implementation, setting or testing bits in sorted order
+(either forwards or reverse) is O(1) worst case.  Testing and setting bits within 128 bits (depends on size) of the current bit is also O(1).  As a general statement, testing/setting bits in a SparseBitVector is O(distance away from last set bit).
+</p>
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="common">Helpful Hints for Common Operations</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>This section describes how to perform some very simple transformations of
+LLVM code.  This is meant to give examples of common idioms used, showing the
+practical side of LLVM transformations.  <p> Because this is a "how-to" section,
+you should also read about the main classes that you will be working with.  The
+<a href="#coreclasses">Core LLVM Class Hierarchy Reference</a> contains details
+and descriptions of the main classes that you should know about.</p>
+
+<!-- NOTE: this section should be heavy on example code -->
+<!-- ======================================================================= -->
+<h3>
+  <a name="inspection">Basic Inspection and Traversal Routines</a>
+</h3>
+
+<div>
+
+<p>The LLVM compiler infrastructure have many different data structures that may
+be traversed.  Following the example of the C++ standard template library, the
+techniques used to traverse these various data structures are all basically the
+same.  For a enumerable sequence of values, the <tt>XXXbegin()</tt> function (or
+method) returns an iterator to the start of the sequence, the <tt>XXXend()</tt>
+function returns an iterator pointing to one past the last valid element of the
+sequence, and there is some <tt>XXXiterator</tt> data type that is common
+between the two operations.</p>
+
+<p>Because the pattern for iteration is common across many different aspects of
+the program representation, the standard template library algorithms may be used
+on them, and it is easier to remember how to iterate. First we show a few common
+examples of the data structures that need to be traversed.  Other data
+structures are traversed in very similar ways.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="iterate_function">Iterating over the </a><a
+  href="#BasicBlock"><tt>BasicBlock</tt></a>s in a <a
+  href="#Function"><tt>Function</tt></a>
+</h4>
+
+<div>
+
+<p>It's quite common to have a <tt>Function</tt> instance that you'd like to
+transform in some way; in particular, you'd like to manipulate its
+<tt>BasicBlock</tt>s.  To facilitate this, you'll need to iterate over all of
+the <tt>BasicBlock</tt>s that constitute the <tt>Function</tt>. The following is
+an example that prints the name of a <tt>BasicBlock</tt> and the number of
+<tt>Instruction</tt>s it contains:</p>
+
+<div class="doc_code">
+<pre>
+// <i>func is a pointer to a Function instance</i>
+for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i)
+  // <i>Print out the name of the basic block if it has one, and then the</i>
+  // <i>number of instructions that it contains</i>
+  errs() << "Basic block (name=" << i->getName() << ") has "
+             << i->size() << " instructions.\n";
+</pre>
+</div>
+
+<p>Note that i can be used as if it were a pointer for the purposes of
+invoking member functions of the <tt>Instruction</tt> class.  This is
+because the indirection operator is overloaded for the iterator
+classes.  In the above code, the expression <tt>i->size()</tt> is
+exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="iterate_basicblock">Iterating over the </a><a
+  href="#Instruction"><tt>Instruction</tt></a>s in a <a
+  href="#BasicBlock"><tt>BasicBlock</tt></a>
+</h4>
+
+<div>
+
+<p>Just like when dealing with <tt>BasicBlock</tt>s in <tt>Function</tt>s, it's
+easy to iterate over the individual instructions that make up
+<tt>BasicBlock</tt>s. Here's a code snippet that prints out each instruction in
+a <tt>BasicBlock</tt>:</p>
+
+<div class="doc_code">
+<pre>
+// <i>blk is a pointer to a BasicBlock instance</i>
+for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
+   // <i>The next statement works since operator<<(ostream&,...)</i>
+   // <i>is overloaded for Instruction&</i>
+   errs() << *i << "\n";
+</pre>
+</div>
+
+<p>However, this isn't really the best way to print out the contents of a
+<tt>BasicBlock</tt>!  Since the ostream operators are overloaded for virtually
+anything you'll care about, you could have just invoked the print routine on the
+basic block itself: <tt>errs() << *blk << "\n";</tt>.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="iterate_institer">Iterating over the </a><a
+  href="#Instruction"><tt>Instruction</tt></a>s in a <a
+  href="#Function"><tt>Function</tt></a>
+</h4>
+
+<div>
+
+<p>If you're finding that you commonly iterate over a <tt>Function</tt>'s
+<tt>BasicBlock</tt>s and then that <tt>BasicBlock</tt>'s <tt>Instruction</tt>s,
+<tt>InstIterator</tt> should be used instead. You'll need to include <a
+href="/doxygen/InstIterator_8h-source.html"><tt>llvm/Support/InstIterator.h</tt></a>,
+and then instantiate <tt>InstIterator</tt>s explicitly in your code.  Here's a
+small example that shows how to dump all instructions in a function to the standard error stream:<p>
+
+<div class="doc_code">
+<pre>
+#include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"
+
+// <i>F is a pointer to a Function instance</i>
+for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I)
+  errs() << *I << "\n";
+</pre>
+</div>
+
+<p>Easy, isn't it?  You can also use <tt>InstIterator</tt>s to fill a
+work list with its initial contents.  For example, if you wanted to
+initialize a work list to contain all instructions in a <tt>Function</tt>
+F, all you would need to do is something like:</p>
+
+<div class="doc_code">
+<pre>
+std::set<Instruction*> worklist;
+// or better yet, SmallPtrSet<Instruction*, 64> worklist;
+
+for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I)
+   worklist.insert(&*I);
+</pre>
+</div>
+
+<p>The STL set <tt>worklist</tt> would now contain all instructions in the
+<tt>Function</tt> pointed to by F.</p>
+
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="iterate_convert">Turning an iterator into a class pointer (and
+  vice-versa)</a>
+</h4>
+
+<div>
+
+<p>Sometimes, it'll be useful to grab a reference (or pointer) to a class
+instance when all you've got at hand is an iterator.  Well, extracting
+a reference or a pointer from an iterator is very straight-forward.
+Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and <tt>j</tt>
+is a <tt>BasicBlock::const_iterator</tt>:</p>
+
+<div class="doc_code">
+<pre>
+Instruction& inst = *i;   // <i>Grab reference to instruction reference</i>
+Instruction* pinst = &*i; // <i>Grab pointer to instruction reference</i>
+const Instruction& inst = *j;
+</pre>
+</div>
+
+<p>However, the iterators you'll be working with in the LLVM framework are
+special: they will automatically convert to a ptr-to-instance type whenever they
+need to.  Instead of dereferencing the iterator and then taking the address of
+the result, you can simply assign the iterator to the proper pointer type and
+you get the dereference and address-of operation as a result of the assignment
+(behind the scenes, this is a result of overloading casting mechanisms).  Thus
+the last line of the last example,</p>
+
+<div class="doc_code">
+<pre>
+Instruction *pinst = &*i;
+</pre>
+</div>
+
+<p>is semantically equivalent to</p>
+
+<div class="doc_code">
+<pre>
+Instruction *pinst = i;
+</pre>
+</div>
+
+<p>It's also possible to turn a class pointer into the corresponding iterator,
+and this is a constant time operation (very efficient).  The following code
+snippet illustrates use of the conversion constructors provided by LLVM
+iterators.  By using these, you can explicitly grab the iterator of something
+without actually obtaining it via iteration over some structure:</p>
+
+<div class="doc_code">
+<pre>
+void printNextInstruction(Instruction* inst) {
+  BasicBlock::iterator it(inst);
+  ++it; // <i>After this line, it refers to the instruction after *inst</i>
+  if (it != inst->getParent()->end()) errs() << *it << "\n";
+}
+</pre>
+</div>
+
+<p>Unfortunately, these implicit conversions come at a cost; they prevent
+these iterators from conforming to standard iterator conventions, and thus
+from being usable with standard algorithms and containers. For example, they
+prevent the following code, where <tt>B</tt> is a <tt>BasicBlock</tt>,
+from compiling:</p>
+
+<div class="doc_code">
+<pre>
+  llvm::SmallVector<llvm::Instruction *, 16>(B->begin(), B->end());
+</pre>
+</div>
+
+<p>Because of this, these implicit conversions may be removed some day,
+and <tt>operator*</tt> changed to return a pointer instead of a reference.</p>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<h4>
+  <a name="iterate_complex">Finding call sites: a slightly more complex
+  example</a>
+</h4>
+
+<div>
+
+<p>Say that you're writing a FunctionPass and would like to count all the
+locations in the entire module (that is, across every <tt>Function</tt>) where a
+certain function (i.e., some <tt>Function</tt>*) is already in scope.  As you'll
+learn later, you may want to use an <tt>InstVisitor</tt> to accomplish this in a
+much more straight-forward manner, but this example will allow us to explore how
+you'd do it if you didn't have <tt>InstVisitor</tt> around. In pseudo-code, this
+is what we want to do:</p>
+
+<div class="doc_code">
+<pre>
+initialize callCounter to zero
+for each Function f in the Module
+  for each BasicBlock b in f
+    for each Instruction i in b
+      if (i is a CallInst and calls the given function)
+        increment callCounter
+</pre>
+</div>
+
+<p>And the actual code is (remember, because we're writing a
+<tt>FunctionPass</tt>, our <tt>FunctionPass</tt>-derived class simply has to
+override the <tt>runOnFunction</tt> method):</p>
+
+<div class="doc_code">
+<pre>
+Function* targetFunc = ...;
+
+class OurFunctionPass : public FunctionPass {
+  public:
+    OurFunctionPass(): callCounter(0) { }
+
+    virtual runOnFunction(Function& F) {
+      for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
+        for (BasicBlock::iterator i = b->begin(), ie = b->end(); i != ie; ++i) {
+          if (<a href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a><<a
+ href="#CallInst">CallInst</a>>(&*i)) {
+            // <i>We know we've encountered a call instruction, so we</i>
+            // <i>need to determine if it's a call to the</i>
+            // <i>function pointed to by m_func or not.</i>
+            if (callInst->getCalledFunction() == targetFunc)
+              ++callCounter;
+          }
+        }
+      }
+    }
+
+  private:
+    unsigned callCounter;
+};
+</pre>
+</div>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<h4>
+  <a name="calls_and_invokes">Treating calls and invokes the same way</a>
+</h4>
+
+<div>
+
+<p>You may have noticed that the previous example was a bit oversimplified in
+that it did not deal with call sites generated by 'invoke' instructions. In
+this, and in other situations, you may find that you want to treat
+<tt>CallInst</tt>s and <tt>InvokeInst</tt>s the same way, even though their
+most-specific common base class is <tt>Instruction</tt>, which includes lots of
+less closely-related things. For these cases, LLVM provides a handy wrapper
+class called <a
+href="http://llvm.org/doxygen/classllvm_1_1CallSite.html"><tt>CallSite</tt></a>.
+It is essentially a wrapper around an <tt>Instruction</tt> pointer, with some
+methods that provide functionality common to <tt>CallInst</tt>s and
+<tt>InvokeInst</tt>s.</p>
+
+<p>This class has "value semantics": it should be passed by value, not by
+reference and it should not be dynamically allocated or deallocated using
+<tt>operator new</tt> or <tt>operator delete</tt>. It is efficiently copyable,
+assignable and constructable, with costs equivalents to that of a bare pointer.
+If you look at its definition, it has only a single pointer member.</p>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<h4>
+  <a name="iterate_chains">Iterating over def-use & use-def chains</a>
+</h4>
+
+<div>
+
+<p>Frequently, we might have an instance of the <a
+href="/doxygen/classllvm_1_1Value.html">Value Class</a> and we want to
+determine which <tt>User</tt>s use the <tt>Value</tt>.  The list of all
+<tt>User</tt>s of a particular <tt>Value</tt> is called a <i>def-use</i> chain.
+For example, let's say we have a <tt>Function*</tt> named <tt>F</tt> to a
+particular function <tt>foo</tt>. Finding all of the instructions that
+<i>use</i> <tt>foo</tt> is as simple as iterating over the <i>def-use</i> chain
+of <tt>F</tt>:</p>
+
+<div class="doc_code">
+<pre>
+Function *F = ...;
+
+for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i)
+  if (Instruction *Inst = dyn_cast<Instruction>(*i)) {
+    errs() << "F is used in instruction:\n";
+    errs() << *Inst << "\n";
+  }
+</pre>
+</div>
+
+<p>Note that dereferencing a <tt>Value::use_iterator</tt> is not a very cheap
+operation. Instead of performing <tt>*i</tt> above several times, consider
+doing it only once in the loop body and reusing its result.</p>
+
+<p>Alternatively, it's common to have an instance of the <a
+href="/doxygen/classllvm_1_1User.html">User Class</a> and need to know what
+<tt>Value</tt>s are used by it.  The list of all <tt>Value</tt>s used by a
+<tt>User</tt> is known as a <i>use-def</i> chain.  Instances of class
+<tt>Instruction</tt> are common <tt>User</tt>s, so we might want to iterate over
+all of the values that a particular instruction uses (that is, the operands of
+the particular <tt>Instruction</tt>):</p>
+
+<div class="doc_code">
+<pre>
+Instruction *pi = ...;
+
+for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
+  Value *v = *i;
+  // <i>...</i>
+}
+</pre>
+</div>
+
+<p>Declaring objects as <tt>const</tt> is an important tool of enforcing
+mutation free algorithms (such as analyses, etc.). For this purpose above
+iterators come in constant flavors as <tt>Value::const_use_iterator</tt>
+and <tt>Value::const_op_iterator</tt>.  They automatically arise when
+calling <tt>use/op_begin()</tt> on <tt>const Value*</tt>s or
+<tt>const User*</tt>s respectively.  Upon dereferencing, they return
+<tt>const Use*</tt>s. Otherwise the above patterns remain unchanged.</p>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<h4>
+  <a name="iterate_preds">Iterating over predecessors &
+successors of blocks</a>
+</h4>
+
+<div>
+
+<p>Iterating over the predecessors and successors of a block is quite easy
+with the routines defined in <tt>"llvm/Support/CFG.h"</tt>.  Just use code like
+this to iterate over all predecessors of BB:</p>
+
+<div class="doc_code">
+<pre>
+#include "llvm/Support/CFG.h"
+BasicBlock *BB = ...;
+
+for (pred_iterator PI = pred_begin(BB), E = pred_end(BB); PI != E; ++PI) {
+  BasicBlock *Pred = *PI;
+  // <i>...</i>
+}
+</pre>
+</div>
+
+<p>Similarly, to iterate over successors use
+succ_iterator/succ_begin/succ_end.</p>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="simplechanges">Making simple changes</a>
+</h3>
+
+<div>
+
+<p>There are some primitive transformation operations present in the LLVM
+infrastructure that are worth knowing about.  When performing
+transformations, it's fairly common to manipulate the contents of basic
+blocks. This section describes some of the common methods for doing so
+and gives example code.</p>
+
+<!--_______________________________________________________________________-->
+<h4>
+  <a name="schanges_creating">Creating and inserting new
+  <tt>Instruction</tt>s</a>
+</h4>
+
+<div>
+
+<p><i>Instantiating Instructions</i></p>
+
+<p>Creation of <tt>Instruction</tt>s is straight-forward: simply call the
+constructor for the kind of instruction to instantiate and provide the necessary
+parameters. For example, an <tt>AllocaInst</tt> only <i>requires</i> a
+(const-ptr-to) <tt>Type</tt>. Thus:</p> 
+
+<div class="doc_code">
+<pre>
+AllocaInst* ai = new AllocaInst(Type::Int32Ty);
+</pre>
+</div>
+
+<p>will create an <tt>AllocaInst</tt> instance that represents the allocation of
+one integer in the current stack frame, at run time. Each <tt>Instruction</tt>
+subclass is likely to have varying default parameters which change the semantics
+of the instruction, so refer to the <a
+href="/doxygen/classllvm_1_1Instruction.html">doxygen documentation for the subclass of
+Instruction</a> that you're interested in instantiating.</p>
+
+<p><i>Naming values</i></p>
+
+<p>It is very useful to name the values of instructions when you're able to, as
+this facilitates the debugging of your transformations.  If you end up looking
+at generated LLVM machine code, you definitely want to have logical names
+associated with the results of instructions!  By supplying a value for the
+<tt>Name</tt> (default) parameter of the <tt>Instruction</tt> constructor, you
+associate a logical name with the result of the instruction's execution at
+run time.  For example, say that I'm writing a transformation that dynamically
+allocates space for an integer on the stack, and that integer is going to be
+used as some kind of index by some other code.  To accomplish this, I place an
+<tt>AllocaInst</tt> at the first point in the first <tt>BasicBlock</tt> of some
+<tt>Function</tt>, and I'm intending to use it within the same
+<tt>Function</tt>. I might do:</p>
+
+<div class="doc_code">
+<pre>
+AllocaInst* pa = new AllocaInst(Type::Int32Ty, 0, "indexLoc");
+</pre>
+</div>
+
+<p>where <tt>indexLoc</tt> is now the logical name of the instruction's
+execution value, which is a pointer to an integer on the run time stack.</p>
+
+<p><i>Inserting instructions</i></p>
+
+<p>There are essentially two ways to insert an <tt>Instruction</tt>
+into an existing sequence of instructions that form a <tt>BasicBlock</tt>:</p>
+
+<ul>
+  <li>Insertion into an explicit instruction list
+
+    <p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt> within that
+    <tt>BasicBlock</tt>, and a newly-created instruction we wish to insert
+    before <tt>*pi</tt>, we do the following: </p>
+
+<div class="doc_code">
+<pre>
+BasicBlock *pb = ...;
+Instruction *pi = ...;
+Instruction *newInst = new Instruction(...);
+
+pb->getInstList().insert(pi, newInst); // <i>Inserts newInst before pi in pb</i>
+</pre>
+</div>
+
+    <p>Appending to the end of a <tt>BasicBlock</tt> is so common that
+    the <tt>Instruction</tt> class and <tt>Instruction</tt>-derived
+    classes provide constructors which take a pointer to a
+    <tt>BasicBlock</tt> to be appended to. For example code that
+    looked like: </p>
+
+<div class="doc_code">
+<pre>
+BasicBlock *pb = ...;
+Instruction *newInst = new Instruction(...);
+
+pb->getInstList().push_back(newInst); // <i>Appends newInst to pb</i>
+</pre>
+</div>
+
+    <p>becomes: </p>
+
+<div class="doc_code">
+<pre>
+BasicBlock *pb = ...;
+Instruction *newInst = new Instruction(..., pb);
+</pre>
+</div>
+
+    <p>which is much cleaner, especially if you are creating
+    long instruction streams.</p></li>
+
+  <li>Insertion into an implicit instruction list
+
+    <p><tt>Instruction</tt> instances that are already in <tt>BasicBlock</tt>s
+    are implicitly associated with an existing instruction list: the instruction
+    list of the enclosing basic block. Thus, we could have accomplished the same
+    thing as the above code without being given a <tt>BasicBlock</tt> by doing:
+    </p>
+
+<div class="doc_code">
+<pre>
+Instruction *pi = ...;
+Instruction *newInst = new Instruction(...);
+
+pi->getParent()->getInstList().insert(pi, newInst);
+</pre>
+</div>
+
+    <p>In fact, this sequence of steps occurs so frequently that the
+    <tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes provide
+    constructors which take (as a default parameter) a pointer to an
+    <tt>Instruction</tt> which the newly-created <tt>Instruction</tt> should
+    precede.  That is, <tt>Instruction</tt> constructors are capable of
+    inserting the newly-created instance into the <tt>BasicBlock</tt> of a
+    provided instruction, immediately before that instruction.  Using an
+    <tt>Instruction</tt> constructor with a <tt>insertBefore</tt> (default)
+    parameter, the above code becomes:</p>
+
+<div class="doc_code">
+<pre>
+Instruction* pi = ...;
+Instruction* newInst = new Instruction(..., pi);
+</pre>
+</div>
+
+    <p>which is much cleaner, especially if you're creating a lot of
+    instructions and adding them to <tt>BasicBlock</tt>s.</p></li>
+</ul>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<h4>
+  <a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a>
+</h4>
+
+<div>
+
+<p>Deleting an instruction from an existing sequence of instructions that form a
+<a href="#BasicBlock"><tt>BasicBlock</tt></a> is very straight-forward: just
+call the instruction's eraseFromParent() method.  For example:</p>
+
+<div class="doc_code">
+<pre>
+<a href="#Instruction">Instruction</a> *I = .. ;
+I->eraseFromParent();
+</pre>
+</div>
+
+<p>This unlinks the instruction from its containing basic block and deletes 
+it.  If you'd just like to unlink the instruction from its containing basic
+block but not delete it, you can use the <tt>removeFromParent()</tt> method.</p>
+
+</div>
+
+<!--_______________________________________________________________________-->
+<h4>
+  <a name="schanges_replacing">Replacing an <tt>Instruction</tt> with another
+  <tt>Value</tt></a>
+</h4>
+
+<div>
+
+<h5><i>Replacing individual instructions</i></h5>
+
+<p>Including "<a href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>"
+permits use of two very useful replace functions: <tt>ReplaceInstWithValue</tt>
+and <tt>ReplaceInstWithInst</tt>.</p>
+
+<h5><a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a></h5>
+
+<div>
+<ul>
+  <li><tt>ReplaceInstWithValue</tt>
+
+    <p>This function replaces all uses of a given instruction with a value,
+    and then removes the original instruction. The following example
+    illustrates the replacement of the result of a particular
+    <tt>AllocaInst</tt> that allocates memory for a single integer with a null
+    pointer to an integer.</p>
+
+<div class="doc_code">
+<pre>
+AllocaInst* instToReplace = ...;
+BasicBlock::iterator ii(instToReplace);
+
+ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
+                     Constant::getNullValue(PointerType::getUnqual(Type::Int32Ty)));
+</pre></div></li>
+
+  <li><tt>ReplaceInstWithInst</tt> 
+
+    <p>This function replaces a particular instruction with another
+    instruction, inserting the new instruction into the basic block at the
+    location where the old instruction was, and replacing any uses of the old
+    instruction with the new instruction. The following example illustrates
+    the replacement of one <tt>AllocaInst</tt> with another.</p>
+
+<div class="doc_code">
+<pre>
+AllocaInst* instToReplace = ...;
+BasicBlock::iterator ii(instToReplace);
+
+ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
+                    new AllocaInst(Type::Int32Ty, 0, "ptrToReplacedInt"));
+</pre></div></li>
+</ul>
+
+</div>
+
+<h5><i>Replacing multiple uses of <tt>User</tt>s and <tt>Value</tt>s</i></h5>
+
+<p>You can use <tt>Value::replaceAllUsesWith</tt> and
+<tt>User::replaceUsesOfWith</tt> to change more than one use at a time.  See the
+doxygen documentation for the <a href="/doxygen/classllvm_1_1Value.html">Value Class</a>
+and <a href="/doxygen/classllvm_1_1User.html">User Class</a>, respectively, for more
+information.</p>
+
+<!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out:
+include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with:
+ReplaceInstWithValue, ReplaceInstWithInst -->
+
+</div>
+
+<!--_______________________________________________________________________-->
+<h4>
+  <a name="schanges_deletingGV">Deleting <tt>GlobalVariable</tt>s</a>
+</h4>
+
+<div>
+
+<p>Deleting a global variable from a module is just as easy as deleting an 
+Instruction. First, you must have a pointer to the global variable that you wish
+ to delete.  You use this pointer to erase it from its parent, the module.
+ For example:</p>
+
+<div class="doc_code">
+<pre>
+<a href="#GlobalVariable">GlobalVariable</a> *GV = .. ;
+
+GV->eraseFromParent();
+</pre>
+</div>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="create_types">How to Create Types</a>
+</h3>
+
+<div>
+
+<p>In generating IR, you may need some complex types.  If you know these types
+statically, you can use <tt>TypeBuilder<...>::get()</tt>, defined
+in <tt>llvm/Support/TypeBuilder.h</tt>, to retrieve them.  <tt>TypeBuilder</tt>
+has two forms depending on whether you're building types for cross-compilation
+or native library use.  <tt>TypeBuilder<T, true></tt> requires
+that <tt>T</tt> be independent of the host environment, meaning that it's built
+out of types from
+the <a href="/doxygen/namespacellvm_1_1types.html"><tt>llvm::types</tt></a>
+namespace and pointers, functions, arrays, etc. built of
+those.  <tt>TypeBuilder<T, false></tt> additionally allows native C types
+whose size may depend on the host compiler.  For example,</p>
+
+<div class="doc_code">
+<pre>
+FunctionType *ft = TypeBuilder<types::i<8>(types::i<32>*), true>::get();
+</pre>
+</div>
+
+<p>is easier to read and write than the equivalent</p>
+
+<div class="doc_code">
+<pre>
+std::vector<const Type*> params;
+params.push_back(PointerType::getUnqual(Type::Int32Ty));
+FunctionType *ft = FunctionType::get(Type::Int8Ty, params, false);
+</pre>
+</div>
+
+<p>See the <a href="/doxygen/TypeBuilder_8h-source.html#l00001">class
+comment</a> for more details.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="threading">Threads and LLVM</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+<p>
+This section describes the interaction of the LLVM APIs with multithreading,
+both on the part of client applications, and in the JIT, in the hosted
+application.
+</p>
+
+<p>
+Note that LLVM's support for multithreading is still relatively young.  Up 
+through version 2.5, the execution of threaded hosted applications was
+supported, but not threaded client access to the APIs.  While this use case is
+now supported, clients <em>must</em> adhere to the guidelines specified below to
+ensure proper operation in multithreaded mode.
+</p>
+
+<p>
+Note that, on Unix-like platforms, LLVM requires the presence of GCC's atomic
+intrinsics in order to support threaded operation.  If you need a
+multhreading-capable LLVM on a platform without a suitably modern system
+compiler, consider compiling LLVM and LLVM-GCC in single-threaded mode, and 
+using the resultant compiler to build a copy of LLVM with multithreading
+support.
+</p>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="startmultithreaded">Entering and Exiting Multithreaded Mode</a>
+</h3>
+
+<div>
+
+<p>
+In order to properly protect its internal data structures while avoiding 
+excessive locking overhead in the single-threaded case, the LLVM must intialize
+certain data structures necessary to provide guards around its internals.  To do
+so, the client program must invoke <tt>llvm_start_multithreaded()</tt> before
+making any concurrent LLVM API calls.  To subsequently tear down these
+structures, use the <tt>llvm_stop_multithreaded()</tt> call.  You can also use
+the <tt>llvm_is_multithreaded()</tt> call to check the status of multithreaded
+mode.
+</p>
+
+<p>
+Note that both of these calls must be made <em>in isolation</em>.  That is to
+say that no other LLVM API calls may be executing at any time during the 
+execution of <tt>llvm_start_multithreaded()</tt> or <tt>llvm_stop_multithreaded
+</tt>.  It's is the client's responsibility to enforce this isolation.
+</p>
+
+<p>
+The return value of <tt>llvm_start_multithreaded()</tt> indicates the success or
+failure of the initialization.  Failure typically indicates that your copy of
+LLVM was built without multithreading support, typically because GCC atomic
+intrinsics were not found in your system compiler.  In this case, the LLVM API
+will not be safe for concurrent calls.  However, it <em>will</em> be safe for
+hosting threaded applications in the JIT, though <a href="#jitthreading">care
+must be taken</a> to ensure that side exits and the like do not accidentally
+result in concurrent LLVM API calls.
+</p>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="shutdown">Ending Execution with <tt>llvm_shutdown()</tt></a>
+</h3>
+
+<div>
+<p>
+When you are done using the LLVM APIs, you should call <tt>llvm_shutdown()</tt>
+to deallocate memory used for internal structures.  This will also invoke 
+<tt>llvm_stop_multithreaded()</tt> if LLVM is operating in multithreaded mode.
+As such, <tt>llvm_shutdown()</tt> requires the same isolation guarantees as
+<tt>llvm_stop_multithreaded()</tt>.
+</p>
+
+<p>
+Note that, if you use scope-based shutdown, you can use the
+<tt>llvm_shutdown_obj</tt> class, which calls <tt>llvm_shutdown()</tt> in its
+destructor.
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="managedstatic">Lazy Initialization with <tt>ManagedStatic</tt></a>
+</h3>
+
+<div>
+<p>
+<tt>ManagedStatic</tt> is a utility class in LLVM used to implement static
+initialization of static resources, such as the global type tables.  Before the
+invocation of <tt>llvm_shutdown()</tt>, it implements a simple lazy 
+initialization scheme.  Once <tt>llvm_start_multithreaded()</tt> returns,
+however, it uses double-checked locking to implement thread-safe lazy
+initialization.
+</p>
+
+<p>
+Note that, because no other threads are allowed to issue LLVM API calls before
+<tt>llvm_start_multithreaded()</tt> returns, it is possible to have 
+<tt>ManagedStatic</tt>s of <tt>llvm::sys::Mutex</tt>s.
+</p>
+
+<p>
+The <tt>llvm_acquire_global_lock()</tt> and <tt>llvm_release_global_lock</tt> 
+APIs provide access to the global lock used to implement the double-checked
+locking for lazy initialization.  These should only be used internally to LLVM,
+and only if you know what you're doing!
+</p>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="llvmcontext">Achieving Isolation with <tt>LLVMContext</tt></a>
+</h3>
+
+<div>
+<p>
+<tt>LLVMContext</tt> is an opaque class in the LLVM API which clients can use
+to operate multiple, isolated instances of LLVM concurrently within the same
+address space.  For instance, in a hypothetical compile-server, the compilation
+of an individual translation unit is conceptually independent from all the 
+others, and it would be desirable to be able to compile incoming translation 
+units concurrently on independent server threads.  Fortunately, 
+<tt>LLVMContext</tt> exists to enable just this kind of scenario!
+</p>
+
+<p>
+Conceptually, <tt>LLVMContext</tt> provides isolation.  Every LLVM entity 
+(<tt>Module</tt>s, <tt>Value</tt>s, <tt>Type</tt>s, <tt>Constant</tt>s, etc.)
+in LLVM's in-memory IR belongs to an <tt>LLVMContext</tt>.  Entities in 
+different contexts <em>cannot</em> interact with each other: <tt>Module</tt>s in
+different contexts cannot be linked together, <tt>Function</tt>s cannot be added
+to <tt>Module</tt>s in different contexts, etc.  What this means is that is is
+safe to compile on multiple threads simultaneously, as long as no two threads
+operate on entities within the same context.
+</p>
+
+<p>
+In practice, very few places in the API require the explicit specification of a
+<tt>LLVMContext</tt>, other than the <tt>Type</tt> creation/lookup APIs.
+Because every <tt>Type</tt> carries a reference to its owning context, most
+other entities can determine what context they belong to by looking at their
+own <tt>Type</tt>.  If you are adding new entities to LLVM IR, please try to
+maintain this interface design.
+</p>
+
+<p>
+For clients that do <em>not</em> require the benefits of isolation, LLVM 
+provides a convenience API <tt>getGlobalContext()</tt>.  This returns a global,
+lazily initialized <tt>LLVMContext</tt> that may be used in situations where
+isolation is not a concern.
+</p>
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="jitthreading">Threads and the JIT</a>
+</h3>
+
+<div>
+<p>
+LLVM's "eager" JIT compiler is safe to use in threaded programs.  Multiple
+threads can call <tt>ExecutionEngine::getPointerToFunction()</tt> or
+<tt>ExecutionEngine::runFunction()</tt> concurrently, and multiple threads can
+run code output by the JIT concurrently.  The user must still ensure that only
+one thread accesses IR in a given <tt>LLVMContext</tt> while another thread
+might be modifying it.  One way to do that is to always hold the JIT lock while
+accessing IR outside the JIT (the JIT <em>modifies</em> the IR by adding
+<tt>CallbackVH</tt>s).  Another way is to only
+call <tt>getPointerToFunction()</tt> from the <tt>LLVMContext</tt>'s thread.
+</p>
+
+<p>When the JIT is configured to compile lazily (using
+<tt>ExecutionEngine::DisableLazyCompilation(false)</tt>), there is currently a
+<a href="http://llvm.org/bugs/show_bug.cgi?id=5184">race condition</a> in
+updating call sites after a function is lazily-jitted.  It's still possible to
+use the lazy JIT in a threaded program if you ensure that only one thread at a
+time can call any particular lazy stub and that the JIT lock guards any IR
+access, but we suggest using only the eager JIT in threaded programs.
+</p>
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="advanced">Advanced Topics</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+<p>
+This section describes some of the advanced or obscure API's that most clients
+do not need to be aware of.  These API's tend manage the inner workings of the
+LLVM system, and only need to be accessed in unusual circumstances.
+</p>
+
+  
+<!-- ======================================================================= -->
+<h3>
+  <a name="SymbolTable">The <tt>ValueSymbolTable</tt> class</a>
+</h3>
+
+<div>
+<p>The <tt><a href="http://llvm.org/doxygen/classllvm_1_1ValueSymbolTable.html">
+ValueSymbolTable</a></tt> class provides a symbol table that the <a
+href="#Function"><tt>Function</tt></a> and <a href="#Module">
+<tt>Module</tt></a> classes use for naming value definitions. The symbol table
+can provide a name for any <a href="#Value"><tt>Value</tt></a>. 
+</p>
+
+<p>Note that the <tt>SymbolTable</tt> class should not be directly accessed 
+by most clients.  It should only be used when iteration over the symbol table 
+names themselves are required, which is very special purpose.  Note that not 
+all LLVM
+<tt><a href="#Value">Value</a></tt>s have names, and those without names (i.e. they have
+an empty name) do not exist in the symbol table.
+</p>
+
+<p>Symbol tables support iteration over the values in the symbol
+table with <tt>begin/end/iterator</tt> and supports querying to see if a
+specific name is in the symbol table (with <tt>lookup</tt>).  The
+<tt>ValueSymbolTable</tt> class exposes no public mutator methods, instead,
+simply call <tt>setName</tt> on a value, which will autoinsert it into the
+appropriate symbol table.</p>
+
+</div>
+
+
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="UserLayout">The <tt>User</tt> and owned <tt>Use</tt> classes' memory layout</a>
+</h3>
+
+<div>
+<p>The <tt><a href="http://llvm.org/doxygen/classllvm_1_1User.html">
+User</a></tt> class provides a basis for expressing the ownership of <tt>User</tt>
+towards other <tt><a href="http://llvm.org/doxygen/classllvm_1_1Value.html">
+Value</a></tt>s. The <tt><a href="http://llvm.org/doxygen/classllvm_1_1Use.html">
+Use</a></tt> helper class is employed to do the bookkeeping and to facilitate <i>O(1)</i>
+addition and removal.</p>
+
+<!-- ______________________________________________________________________ -->
+<h4>
+  <a name="Use2User">
+    Interaction and relationship between <tt>User</tt> and <tt>Use</tt> objects
+  </a>
+</h4>
+
+<div>
+<p>
+A subclass of <tt>User</tt> can choose between incorporating its <tt>Use</tt> objects
+or refer to them out-of-line by means of a pointer. A mixed variant
+(some <tt>Use</tt>s inline others hung off) is impractical and breaks the invariant
+that the <tt>Use</tt> objects belonging to the same <tt>User</tt> form a contiguous array.
+</p>
+
+<p>
+We have 2 different layouts in the <tt>User</tt> (sub)classes:
+<ul>
+<li><p>Layout a)
+The <tt>Use</tt> object(s) are inside (resp. at fixed offset) of the <tt>User</tt>
+object and there are a fixed number of them.</p>
+
+<li><p>Layout b)
+The <tt>Use</tt> object(s) are referenced by a pointer to an
+array from the <tt>User</tt> object and there may be a variable
+number of them.</p>
+</ul>
+<p>
+As of v2.4 each layout still possesses a direct pointer to the
+start of the array of <tt>Use</tt>s. Though not mandatory for layout a),
+we stick to this redundancy for the sake of simplicity.
+The <tt>User</tt> object also stores the number of <tt>Use</tt> objects it
+has. (Theoretically this information can also be calculated
+given the scheme presented below.)</p>
+<p>
+Special forms of allocation operators (<tt>operator new</tt>)
+enforce the following memory layouts:</p>
+
+<ul>
+<li><p>Layout a) is modelled by prepending the <tt>User</tt> object by the <tt>Use[]</tt> array.</p>
+
+<pre>
+...---.---.---.---.-------...
+  | P | P | P | P | User
+'''---'---'---'---'-------'''
+</pre>
+
+<li><p>Layout b) is modelled by pointing at the <tt>Use[]</tt> array.</p>
+<pre>
+.-------...
+| User
+'-------'''
+    |
+    v
+    .---.---.---.---...
+    | P | P | P | P |
+    '---'---'---'---'''
+</pre>
+</ul>
+<i>(In the above figures '<tt>P</tt>' stands for the <tt>Use**</tt> that
+    is stored in each <tt>Use</tt> object in the member <tt>Use::Prev</tt>)</i>
+
+</div>
+
+<!-- ______________________________________________________________________ -->
+<h4>
+  <a name="Waymarking">The waymarking algorithm</a>
+</h4>
+
+<div>
+<p>
+Since the <tt>Use</tt> objects are deprived of the direct (back)pointer to
+their <tt>User</tt> objects, there must be a fast and exact method to
+recover it. This is accomplished by the following scheme:</p>
+
+A bit-encoding in the 2 LSBits (least significant bits) of the <tt>Use::Prev</tt> allows to find the
+start of the <tt>User</tt> object:
+<ul>
+<li><tt>00</tt> —> binary digit 0</li>
+<li><tt>01</tt> —> binary digit 1</li>
+<li><tt>10</tt> —> stop and calculate (<tt>s</tt>)</li>
+<li><tt>11</tt> —> full stop (<tt>S</tt>)</li>
+</ul>
+<p>
+Given a <tt>Use*</tt>, all we have to do is to walk till we get
+a stop and we either have a <tt>User</tt> immediately behind or
+we have to walk to the next stop picking up digits
+and calculating the offset:</p>
+<pre>
+.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
+| 1 | s | 1 | 0 | 1 | 0 | s | 1 | 1 | 0 | s | 1 | 1 | s | 1 | S | User (or User*)
+'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'----------------
+    |+15                |+10            |+6         |+3     |+1
+    |                   |               |           |       |__>
+    |                   |               |           |__________>
+    |                   |               |______________________>
+    |                   |______________________________________>
+    |__________________________________________________________>
+</pre>
+<p>
+Only the significant number of bits need to be stored between the
+stops, so that the <i>worst case is 20 memory accesses</i> when there are
+1000 <tt>Use</tt> objects associated with a <tt>User</tt>.</p>
+
+</div>
+
+<!-- ______________________________________________________________________ -->
+<h4>
+  <a name="ReferenceImpl">Reference implementation</a>
+</h4>
+
+<div>
+<p>
+The following literate Haskell fragment demonstrates the concept:</p>
+
+<div class="doc_code">
+<pre>
+> import Test.QuickCheck
+> 
+> digits :: Int -> [Char] -> [Char]
+> digits 0 acc = '0' : acc
+> digits 1 acc = '1' : acc
+> digits n acc = digits (n `div` 2) $ digits (n `mod` 2) acc
+> 
+> dist :: Int -> [Char] -> [Char]
+> dist 0 [] = ['S']
+> dist 0 acc = acc
+> dist 1 acc = let r = dist 0 acc in 's' : digits (length r) r
+> dist n acc = dist (n - 1) $ dist 1 acc
+> 
+> takeLast n ss = reverse $ take n $ reverse ss
+> 
+> test = takeLast 40 $ dist 20 []
+> 
+</pre>
+</div>
+<p>
+Printing <test> gives: <tt>"1s100000s11010s10100s1111s1010s110s11s1S"</tt></p>
+<p>
+The reverse algorithm computes the length of the string just by examining
+a certain prefix:</p>
+
+<div class="doc_code">
+<pre>
+> pref :: [Char] -> Int
+> pref "S" = 1
+> pref ('s':'1':rest) = decode 2 1 rest
+> pref (_:rest) = 1 + pref rest
+> 
+> decode walk acc ('0':rest) = decode (walk + 1) (acc * 2) rest
+> decode walk acc ('1':rest) = decode (walk + 1) (acc * 2 + 1) rest
+> decode walk acc _ = walk + acc
+> 
+</pre>
+</div>
+<p>
+Now, as expected, printing <pref test> gives <tt>40</tt>.</p>
+<p>
+We can <i>quickCheck</i> this with following property:</p>
+
+<div class="doc_code">
+<pre>
+> testcase = dist 2000 []
+> testcaseLength = length testcase
+> 
+> identityProp n = n > 0 && n <= testcaseLength ==> length arr == pref arr
+>     where arr = takeLast n testcase
+> 
+</pre>
+</div>
+<p>
+As expected <quickCheck identityProp> gives:</p>
+
+<pre>
+*Main> quickCheck identityProp
+OK, passed 100 tests.
+</pre>
+<p>
+Let's be a bit more exhaustive:</p>
+
+<div class="doc_code">
+<pre>
+> 
+> deepCheck p = check (defaultConfig { configMaxTest = 500 }) p
+> 
+</pre>
+</div>
+<p>
+And here is the result of <deepCheck identityProp>:</p>
+
+<pre>
+*Main> deepCheck identityProp
+OK, passed 500 tests.
+</pre>
+
+</div>
+
+<!-- ______________________________________________________________________ -->
+<h4>
+  <a name="Tagging">Tagging considerations</a>
+</h4>
+
+<div>
+
+<p>
+To maintain the invariant that the 2 LSBits of each <tt>Use**</tt> in <tt>Use</tt>
+never change after being set up, setters of <tt>Use::Prev</tt> must re-tag the
+new <tt>Use**</tt> on every modification. Accordingly getters must strip the
+tag bits.</p>
+<p>
+For layout b) instead of the <tt>User</tt> we find a pointer (<tt>User*</tt> with LSBit set).
+Following this pointer brings us to the <tt>User</tt>. A portable trick ensures
+that the first bytes of <tt>User</tt> (if interpreted as a pointer) never has
+the LSBit set. (Portability is relying on the fact that all known compilers place the
+<tt>vptr</tt> in the first word of the instances.)</p>
+
+</div>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<h2>
+  <a name="coreclasses">The Core LLVM Class Hierarchy Reference </a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+<p><tt>#include "<a href="/doxygen/Type_8h-source.html">llvm/Type.h</a>"</tt>
+<br>doxygen info: <a href="/doxygen/classllvm_1_1Type.html">Type Class</a></p>
+
+<p>The Core LLVM classes are the primary means of representing the program
+being inspected or transformed.  The core LLVM classes are defined in
+header files in the <tt>include/llvm/</tt> directory, and implemented in
+the <tt>lib/VMCore</tt> directory.</p>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="Type">The <tt>Type</tt> class and Derived Types</a>
+</h3>
+
+<div>
+
+  <p><tt>Type</tt> is a superclass of all type classes. Every <tt>Value</tt> has
+  a <tt>Type</tt>. <tt>Type</tt> cannot be instantiated directly but only
+  through its subclasses. Certain primitive types (<tt>VoidType</tt>,
+  <tt>LabelType</tt>, <tt>FloatType</tt> and <tt>DoubleType</tt>) have hidden 
+  subclasses. They are hidden because they offer no useful functionality beyond
+  what the <tt>Type</tt> class offers except to distinguish themselves from 
+  other subclasses of <tt>Type</tt>.</p>
+  <p>All other types are subclasses of <tt>DerivedType</tt>.  Types can be 
+  named, but this is not a requirement. There exists exactly 
+  one instance of a given shape at any one time.  This allows type equality to
+  be performed with address equality of the Type Instance. That is, given two 
+  <tt>Type*</tt> values, the types are identical if the pointers are identical.
+  </p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="m_Type">Important Public Methods</a>
+</h4>
+
+<div>
+
+<ul>
+  <li><tt>bool isIntegerTy() const</tt>: Returns true for any integer type.</li>
+
+  <li><tt>bool isFloatingPointTy()</tt>: Return true if this is one of the five
+  floating point types.</li>
+
+  <li><tt>bool isSized()</tt>: Return true if the type has known size. Things
+  that don't have a size are abstract types, labels and void.</li>
+
+</ul>
+</div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="derivedtypes">Important Derived Types</a>
+</h4>
+<div>
+<dl>
+  <dt><tt>IntegerType</tt></dt>
+  <dd>Subclass of DerivedType that represents integer types of any bit width. 
+  Any bit width between <tt>IntegerType::MIN_INT_BITS</tt> (1) and 
+  <tt>IntegerType::MAX_INT_BITS</tt> (~8 million) can be represented.
+  <ul>
+    <li><tt>static const IntegerType* get(unsigned NumBits)</tt>: get an integer
+    type of a specific bit width.</li>
+    <li><tt>unsigned getBitWidth() const</tt>: Get the bit width of an integer
+    type.</li>
+  </ul>
+  </dd>
+  <dt><tt>SequentialType</tt></dt>
+  <dd>This is subclassed by ArrayType, PointerType and VectorType.
+    <ul>
+      <li><tt>const Type * getElementType() const</tt>: Returns the type of each
+      of the elements in the sequential type. </li>
+    </ul>
+  </dd>
+  <dt><tt>ArrayType</tt></dt>
+  <dd>This is a subclass of SequentialType and defines the interface for array 
+  types.
+    <ul>
+      <li><tt>unsigned getNumElements() const</tt>: Returns the number of 
+      elements in the array. </li>
+    </ul>
+  </dd>
+  <dt><tt>PointerType</tt></dt>
+  <dd>Subclass of SequentialType for pointer types.</dd>
+  <dt><tt>VectorType</tt></dt>
+  <dd>Subclass of SequentialType for vector types. A 
+  vector type is similar to an ArrayType but is distinguished because it is 
+  a first class type whereas ArrayType is not. Vector types are used for 
+  vector operations and are usually small vectors of of an integer or floating 
+  point type.</dd>
+  <dt><tt>StructType</tt></dt>
+  <dd>Subclass of DerivedTypes for struct types.</dd>
+  <dt><tt><a name="FunctionType">FunctionType</a></tt></dt>
+  <dd>Subclass of DerivedTypes for function types.
+    <ul>
+      <li><tt>bool isVarArg() const</tt>: Returns true if it's a vararg
+      function</li>
+      <li><tt> const Type * getReturnType() const</tt>: Returns the
+      return type of the function.</li>
+      <li><tt>const Type * getParamType (unsigned i)</tt>: Returns
+      the type of the ith parameter.</li>
+      <li><tt> const unsigned getNumParams() const</tt>: Returns the
+      number of formal parameters.</li>
+    </ul>
+  </dd>
+</dl>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="Module">The <tt>Module</tt> class</a>
+</h3>
+
+<div>
+
+<p><tt>#include "<a
+href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt><br> doxygen info:
+<a href="/doxygen/classllvm_1_1Module.html">Module Class</a></p>
+
+<p>The <tt>Module</tt> class represents the top level structure present in LLVM
+programs.  An LLVM module is effectively either a translation unit of the
+original program or a combination of several translation units merged by the
+linker.  The <tt>Module</tt> class keeps track of a list of <a
+href="#Function"><tt>Function</tt></a>s, a list of <a
+href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a
+href="#SymbolTable"><tt>SymbolTable</tt></a>.  Additionally, it contains a few
+helpful member functions that try to make common operations easy.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="m_Module">Important Public Members of the <tt>Module</tt> class</a>
+</h4>
+
+<div>
+
+<ul>
+  <li><tt>Module::Module(std::string name = "")</tt>
+
+  <p>Constructing a <a href="#Module">Module</a> is easy. You can optionally
+provide a name for it (probably based on the name of the translation unit).</p>
+  </li>
+
+  <li><tt>Module::iterator</tt> - Typedef for function list iterator<br>
+    <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br>
+
+    <tt>begin()</tt>, <tt>end()</tt>
+    <tt>size()</tt>, <tt>empty()</tt>
+
+    <p>These are forwarding methods that make it easy to access the contents of
+    a <tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a>
+    list.</p></li>
+
+  <li><tt>Module::FunctionListType &getFunctionList()</tt>
+
+    <p> Returns the list of <a href="#Function"><tt>Function</tt></a>s.  This is
+    necessary to use when you need to update the list or perform a complex
+    action that doesn't have a forwarding method.</p>
+
+    <p><!--  Global Variable --></p></li> 
+</ul>
+
+<hr>
+
+<ul>
+  <li><tt>Module::global_iterator</tt> - Typedef for global variable list iterator<br>
+
+    <tt>Module::const_global_iterator</tt> - Typedef for const_iterator.<br>
+
+    <tt>global_begin()</tt>, <tt>global_end()</tt>
+    <tt>global_size()</tt>, <tt>global_empty()</tt>
+
+    <p> These are forwarding methods that make it easy to access the contents of
+    a <tt>Module</tt> object's <a
+    href="#GlobalVariable"><tt>GlobalVariable</tt></a> list.</p></li>
+
+  <li><tt>Module::GlobalListType &getGlobalList()</tt>
+
+    <p>Returns the list of <a
+    href="#GlobalVariable"><tt>GlobalVariable</tt></a>s.  This is necessary to
+    use when you need to update the list or perform a complex action that
+    doesn't have a forwarding method.</p>
+
+    <p><!--  Symbol table stuff --> </p></li>
+</ul>
+
+<hr>
+
+<ul>
+  <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
+
+    <p>Return a reference to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
+    for this <tt>Module</tt>.</p>
+
+    <p><!--  Convenience methods --></p></li>
+</ul>
+
+<hr>
+
+<ul>
+
+  <li><tt><a href="#Function">Function</a> *getFunction(StringRef Name) const
+    </tt>
+
+    <p>Look up the specified function in the <tt>Module</tt> <a
+    href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, return
+    <tt>null</tt>.</p></li>
+
+  <li><tt><a href="#Function">Function</a> *getOrInsertFunction(const
+  std::string &Name, const <a href="#FunctionType">FunctionType</a> *T)</tt>
+
+    <p>Look up the specified function in the <tt>Module</tt> <a
+    href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, add an
+    external declaration for the function and return it.</p></li>
+
+  <li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt>
+
+    <p>If there is at least one entry in the <a
+    href="#SymbolTable"><tt>SymbolTable</tt></a> for the specified <a
+    href="#Type"><tt>Type</tt></a>, return it.  Otherwise return the empty
+    string.</p></li>
+
+  <li><tt>bool addTypeName(const std::string &Name, const <a
+  href="#Type">Type</a> *Ty)</tt>
+
+    <p>Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
+    mapping <tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for this
+    name, true is returned and the <a
+    href="#SymbolTable"><tt>SymbolTable</tt></a> is not modified.</p></li>
+</ul>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="Value">The <tt>Value</tt> class</a>
+</h3>
+
+<div>
+
+<p><tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt>
+<br> 
+doxygen info: <a href="/doxygen/classllvm_1_1Value.html">Value Class</a></p>
+
+<p>The <tt>Value</tt> class is the most important class in the LLVM Source
+base.  It represents a typed value that may be used (among other things) as an
+operand to an instruction.  There are many different types of <tt>Value</tt>s,
+such as <a href="#Constant"><tt>Constant</tt></a>s,<a
+href="#Argument"><tt>Argument</tt></a>s. Even <a
+href="#Instruction"><tt>Instruction</tt></a>s and <a
+href="#Function"><tt>Function</tt></a>s are <tt>Value</tt>s.</p>
+
+<p>A particular <tt>Value</tt> may be used many times in the LLVM representation
+for a program.  For example, an incoming argument to a function (represented
+with an instance of the <a href="#Argument">Argument</a> class) is "used" by
+every instruction in the function that references the argument.  To keep track
+of this relationship, the <tt>Value</tt> class keeps a list of all of the <a
+href="#User"><tt>User</tt></a>s that is using it (the <a
+href="#User"><tt>User</tt></a> class is a base class for all nodes in the LLVM
+graph that can refer to <tt>Value</tt>s).  This use list is how LLVM represents
+def-use information in the program, and is accessible through the <tt>use_</tt>*
+methods, shown below.</p>
+
+<p>Because LLVM is a typed representation, every LLVM <tt>Value</tt> is typed,
+and this <a href="#Type">Type</a> is available through the <tt>getType()</tt>
+method. In addition, all LLVM values can be named.  The "name" of the
+<tt>Value</tt> is a symbolic string printed in the LLVM code:</p>
+
+<div class="doc_code">
+<pre>
+%<b>foo</b> = add i32 1, 2
+</pre>
+</div>
+
+<p><a name="nameWarning">The name of this instruction is "foo".</a> <b>NOTE</b>
+that the name of any value may be missing (an empty string), so names should
+<b>ONLY</b> be used for debugging (making the source code easier to read,
+debugging printouts), they should not be used to keep track of values or map
+between them.  For this purpose, use a <tt>std::map</tt> of pointers to the
+<tt>Value</tt> itself instead.</p>
+
+<p>One important aspect of LLVM is that there is no distinction between an SSA
+variable and the operation that produces it.  Because of this, any reference to
+the value produced by an instruction (or the value available as an incoming
+argument, for example) is represented as a direct pointer to the instance of
+the class that
+represents this value.  Although this may take some getting used to, it
+simplifies the representation and makes it easier to manipulate.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="m_Value">Important Public Members of the <tt>Value</tt> class</a>
+</h4>
+
+<div>
+
+<ul>
+  <li><tt>Value::use_iterator</tt> - Typedef for iterator over the
+use-list<br>
+    <tt>Value::const_use_iterator</tt> - Typedef for const_iterator over
+the use-list<br>
+    <tt>unsigned use_size()</tt> - Returns the number of users of the
+value.<br>
+    <tt>bool use_empty()</tt> - Returns true if there are no users.<br>
+    <tt>use_iterator use_begin()</tt> - Get an iterator to the start of
+the use-list.<br>
+    <tt>use_iterator use_end()</tt> - Get an iterator to the end of the
+use-list.<br>
+    <tt><a href="#User">User</a> *use_back()</tt> - Returns the last
+element in the list.
+    <p> These methods are the interface to access the def-use
+information in LLVM.  As with all other iterators in LLVM, the naming
+conventions follow the conventions defined by the <a href="#stl">STL</a>.</p>
+  </li>
+  <li><tt><a href="#Type">Type</a> *getType() const</tt>
+    <p>This method returns the Type of the Value.</p>
+  </li>
+  <li><tt>bool hasName() const</tt><br>
+    <tt>std::string getName() const</tt><br>
+    <tt>void setName(const std::string &Name)</tt>
+    <p> This family of methods is used to access and assign a name to a <tt>Value</tt>,
+be aware of the <a href="#nameWarning">precaution above</a>.</p>
+  </li>
+  <li><tt>void replaceAllUsesWith(Value *V)</tt>
+
+    <p>This method traverses the use list of a <tt>Value</tt> changing all <a
+    href="#User"><tt>User</tt>s</a> of the current value to refer to
+    "<tt>V</tt>" instead.  For example, if you detect that an instruction always
+    produces a constant value (for example through constant folding), you can
+    replace all uses of the instruction with the constant like this:</p>
+
+<div class="doc_code">
+<pre>
+Inst->replaceAllUsesWith(ConstVal);
+</pre>
+</div>
+
+</ul>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="User">The <tt>User</tt> class</a>
+</h3>
+
+<div>
+  
+<p>
+<tt>#include "<a href="/doxygen/User_8h-source.html">llvm/User.h</a>"</tt><br>
+doxygen info: <a href="/doxygen/classllvm_1_1User.html">User Class</a><br>
+Superclass: <a href="#Value"><tt>Value</tt></a></p>
+
+<p>The <tt>User</tt> class is the common base class of all LLVM nodes that may
+refer to <a href="#Value"><tt>Value</tt></a>s.  It exposes a list of "Operands"
+that are all of the <a href="#Value"><tt>Value</tt></a>s that the User is
+referring to.  The <tt>User</tt> class itself is a subclass of
+<tt>Value</tt>.</p>
+
+<p>The operands of a <tt>User</tt> point directly to the LLVM <a
+href="#Value"><tt>Value</tt></a> that it refers to.  Because LLVM uses Static
+Single Assignment (SSA) form, there can only be one definition referred to,
+allowing this direct connection.  This connection provides the use-def
+information in LLVM.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="m_User">Important Public Members of the <tt>User</tt> class</a>
+</h4>
+
+<div>
+
+<p>The <tt>User</tt> class exposes the operand list in two ways: through
+an index access interface and through an iterator based interface.</p>
+
+<ul>
+  <li><tt>Value *getOperand(unsigned i)</tt><br>
+    <tt>unsigned getNumOperands()</tt>
+    <p> These two methods expose the operands of the <tt>User</tt> in a
+convenient form for direct access.</p></li>
+
+  <li><tt>User::op_iterator</tt> - Typedef for iterator over the operand
+list<br>
+    <tt>op_iterator op_begin()</tt> - Get an iterator to the start of 
+the operand list.<br>
+    <tt>op_iterator op_end()</tt> - Get an iterator to the end of the
+operand list.
+    <p> Together, these methods make up the iterator based interface to
+the operands of a <tt>User</tt>.</p></li>
+</ul>
+
+</div>    
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="Instruction">The <tt>Instruction</tt> class</a>
+</h3>
+
+<div>
+
+<p><tt>#include "</tt><tt><a
+href="/doxygen/Instruction_8h-source.html">llvm/Instruction.h</a>"</tt><br>
+doxygen info: <a href="/doxygen/classllvm_1_1Instruction.html">Instruction Class</a><br>
+Superclasses: <a href="#User"><tt>User</tt></a>, <a
+href="#Value"><tt>Value</tt></a></p>
+
+<p>The <tt>Instruction</tt> class is the common base class for all LLVM
+instructions.  It provides only a few methods, but is a very commonly used
+class.  The primary data tracked by the <tt>Instruction</tt> class itself is the
+opcode (instruction type) and the parent <a
+href="#BasicBlock"><tt>BasicBlock</tt></a> the <tt>Instruction</tt> is embedded
+into.  To represent a specific type of instruction, one of many subclasses of
+<tt>Instruction</tt> are used.</p>
+
+<p> Because the <tt>Instruction</tt> class subclasses the <a
+href="#User"><tt>User</tt></a> class, its operands can be accessed in the same
+way as for other <a href="#User"><tt>User</tt></a>s (with the
+<tt>getOperand()</tt>/<tt>getNumOperands()</tt> and
+<tt>op_begin()</tt>/<tt>op_end()</tt> methods).</p> <p> An important file for
+the <tt>Instruction</tt> class is the <tt>llvm/Instruction.def</tt> file. This
+file contains some meta-data about the various different types of instructions
+in LLVM.  It describes the enum values that are used as opcodes (for example
+<tt>Instruction::Add</tt> and <tt>Instruction::ICmp</tt>), as well as the
+concrete sub-classes of <tt>Instruction</tt> that implement the instruction (for
+example <tt><a href="#BinaryOperator">BinaryOperator</a></tt> and <tt><a
+href="#CmpInst">CmpInst</a></tt>).  Unfortunately, the use of macros in
+this file confuses doxygen, so these enum values don't show up correctly in the
+<a href="/doxygen/classllvm_1_1Instruction.html">doxygen output</a>.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="s_Instruction">
+    Important Subclasses of the <tt>Instruction</tt> class
+  </a>
+</h4>
+<div>
+  <ul>
+    <li><tt><a name="BinaryOperator">BinaryOperator</a></tt>
+    <p>This subclasses represents all two operand instructions whose operands
+    must be the same type, except for the comparison instructions.</p></li>
+    <li><tt><a name="CastInst">CastInst</a></tt>
+    <p>This subclass is the parent of the 12 casting instructions. It provides
+    common operations on cast instructions.</p>
+    <li><tt><a name="CmpInst">CmpInst</a></tt>
+    <p>This subclass respresents the two comparison instructions, 
+    <a href="LangRef.html#i_icmp">ICmpInst</a> (integer opreands), and
+    <a href="LangRef.html#i_fcmp">FCmpInst</a> (floating point operands).</p>
+    <li><tt><a name="TerminatorInst">TerminatorInst</a></tt>
+    <p>This subclass is the parent of all terminator instructions (those which
+    can terminate a block).</p>
+  </ul>
+  </div>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="m_Instruction">
+    Important Public Members of the <tt>Instruction</tt> class
+  </a>
+</h4>
+
+<div>
+
+<ul>
+  <li><tt><a href="#BasicBlock">BasicBlock</a> *getParent()</tt>
+    <p>Returns the <a href="#BasicBlock"><tt>BasicBlock</tt></a> that
+this  <tt>Instruction</tt> is embedded into.</p></li>
+  <li><tt>bool mayWriteToMemory()</tt>
+    <p>Returns true if the instruction writes to memory, i.e. it is a
+      <tt>call</tt>,<tt>free</tt>,<tt>invoke</tt>, or <tt>store</tt>.</p></li>
+  <li><tt>unsigned getOpcode()</tt>
+    <p>Returns the opcode for the <tt>Instruction</tt>.</p></li>
+  <li><tt><a href="#Instruction">Instruction</a> *clone() const</tt>
+    <p>Returns another instance of the specified instruction, identical
+in all ways to the original except that the instruction has no parent
+(ie it's not embedded into a <a href="#BasicBlock"><tt>BasicBlock</tt></a>),
+and it has no name</p></li>
+</ul>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="Constant">The <tt>Constant</tt> class and subclasses</a>
+</h3>
+
+<div>
+
+<p>Constant represents a base class for different types of constants. It
+is subclassed by ConstantInt, ConstantArray, etc. for representing 
+the various types of Constants.  <a href="#GlobalValue">GlobalValue</a> is also
+a subclass, which represents the address of a global variable or function.
+</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>Important Subclasses of Constant</h4>
+<div>
+<ul>
+  <li>ConstantInt : This subclass of Constant represents an integer constant of
+  any width.
+    <ul>
+      <li><tt>const APInt& getValue() const</tt>: Returns the underlying
+      value of this constant, an APInt value.</li>
+      <li><tt>int64_t getSExtValue() const</tt>: Converts the underlying APInt
+      value to an int64_t via sign extension. If the value (not the bit width)
+      of the APInt is too large to fit in an int64_t, an assertion will result.
+      For this reason, use of this method is discouraged.</li>
+      <li><tt>uint64_t getZExtValue() const</tt>: Converts the underlying APInt
+      value to a uint64_t via zero extension. IF the value (not the bit width)
+      of the APInt is too large to fit in a uint64_t, an assertion will result.
+      For this reason, use of this method is discouraged.</li>
+      <li><tt>static ConstantInt* get(const APInt& Val)</tt>: Returns the
+      ConstantInt object that represents the value provided by <tt>Val</tt>.
+      The type is implied as the IntegerType that corresponds to the bit width
+      of <tt>Val</tt>.</li>
+      <li><tt>static ConstantInt* get(const Type *Ty, uint64_t Val)</tt>: 
+      Returns the ConstantInt object that represents the value provided by 
+      <tt>Val</tt> for integer type <tt>Ty</tt>.</li>
+    </ul>
+  </li>
+  <li>ConstantFP : This class represents a floating point constant.
+    <ul>
+      <li><tt>double getValue() const</tt>: Returns the underlying value of 
+      this constant. </li>
+    </ul>
+  </li>
+  <li>ConstantArray : This represents a constant array.
+    <ul>
+      <li><tt>const std::vector<Use> &getValues() const</tt>: Returns 
+      a vector of component constants that makeup this array. </li>
+    </ul>
+  </li>
+  <li>ConstantStruct : This represents a constant struct.
+    <ul>
+      <li><tt>const std::vector<Use> &getValues() const</tt>: Returns 
+      a vector of component constants that makeup this array. </li>
+    </ul>
+  </li>
+  <li>GlobalValue : This represents either a global variable or a function. In 
+  either case, the value is a constant fixed address (after linking). 
+  </li>
+</ul>
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="GlobalValue">The <tt>GlobalValue</tt> class</a>
+</h3>
+
+<div>
+
+<p><tt>#include "<a
+href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt><br>
+doxygen info: <a href="/doxygen/classllvm_1_1GlobalValue.html">GlobalValue
+Class</a><br>
+Superclasses: <a href="#Constant"><tt>Constant</tt></a>, 
+<a href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a></p>
+
+<p>Global values (<a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s or <a
+href="#Function"><tt>Function</tt></a>s) are the only LLVM values that are
+visible in the bodies of all <a href="#Function"><tt>Function</tt></a>s.
+Because they are visible at global scope, they are also subject to linking with
+other globals defined in different translation units.  To control the linking
+process, <tt>GlobalValue</tt>s know their linkage rules. Specifically,
+<tt>GlobalValue</tt>s know whether they have internal or external linkage, as
+defined by the <tt>LinkageTypes</tt> enumeration.</p>
+
+<p>If a <tt>GlobalValue</tt> has internal linkage (equivalent to being
+<tt>static</tt> in C), it is not visible to code outside the current translation
+unit, and does not participate in linking.  If it has external linkage, it is
+visible to external code, and does participate in linking.  In addition to
+linkage information, <tt>GlobalValue</tt>s keep track of which <a
+href="#Module"><tt>Module</tt></a> they are currently part of.</p>
+
+<p>Because <tt>GlobalValue</tt>s are memory objects, they are always referred to
+by their <b>address</b>. As such, the <a href="#Type"><tt>Type</tt></a> of a
+global is always a pointer to its contents. It is important to remember this
+when using the <tt>GetElementPtrInst</tt> instruction because this pointer must
+be dereferenced first. For example, if you have a <tt>GlobalVariable</tt> (a
+subclass of <tt>GlobalValue)</tt> that is an array of 24 ints, type <tt>[24 x
+i32]</tt>, then the <tt>GlobalVariable</tt> is a pointer to that array. Although
+the address of the first element of this array and the value of the
+<tt>GlobalVariable</tt> are the same, they have different types. The
+<tt>GlobalVariable</tt>'s type is <tt>[24 x i32]</tt>. The first element's type
+is <tt>i32.</tt> Because of this, accessing a global value requires you to
+dereference the pointer with <tt>GetElementPtrInst</tt> first, then its elements
+can be accessed. This is explained in the <a href="LangRef.html#globalvars">LLVM
+Language Reference Manual</a>.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="m_GlobalValue">
+    Important Public Members of the <tt>GlobalValue</tt> class
+  </a>
+</h4>
+
+<div>
+
+<ul>
+  <li><tt>bool hasInternalLinkage() const</tt><br>
+    <tt>bool hasExternalLinkage() const</tt><br>
+    <tt>void setInternalLinkage(bool HasInternalLinkage)</tt>
+    <p> These methods manipulate the linkage characteristics of the <tt>GlobalValue</tt>.</p>
+    <p> </p>
+  </li>
+  <li><tt><a href="#Module">Module</a> *getParent()</tt>
+    <p> This returns the <a href="#Module"><tt>Module</tt></a> that the
+GlobalValue is currently embedded into.</p></li>
+</ul>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="Function">The <tt>Function</tt> class</a>
+</h3>
+
+<div>
+
+<p><tt>#include "<a
+href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt><br> doxygen
+info: <a href="/doxygen/classllvm_1_1Function.html">Function Class</a><br>
+Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, 
+<a href="#Constant"><tt>Constant</tt></a>, 
+<a href="#User"><tt>User</tt></a>, 
+<a href="#Value"><tt>Value</tt></a></p>
+
+<p>The <tt>Function</tt> class represents a single procedure in LLVM.  It is
+actually one of the more complex classes in the LLVM hierarchy because it must
+keep track of a large amount of data.  The <tt>Function</tt> class keeps track
+of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal 
+<a href="#Argument"><tt>Argument</tt></a>s, and a 
+<a href="#SymbolTable"><tt>SymbolTable</tt></a>.</p>
+
+<p>The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the most
+commonly used part of <tt>Function</tt> objects.  The list imposes an implicit
+ordering of the blocks in the function, which indicate how the code will be
+laid out by the backend.  Additionally, the first <a
+href="#BasicBlock"><tt>BasicBlock</tt></a> is the implicit entry node for the
+<tt>Function</tt>.  It is not legal in LLVM to explicitly branch to this initial
+block.  There are no implicit exit nodes, and in fact there may be multiple exit
+nodes from a single <tt>Function</tt>.  If the <a
+href="#BasicBlock"><tt>BasicBlock</tt></a> list is empty, this indicates that
+the <tt>Function</tt> is actually a function declaration: the actual body of the
+function hasn't been linked in yet.</p>
+
+<p>In addition to a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, the
+<tt>Function</tt> class also keeps track of the list of formal <a
+href="#Argument"><tt>Argument</tt></a>s that the function receives.  This
+container manages the lifetime of the <a href="#Argument"><tt>Argument</tt></a>
+nodes, just like the <a href="#BasicBlock"><tt>BasicBlock</tt></a> list does for
+the <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.</p>
+
+<p>The <a href="#SymbolTable"><tt>SymbolTable</tt></a> is a very rarely used
+LLVM feature that is only used when you have to look up a value by name.  Aside
+from that, the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is used
+internally to make sure that there are not conflicts between the names of <a
+href="#Instruction"><tt>Instruction</tt></a>s, <a
+href="#BasicBlock"><tt>BasicBlock</tt></a>s, or <a
+href="#Argument"><tt>Argument</tt></a>s in the function body.</p>
+
+<p>Note that <tt>Function</tt> is a <a href="#GlobalValue">GlobalValue</a>
+and therefore also a <a href="#Constant">Constant</a>. The value of the function
+is its address (after linking) which is guaranteed to be constant.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="m_Function">
+    Important Public Members of the <tt>Function</tt> class
+  </a>
+</h4>
+
+<div>
+
+<ul>
+  <li><tt>Function(const </tt><tt><a href="#FunctionType">FunctionType</a>
+  *Ty, LinkageTypes Linkage, const std::string &N = "", Module* Parent = 0)</tt>
+
+    <p>Constructor used when you need to create new <tt>Function</tt>s to add
+    the program.  The constructor must specify the type of the function to
+    create and what type of linkage the function should have. The <a 
+    href="#FunctionType"><tt>FunctionType</tt></a> argument
+    specifies the formal arguments and return value for the function. The same
+    <a href="#FunctionType"><tt>FunctionType</tt></a> value can be used to
+    create multiple functions. The <tt>Parent</tt> argument specifies the Module
+    in which the function is defined. If this argument is provided, the function
+    will automatically be inserted into that module's list of
+    functions.</p></li>
+
+  <li><tt>bool isDeclaration()</tt>
+
+    <p>Return whether or not the <tt>Function</tt> has a body defined.  If the
+    function is "external", it does not have a body, and thus must be resolved
+    by linking with a function defined in a different translation unit.</p></li>
+
+  <li><tt>Function::iterator</tt> - Typedef for basic block list iterator<br>
+    <tt>Function::const_iterator</tt> - Typedef for const_iterator.<br>
+
+    <tt>begin()</tt>, <tt>end()</tt>
+    <tt>size()</tt>, <tt>empty()</tt>
+
+    <p>These are forwarding methods that make it easy to access the contents of
+    a <tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a>
+    list.</p></li>
+
+  <li><tt>Function::BasicBlockListType &getBasicBlockList()</tt>
+
+    <p>Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.  This
+    is necessary to use when you need to update the list or perform a complex
+    action that doesn't have a forwarding method.</p></li>
+
+  <li><tt>Function::arg_iterator</tt> - Typedef for the argument list
+iterator<br>
+    <tt>Function::const_arg_iterator</tt> - Typedef for const_iterator.<br>
+
+    <tt>arg_begin()</tt>, <tt>arg_end()</tt>
+    <tt>arg_size()</tt>, <tt>arg_empty()</tt>
+
+    <p>These are forwarding methods that make it easy to access the contents of
+    a <tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a>
+    list.</p></li>
+
+  <li><tt>Function::ArgumentListType &getArgumentList()</tt>
+
+    <p>Returns the list of <a href="#Argument"><tt>Argument</tt></a>s.  This is
+    necessary to use when you need to update the list or perform a complex
+    action that doesn't have a forwarding method.</p></li>
+
+  <li><tt><a href="#BasicBlock">BasicBlock</a> &getEntryBlock()</tt>
+
+    <p>Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the
+    function.  Because the entry block for the function is always the first
+    block, this returns the first block of the <tt>Function</tt>.</p></li>
+
+  <li><tt><a href="#Type">Type</a> *getReturnType()</tt><br>
+    <tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt>
+
+    <p>This traverses the <a href="#Type"><tt>Type</tt></a> of the
+    <tt>Function</tt> and returns the return type of the function, or the <a
+    href="#FunctionType"><tt>FunctionType</tt></a> of the actual
+    function.</p></li>
+
+  <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
+
+    <p> Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
+    for this <tt>Function</tt>.</p></li>
+</ul>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a>
+</h3>
+
+<div>
+
+<p><tt>#include "<a
+href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt>
+<br>
+doxygen info: <a href="/doxygen/classllvm_1_1GlobalVariable.html">GlobalVariable
+ Class</a><br>
+Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, 
+<a href="#Constant"><tt>Constant</tt></a>,
+<a href="#User"><tt>User</tt></a>,
+<a href="#Value"><tt>Value</tt></a></p>
+
+<p>Global variables are represented with the (surprise surprise)
+<tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are also
+subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such are
+always referenced by their address (global values must live in memory, so their
+"name" refers to their constant address). See 
+<a href="#GlobalValue"><tt>GlobalValue</tt></a> for more on this.  Global 
+variables may have an initial value (which must be a 
+<a href="#Constant"><tt>Constant</tt></a>), and if they have an initializer, 
+they may be marked as "constant" themselves (indicating that their contents 
+never change at runtime).</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="m_GlobalVariable">
+    Important Public Members of the <tt>GlobalVariable</tt> class
+  </a>
+</h4>
+
+<div>
+
+<ul>
+  <li><tt>GlobalVariable(const </tt><tt><a href="#Type">Type</a> *Ty, bool
+  isConstant, LinkageTypes& Linkage, <a href="#Constant">Constant</a>
+  *Initializer = 0, const std::string &Name = "", Module* Parent = 0)</tt>
+
+    <p>Create a new global variable of the specified type. If
+    <tt>isConstant</tt> is true then the global variable will be marked as
+    unchanging for the program. The Linkage parameter specifies the type of
+    linkage (internal, external, weak, linkonce, appending) for the variable.
+    If the linkage is InternalLinkage, WeakAnyLinkage, WeakODRLinkage,
+    LinkOnceAnyLinkage or LinkOnceODRLinkage,  then the resultant
+    global variable will have internal linkage.  AppendingLinkage concatenates
+    together all instances (in different translation units) of the variable
+    into a single variable but is only applicable to arrays.   See
+    the <a href="LangRef.html#modulestructure">LLVM Language Reference</a> for
+    further details on linkage types. Optionally an initializer, a name, and the
+    module to put the variable into may be specified for the global variable as
+    well.</p></li>
+
+  <li><tt>bool isConstant() const</tt>
+
+    <p>Returns true if this is a global variable that is known not to
+    be modified at runtime.</p></li>
+
+  <li><tt>bool hasInitializer()</tt>
+
+    <p>Returns true if this <tt>GlobalVariable</tt> has an intializer.</p></li>
+
+  <li><tt><a href="#Constant">Constant</a> *getInitializer()</tt>
+
+    <p>Returns the initial value for a <tt>GlobalVariable</tt>.  It is not legal
+    to call this method if there is no initializer.</p></li>
+</ul>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="BasicBlock">The <tt>BasicBlock</tt> class</a>
+</h3>
+
+<div>
+
+<p><tt>#include "<a
+href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt><br>
+doxygen info: <a href="/doxygen/classllvm_1_1BasicBlock.html">BasicBlock
+Class</a><br>
+Superclass: <a href="#Value"><tt>Value</tt></a></p>
+
+<p>This class represents a single entry single exit section of the code,
+commonly known as a basic block by the compiler community.  The
+<tt>BasicBlock</tt> class maintains a list of <a
+href="#Instruction"><tt>Instruction</tt></a>s, which form the body of the block.
+Matching the language definition, the last element of this list of instructions
+is always a terminator instruction (a subclass of the <a
+href="#TerminatorInst"><tt>TerminatorInst</tt></a> class).</p>
+
+<p>In addition to tracking the list of instructions that make up the block, the
+<tt>BasicBlock</tt> class also keeps track of the <a
+href="#Function"><tt>Function</tt></a> that it is embedded into.</p>
+
+<p>Note that <tt>BasicBlock</tt>s themselves are <a
+href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions
+like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type
+<tt>label</tt>.</p>
+
+<!-- _______________________________________________________________________ -->
+<h4>
+  <a name="m_BasicBlock">
+    Important Public Members of the <tt>BasicBlock</tt> class
+  </a>
+</h4>
+
+<div>
+<ul>
+
+<li><tt>BasicBlock(const std::string &Name = "", </tt><tt><a
+ href="#Function">Function</a> *Parent = 0)</tt>
+
+<p>The <tt>BasicBlock</tt> constructor is used to create new basic blocks for
+insertion into a function.  The constructor optionally takes a name for the new
+block, and a <a href="#Function"><tt>Function</tt></a> to insert it into.  If
+the <tt>Parent</tt> parameter is specified, the new <tt>BasicBlock</tt> is
+automatically inserted at the end of the specified <a
+href="#Function"><tt>Function</tt></a>, if not specified, the BasicBlock must be
+manually inserted into the <a href="#Function"><tt>Function</tt></a>.</p></li>
+
+<li><tt>BasicBlock::iterator</tt> - Typedef for instruction list iterator<br>
+<tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br>
+<tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
+<tt>size()</tt>, <tt>empty()</tt>
+STL-style functions for accessing the instruction list.
+
+<p>These methods and typedefs are forwarding functions that have the same
+semantics as the standard library methods of the same names.  These methods
+expose the underlying instruction list of a basic block in a way that is easy to
+manipulate.  To get the full complement of container operations (including
+operations to update the list), you must use the <tt>getInstList()</tt>
+method.</p></li>
+
+<li><tt>BasicBlock::InstListType &getInstList()</tt>
+
+<p>This method is used to get access to the underlying container that actually
+holds the Instructions.  This method must be used when there isn't a forwarding
+function in the <tt>BasicBlock</tt> class for the operation that you would like
+to perform.  Because there are no forwarding functions for "updating"
+operations, you need to use this if you want to update the contents of a
+<tt>BasicBlock</tt>.</p></li>
+
+<li><tt><a href="#Function">Function</a> *getParent()</tt>
+
+<p> Returns a pointer to <a href="#Function"><tt>Function</tt></a> the block is
+embedded into, or a null pointer if it is homeless.</p></li>
+
+<li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt>
+
+<p> Returns a pointer to the terminator instruction that appears at the end of
+the <tt>BasicBlock</tt>.  If there is no terminator instruction, or if the last
+instruction in the block is not a terminator, then a null pointer is
+returned.</p></li>
+
+</ul>
+
+</div>
+
+</div>
+
+<!-- ======================================================================= -->
+<h3>
+  <a name="Argument">The <tt>Argument</tt> class</a>
+</h3>
+
+<div>
+
+<p>This subclass of Value defines the interface for incoming formal
+arguments to a function. A Function maintains a list of its formal
+arguments. An argument has a pointer to the parent Function.</p>
+
+</div>
+
+</div>
+
+<!-- *********************************************************************** -->
+<hr>
+<address>
+  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
+  <a href="http://validator.w3.org/check/referer"><img
+  src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01 Strict"></a>
+
+  <a href="mailto:dhurjati at cs.uiuc.edu">Dinakar Dhurjati</a> and
+  <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
+  <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
+  Last modified: $Date: 2012-10-06 19:56:09 -0500 (Sat, 06 Oct 2012) $
+</address>
+
+</body>
+</html>

Added: www-releases/trunk/3.2/docs/Projects.rst
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/Projects.rst?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/Projects.rst (added)
+++ www-releases/trunk/3.2/docs/Projects.rst Fri Dec 21 00:57:24 2012
@@ -0,0 +1,327 @@
+.. _projects:
+
+========================
+Creating an LLVM Project
+========================
+
+.. contents::
+   :local:
+
+Overview
+========
+
+The LLVM build system is designed to facilitate the building of third party
+projects that use LLVM header files, libraries, and tools.  In order to use
+these facilities, a ``Makefile`` from a project must do the following things:
+
+* Set ``make`` variables. There are several variables that a ``Makefile`` needs
+  to set to use the LLVM build system:
+
+  * ``PROJECT_NAME`` - The name by which your project is known.
+  * ``LLVM_SRC_ROOT`` - The root of the LLVM source tree.
+  * ``LLVM_OBJ_ROOT`` - The root of the LLVM object tree.
+  * ``PROJ_SRC_ROOT`` - The root of the project's source tree.
+  * ``PROJ_OBJ_ROOT`` - The root of the project's object tree.
+  * ``PROJ_INSTALL_ROOT`` - The root installation directory.
+  * ``LEVEL`` - The relative path from the current directory to the
+    project's root ``($PROJ_OBJ_ROOT)``.
+
+* Include ``Makefile.config`` from ``$(LLVM_OBJ_ROOT)``.
+
+* Include ``Makefile.rules`` from ``$(LLVM_SRC_ROOT)``.
+
+There are two ways that you can set all of these variables:
+
+* You can write your own ``Makefiles`` which hard-code these values.
+
+* You can use the pre-made LLVM sample project. This sample project includes
+  ``Makefiles``, a configure script that can be used to configure the location
+  of LLVM, and the ability to support multiple object directories from a single
+  source directory.
+
+This document assumes that you will base your project on the LLVM sample project
+found in ``llvm/projects/sample``. If you want to devise your own build system,
+studying the sample project and LLVM ``Makefiles`` will probably provide enough
+information on how to write your own ``Makefiles``.
+
+Create a Project from the Sample Project
+========================================
+
+Follow these simple steps to start your project:
+
+1. Copy the ``llvm/projects/sample`` directory to any place of your choosing.
+   You can place it anywhere you like. Rename the directory to match the name
+   of your project.
+
+2. If you downloaded LLVM using Subversion, remove all the directories named
+   ``.svn`` (and all the files therein) from your project's new source tree.
+   This will keep Subversion from thinking that your project is inside
+   ``llvm/trunk/projects/sample``.
+
+3. Add your source code and Makefiles to your source tree.
+
+4. If you want your project to be configured with the ``configure`` script then
+   you need to edit ``autoconf/configure.ac`` as follows:
+
+   * **AC_INIT** - Place the name of your project, its version number and a
+     contact email address for your project as the arguments to this macro
+ 
+   * **AC_CONFIG_AUX_DIR** - If your project isn't in the ``llvm/projects``
+     directory then you might need to adjust this so that it specifies a
+     relative path to the ``llvm/autoconf`` directory.
+
+   * **LLVM_CONFIG_PROJECT** - Just leave this alone.
+
+   * **AC_CONFIG_SRCDIR** - Specify a path to a file name that identifies your
+     project; or just leave it at ``Makefile.common.in``.
+
+   * **AC_CONFIG_FILES** - Do not change.
+
+   * **AC_CONFIG_MAKEFILE** - Use one of these macros for each Makefile that
+     your project uses. This macro arranges for your makefiles to be copied from
+     the source directory, unmodified, to the build directory.
+
+5. After updating ``autoconf/configure.ac``, regenerate the configure script
+   with these commands. (You must be using ``Autoconf`` version 2.59 or later
+   and your ``aclocal`` version should be 1.9 or later.)
+
+       .. code-block:: bash
+
+         % cd autoconf
+         % ./AutoRegen.sh
+
+6. Run ``configure`` in the directory in which you want to place object code.
+   Use the following options to tell your project where it can find LLVM:
+
+   ``--with-llvmsrc=<directory>``
+       Tell your project where the LLVM source tree is located.
+
+   ``--with-llvmobj=<directory>``
+       Tell your project where the LLVM object tree is located.
+
+   ``--prefix=<directory>``
+       Tell your project where it should get installed.
+
+That's it!  Now all you have to do is type ``gmake`` (or ``make`` if you're on a
+GNU/Linux system) in the root of your object directory, and your project should
+build.
+
+Source Tree Layout
+==================
+
+In order to use the LLVM build system, you will want to organize your source
+code so that it can benefit from the build system's features.  Mainly, you want
+your source tree layout to look similar to the LLVM source tree layout.  The
+best way to do this is to just copy the project tree from
+``llvm/projects/sample`` and modify it to meet your needs, but you can certainly
+add to it if you want.
+
+Underneath your top level directory, you should have the following directories:
+
+**lib**
+
+    This subdirectory should contain all of your library source code.  For each
+    library that you build, you will have one directory in **lib** that will
+    contain that library's source code.
+
+    Libraries can be object files, archives, or dynamic libraries.  The **lib**
+    directory is just a convenient place for libraries as it places them all in
+    a directory from which they can be linked later.
+
+**include**
+
+    This subdirectory should contain any header files that are global to your
+    project. By global, we mean that they are used by more than one library or
+    executable of your project.
+
+    By placing your header files in **include**, they will be found
+    automatically by the LLVM build system.  For example, if you have a file
+    **include/jazz/note.h**, then your source files can include it simply with
+    **#include "jazz/note.h"**.
+
+**tools**
+
+    This subdirectory should contain all of your source code for executables.
+    For each program that you build, you will have one directory in **tools**
+    that will contain that program's source code.
+
+**test**
+
+    This subdirectory should contain tests that verify that your code works
+    correctly.  Automated tests are especially useful.
+
+    Currently, the LLVM build system provides basic support for tests. The LLVM
+    system provides the following:
+
+* LLVM provides a ``tcl`` procedure that is used by ``Dejagnu`` to run tests.
+  It can be found in ``llvm/lib/llvm-dg.exp``.  This test procedure uses ``RUN``
+  lines in the actual test case to determine how to run the test.  See the
+  `TestingGuide <TestingGuide.html>`_ for more details. You can easily write
+  Makefile support similar to the Makefiles in ``llvm/test`` to use ``Dejagnu``
+  to run your project's tests.
+
+* LLVM contains an optional package called ``llvm-test``, which provides
+  benchmarks and programs that are known to compile with the Clang front
+  end. You can use these programs to test your code, gather statistical
+  information, and compare it to the current LLVM performance statistics.
+  
+  Currently, there is no way to hook your tests directly into the ``llvm/test``
+  testing harness. You will simply need to find a way to use the source
+  provided within that directory on your own.
+
+Typically, you will want to build your **lib** directory first followed by your
+**tools** directory.
+
+Writing LLVM Style Makefiles
+============================
+
+The LLVM build system provides a convenient way to build libraries and
+executables.  Most of your project Makefiles will only need to define a few
+variables.  Below is a list of the variables one can set and what they can
+do:
+
+Required Variables
+------------------
+
+``LEVEL``
+
+    This variable is the relative path from this ``Makefile`` to the top
+    directory of your project's source code.  For example, if your source code
+    is in ``/tmp/src``, then the ``Makefile`` in ``/tmp/src/jump/high``
+    would set ``LEVEL`` to ``"../.."``.
+
+Variables for Building Subdirectories
+-------------------------------------
+
+``DIRS``
+
+    This is a space separated list of subdirectories that should be built.  They
+    will be built, one at a time, in the order specified.
+
+``PARALLEL_DIRS``
+
+    This is a list of directories that can be built in parallel. These will be
+    built after the directories in DIRS have been built.
+
+``OPTIONAL_DIRS``
+
+    This is a list of directories that can be built if they exist, but will not
+    cause an error if they do not exist.  They are built serially in the order
+    in which they are listed.
+
+Variables for Building Libraries
+--------------------------------
+
+``LIBRARYNAME``
+
+    This variable contains the base name of the library that will be built.  For
+    example, to build a library named ``libsample.a``, ``LIBRARYNAME`` should
+    be set to ``sample``.
+
+``BUILD_ARCHIVE``
+
+    By default, a library is a ``.o`` file that is linked directly into a
+    program.  To build an archive (also known as a static library), set the
+    ``BUILD_ARCHIVE`` variable.
+
+``SHARED_LIBRARY``
+
+    If ``SHARED_LIBRARY`` is defined in your Makefile, a shared (or dynamic)
+    library will be built.
+
+Variables for Building Programs
+-------------------------------
+
+``TOOLNAME``
+
+    This variable contains the name of the program that will be built.  For
+    example, to build an executable named ``sample``, ``TOOLNAME`` should be set
+    to ``sample``.
+
+``USEDLIBS``
+
+    This variable holds a space separated list of libraries that should be
+    linked into the program.  These libraries must be libraries that come from
+    your **lib** directory.  The libraries must be specified without their
+    ``lib`` prefix.  For example, to link ``libsample.a``, you would set
+    ``USEDLIBS`` to ``sample.a``.
+
+    Note that this works only for statically linked libraries.
+
+``LLVMLIBS``
+
+    This variable holds a space separated list of libraries that should be
+    linked into the program.  These libraries must be LLVM libraries.  The
+    libraries must be specified without their ``lib`` prefix.  For example, to
+    link with a driver that performs an IR transformation you might set
+    ``LLVMLIBS`` to this minimal set of libraries ``LLVMSupport.a LLVMCore.a
+    LLVMBitReader.a LLVMAsmParser.a LLVMAnalysis.a LLVMTransformUtils.a
+    LLVMScalarOpts.a LLVMTarget.a``.
+
+    Note that this works only for statically linked libraries. LLVM is split
+    into a large number of static libraries, and the list of libraries you
+    require may be much longer than the list above. To see a full list of
+    libraries use: ``llvm-config --libs all``.  Using ``LINK_COMPONENTS`` as
+    described below, obviates the need to set ``LLVMLIBS``.
+
+``LINK_COMPONENTS``
+
+    This variable holds a space separated list of components that the LLVM
+    ``Makefiles`` pass to the ``llvm-config`` tool to generate a link line for
+    the program. For example, to link with all LLVM libraries use
+    ``LINK_COMPONENTS = all``.
+
+``LIBS``
+
+    To link dynamic libraries, add ``-l<library base name>`` to the ``LIBS``
+    variable.  The LLVM build system will look in the same places for dynamic
+    libraries as it does for static libraries.
+
+    For example, to link ``libsample.so``, you would have the following line in
+    your ``Makefile``:
+
+        .. code-block:: makefile
+
+          LIBS += -lsample
+
+Note that ``LIBS`` must occur in the Makefile after the inclusion of
+``Makefile.common``.
+
+Miscellaneous Variables
+-----------------------
+
+``CFLAGS`` & ``CPPFLAGS``
+
+    This variable can be used to add options to the C and C++ compiler,
+    respectively.  It is typically used to add options that tell the compiler
+    the location of additional directories to search for header files.
+
+    It is highly suggested that you append to ``CFLAGS`` and ``CPPFLAGS`` as
+    opposed to overwriting them.  The master ``Makefiles`` may already have
+    useful options in them that you may not want to overwrite.
+
+Placement of Object Code
+========================
+
+The final location of built libraries and executables will depend upon whether
+you do a ``Debug``, ``Release``, or ``Profile`` build.
+
+Libraries
+
+    All libraries (static and dynamic) will be stored in
+    ``PROJ_OBJ_ROOT/<type>/lib``, where *type* is ``Debug``, ``Release``, or
+    ``Profile`` for a debug, optimized, or profiled build, respectively.
+
+Executables
+
+    All executables will be stored in ``PROJ_OBJ_ROOT/<type>/bin``, where *type*
+    is ``Debug``, ``Release``, or ``Profile`` for a debug, optimized, or
+    profiled build, respectively.
+
+Further Help
+============
+
+If you have any questions or need any help creating an LLVM project, the LLVM
+team would be more than happy to help.  You can always post your questions to
+the `LLVM Developers Mailing List
+<http://lists.cs.uiuc.edu/pipermail/llvmdev/>`_.

Added: www-releases/trunk/3.2/docs/README.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.2/docs/README.txt?rev=170845&view=auto
==============================================================================
--- www-releases/trunk/3.2/docs/README.txt (added)
+++ www-releases/trunk/3.2/docs/README.txt Fri Dec 21 00:57:24 2012
@@ -0,0 +1,12 @@
+LLVM Documentation
+==================
+
+The LLVM documentation is currently written in two formats:
+
+  * Plain HTML documentation.
+
+  * reStructured Text documentation using the Sphinx documentation generator. It
+    is currently tested with Sphinx 1.1.3. 
+
+    For more information, see the "Sphinx Introduction for LLVM Developers"
+    document.





More information about the llvm-commits mailing list