[www-releases] r225843 - Add documentation for 3.5.1
Tom Stellard
thomas.stellard at amd.com
Tue Jan 13 14:55:45 PST 2015
Added: www-releases/trunk/3.5.1/docs/_sources/FAQ.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/FAQ.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/FAQ.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/FAQ.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,477 @@
+================================
+Frequently Asked Questions (FAQ)
+================================
+
+.. contents::
+ :local:
+
+
+License
+=======
+
+Does the University of Illinois Open Source License really qualify as an "open source" license?
+-----------------------------------------------------------------------------------------------
+Yes, the license is `certified
+<http://www.opensource.org/licenses/UoI-NCSA.php>`_ by the Open Source
+Initiative (OSI).
+
+
+Can I modify LLVM source code and redistribute the modified source?
+-------------------------------------------------------------------
+Yes. The modified source distribution must retain the copyright notice and
+follow the three bulletted conditions listed in the `LLVM license
+<http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT>`_.
+
+
+Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?
+--------------------------------------------------------------------------------------------------------------------------
+Yes. This is why we distribute LLVM under a less restrictive license than GPL,
+as explained in the first question above.
+
+
+Source Code
+===========
+
+In what language is LLVM written?
+---------------------------------
+All of the LLVM tools and libraries are written in C++ with extensive use of
+the STL.
+
+
+How portable is the LLVM source code?
+-------------------------------------
+The LLVM source code should be portable to most modern Unix-like operating
+systems. Most of the code is written in standard C++ with operating system
+services abstracted to a support library. The tools required to build and
+test LLVM have been ported to a plethora of platforms.
+
+Some porting problems may exist in the following areas:
+
+* The autoconf/makefile build system relies heavily on UNIX shell tools,
+ like the Bourne Shell and sed. Porting to systems without these tools
+ (MacOS 9, Plan 9) will require more effort.
+
+What API do I use to store a value to one of the virtual registers in LLVM IR's SSA representation?
+---------------------------------------------------------------------------------------------------
+
+In short: you can't. It's actually kind of a silly question once you grok
+what's going on. Basically, in code like:
+
+.. code-block:: llvm
+
+ %result = add i32 %foo, %bar
+
+, ``%result`` is just a name given to the ``Value`` of the ``add``
+instruction. In other words, ``%result`` *is* the add instruction. The
+"assignment" doesn't explicitly "store" anything to any "virtual register";
+the "``=``" is more like the mathematical sense of equality.
+
+Longer explanation: In order to generate a textual representation of the
+IR, some kind of name has to be given to each instruction so that other
+instructions can textually reference it. However, the isomorphic in-memory
+representation that you manipulate from C++ has no such restriction since
+instructions can simply keep pointers to any other ``Value``'s that they
+reference. In fact, the names of dummy numbered temporaries like ``%1`` are
+not explicitly represented in the in-memory representation at all (see
+``Value::getName()``).
+
+Build Problems
+==============
+
+When I run configure, it finds the wrong C compiler.
+----------------------------------------------------
+The ``configure`` script attempts to locate first ``gcc`` and then ``cc``,
+unless it finds compiler paths set in ``CC`` and ``CXX`` for the C and C++
+compiler, respectively.
+
+If ``configure`` finds the wrong compiler, either adjust your ``PATH``
+environment variable or set ``CC`` and ``CXX`` explicitly.
+
+
+The ``configure`` script finds the right C compiler, but it uses the LLVM tools from a previous build. What do I do?
+---------------------------------------------------------------------------------------------------------------------
+The ``configure`` script uses the ``PATH`` to find executables, so if it's
+grabbing the wrong linker/assembler/etc, there are two ways to fix it:
+
+#. Adjust your ``PATH`` environment variable so that the correct program
+ appears first in the ``PATH``. This may work, but may not be convenient
+ when you want them *first* in your path for other work.
+
+#. Run ``configure`` with an alternative ``PATH`` that is correct. In a
+ Bourne compatible shell, the syntax would be:
+
+.. code-block:: console
+
+ % PATH=[the path without the bad program] ./configure ...
+
+This is still somewhat inconvenient, but it allows ``configure`` to do its
+work without having to adjust your ``PATH`` permanently.
+
+
+When creating a dynamic library, I get a strange GLIBC error.
+-------------------------------------------------------------
+Under some operating systems (i.e. Linux), libtool does not work correctly if
+GCC was compiled with the ``--disable-shared option``. To work around this,
+install your own version of GCC that has shared libraries enabled by default.
+
+
+I've updated my source tree from Subversion, and now my build is trying to use a file/directory that doesn't exist.
+-------------------------------------------------------------------------------------------------------------------
+You need to re-run configure in your object directory. When new Makefiles
+are added to the source tree, they have to be copied over to the object tree
+in order to be used by the build.
+
+
+I've modified a Makefile in my source tree, but my build tree keeps using the old version. What do I do?
+---------------------------------------------------------------------------------------------------------
+If the Makefile already exists in your object tree, you can just run the
+following command in the top level directory of your object tree:
+
+.. code-block:: console
+
+ % ./config.status <relative path to Makefile>;
+
+If the Makefile is new, you will have to modify the configure script to copy
+it over.
+
+
+I've upgraded to a new version of LLVM, and I get strange build errors.
+-----------------------------------------------------------------------
+Sometimes, changes to the LLVM source code alters how the build system works.
+Changes in ``libtool``, ``autoconf``, or header file dependencies are
+especially prone to this sort of problem.
+
+The best thing to try is to remove the old files and re-build. In most cases,
+this takes care of the problem. To do this, just type ``make clean`` and then
+``make`` in the directory that fails to build.
+
+
+I've built LLVM and am testing it, but the tests freeze.
+--------------------------------------------------------
+This is most likely occurring because you built a profile or release
+(optimized) build of LLVM and have not specified the same information on the
+``gmake`` command line.
+
+For example, if you built LLVM with the command:
+
+.. code-block:: console
+
+ % gmake ENABLE_PROFILING=1
+
+...then you must run the tests with the following commands:
+
+.. code-block:: console
+
+ % cd llvm/test
+ % gmake ENABLE_PROFILING=1
+
+Why do test results differ when I perform different types of builds?
+--------------------------------------------------------------------
+The LLVM test suite is dependent upon several features of the LLVM tools and
+libraries.
+
+First, the debugging assertions in code are not enabled in optimized or
+profiling builds. Hence, tests that used to fail may pass.
+
+Second, some tests may rely upon debugging options or behavior that is only
+available in the debug build. These tests will fail in an optimized or
+profile build.
+
+
+Compiling LLVM with GCC 3.3.2 fails, what should I do?
+------------------------------------------------------
+This is `a bug in GCC <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13392>`_,
+and affects projects other than LLVM. Try upgrading or downgrading your GCC.
+
+
+After Subversion update, rebuilding gives the error "No rule to make target".
+-----------------------------------------------------------------------------
+If the error is of the form:
+
+.. code-block:: console
+
+ gmake[2]: *** No rule to make target `/path/to/somefile',
+ needed by `/path/to/another/file.d'.
+ Stop.
+
+This may occur anytime files are moved within the Subversion repository or
+removed entirely. In this case, the best solution is to erase all ``.d``
+files, which list dependencies for source files, and rebuild:
+
+.. code-block:: console
+
+ % cd $LLVM_OBJ_DIR
+ % rm -f `find . -name \*\.d`
+ % gmake
+
+In other cases, it may be necessary to run ``make clean`` before rebuilding.
+
+
+Source Languages
+================
+
+What source languages are supported?
+------------------------------------
+LLVM currently has full support for C and C++ source languages. These are
+available through both `Clang <http://clang.llvm.org/>`_ and `DragonEgg
+<http://dragonegg.llvm.org/>`_.
+
+The PyPy developers are working on integrating LLVM into the PyPy backend so
+that PyPy language can translate to LLVM.
+
+
+I'd like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?
+----------------------------------------------------------------------------------------------------------------------------------------
+Your compiler front-end will communicate with LLVM by creating a module in the
+LLVM intermediate representation (IR) format. Assuming you want to write your
+language's compiler in the language itself (rather than C++), there are 3
+major ways to tackle generating LLVM IR from a front-end:
+
+1. **Call into the LLVM libraries code using your language's FFI (foreign
+ function interface).**
+
+ * *for:* best tracks changes to the LLVM IR, .ll syntax, and .bc format
+
+ * *for:* enables running LLVM optimization passes without a emit/parse
+ overhead
+
+ * *for:* adapts well to a JIT context
+
+ * *against:* lots of ugly glue code to write
+
+2. **Emit LLVM assembly from your compiler's native language.**
+
+ * *for:* very straightforward to get started
+
+ * *against:* the .ll parser is slower than the bitcode reader when
+ interfacing to the middle end
+
+ * *against:* it may be harder to track changes to the IR
+
+3. **Emit LLVM bitcode from your compiler's native language.**
+
+ * *for:* can use the more-efficient bitcode reader when interfacing to the
+ middle end
+
+ * *against:* you'll have to re-engineer the LLVM IR object model and bitcode
+ writer in your language
+
+ * *against:* it may be harder to track changes to the IR
+
+If you go with the first option, the C bindings in include/llvm-c should help
+a lot, since most languages have strong support for interfacing with C. The
+most common hurdle with calling C from managed code is interfacing with the
+garbage collector. The C interface was designed to require very little memory
+management, and so is straightforward in this regard.
+
+What support is there for a higher level source language constructs for building a compiler?
+--------------------------------------------------------------------------------------------
+Currently, there isn't much. LLVM supports an intermediate representation
+which is useful for code representation but will not support the high level
+(abstract syntax tree) representation needed by most compilers. There are no
+facilities for lexical nor semantic analysis.
+
+
+I don't understand the ``GetElementPtr`` instruction. Help!
+-----------------------------------------------------------
+See `The Often Misunderstood GEP Instruction <GetElementPtr.html>`_.
+
+
+Using the C and C++ Front Ends
+==============================
+
+Can I compile C or C++ code to platform-independent LLVM bitcode?
+-----------------------------------------------------------------
+No. C and C++ are inherently platform-dependent languages. The most obvious
+example of this is the preprocessor. A very common way that C code is made
+portable is by using the preprocessor to include platform-specific code. In
+practice, information about other platforms is lost after preprocessing, so
+the result is inherently dependent on the platform that the preprocessing was
+targeting.
+
+Another example is ``sizeof``. It's common for ``sizeof(long)`` to vary
+between platforms. In most C front-ends, ``sizeof`` is expanded to a
+constant immediately, thus hard-wiring a platform-specific detail.
+
+Also, since many platforms define their ABIs in terms of C, and since LLVM is
+lower-level than C, front-ends currently must emit platform-specific IR in
+order to have the result conform to the platform ABI.
+
+
+Questions about code generated by the demo page
+===============================================
+
+What is this ``llvm.global_ctors`` and ``_GLOBAL__I_a...`` stuff that happens when I ``#include <iostream>``?
+-------------------------------------------------------------------------------------------------------------
+If you ``#include`` the ``<iostream>`` header into a C++ translation unit,
+the file will probably use the ``std::cin``/``std::cout``/... global objects.
+However, C++ does not guarantee an order of initialization between static
+objects in different translation units, so if a static ctor/dtor in your .cpp
+file used ``std::cout``, for example, the object would not necessarily be
+automatically initialized before your use.
+
+To make ``std::cout`` and friends work correctly in these scenarios, the STL
+that we use declares a static object that gets created in every translation
+unit that includes ``<iostream>``. This object has a static constructor
+and destructor that initializes and destroys the global iostream objects
+before they could possibly be used in the file. The code that you see in the
+``.ll`` file corresponds to the constructor and destructor registration code.
+
+If you would like to make it easier to *understand* the LLVM code generated
+by the compiler in the demo page, consider using ``printf()`` instead of
+``iostream``\s to print values.
+
+
+Where did all of my code go??
+-----------------------------
+If you are using the LLVM demo page, you may often wonder what happened to
+all of the code that you typed in. Remember that the demo script is running
+the code through the LLVM optimizers, so if your code doesn't actually do
+anything useful, it might all be deleted.
+
+To prevent this, make sure that the code is actually needed. For example, if
+you are computing some expression, return the value from the function instead
+of leaving it in a local variable. If you really want to constrain the
+optimizer, you can read from and assign to ``volatile`` global variables.
+
+
+What is this "``undef``" thing that shows up in my code?
+--------------------------------------------------------
+``undef`` is the LLVM way of representing a value that is not defined. You
+can get these if you do not initialize a variable before you use it. For
+example, the C function:
+
+.. code-block:: c
+
+ int X() { int i; return i; }
+
+Is compiled to "``ret i32 undef``" because "``i``" never has a value specified
+for it.
+
+
+Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into "unreachable"? Why not make the verifier reject it?
+----------------------------------------------------------------------------------------------------------------------------------------------------------
+This is a common problem run into by authors of front-ends that are using
+custom calling conventions: you need to make sure to set the right calling
+convention on both the function and on each call to the function. For
+example, this code:
+
+.. code-block:: llvm
+
+ define fastcc void @foo() {
+ ret void
+ }
+ define void @bar() {
+ call void @foo()
+ ret void
+ }
+
+Is optimized to:
+
+.. code-block:: llvm
+
+ define fastcc void @foo() {
+ ret void
+ }
+ define void @bar() {
+ unreachable
+ }
+
+... with "``opt -instcombine -simplifycfg``". This often bites people because
+"all their code disappears". Setting the calling convention on the caller and
+callee is required for indirect calls to work, so people often ask why not
+make the verifier reject this sort of thing.
+
+The answer is that this code has undefined behavior, but it is not illegal.
+If we made it illegal, then every transformation that could potentially create
+this would have to ensure that it doesn't, and there is valid code that can
+create this sort of construct (in dead code). The sorts of things that can
+cause this to happen are fairly contrived, but we still need to accept them.
+Here's an example:
+
+.. code-block:: llvm
+
+ define fastcc void @foo() {
+ ret void
+ }
+ define internal void @bar(void()* %FP, i1 %cond) {
+ br i1 %cond, label %T, label %F
+ T:
+ call void %FP()
+ ret void
+ F:
+ call fastcc void %FP()
+ ret void
+ }
+ define void @test() {
+ %X = or i1 false, false
+ call void @bar(void()* @foo, i1 %X)
+ ret void
+ }
+
+In this example, "test" always passes ``@foo``/``false`` into ``bar``, which
+ensures that it is dynamically called with the right calling conv (thus, the
+code is perfectly well defined). If you run this through the inliner, you
+get this (the explicit "or" is there so that the inliner doesn't dead code
+eliminate a bunch of stuff):
+
+.. code-block:: llvm
+
+ define fastcc void @foo() {
+ ret void
+ }
+ define void @test() {
+ %X = or i1 false, false
+ br i1 %X, label %T.i, label %F.i
+ T.i:
+ call void @foo()
+ br label %bar.exit
+ F.i:
+ call fastcc void @foo()
+ br label %bar.exit
+ bar.exit:
+ ret void
+ }
+
+Here you can see that the inlining pass made an undefined call to ``@foo``
+with the wrong calling convention. We really don't want to make the inliner
+have to know about this sort of thing, so it needs to be valid code. In this
+case, dead code elimination can trivially remove the undefined code. However,
+if ``%X`` was an input argument to ``@test``, the inliner would produce this:
+
+.. code-block:: llvm
+
+ define fastcc void @foo() {
+ ret void
+ }
+
+ define void @test(i1 %X) {
+ br i1 %X, label %T.i, label %F.i
+ T.i:
+ call void @foo()
+ br label %bar.exit
+ F.i:
+ call fastcc void @foo()
+ br label %bar.exit
+ bar.exit:
+ ret void
+ }
+
+The interesting thing about this is that ``%X`` *must* be false for the
+code to be well-defined, but no amount of dead code elimination will be able
+to delete the broken call as unreachable. However, since
+``instcombine``/``simplifycfg`` turns the undefined call into unreachable, we
+end up with a branch on a condition that goes to unreachable: a branch to
+unreachable can never happen, so "``-inline -instcombine -simplifycfg``" is
+able to produce:
+
+.. code-block:: llvm
+
+ define fastcc void @foo() {
+ ret void
+ }
+ define void @test(i1 %X) {
+ F.i:
+ call fastcc void @foo()
+ ret void
+ }
Added: www-releases/trunk/3.5.1/docs/_sources/GarbageCollection.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/GarbageCollection.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/GarbageCollection.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/GarbageCollection.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,1014 @@
+=====================================
+Accurate Garbage Collection with LLVM
+=====================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Garbage collection is a widely used technique that frees the programmer from
+having to know the lifetimes of heap objects, making software easier to produce
+and maintain. Many programming languages rely on garbage collection for
+automatic memory management. There are two primary forms of garbage collection:
+conservative and accurate.
+
+Conservative garbage collection often does not require any special support from
+either the language or the compiler: it can handle non-type-safe programming
+languages (such as C/C++) and does not require any special information from the
+compiler. The `Boehm collector
+<http://www.hpl.hp.com/personal/Hans_Boehm/gc/>`__ is an example of a
+state-of-the-art conservative collector.
+
+Accurate garbage collection requires the ability to identify all pointers in the
+program at run-time (which requires that the source-language be type-safe in
+most cases). Identifying pointers at run-time requires compiler support to
+locate all places that hold live pointer variables at run-time, including the
+:ref:`processor stack and registers <gcroot>`.
+
+Conservative garbage collection is attractive because it does not require any
+special compiler support, but it does have problems. In particular, because the
+conservative garbage collector cannot *know* that a particular word in the
+machine is a pointer, it cannot move live objects in the heap (preventing the
+use of compacting and generational GC algorithms) and it can occasionally suffer
+from memory leaks due to integer values that happen to point to objects in the
+program. In addition, some aggressive compiler transformations can break
+conservative garbage collectors (though these seem rare in practice).
+
+Accurate garbage collectors do not suffer from any of these problems, but they
+can suffer from degraded scalar optimization of the program. In particular,
+because the runtime must be able to identify and update all pointers active in
+the program, some optimizations are less effective. In practice, however, the
+locality and performance benefits of using aggressive garbage collection
+techniques dominates any low-level losses.
+
+This document describes the mechanisms and interfaces provided by LLVM to
+support accurate garbage collection.
+
+Goals and non-goals
+-------------------
+
+LLVM's intermediate representation provides :ref:`garbage collection intrinsics
+<gc_intrinsics>` that offer support for a broad class of collector models. For
+instance, the intrinsics permit:
+
+* semi-space collectors
+
+* mark-sweep collectors
+
+* generational collectors
+
+* reference counting
+
+* incremental collectors
+
+* concurrent collectors
+
+* cooperative collectors
+
+We hope that the primitive support built into the LLVM IR is sufficient to
+support a broad class of garbage collected languages including Scheme, ML, Java,
+C#, Perl, Python, Lua, Ruby, other scripting languages, and more.
+
+However, LLVM does not itself provide a garbage collector --- this should be
+part of your language's runtime library. LLVM provides a framework for compile
+time :ref:`code generation plugins <plugin>`. The role of these plugins is to
+generate code and data structures which conforms to the *binary interface*
+specified by the *runtime library*. This is similar to the relationship between
+LLVM and DWARF debugging info, for example. The difference primarily lies in
+the lack of an established standard in the domain of garbage collection --- thus
+the plugins.
+
+The aspects of the binary interface with which LLVM's GC support is
+concerned are:
+
+* Creation of GC-safe points within code where collection is allowed to execute
+ safely.
+
+* Computation of the stack map. For each safe point in the code, object
+ references within the stack frame must be identified so that the collector may
+ traverse and perhaps update them.
+
+* Write barriers when storing object references to the heap. These are commonly
+ used to optimize incremental scans in generational collectors.
+
+* Emission of read barriers when loading object references. These are useful
+ for interoperating with concurrent collectors.
+
+There are additional areas that LLVM does not directly address:
+
+* Registration of global roots with the runtime.
+
+* Registration of stack map entries with the runtime.
+
+* The functions used by the program to allocate memory, trigger a collection,
+ etc.
+
+* Computation or compilation of type maps, or registration of them with the
+ runtime. These are used to crawl the heap for object references.
+
+In general, LLVM's support for GC does not include features which can be
+adequately addressed with other features of the IR and does not specify a
+particular binary interface. On the plus side, this means that you should be
+able to integrate LLVM with an existing runtime. On the other hand, it leaves a
+lot of work for the developer of a novel language. However, it's easy to get
+started quickly and scale up to a more sophisticated implementation as your
+compiler matures.
+
+Getting started
+===============
+
+Using a GC with LLVM implies many things, for example:
+
+* Write a runtime library or find an existing one which implements a GC heap.
+
+ #. Implement a memory allocator.
+
+ #. Design a binary interface for the stack map, used to identify references
+ within a stack frame on the machine stack.\*
+
+ #. Implement a stack crawler to discover functions on the call stack.\*
+
+ #. Implement a registry for global roots.
+
+ #. Design a binary interface for type maps, used to identify references
+ within heap objects.
+
+ #. Implement a collection routine bringing together all of the above.
+
+* Emit compatible code from your compiler.
+
+ * Initialization in the main function.
+
+ * Use the ``gc "..."`` attribute to enable GC code generation (or
+ ``F.setGC("...")``).
+
+ * Use ``@llvm.gcroot`` to mark stack roots.
+
+ * Use ``@llvm.gcread`` and/or ``@llvm.gcwrite`` to manipulate GC references,
+ if necessary.
+
+ * Allocate memory using the GC allocation routine provided by the runtime
+ library.
+
+ * Generate type maps according to your runtime's binary interface.
+
+* Write a compiler plugin to interface LLVM with the runtime library.\*
+
+ * Lower ``@llvm.gcread`` and ``@llvm.gcwrite`` to appropriate code
+ sequences.\*
+
+ * Compile LLVM's stack map to the binary form expected by the runtime.
+
+* Load the plugin into the compiler. Use ``llc -load`` or link the plugin
+ statically with your language's compiler.\*
+
+* Link program executables with the runtime.
+
+To help with several of these tasks (those indicated with a \*), LLVM includes a
+highly portable, built-in ShadowStack code generator. It is compiled into
+``llc`` and works even with the interpreter and C backends.
+
+In your compiler
+----------------
+
+To turn the shadow stack on for your functions, first call:
+
+.. code-block:: c++
+
+ F.setGC("shadow-stack");
+
+for each function your compiler emits. Since the shadow stack is built into
+LLVM, you do not need to load a plugin.
+
+Your compiler must also use ``@llvm.gcroot`` as documented. Don't forget to
+create a root for each intermediate value that is generated when evaluating an
+expression. In ``h(f(), g())``, the result of ``f()`` could easily be collected
+if evaluating ``g()`` triggers a collection.
+
+There's no need to use ``@llvm.gcread`` and ``@llvm.gcwrite`` over plain
+``load`` and ``store`` for now. You will need them when switching to a more
+advanced GC.
+
+In your runtime
+---------------
+
+The shadow stack doesn't imply a memory allocation algorithm. A semispace
+collector or building atop ``malloc`` are great places to start, and can be
+implemented with very little code.
+
+When it comes time to collect, however, your runtime needs to traverse the stack
+roots, and for this it needs to integrate with the shadow stack. Luckily, doing
+so is very simple. (This code is heavily commented to help you understand the
+data structure, but there are only 20 lines of meaningful code.)
+
+.. code-block:: c++
+
+ /// @brief The map for a single function's stack frame. One of these is
+ /// compiled as constant data into the executable for each function.
+ ///
+ /// Storage of metadata values is elided if the %metadata parameter to
+ /// @llvm.gcroot is null.
+ struct FrameMap {
+ int32_t NumRoots; //< Number of roots in stack frame.
+ int32_t NumMeta; //< Number of metadata entries. May be < NumRoots.
+ const void *Meta[0]; //< Metadata for each root.
+ };
+
+ /// @brief A link in the dynamic shadow stack. One of these is embedded in
+ /// the stack frame of each function on the call stack.
+ struct StackEntry {
+ StackEntry *Next; //< Link to next stack entry (the caller's).
+ const FrameMap *Map; //< Pointer to constant FrameMap.
+ void *Roots[0]; //< Stack roots (in-place array).
+ };
+
+ /// @brief The head of the singly-linked list of StackEntries. Functions push
+ /// and pop onto this in their prologue and epilogue.
+ ///
+ /// Since there is only a global list, this technique is not threadsafe.
+ StackEntry *llvm_gc_root_chain;
+
+ /// @brief Calls Visitor(root, meta) for each GC root on the stack.
+ /// root and meta are exactly the values passed to
+ /// @llvm.gcroot.
+ ///
+ /// Visitor could be a function to recursively mark live objects. Or it
+ /// might copy them to another heap or generation.
+ ///
+ /// @param Visitor A function to invoke for every GC root on the stack.
+ void visitGCRoots(void (*Visitor)(void **Root, const void *Meta)) {
+ for (StackEntry *R = llvm_gc_root_chain; R; R = R->Next) {
+ unsigned i = 0;
+
+ // For roots [0, NumMeta), the metadata pointer is in the FrameMap.
+ for (unsigned e = R->Map->NumMeta; i != e; ++i)
+ Visitor(&R->Roots[i], R->Map->Meta[i]);
+
+ // For roots [NumMeta, NumRoots), the metadata pointer is null.
+ for (unsigned e = R->Map->NumRoots; i != e; ++i)
+ Visitor(&R->Roots[i], NULL);
+ }
+ }
+
+About the shadow stack
+----------------------
+
+Unlike many GC algorithms which rely on a cooperative code generator to compile
+stack maps, this algorithm carefully maintains a linked list of stack roots
+[:ref:`Henderson2002 <henderson02>`]. This so-called "shadow stack" mirrors the
+machine stack. Maintaining this data structure is slower than using a stack map
+compiled into the executable as constant data, but has a significant portability
+advantage because it requires no special support from the target code generator,
+and does not require tricky platform-specific code to crawl the machine stack.
+
+The tradeoff for this simplicity and portability is:
+
+* High overhead per function call.
+
+* Not thread-safe.
+
+Still, it's an easy way to get started. After your compiler and runtime are up
+and running, writing a :ref:`plugin <plugin>` will allow you to take advantage
+of :ref:`more advanced GC features <collector-algos>` of LLVM in order to
+improve performance.
+
+.. _gc_intrinsics:
+
+IR features
+===========
+
+This section describes the garbage collection facilities provided by the
+:doc:`LLVM intermediate representation <LangRef>`. The exact behavior of these
+IR features is specified by the binary interface implemented by a :ref:`code
+generation plugin <plugin>`, not by this document.
+
+These facilities are limited to those strictly necessary; they are not intended
+to be a complete interface to any garbage collector. A program will need to
+interface with the GC library using the facilities provided by that program.
+
+Specifying GC code generation: ``gc "..."``
+-------------------------------------------
+
+.. code-block:: llvm
+
+ define ty @name(...) gc "name" { ...
+
+The ``gc`` function attribute is used to specify the desired GC style to the
+compiler. Its programmatic equivalent is the ``setGC`` method of ``Function``.
+
+Setting ``gc "name"`` on a function triggers a search for a matching code
+generation plugin "*name*"; it is that plugin which defines the exact nature of
+the code generated to support GC. If none is found, the compiler will raise an
+error.
+
+Specifying the GC style on a per-function basis allows LLVM to link together
+programs that use different garbage collection algorithms (or none at all).
+
+.. _gcroot:
+
+Identifying GC roots on the stack: ``llvm.gcroot``
+--------------------------------------------------
+
+.. code-block:: llvm
+
+ void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
+
+The ``llvm.gcroot`` intrinsic is used to inform LLVM that a stack variable
+references an object on the heap and is to be tracked for garbage collection.
+The exact impact on generated code is specified by a :ref:`compiler plugin
+<plugin>`. All calls to ``llvm.gcroot`` **must** reside inside the first basic
+block.
+
+A compiler which uses mem2reg to raise imperative code using ``alloca`` into SSA
+form need only add a call to ``@llvm.gcroot`` for those variables which a
+pointers into the GC heap.
+
+It is also important to mark intermediate values with ``llvm.gcroot``. For
+example, consider ``h(f(), g())``. Beware leaking the result of ``f()`` in the
+case that ``g()`` triggers a collection. Note, that stack variables must be
+initialized and marked with ``llvm.gcroot`` in function's prologue.
+
+The first argument **must** be a value referring to an alloca instruction or a
+bitcast of an alloca. The second contains a pointer to metadata that should be
+associated with the pointer, and **must** be a constant or global value
+address. If your target collector uses tags, use a null pointer for metadata.
+
+The ``%metadata`` argument can be used to avoid requiring heap objects to have
+'isa' pointers or tag bits. [Appel89_, Goldberg91_, Tolmach94_] If specified,
+its value will be tracked along with the location of the pointer in the stack
+frame.
+
+Consider the following fragment of Java code:
+
+.. code-block:: java
+
+ {
+ Object X; // A null-initialized reference to an object
+ ...
+ }
+
+This block (which may be located in the middle of a function or in a loop nest),
+could be compiled to this LLVM code:
+
+.. code-block:: llvm
+
+ Entry:
+ ;; In the entry block for the function, allocate the
+ ;; stack space for X, which is an LLVM pointer.
+ %X = alloca %Object*
+
+ ;; Tell LLVM that the stack space is a stack root.
+ ;; Java has type-tags on objects, so we pass null as metadata.
+ %tmp = bitcast %Object** %X to i8**
+ call void @llvm.gcroot(i8** %tmp, i8* null)
+ ...
+
+ ;; "CodeBlock" is the block corresponding to the start
+ ;; of the scope above.
+ CodeBlock:
+ ;; Java null-initializes pointers.
+ store %Object* null, %Object** %X
+
+ ...
+
+ ;; As the pointer goes out of scope, store a null value into
+ ;; it, to indicate that the value is no longer live.
+ store %Object* null, %Object** %X
+ ...
+
+Reading and writing references in the heap
+------------------------------------------
+
+Some collectors need to be informed when the mutator (the program that needs
+garbage collection) either reads a pointer from or writes a pointer to a field
+of a heap object. The code fragments inserted at these points are called *read
+barriers* and *write barriers*, respectively. The amount of code that needs to
+be executed is usually quite small and not on the critical path of any
+computation, so the overall performance impact of the barrier is tolerable.
+
+Barriers often require access to the *object pointer* rather than the *derived
+pointer* (which is a pointer to the field within the object). Accordingly,
+these intrinsics take both pointers as separate arguments for completeness. In
+this snippet, ``%object`` is the object pointer, and ``%derived`` is the derived
+pointer:
+
+.. code-block:: llvm
+
+ ;; An array type.
+ %class.Array = type { %class.Object, i32, [0 x %class.Object*] }
+ ...
+
+ ;; Load the object pointer from a gcroot.
+ %object = load %class.Array** %object_addr
+
+ ;; Compute the derived pointer.
+ %derived = getelementptr %object, i32 0, i32 2, i32 %n
+
+LLVM does not enforce this relationship between the object and derived pointer
+(although a :ref:`plugin <plugin>` might). However, it would be an unusual
+collector that violated it.
+
+The use of these intrinsics is naturally optional if the target GC does require
+the corresponding barrier. Such a GC plugin will replace the intrinsic calls
+with the corresponding ``load`` or ``store`` instruction if they are used.
+
+Write barrier: ``llvm.gcwrite``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ void @llvm.gcwrite(i8* %value, i8* %object, i8** %derived)
+
+For write barriers, LLVM provides the ``llvm.gcwrite`` intrinsic function. It
+has exactly the same semantics as a non-volatile ``store`` to the derived
+pointer (the third argument). The exact code generated is specified by a
+compiler :ref:`plugin <plugin>`.
+
+Many important algorithms require write barriers, including generational and
+concurrent collectors. Additionally, write barriers could be used to implement
+reference counting.
+
+Read barrier: ``llvm.gcread``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ i8* @llvm.gcread(i8* %object, i8** %derived)
+
+For read barriers, LLVM provides the ``llvm.gcread`` intrinsic function. It has
+exactly the same semantics as a non-volatile ``load`` from the derived pointer
+(the second argument). The exact code generated is specified by a
+:ref:`compiler plugin <plugin>`.
+
+Read barriers are needed by fewer algorithms than write barriers, and may have a
+greater performance impact since pointer reads are more frequent than writes.
+
+.. _plugin:
+
+Implementing a collector plugin
+===============================
+
+User code specifies which GC code generation to use with the ``gc`` function
+attribute or, equivalently, with the ``setGC`` method of ``Function``.
+
+To implement a GC plugin, it is necessary to subclass ``llvm::GCStrategy``,
+which can be accomplished in a few lines of boilerplate code. LLVM's
+infrastructure provides access to several important algorithms. For an
+uncontroversial collector, all that remains may be to compile LLVM's computed
+stack map to assembly code (using the binary representation expected by the
+runtime library). This can be accomplished in about 100 lines of code.
+
+This is not the appropriate place to implement a garbage collected heap or a
+garbage collector itself. That code should exist in the language's runtime
+library. The compiler plugin is responsible for generating code which conforms
+to the binary interface defined by library, most essentially the :ref:`stack map
+<stack-map>`.
+
+To subclass ``llvm::GCStrategy`` and register it with the compiler:
+
+.. code-block:: c++
+
+ // lib/MyGC/MyGC.cpp - Example LLVM GC plugin
+
+ #include "llvm/CodeGen/GCStrategy.h"
+ #include "llvm/CodeGen/GCMetadata.h"
+ #include "llvm/Support/Compiler.h"
+
+ using namespace llvm;
+
+ namespace {
+ class LLVM_LIBRARY_VISIBILITY MyGC : public GCStrategy {
+ public:
+ MyGC() {}
+ };
+
+ GCRegistry::Add<MyGC>
+ X("mygc", "My bespoke garbage collector.");
+ }
+
+This boilerplate collector does nothing. More specifically:
+
+* ``llvm.gcread`` calls are replaced with the corresponding ``load``
+ instruction.
+
+* ``llvm.gcwrite`` calls are replaced with the corresponding ``store``
+ instruction.
+
+* No safe points are added to the code.
+
+* The stack map is not compiled into the executable.
+
+Using the LLVM makefiles, this code
+can be compiled as a plugin using a simple makefile:
+
+.. code-block:: make
+
+ # lib/MyGC/Makefile
+
+ LEVEL := ../..
+ LIBRARYNAME = MyGC
+ LOADABLE_MODULE = 1
+
+ include $(LEVEL)/Makefile.common
+
+Once the plugin is compiled, code using it may be compiled using ``llc
+-load=MyGC.so`` (though MyGC.so may have some other platform-specific
+extension):
+
+::
+
+ $ cat sample.ll
+ define void @f() gc "mygc" {
+ entry:
+ ret void
+ }
+ $ llvm-as < sample.ll | llc -load=MyGC.so
+
+It is also possible to statically link the collector plugin into tools, such as
+a language-specific compiler front-end.
+
+.. _collector-algos:
+
+Overview of available features
+------------------------------
+
+``GCStrategy`` provides a range of features through which a plugin may do useful
+work. Some of these are callbacks, some are algorithms that can be enabled,
+disabled, or customized. This matrix summarizes the supported (and planned)
+features and correlates them with the collection techniques which typically
+require them.
+
+.. |v| unicode:: 0x2714
+ :trim:
+
+.. |x| unicode:: 0x2718
+ :trim:
+
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| Algorithm | Done | Shadow | refcount | mark- | copying | incremental | threaded | concurrent |
+| | | stack | | sweep | | | | |
++============+======+========+==========+=======+=========+=============+==========+============+
+| stack map | |v| | | | |x| | |x| | |x| | |x| | |x| |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| initialize | |v| | |x| | |x| | |x| | |x| | |x| | |x| | |x| |
+| roots | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| derived | NO | | | | | | **N**\* | **N**\* |
+| pointers | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| **custom | |v| | | | | | | | |
+| lowering** | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *gcroot* | |v| | |x| | |x| | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *gcwrite* | |v| | | |x| | | | |x| | | |x| |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *gcread* | |v| | | | | | | | |x| |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| **safe | | | | | | | | |
+| points** | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *in | |v| | | | |x| | |x| | |x| | |x| | |x| |
+| calls* | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *before | |v| | | | | | | |x| | |x| |
+| calls* | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *for | NO | | | | | | **N** | **N** |
+| loops* | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *before | |v| | | | | | | |x| | |x| |
+| escape* | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| emit code | NO | | | | | | **N** | **N** |
+| at safe | | | | | | | | |
+| points | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| **output** | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *assembly* | |v| | | | |x| | |x| | |x| | |x| | |x| |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *JIT* | NO | | | **?** | **?** | **?** | **?** | **?** |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| *obj* | NO | | | **?** | **?** | **?** | **?** | **?** |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| live | NO | | | **?** | **?** | **?** | **?** | **?** |
+| analysis | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| register | NO | | | **?** | **?** | **?** | **?** | **?** |
+| map | | | | | | | | |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| \* Derived pointers only pose a hasard to copying collections. |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+| **?** denotes a feature which could be utilized if available. |
++------------+------+--------+----------+-------+---------+-------------+----------+------------+
+
+To be clear, the collection techniques above are defined as:
+
+Shadow Stack
+ The mutator carefully maintains a linked list of stack roots.
+
+Reference Counting
+ The mutator maintains a reference count for each object and frees an object
+ when its count falls to zero.
+
+Mark-Sweep
+ When the heap is exhausted, the collector marks reachable objects starting
+ from the roots, then deallocates unreachable objects in a sweep phase.
+
+Copying
+ As reachability analysis proceeds, the collector copies objects from one heap
+ area to another, compacting them in the process. Copying collectors enable
+ highly efficient "bump pointer" allocation and can improve locality of
+ reference.
+
+Incremental
+ (Including generational collectors.) Incremental collectors generally have all
+ the properties of a copying collector (regardless of whether the mature heap
+ is compacting), but bring the added complexity of requiring write barriers.
+
+Threaded
+ Denotes a multithreaded mutator; the collector must still stop the mutator
+ ("stop the world") before beginning reachability analysis. Stopping a
+ multithreaded mutator is a complicated problem. It generally requires highly
+ platform-specific code in the runtime, and the production of carefully
+ designed machine code at safe points.
+
+Concurrent
+ In this technique, the mutator and the collector run concurrently, with the
+ goal of eliminating pause times. In a *cooperative* collector, the mutator
+ further aids with collection should a pause occur, allowing collection to take
+ advantage of multiprocessor hosts. The "stop the world" problem of threaded
+ collectors is generally still present to a limited extent. Sophisticated
+ marking algorithms are necessary. Read barriers may be necessary.
+
+As the matrix indicates, LLVM's garbage collection infrastructure is already
+suitable for a wide variety of collectors, but does not currently extend to
+multithreaded programs. This will be added in the future as there is
+interest.
+
+.. _stack-map:
+
+Computing stack maps
+--------------------
+
+LLVM automatically computes a stack map. One of the most important features
+of a ``GCStrategy`` is to compile this information into the executable in
+the binary representation expected by the runtime library.
+
+The stack map consists of the location and identity of each GC root in the
+each function in the module. For each root:
+
+* ``RootNum``: The index of the root.
+
+* ``StackOffset``: The offset of the object relative to the frame pointer.
+
+* ``RootMetadata``: The value passed as the ``%metadata`` parameter to the
+ ``@llvm.gcroot`` intrinsic.
+
+Also, for the function as a whole:
+
+* ``getFrameSize()``: The overall size of the function's initial stack frame,
+ not accounting for any dynamic allocation.
+
+* ``roots_size()``: The count of roots in the function.
+
+To access the stack map, use ``GCFunctionMetadata::roots_begin()`` and
+-``end()`` from the :ref:`GCMetadataPrinter <assembly>`:
+
+.. code-block:: c++
+
+ for (iterator I = begin(), E = end(); I != E; ++I) {
+ GCFunctionInfo *FI = *I;
+ unsigned FrameSize = FI->getFrameSize();
+ size_t RootCount = FI->roots_size();
+
+ for (GCFunctionInfo::roots_iterator RI = FI->roots_begin(),
+ RE = FI->roots_end();
+ RI != RE; ++RI) {
+ int RootNum = RI->Num;
+ int RootStackOffset = RI->StackOffset;
+ Constant *RootMetadata = RI->Metadata;
+ }
+ }
+
+If the ``llvm.gcroot`` intrinsic is eliminated before code generation by a
+custom lowering pass, LLVM will compute an empty stack map. This may be useful
+for collector plugins which implement reference counting or a shadow stack.
+
+.. _init-roots:
+
+Initializing roots to null: ``InitRoots``
+-----------------------------------------
+
+.. code-block:: c++
+
+ MyGC::MyGC() {
+ InitRoots = true;
+ }
+
+When set, LLVM will automatically initialize each root to ``null`` upon entry to
+the function. This prevents the GC's sweep phase from visiting uninitialized
+pointers, which will almost certainly cause it to crash. This initialization
+occurs before custom lowering, so the two may be used together.
+
+Since LLVM does not yet compute liveness information, there is no means of
+distinguishing an uninitialized stack root from an initialized one. Therefore,
+this feature should be used by all GC plugins. It is enabled by default.
+
+Custom lowering of intrinsics: ``CustomRoots``, ``CustomReadBarriers``, and ``CustomWriteBarriers``
+---------------------------------------------------------------------------------------------------
+
+For GCs which use barriers or unusual treatment of stack roots, these flags
+allow the collector to perform arbitrary transformations of the LLVM IR:
+
+.. code-block:: c++
+
+ class MyGC : public GCStrategy {
+ public:
+ MyGC() {
+ CustomRoots = true;
+ CustomReadBarriers = true;
+ CustomWriteBarriers = true;
+ }
+
+ virtual bool initializeCustomLowering(Module &M);
+ virtual bool performCustomLowering(Function &F);
+ };
+
+If any of these flags are set, then LLVM suppresses its default lowering for the
+corresponding intrinsics and instead calls ``performCustomLowering``.
+
+LLVM's default action for each intrinsic is as follows:
+
+* ``llvm.gcroot``: Leave it alone. The code generator must see it or the stack
+ map will not be computed.
+
+* ``llvm.gcread``: Substitute a ``load`` instruction.
+
+* ``llvm.gcwrite``: Substitute a ``store`` instruction.
+
+If ``CustomReadBarriers`` or ``CustomWriteBarriers`` are specified, then
+``performCustomLowering`` **must** eliminate the corresponding barriers.
+
+``performCustomLowering`` must comply with the same restrictions as
+:ref:`FunctionPass::runOnFunction <writing-an-llvm-pass-runOnFunction>`
+Likewise, ``initializeCustomLowering`` has the same semantics as
+:ref:`Pass::doInitialization(Module&)
+<writing-an-llvm-pass-doInitialization-mod>`
+
+The following can be used as a template:
+
+.. code-block:: c++
+
+ #include "llvm/IR/Module.h"
+ #include "llvm/IR/IntrinsicInst.h"
+
+ bool MyGC::initializeCustomLowering(Module &M) {
+ return false;
+ }
+
+ bool MyGC::performCustomLowering(Function &F) {
+ bool MadeChange = false;
+
+ for (Function::iterator BB = F.begin(), E = F.end(); BB != E; ++BB)
+ for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; )
+ if (IntrinsicInst *CI = dyn_cast<IntrinsicInst>(II++))
+ if (Function *F = CI->getCalledFunction())
+ switch (F->getIntrinsicID()) {
+ case Intrinsic::gcwrite:
+ // Handle llvm.gcwrite.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ case Intrinsic::gcread:
+ // Handle llvm.gcread.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ case Intrinsic::gcroot:
+ // Handle llvm.gcroot.
+ CI->eraseFromParent();
+ MadeChange = true;
+ break;
+ }
+
+ return MadeChange;
+ }
+
+.. _safe-points:
+
+Generating safe points: ``NeededSafePoints``
+--------------------------------------------
+
+LLVM can compute four kinds of safe points:
+
+.. code-block:: c++
+
+ namespace GC {
+ /// PointKind - The type of a collector-safe point.
+ ///
+ enum PointKind {
+ Loop, //< Instr is a loop (backwards branch).
+ Return, //< Instr is a return instruction.
+ PreCall, //< Instr is a call instruction.
+ PostCall //< Instr is the return address of a call.
+ };
+ }
+
+A collector can request any combination of the four by setting the
+``NeededSafePoints`` mask:
+
+.. code-block:: c++
+
+ MyGC::MyGC() {
+ NeededSafePoints = 1 << GC::Loop
+ | 1 << GC::Return
+ | 1 << GC::PreCall
+ | 1 << GC::PostCall;
+ }
+
+It can then use the following routines to access safe points.
+
+.. code-block:: c++
+
+ for (iterator I = begin(), E = end(); I != E; ++I) {
+ GCFunctionInfo *MD = *I;
+ size_t PointCount = MD->size();
+
+ for (GCFunctionInfo::iterator PI = MD->begin(),
+ PE = MD->end(); PI != PE; ++PI) {
+ GC::PointKind PointKind = PI->Kind;
+ unsigned PointNum = PI->Num;
+ }
+ }
+
+Almost every collector requires ``PostCall`` safe points, since these correspond
+to the moments when the function is suspended during a call to a subroutine.
+
+Threaded programs generally require ``Loop`` safe points to guarantee that the
+application will reach a safe point within a bounded amount of time, even if it
+is executing a long-running loop which contains no function calls.
+
+Threaded collectors may also require ``Return`` and ``PreCall`` safe points to
+implement "stop the world" techniques using self-modifying code, where it is
+important that the program not exit the function without reaching a safe point
+(because only the topmost function has been patched).
+
+.. _assembly:
+
+Emitting assembly code: ``GCMetadataPrinter``
+---------------------------------------------
+
+LLVM allows a plugin to print arbitrary assembly code before and after the rest
+of a module's assembly code. At the end of the module, the GC can compile the
+LLVM stack map into assembly code. (At the beginning, this information is not
+yet computed.)
+
+Since AsmWriter and CodeGen are separate components of LLVM, a separate abstract
+base class and registry is provided for printing assembly code, the
+``GCMetadaPrinter`` and ``GCMetadataPrinterRegistry``. The AsmWriter will look
+for such a subclass if the ``GCStrategy`` sets ``UsesMetadata``:
+
+.. code-block:: c++
+
+ MyGC::MyGC() {
+ UsesMetadata = true;
+ }
+
+This separation allows JIT-only clients to be smaller.
+
+Note that LLVM does not currently have analogous APIs to support code generation
+in the JIT, nor using the object writers.
+
+.. code-block:: c++
+
+ // lib/MyGC/MyGCPrinter.cpp - Example LLVM GC printer
+
+ #include "llvm/CodeGen/GCMetadataPrinter.h"
+ #include "llvm/Support/Compiler.h"
+
+ using namespace llvm;
+
+ namespace {
+ class LLVM_LIBRARY_VISIBILITY MyGCPrinter : public GCMetadataPrinter {
+ public:
+ virtual void beginAssembly(AsmPrinter &AP);
+
+ virtual void finishAssembly(AsmPrinter &AP);
+ };
+
+ GCMetadataPrinterRegistry::Add<MyGCPrinter>
+ X("mygc", "My bespoke garbage collector.");
+ }
+
+The collector should use ``AsmPrinter`` to print portable assembly code. The
+collector itself contains the stack map for the entire module, and may access
+the ``GCFunctionInfo`` using its own ``begin()`` and ``end()`` methods. Here's
+a realistic example:
+
+.. code-block:: c++
+
+ #include "llvm/CodeGen/AsmPrinter.h"
+ #include "llvm/IR/Function.h"
+ #include "llvm/IR/DataLayout.h"
+ #include "llvm/Target/TargetAsmInfo.h"
+ #include "llvm/Target/TargetMachine.h"
+
+ void MyGCPrinter::beginAssembly(AsmPrinter &AP) {
+ // Nothing to do.
+ }
+
+ void MyGCPrinter::finishAssembly(AsmPrinter &AP) {
+ MCStreamer &OS = AP.OutStreamer;
+ unsigned IntPtrSize = AP.TM.getDataLayout()->getPointerSize();
+
+ // Put this in the data section.
+ OS.SwitchSection(AP.getObjFileLowering().getDataSection());
+
+ // For each function...
+ for (iterator FI = begin(), FE = end(); FI != FE; ++FI) {
+ GCFunctionInfo &MD = **FI;
+
+ // A compact GC layout. Emit this data structure:
+ //
+ // struct {
+ // int32_t PointCount;
+ // void *SafePointAddress[PointCount];
+ // int32_t StackFrameSize; // in words
+ // int32_t StackArity;
+ // int32_t LiveCount;
+ // int32_t LiveOffsets[LiveCount];
+ // } __gcmap_<FUNCTIONNAME>;
+
+ // Align to address width.
+ AP.EmitAlignment(IntPtrSize == 4 ? 2 : 3);
+
+ // Emit PointCount.
+ OS.AddComment("safe point count");
+ AP.EmitInt32(MD.size());
+
+ // And each safe point...
+ for (GCFunctionInfo::iterator PI = MD.begin(),
+ PE = MD.end(); PI != PE; ++PI) {
+ // Emit the address of the safe point.
+ OS.AddComment("safe point address");
+ MCSymbol *Label = PI->Label;
+ AP.EmitLabelPlusOffset(Label/*Hi*/, 0/*Offset*/, 4/*Size*/);
+ }
+
+ // Stack information never change in safe points! Only print info from the
+ // first call-site.
+ GCFunctionInfo::iterator PI = MD.begin();
+
+ // Emit the stack frame size.
+ OS.AddComment("stack frame size (in words)");
+ AP.EmitInt32(MD.getFrameSize() / IntPtrSize);
+
+ // Emit stack arity, i.e. the number of stacked arguments.
+ unsigned RegisteredArgs = IntPtrSize == 4 ? 5 : 6;
+ unsigned StackArity = MD.getFunction().arg_size() > RegisteredArgs ?
+ MD.getFunction().arg_size() - RegisteredArgs : 0;
+ OS.AddComment("stack arity");
+ AP.EmitInt32(StackArity);
+
+ // Emit the number of live roots in the function.
+ OS.AddComment("live root count");
+ AP.EmitInt32(MD.live_size(PI));
+
+ // And for each live root...
+ for (GCFunctionInfo::live_iterator LI = MD.live_begin(PI),
+ LE = MD.live_end(PI);
+ LI != LE; ++LI) {
+ // Emit live root's offset within the stack frame.
+ OS.AddComment("stack index (offset / wordsize)");
+ AP.EmitInt32(LI->StackOffset);
+ }
+ }
+ }
+
+References
+==========
+
+.. _appel89:
+
+[Appel89] Runtime Tags Aren't Necessary. Andrew W. Appel. Lisp and Symbolic
+Computation 19(7):703-705, July 1989.
+
+.. _goldberg91:
+
+[Goldberg91] Tag-free garbage collection for strongly typed programming
+languages. Benjamin Goldberg. ACM SIGPLAN PLDI'91.
+
+.. _tolmach94:
+
+[Tolmach94] Tag-free garbage collection using explicit type parameters. Andrew
+Tolmach. Proceedings of the 1994 ACM conference on LISP and functional
+programming.
+
+.. _henderson02:
+
+[Henderson2002] `Accurate Garbage Collection in an Uncooperative Environment
+<http://citeseer.ist.psu.edu/henderson02accurate.html>`__
Added: www-releases/trunk/3.5.1/docs/_sources/GetElementPtr.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/GetElementPtr.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/GetElementPtr.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/GetElementPtr.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,536 @@
+=======================================
+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 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 (Clang) 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 *must* 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.5.1/docs/_sources/GettingStarted.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/GettingStarted.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/GettingStarted.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/GettingStarted.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,1329 @@
+====================================
+Getting Started with the LLVM System
+====================================
+
+.. contents::
+ :local:
+
+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 ``--enable-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.
+
+ * It is also possible to use `CMake <CMake.html>`_ instead of the makefiles.
+ With CMake it is possible to generate project files for several IDEs:
+ Xcode, 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 host platforms:
+
+================== ===================== =============
+OS Arch Compilers
+================== ===================== =============
+AuroraUX x86\ :sup:`1` GCC
+Linux x86\ :sup:`1` GCC, Clang
+Linux amd64 GCC, Clang
+Linux ARM\ :sup:`4` GCC, Clang
+Linux PowerPC GCC, Clang
+Solaris V9 (Ultrasparc) GCC
+FreeBSD x86\ :sup:`1` GCC, Clang
+FreeBSD amd64 GCC, Clang
+MacOS X\ :sup:`2` PowerPC GCC
+MacOS X x86 GCC, Clang
+Cygwin/Win32 x86\ :sup:`1, 3` GCC
+Windows x86\ :sup:`1` Visual Studio
+Windows x64 x86-64 Visual Studio
+================== ===================== =============
+
+.. note::
+
+ #. Code generation supported for Pentium processors and up
+ #. Code generation supported for 32-bit ABI only
+ #. To use LLVM modules on Win32-based system, you may configure LLVM
+ with ``--enable-shared``.
+ #. MCJIT not working well pre-v7, old JIT engine not supported any more.
+
+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/>`_ >=4.7.0 C/C++ compiler\ :sup:`1`
+`python <http://www.python.org/>`_ >=2.5 Automated test suite\ :sup:`2`
+`GNU M4 <http://savannah.gnu.org/projects/m4>`_ 1.4 Macro processor for configuration\ :sup:`3`
+`GNU Autoconf <http://www.gnu.org/software/autoconf/>`_ 2.60 Configuration script builder\ :sup:`3`
+`GNU Automake <http://www.gnu.org/software/automake/>`_ 1.9.6 aclocal macro generator\ :sup:`3`
+`libtool <http://savannah.gnu.org/projects/libtool>`_ 1.5.22 Shared library manager\ :sup:`3`
+`zlib <http://zlib.net>`_ >=1.2.3.4 Compression library\ :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.
+ #. 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.
+ #. Optional, adds compression / uncompression capabilities to selected LLVM
+ tools.
+
+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:
+
+Host C++ Toolchain, both Compiler and Standard Library
+------------------------------------------------------
+
+LLVM is very demanding of the host C++ compiler, and as such tends to expose
+bugs in the compiler. We are also planning to follow improvements and
+developments in the C++ language and library reasonably closely. As such, we
+require a modern host C++ toolchain, both compiler and standard library, in
+order to build LLVM.
+
+For the most popular host toolchains we check for specific minimum versions in
+our build systems:
+
+* Clang 3.1
+* GCC 4.7
+* Visual Studio 2012
+
+Anything older than these toolchains *may* work, but will require forcing the
+build system with a special option and is not really a supported host platform.
+Also note that older versions of these compilers have often crashed or
+miscompiled LLVM.
+
+For less widely used host toolchains such as ICC or xlC, be aware that a very
+recent version may be required to support all of the C++ features used in LLVM.
+
+We track certain versions of software that are *known* to fail when used as
+part of the host toolchain. These even include linkers at times.
+
+**GCC 4.6.3 on ARM**: Miscompiles ``llvm-readobj`` at ``-O3``. A test failure
+in ``test/Object/readobj-shared-object.test`` 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.
+
+**Clang 3.0 with libstdc++ 4.7.x**: a few Linux distributions (Ubuntu 12.10,
+Fedora 17) have both Clang 3.0 and libstdc++ 4.7 in their repositories. Clang
+3.0 does not implement a few builtins that are used in this library. We
+recommend using the system GCC to compile LLVM and Clang in this case.
+
+**Clang 3.0 on Mageia 2**. There's a packaging issue: Clang can not find at
+least some (``cxxabi.h``) libstdc++ headers.
+
+**Clang in C++11 mode and libstdc++ 4.7.2**. This version of libstdc++
+contained `a bug <http://gcc.gnu.org/bugzilla/show_bug.cgi?id=53841>`__ which
+causes Clang to refuse to compile condition_variable header file. At the time
+of writing, this breaks LLD build.
+
+Getting a Modern Host C++ Toolchain
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section mostly applies to Linux and older BSDs. On Mac OS X, you should
+have a sufficiently modern Xcode, or you will likely need to upgrade until you
+do. On Windows, just use Visual Studio 2012 as the host compiler, it is
+explicitly supported and widely available. FreeBSD 10.0 and newer have a modern
+Clang as the system compiler.
+
+However, some Linux distributions and some other or older BSDs sometimes have
+extremely old versions of GCC. These steps attempt to help you upgrade you
+compiler even on such a system. However, if at all possible, we encourage you
+to use a recent version of a distribution with a modern system compiler that
+meets these requirements. Note that it is tempting to to install a prior
+version of Clang and libc++ to be the host compiler, however libc++ was not
+well tested or set up to build on Linux until relatively recently. As
+a consequence, this guide suggests just using libstdc++ and a modern GCC as the
+initial host in a bootstrap, and then using Clang (and potentially libc++).
+
+The first step is to get a recent GCC toolchain installed. The most common
+distribution on which users have struggled with the version requirements is
+Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install
+the `toolchain testing PPA`_ and use it to install a modern GCC. There is
+a really nice discussions of this on the `ask ubuntu stack exchange`_. However,
+not all users can use PPAs and there are many other distributions, so it may be
+necessary (or just useful, if you're here you *are* doing compiler development
+after all) to build and install GCC from source. It is also quite easy to do
+these days.
+
+.. _toolchain testing PPA:
+ https://launchpad.net/~ubuntu-toolchain-r/+archive/test
+.. _ask ubuntu stack exchange:
+ http://askubuntu.com/questions/271388/how-to-install-gcc-4-8-in-ubuntu-12-04-from-the-terminal
+
+Easy steps for installing GCC 4.8.2:
+
+.. code-block:: console
+
+ % wget ftp://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
+ % tar -xvjf gcc-4.8.2.tar.bz2
+ % cd gcc-4.8.2
+ % ./contrib/download_prerequisites
+ % cd ..
+ % mkdir gcc-4.8.2-build
+ % cd gcc-4.8.2-build
+ % $PWD/../gcc-4.8.2/configure --prefix=$HOME/toolchains --enable-languages=c,c++
+ % make -j$(nproc)
+ % make install
+
+For more details, check out the excellent `GCC wiki entry`_, where I got most
+of this information from.
+
+.. _GCC wiki entry:
+ http://gcc.gnu.org/wiki/InstallingGCC
+
+Once you have a GCC toolchain, use it as your host compiler. Things should
+generally "just work". You may need to pass a special linker flag,
+``-Wl,-rpath,$HOME/toolchains/lib`` or some variant thereof to get things to
+find the libstdc++ DSO in this toolchain.
+
+When you build Clang, you will need to give *it* access to modern C++11
+standard library in order to use it as your new host in part of a bootstrap.
+There are two easy ways to do this, either build (and install) libc++ along
+with Clang and then use it with the ``-stdlib=libc++`` compile and link flag,
+or install Clang into the same prefix (``$HOME/toolchains`` above) as GCC.
+Clang will look within its own prefix for libstdc++ and use it if found. You
+can also add an explicit prefix for Clang to look in for a GCC toolchain with
+the ``--gcc-toolchain=/opt/my/gcc/prefix`` flag, passing it to both compile and
+link commands when using your just-built-Clang to bootstrap.
+
+.. _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.
+
+.. _checkout:
+
+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.4: **RELEASE_34/final**
+* Release 3.3: **RELEASE_33/final**
+* Release 3.2: **RELEASE_32/final**
+* 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:: console
+
+ % 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:: console
+
+ % git clone http://llvm.org/git/llvm.git
+
+If you want to check out clang too, run:
+
+.. code-block:: console
+
+ % cd llvm/tools
+ % git clone http://llvm.org/git/clang.git
+
+If you want to check out compiler-rt too, run:
+
+.. code-block:: console
+
+ % cd llvm/projects
+ % git clone http://llvm.org/git/compiler-rt.git
+
+If you want to check out the Test Suite Source Code (optional), run:
+
+.. code-block:: console
+
+ % cd llvm/projects
+ % git clone http://llvm.org/git/test-suite.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:: console
+
+ % 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:: console
+
+ % git diff --check master..mybranch
+
+The easiest way to generate a patch is as below:
+
+.. code-block:: console
+
+ % 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:: console
+
+ % 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:: console
+
+ % git format-patch --attach master..mybranch --stdout | git imap-send
+
+Then, your .git/config should have [imap] sections.
+
+.. code-block:: ini
+
+ [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:: console
+
+ % 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
+
+Likewise for compiler-rt and test-suite.
+
+To update this clone without generating git-svn tags that conflict with the
+upstream Git repo, run:
+
+.. code-block:: console
+
+ % 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)
+
+Likewise for compiler-rt and test-suite.
+
+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.
+
+For those who wish to be able to update an llvm repo/revert patches easily using
+git-svn, please look in the directory for the scripts ``git-svnup`` and
+``git-svnrevert``.
+
+To perform the aforementioned update steps go into your source directory and
+just type ``git-svnup`` or ``git svnup`` and everything will just work.
+
+If one wishes to revert a commit with git-svn, but do not want the git hash to
+escape into the commit message, one can use the script ``git-svnrevert`` or
+``git svnrevert`` which will take in the git hash for the commit you want to
+revert, look up the appropriate svn revision, and output a message where all
+references to the git hash have been replaced with the svn revision.
+
+To commit back changes via git-svn, use ``git svn dcommit``:
+
+.. code-block:: console
+
+ % git svn dcommit
+
+Note that git-svn will create one SVN commit for each Git commit you have pending,
+so squash and edit each commit before executing ``dcommit`` to make sure they all
+conform to the coding standards and the developers' policy.
+
+On success, ``dcommit`` will rebase against the HEAD of SVN, so to avoid conflict,
+please make sure your current branch is up-to-date (via fetch/rebase) before
+proceeding.
+
+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:: console
+
+ % rm -rf .git/svn
+ % git svn rebase -l
+
+Please, refer to the Git-SVN manual (``man git-svn``) for more information.
+
+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 check ``PATH`` for ``clang`` and GCC C |
+| | compilers (in this order). Use this variable to override |
+| | ``configure``\'s default behavior. |
++------------+-----------------------------------------------------------+
+| CXX | Tells ``configure`` which C++ compiler to use. By |
+| | default, ``configure`` will check ``PATH`` for |
+| | ``clang++`` and GCC C++ compilers (in this order). 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 a 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 "host" 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:
+
+ ``aarch64, arm, arm64, cpp, hexagon, mips, mipsel, mips64, mips64el, msp430,
+ powerpc, nvptx, r600, sparc, systemz, 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.
+
+To configure LLVM, follow these steps:
+
+#. Change directory into the object root directory:
+
+ .. code-block:: console
+
+ % cd OBJ_ROOT
+
+#. Run the ``configure`` script located in the LLVM source tree:
+
+ .. code-block:: console
+
+ % 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 a 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:: console
+
+ % 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:: console
+
+ % 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.
+
+This does not apply to building the documentation.
+LLVM's (non-Doxygen) documentation is produced with the
+`Sphinx <http://sphinx-doc.org/>`_ documentation generation system.
+There are some HTML documents that have not yet been converted to the new
+system (which uses the easy-to-read and easy-to-write
+`reStructuredText <http://sphinx-doc.org/rest.html>`_ plaintext markup
+language).
+The generated documentation is built in the ``SRC_ROOT/docs`` directory using
+a special makefile.
+For instructions on how to install Sphinx, see
+`Sphinx Introduction for LLVM Developers
+<http://lld.llvm.org/sphinx_intro.html>`_.
+After following the instructions there for installing Sphinx, build the LLVM
+HTML documentation by doing the following:
+
+.. code-block:: console
+
+ $ cd SRC_ROOT/docs
+ $ make -f Makefile.sphinx
+
+This creates a ``_build/html`` sub-directory with all of the HTML files, not
+just the generated ones.
+This directory corresponds to ``llvm.org/docs``.
+For example, ``_build/html/SphinxQuickstartTemplate.html`` corresponds to
+``llvm.org/docs/SphinxQuickstartTemplate.html``.
+The :doc:`SphinxQuickstartTemplate` is useful when creating a new document.
+
+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 built (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).
+
+Check :doc:`HowToCrossCompileLLVM` and `Clang docs on how to cross-compile in general
+<http://clang.llvm.org/docs/CrossCompilation.html>`_ for more information
+about cross-compiling.
+
+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:: console
+
+ % cd OBJ_ROOT
+
+* Run the ``configure`` script found in the LLVM source directory:
+
+ .. code-block:: console
+
+ % 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://en.wikipedia.org/wiki/binfmt_misc>`_
+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:: console
+
+ % 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:: console
+
+ % 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.
+
+``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 :doc:`Testing Guide
+<TestingGuide>` 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:: console
+
+ % 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 an LLVM bitcode file:
+
+ .. code-block:: console
+
+ % 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:: console
+
+ % ./hello
+
+ and
+
+ .. code-block:: console
+
+ % lli hello.bc
+
+ The second examples shows how to invoke the LLVM JIT, :doc:`lli
+ <CommandGuide/lli>`.
+
+#. Use the ``llvm-dis`` utility to take a look at the LLVM assembly code:
+
+ .. code-block:: console
+
+ % llvm-dis < hello.bc | less
+
+#. Compile the program to native assembly using the LLC code generator:
+
+ .. code-block:: console
+
+ % llc hello.bc -o hello.s
+
+#. Assemble the native assembly language file into a program:
+
+ .. code-block:: console
+
+ % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native # On Solaris
+
+ % gcc hello.s -o hello.native # On others
+
+#. Execute the native code program:
+
+ .. code-block:: console
+
+ % ./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.5.1/docs/_sources/GettingStartedVS.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/GettingStartedVS.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/GettingStartedVS.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/GettingStartedVS.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,234 @@
+==================================================================
+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 :doc:`GettingStarted` 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 2012 is fine. The LLVM
+source tree and object files, libraries and executables will consume
+approximately 3GB.
+
+Software
+--------
+You will need Visual Studio 2012 or higher.
+
+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 :doc:`LLVM CMake guide <CMake>` for detailed information about
+ how to configure the LLVM build.
+ * CMake generates project files for all build types. To select a specific
+ build type, use the Configuration manager from the VS IDE or the
+ ``/property:Configuration`` command line option when using MSBuild.
+
+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 in 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.
+
+9. Test LLVM on the command line:
+
+ * The LLVM tests can be run by changing directory to the llvm source
+ directory and running:
+
+ .. code-block:: bat
+
+ C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg test
+
+ This example assumes that Python is in your PATH variable, you
+ have built a Win32 Debug version of llvm with a standard out of
+ line build. You should not see any unexpected failures, but will
+ see many unsupported tests and expected failures.
+
+ A specific test or test directory can be run with:
+
+ .. code-block:: bat
+
+ C:\..\llvm> python ..\build\bin\llvm-lit --param build_config=Win32 --param build_mode=Debug --param llvm_site_config=../build/test/lit.site.cfg 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 an 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 :doc:`Frequently Asked Questions
+<FAQ>` 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.5.1/docs/_sources/GoldPlugin.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/GoldPlugin.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/GoldPlugin.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/GoldPlugin.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,172 @@
+====================
+The LLVM gold plugin
+====================
+
+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.
+
+* Download, configure and build gold with plugin support:
+
+ .. code-block:: bash
+
+ $ git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils
+ $ mkdir build
+ $ cd build
+ $ ../binutils/configure --enable-gold --enable-plugins --disable-werror
+ $ make all-gold
+
+ That should leave you with ``build/gold/ld-new`` which supports
+ the ``-plugin`` option. Running ``make`` will additionally build
+ ``build/binutils/ar`` and ``nm-new`` binaries supporting plugins.
+
+* Build the LLVMgold plugin: Configure LLVM with
+ ``--with-binutils-include=/path/to/binutils/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 should produce bitcode files from ``clang`` with the option
+``-flto``. This flag 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.
+
+``ar`` and ``nm`` also accept the ``-plugin`` option and it's possible to
+to install ``LLVMgold.so`` to ``/usr/lib/bfd-plugins`` for a seamless setup.
+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
+
+* 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
+* 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.5.1/docs/_sources/HowToAddABuilder.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/HowToAddABuilder.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/HowToAddABuilder.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/HowToAddABuilder.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,86 @@
+===================================================================
+How To Add Your Build Configuration To LLVM Buildbot Infrastructure
+===================================================================
+
+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.5.1/docs/_sources/HowToBuildOnARM.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/HowToBuildOnARM.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/HowToBuildOnARM.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/HowToBuildOnARM.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,69 @@
+===================================================================
+How To Build On ARM
+===================================================================
+
+Introduction
+============
+
+This document contains information about building/testing LLVM and
+Clang on an ARM machine.
+
+This document is *NOT* tailored to help you cross-compile LLVM/Clang
+to ARM on another architecture, for example an x86_64 machine. To find
+out more about cross-compiling, please check :doc:`HowToCrossCompileLLVM`.
+
+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 preferred 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 (e.g., 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, e.g., 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 --enable-optimized --enable-assertions
+
+#. ARM development boards can be unstable and you may experience that cores
+ are disappearing, caches being flushed on every big.LITTLE switch, and
+ other similar issues. To help ease the effect of this, set the Linux
+ scheduler to "performance" on **all** cores using this little script:
+
+ .. code-block:: bash
+
+ # The code below requires the package 'cpufrequtils' to be installed.
+ for ((cpu=0; cpu<`grep -c proc /proc/cpuinfo`; cpu++)); do
+ sudo cpufreq-set -c $cpu -g performance
+ done
+
+#. Running the build on SD cards is ok, but they are more prone to failures
+ than good quality USB sticks, and those are more prone to failures than
+ external hard-drives (those are also a lot faster). So, at least, you
+ should consider to buy a fast USB stick. On systems with a fast eMMC,
+ that's a good option too.
+
+#. Make sure you have a decent power supply (dozens of dollars worth) that can
+ provide *at least* 4 amperes, this is especially important if you use USB
+ devices with your board.
Added: www-releases/trunk/3.5.1/docs/_sources/HowToCrossCompileLLVM.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/HowToCrossCompileLLVM.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/HowToCrossCompileLLVM.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/HowToCrossCompileLLVM.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,175 @@
+===================================================================
+How To Cross-Compile Clang/LLVM using Clang/LLVM
+===================================================================
+
+Introduction
+============
+
+This document contains information about building LLVM and
+Clang on host machine, targeting another platform.
+
+For more information on how to use Clang as a cross-compiler,
+please check http://clang.llvm.org/docs/CrossCompilation.html.
+
+TODO: Add MIPS and other platforms to this document.
+
+Cross-Compiling from x86_64 to ARM
+==================================
+
+In this use case, we'll be using CMake and Ninja, on a Debian-based Linux
+system, cross-compiling from an x86_64 host (most Intel and AMD chips
+nowadays) to a hard-float ARM target (most ARM targets nowadays).
+
+The packages you'll need are:
+
+ * ``cmake``
+ * ``ninja-build`` (from backports in Ubuntu)
+ * ``gcc-4.7-arm-linux-gnueabihf``
+ * ``gcc-4.7-multilib-arm-linux-gnueabihf``
+ * ``binutils-arm-linux-gnueabihf``
+ * ``libgcc1-armhf-cross``
+ * ``libsfgcc1-armhf-cross``
+ * ``libstdc++6-armhf-cross``
+ * ``libstdc++6-4.7-dev-armhf-cross``
+
+Configuring CMake
+-----------------
+
+For more information on how to configure CMake for LLVM/Clang,
+see :doc:`CMake`.
+
+The CMake options you need to add are:
+ * ``-DCMAKE_CROSSCOMPILING=True``
+ * ``-DCMAKE_INSTALL_PREFIX=<install-dir>``
+ * ``-DLLVM_TABLEGEN=<path-to-host-bin>/llvm-tblgen``
+ * ``-DCLANG_TABLEGEN=<path-to-host-bin>/clang-tblgen``
+ * ``-DLLVM_DEFAULT_TARGET_TRIPLE=arm-linux-gnueabihf``
+ * ``-DLLVM_TARGET_ARCH=ARM``
+ * ``-DLLVM_TARGETS_TO_BUILD=ARM``
+ * ``-DCMAKE_CXX_FLAGS='-target armv7a-linux-gnueabihf -mcpu=cortex-a9 -I/usr/arm-linux-gnueabihf/include/c++/4.7.2/arm-linux-gnueabihf/ -I/usr/arm-linux-gnueabihf/include/ -mfloat-abi=hard -ccc-gcc-name arm-linux-gnueabihf-gcc'``
+
+The TableGen options are required to compile it with the host compiler,
+so you'll need to compile LLVM (or at least ``llvm-tblgen``) to your host
+platform before you start. The CXX flags define the target, cpu (which
+defaults to ``fpu=VFP3`` with NEON), and forcing the hard-float ABI. If you're
+using Clang as a cross-compiler, you will *also* have to set ``-ccc-gcc-name``,
+to make sure it picks the correct linker.
+
+Most of the time, what you want is to have a native compiler to the
+platform itself, but not others. It might not even be feasible to
+produce x86 binaries from ARM targets, so there's no point in compiling
+all back-ends. For that reason, you should also set the
+``TARGETS_TO_BUILD`` to only build the ARM back-end.
+
+You must set the ``CMAKE_INSTALL_PREFIX``, otherwise a ``ninja install``
+will copy ARM binaries to your root filesystem, which is not what you
+want.
+
+Hacks
+-----
+
+There are some bugs in current LLVM, which require some fiddling before
+running CMake:
+
+#. If you're using Clang as the cross-compiler, there is a problem in
+ the LLVM ARM back-end that is producing absolute relocations on
+ position-independent code (``R_ARM_THM_MOVW_ABS_NC``), so for now, you
+ should disable PIC:
+
+ .. code-block:: bash
+
+ -DLLVM_ENABLE_PIC=False
+
+ This is not a problem, since Clang/LLVM libraries are statically
+ linked anyway, it shouldn't affect much.
+
+#. The ARM libraries won't be installed in your system, and possibly
+ not easily installable anyway, so you'll have to build/download
+ them separately. But the CMake prepare step, which checks for
+ dependencies, will check the *host* libraries, not the *target*
+ ones.
+
+ A quick way of getting the libraries is to download them from
+ a distribution repository, like Debian (http://packages.debian.org/wheezy/),
+ and download the missing libraries. Note that the ``libXXX``
+ will have the shared objects (``.so``) and the ``libXXX-dev`` will
+ give you the headers and the static (``.a``) library. Just in
+ case, download both.
+
+ The ones you need for ARM are: ``libtinfo``, ``zlib1g``,
+ ``libxml2`` and ``liblzma``. In the Debian repository you'll
+ find downloads for all architectures.
+
+ After you download and unpack all ``.deb`` packages, copy all
+ ``.so`` and ``.a`` to a directory, make the appropriate
+ symbolic links (if necessary), and add the relevant ``-L``
+ and ``-I`` paths to ``-DCMAKE_CXX_FLAGS`` above.
+
+
+Running CMake and Building
+--------------------------
+
+Finally, if you're using your platform compiler, run:
+
+ .. code-block:: bash
+
+ $ cmake -G Ninja <source-dir> <options above>
+
+If you're using Clang as the cross-compiler, run:
+
+ .. code-block:: bash
+
+ $ CC='clang' CXX='clang++' cmake -G Ninja <source-dir> <options above>
+
+If you have ``clang``/``clang++`` on the path, it should just work, and special
+Ninja files will be created in the build directory. I strongly suggest
+you to run ``cmake`` on a separate build directory, *not* inside the
+source tree.
+
+To build, simply type:
+
+ .. code-block:: bash
+
+ $ ninja
+
+It should automatically find out how many cores you have, what are
+the rules that needs building and will build the whole thing.
+
+You can't run ``ninja check-all`` on this tree because the created
+binaries are targeted to ARM, not x86_64.
+
+Installing and Using
+--------------------
+
+After the LLVM/Clang has built successfully, you should install it
+via:
+
+ .. code-block:: bash
+
+ $ ninja install
+
+which will create a sysroot on the install-dir. You can then tar
+that directory into a binary with the full triple name (for easy
+identification), like:
+
+ .. code-block:: bash
+
+ $ ln -sf <install-dir> arm-linux-gnueabihf-clang
+ $ tar zchf arm-linux-gnueabihf-clang.tar.gz arm-linux-gnueabihf-clang
+
+If you copy that tarball to your target board, you'll be able to use
+it for running the test-suite, for example. Follow the guidelines at
+http://llvm.org/docs/lnt/quickstart.html, unpack the tarball in the
+test directory, and use options:
+
+ .. code-block:: bash
+
+ $ ./sandbox/bin/python sandbox/bin/lnt runtest nt \
+ --sandbox sandbox \
+ --test-suite `pwd`/test-suite \
+ --cc `pwd`/arm-linux-gnueabihf-clang/bin/clang \
+ --cxx `pwd`/arm-linux-gnueabihf-clang/bin/clang++
+
+Remember to add the ``-jN`` options to ``lnt`` to the number of CPUs
+on your board. Also, the path to your clang has to be absolute, so
+you'll need the `pwd` trick above.
Added: www-releases/trunk/3.5.1/docs/_sources/HowToReleaseLLVM.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/HowToReleaseLLVM.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/HowToReleaseLLVM.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/HowToReleaseLLVM.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,441 @@
+=================================
+How To Release LLVM To The Public
+=================================
+
+.. contents::
+ :local:
+ :depth: 1
+
+Introduction
+============
+
+This document contains information about successfully releasing LLVM ---
+including subprojects: e.g., ``clang`` and ``dragonegg`` --- to the public. It
+is the Release Manager's responsibility to ensure that a high quality build of
+LLVM is released.
+
+If you're looking for the document on how to test the release candidates and
+create the binary packages, please refer to the :doc:`ReleaseProcess` instead.
+
+.. _timeline:
+
+Release Timeline
+================
+
+LLVM is released on a time based schedule --- with major releases roughly
+every 6 months. In between major releases there may be dot releases.
+The release manager will determine if and when to make a dot release based
+on feedback from the community. Typically, dot releases should be made if
+there are large number of bug-fixes in the stable branch or a critical bug
+has been discovered that affects a large number of users.
+
+Unless otherwise stated, dot releases will follow the same procedure as
+major releases.
+
+The release process is roughly as follows:
+
+* 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.
+
+* Create release branch and begin release process.
+
+* 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.
+
+* Generate and send out the second release candidate sources. Only *critial*
+ 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.
+
+* The release notes are updated.
+
+* Finally, release!
+
+The release process will be accelerated for dot releases. If the first round
+of testing finds no critical bugs and no regressions since the last major release,
+then additional rounds of testing will not be required.
+
+Release Process
+===============
+
+.. contents::
+ :local:
+
+Release Administrative Tasks
+----------------------------
+
+This section describes a few administrative tasks that need to be done for the
+release process to begin. Specifically, it involves:
+
+* Creating the release branch,
+
+* Setting version numbers, and
+
+* Tagging release candidates for the release team to begin testing.
+
+Create Release Branch
+^^^^^^^^^^^^^^^^^^^^^
+
+Branch the Subversion trunk using the following procedure:
+
+#. 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.
+
+#. Verify that the current Subversion trunk is in decent shape by
+ examining nightly tester and buildbot results.
+
+#. Create the release branch for ``llvm``, ``clang``, the ``test-suite``, and
+ ``dragonegg`` from the last known good revision. The branch's name is
+ ``release_XY``, where ``X`` is the major and ``Y`` the minor release
+ numbers. The branches should be created using the following commands:
+
+ ::
+
+ $ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
+ https://llvm.org/svn/llvm-project/llvm/branches/release_XY
+
+ $ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
+ https://llvm.org/svn/llvm-project/cfe/branches/release_XY
+
+ $ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \
+ https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY
+
+ $ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
+ https://llvm.org/svn/llvm-project/test-suite/branches/release_XY
+
+#. Advise developers that they may now check their patches into the Subversion
+ tree again.
+
+#. 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:
+
+ ::
+
+ $ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XY llvm-X.Y
+
+ $ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XY clang-X.Y
+
+ $ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY dragonegg-X.Y
+
+ $ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XY test-suite-X.Y
+
+Update LLVM Version
+^^^^^^^^^^^^^^^^^^^
+
+After creating the LLVM release branch, update the release branches'
+``autoconf`` and ``configure.ac`` versions from '``X.Ysvn``' to '``X.Y``'.
+Update it on mainline as well to be the next version ('``X.Y+1svn``').
+Regenerate the configure scripts for both ``llvm`` and the ``test-suite``.
+
+In addition, the version numbers of all the Bugzilla components must be updated
+for the next release.
+
+Build the LLVM Release Candidates
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create release candidates for ``llvm``, ``clang``, ``dragonegg``, and the LLVM
+``test-suite`` by tagging the branch with the respective release candidate
+number. For instance, to create **Release Candidate 1** you would issue the
+following commands:
+
+::
+
+ $ svn mkdir https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XYZ
+ $ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
+ https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XYZ/rc1
+
+ $ svn mkdir https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XYZ
+ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
+ https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XYZ/rc1
+
+ $ svn mkdir https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XYZ
+ $ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
+ https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XYZ/rc1
+
+ $ svn mkdir https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XYZ
+ $ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
+ https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XYZ/rc1
+
+Similarly, **Release Candidate 2** would be named ``RC2`` 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 ``RELEASE_XYZ``
+directory as ``Final`` (c.f. :ref:`tag`).
+
+The Release Manager may supply pre-packaged source tarballs for users. This can
+be done with the following commands:
+
+::
+
+ $ svn export https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XYZ/rc1 llvm-X.Yrc1
+ $ svn export https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XYZ/rc1 clang-X.Yrc1
+ $ svn export https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XYZ/rc1 dragonegg-X.Yrc1
+ $ svn export https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XYZ/rc1 llvm-test-X.Yrc1
+
+ $ tar -cvf - llvm-X.Yrc1 | gzip > llvm-X.Yrc1.src.tar.gz
+ $ tar -cvf - clang-X.Yrc1 | gzip > clang-X.Yrc1.src.tar.gz
+ $ tar -cvf - dragonegg-X.Yrc1 | gzip > dragonegg-X.Yrc1.src.tar.gz
+ $ tar -cvf - llvm-test-X.Yrc1 | gzip > llvm-test-X.Yrc1.src.tar.gz
+
+Building the Release
+--------------------
+
+The builds of ``llvm``, ``clang``, and ``dragonegg`` *must* be free of
+errors and warnings in Debug, Release+Asserts, and Release builds. If all
+builds are clean, then the release passes Build Qualification.
+
+The ``make`` options for building the different modes:
+
++-----------------+---------------------------------------------+
+| Mode | Options |
++=================+=============================================+
+| Debug | ``ENABLE_OPTIMIZED=0`` |
++-----------------+---------------------------------------------+
+| Release+Asserts | ``ENABLE_OPTIMIZED=1`` |
++-----------------+---------------------------------------------+
+| Release | ``ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1`` |
++-----------------+---------------------------------------------+
+
+Build LLVM
+^^^^^^^^^^
+
+Build ``Debug``, ``Release+Asserts``, and ``Release`` versions
+of ``llvm`` on all supported platforms. Directions to build ``llvm``
+are :doc:`here <GettingStarted>`.
+
+Build Clang Binary Distribution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Creating the ``clang`` binary distribution (Debug/Release+Asserts/Release)
+requires performing the following steps for each supported platform:
+
+#. Build clang according to the directions `here
+ <http://clang.llvm.org/get_started.html>`__.
+
+#. Build both a Debug and Release version of clang. The binary will be the
+ Release build.
+
+#. Package ``clang`` (details to follow).
+
+Target Specific Build Details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The table below specifies which compilers are used for each Arch/OS combination
+when qualifying the build of ``llvm``, ``clang``, and ``dragonegg``.
+
++--------------+---------------+----------------------+
+| Architecture | OS | compiler |
++==============+===============+======================+
+| x86-32 | Mac OS 10.5 | gcc 4.0.1 |
++--------------+---------------+----------------------+
+| x86-32 | Linux | gcc 4.2.X, gcc 4.3.X |
++--------------+---------------+----------------------+
+| x86-32 | FreeBSD | gcc 4.2.X |
++--------------+---------------+----------------------+
+| x86-32 | mingw | gcc 3.4.5 |
++--------------+---------------+----------------------+
+| x86-64 | Mac OS 10.5 | gcc 4.0.1 |
++--------------+---------------+----------------------+
+| x86-64 | Linux | gcc 4.2.X, gcc 4.3.X |
++--------------+---------------+----------------------+
+| x86-64 | FreeBSD | gcc 4.2.X |
++--------------+---------------+----------------------+
+| ARMv7 | Linux | gcc 4.6.X, gcc 4.7.X |
++--------------+---------------+----------------------+
+
+Release Qualification Criteria
+------------------------------
+
+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.)
+
+**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.**
+
+Qualify LLVM
+^^^^^^^^^^^^
+
+LLVM is qualified when it has a clean test run without a front-end. And it has
+no regressions when using either ``clang`` or ``dragonegg`` with the
+``test-suite`` from the previous release.
+
+Qualify Clang
+^^^^^^^^^^^^^
+
+``Clang`` is qualified when front-end specific tests in the ``llvm`` regression
+test suite all pass, clang's own test suite passes cleanly, and there are no
+regressions in the ``test-suite``.
+
+Specific Target Qualification Details
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
++--------------+-------------+----------------+-----------------------------+
+| Architecture | OS | clang baseline | tests |
++==============+=============+================+=============================+
+| x86-32 | Linux | last release | llvm regression tests, |
+| | | | clang regression tests, |
+| | | | test-suite (including spec) |
++--------------+-------------+----------------+-----------------------------+
+| x86-32 | FreeBSD | last release | llvm regression tests, |
+| | | | clang regression tests, |
+| | | | test-suite |
++--------------+-------------+----------------+-----------------------------+
+| x86-32 | mingw | none | QT |
++--------------+-------------+----------------+-----------------------------+
+| x86-64 | Mac OS 10.X | last release | llvm regression tests, |
+| | | | clang regression tests, |
+| | | | test-suite (including spec) |
++--------------+-------------+----------------+-----------------------------+
+| x86-64 | Linux | last release | llvm regression tests, |
+| | | | clang regression tests, |
+| | | | test-suite (including spec) |
++--------------+-------------+----------------+-----------------------------+
+| x86-64 | FreeBSD | last release | llvm regression tests, |
+| | | | clang regression tests, |
+| | | | test-suite |
++--------------+-------------+----------------+-----------------------------+
+| ARMv7A | Linux | last release | llvm regression tests, |
+| | | | clang regression tests, |
+| | | | test-suite |
++--------------+-------------+----------------+-----------------------------+
+
+Community Testing
+-----------------
+
+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:
+
+#. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``
+ binary. Build LLVM. Run ``make check`` and the full LLVM test suite (``make
+ TEST=nightly report``).
+
+#. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the ``clang`` sources. Compile
+ everything. Run ``make check`` and the full LLVM test suite (``make
+ TEST=nightly report``).
+
+Ask LLVM developers to submit the test suite report and ``make check`` 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 ``make check`` is at least
+clean.
+
+During the first round of testing, all regressions must be fixed before the
+second release candidate is tagged.
+
+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. *This is not
+the time to solve additional and unrelated bugs!* If no patches are merged in,
+the release is determined to be ready and the release manager may move onto the
+next stage.
+
+Release Patch Rules
+-------------------
+
+Below are the rules regarding patching the release branch:
+
+#. Patches applied to the release branch may only be applied by the release
+ manager.
+
+#. 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.
+
+#. During the remaining rounds of testing, only patches that fix critical
+ regressions may be applied.
+
+#. For dot releases all patches must mantain both API and ABI compatibility with
+ the previous major release. Only bugfixes will be accepted.
+
+Release Final Tasks
+-------------------
+
+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.
+
+Update Documentation
+^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+.. _tag:
+
+Tag the LLVM Final Release
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Tag the final release sources using the following procedure:
+
+::
+
+ $ svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XY \
+ https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XYZ/Final
+
+ $ svn copy https://llvm.org/svn/llvm-project/cfe/branches/release_XY \
+ https://llvm.org/svn/llvm-project/cfe/tags/RELEASE_XYZ/Final
+
+ $ svn copy https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY \
+ https://llvm.org/svn/llvm-project/dragonegg/tags/RELEASE_XYZ/Final
+
+ $ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XY \
+ https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XYZ/Final
+
+Update the LLVM Demo Page
+-------------------------
+
+The LLVM demo page must be updated to use the new release. This consists of
+using the new ``clang`` binary and building LLVM.
+
+Update the LLVM Website
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The website must be updated before the release announcement is sent out. Here
+is what to do:
+
+#. Check out the ``www`` module from Subversion.
+
+#. Create a new subdirectory ``X.Y`` in the releases directory.
+
+#. Commit the ``llvm``, ``test-suite``, ``clang`` source, ``clang binaries``,
+ ``dragonegg`` source, and ``dragonegg`` binaries in this new directory.
+
+#. Copy and commit the ``llvm/docs`` and ``LICENSE.txt`` files into this new
+ directory. The docs should be built with ``BUILD_FOR_WEBSITE=1``.
+
+#. Commit the ``index.html`` to the ``release/X.Y`` directory to redirect (use
+ from previous release).
+
+#. Update the ``releases/download.html`` file with the new release.
+
+#. Update the ``releases/index.html`` with the new release and link to release
+ documentation.
+
+#. Finally, update the main page (``index.html`` and sidebar) to point to the
+ new release and release announcement. Make sure this all gets committed back
+ into Subversion.
+
+Announce the Release
+^^^^^^^^^^^^^^^^^^^^
+
+Have Chris send out the release announcement when everything is finished.
+
Added: www-releases/trunk/3.5.1/docs/_sources/HowToSetUpLLVMStyleRTTI.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/HowToSetUpLLVMStyleRTTI.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/HowToSetUpLLVMStyleRTTI.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/HowToSetUpLLVMStyleRTTI.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,400 @@
+======================================================
+How to set up LLVM-style RTTI for your class hierarchy
+======================================================
+
+.. 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 *,
+ ::std::enable_if<
+ ::std::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
+
+A Bug to be Aware Of
+--------------------
+
+The example just given opens the door to bugs where the ``classof``\s are
+not updated to match the ``Kind`` enum when adding (or removing) classes to
+(from) the hierarchy.
+
+Continuing the example above, suppose we add a ``SomewhatSpecialSquare`` as
+a subclass of ``Square``, and update the ``ShapeKind`` enum like so:
+
+.. code-block:: c++
+
+ enum ShapeKind {
+ SK_Square,
+ SK_SpecialSquare,
+ SK_OtherSpecialSquare,
+ + SK_SomewhatSpecialSquare,
+ SK_Circle
+ }
+
+Now, suppose that we forget to update ``Square::classof()``, so it still
+looks like:
+
+.. code-block:: c++
+
+ static bool classof(const Shape *S) {
+ // BUG: Returns false when S->getKind() == SK_SomewhatSpecialSquare,
+ // even though SomewhatSpecialSquare "is a" Square.
+ return S->getKind() >= SK_Square &&
+ S->getKind() <= SK_OtherSpecialSquare;
+ }
+
+As the comment indicates, this code contains a bug. A straightforward and
+non-clever way to avoid this is to introduce an explicit ``SK_LastSquare``
+entry in the enum when adding the first subclass(es). For example, we could
+rewrite the example at the beginning of `Concrete Bases and Deeper
+Hierarchies`_ as:
+
+.. code-block:: c++
+
+ enum ShapeKind {
+ SK_Square,
+ + SK_SpecialSquare,
+ + SK_OtherSpecialSquare,
+ + SK_LastSquare,
+ SK_Circle
+ }
+ ...
+ // Square::classof()
+ - 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_LastSquare;
+ + }
+
+Then, adding new subclasses is easy:
+
+.. code-block:: c++
+
+ enum ShapeKind {
+ SK_Square,
+ SK_SpecialSquare,
+ SK_OtherSpecialSquare,
+ + SK_SomewhatSpecialSquare,
+ SK_LastSquare,
+ SK_Circle
+ }
+
+Notice that ``Square::classof`` does not need to be changed.
+
+.. _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.5.1/docs/_sources/HowToSubmitABug.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/HowToSubmitABug.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/HowToSubmitABug.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/HowToSubmitABug.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,229 @@
+================================
+How to submit an LLVM bug report
+================================
+
+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 ``clang`` command line as you were when the crash
+occurred, but with the following extra command line options:
+
+* ``-O0 -emit-llvm``: If ``clang`` 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 ``clang`` 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 ``clang``
+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 ``clang``, 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 clang. 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 clang in the code generator, compile your
+source file to a .bc file by passing "``-emit-llvm -c -o foo.bc``" to
+clang (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 clang 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.5.1/docs/_sources/HowToUseAttributes.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/HowToUseAttributes.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/HowToUseAttributes.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/HowToUseAttributes.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,81 @@
+=====================
+How To Use Attributes
+=====================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Attributes in LLVM have changed in some fundamental ways. It was necessary to
+do this to support expanding the attributes to encompass more than a handful of
+attributes --- e.g. command line options. The old way of handling attributes
+consisted of representing them as a bit mask of values. This bit mask was
+stored in a "list" structure that was reference counted. The advantage of this
+was that attributes could be manipulated with 'or's and 'and's. The
+disadvantage of this was that there was limited room for expansion, and
+virtually no support for attribute-value pairs other than alignment.
+
+In the new scheme, an ``Attribute`` object represents a single attribute that's
+uniqued. You use the ``Attribute::get`` methods to create a new ``Attribute``
+object. An attribute can be a single "enum" value (the enum being the
+``Attribute::AttrKind`` enum), a string representing a target-dependent
+attribute, or an attribute-value pair. Some examples:
+
+* Target-independent: ``noinline``, ``zext``
+* Target-dependent: ``"no-sse"``, ``"thumb2"``
+* Attribute-value pair: ``"cpu" = "cortex-a8"``, ``align = 4``
+
+Note: for an attribute value pair, we expect a target-dependent attribute to
+have a string for the value.
+
+``Attribute``
+=============
+An ``Attribute`` object is designed to be passed around by value.
+
+Because attributes are no longer represented as a bit mask, you will need to
+convert any code which does treat them as a bit mask to use the new query
+methods on the Attribute class.
+
+``AttributeSet``
+================
+
+The ``AttributeSet`` class replaces the old ``AttributeList`` class. The
+``AttributeSet`` stores a collection of Attribute objects for each kind of
+object that may have an attribute associated with it: the function as a
+whole, the return type, or the function's parameters. A function's attributes
+are at index ``AttributeSet::FunctionIndex``; the return type's attributes are
+at index ``AttributeSet::ReturnIndex``; and the function's parameters'
+attributes are at indices 1, ..., n (where 'n' is the number of parameters).
+Most methods on the ``AttributeSet`` class take an index parameter.
+
+An ``AttributeSet`` is also a uniqued and immutable object. You create an
+``AttributeSet`` through the ``AttributeSet::get`` methods. You can add and
+remove attributes, which result in the creation of a new ``AttributeSet``.
+
+An ``AttributeSet`` object is designed to be passed around by value.
+
+Note: It is advised that you do *not* use the ``AttributeSet`` "introspection"
+methods (e.g. ``Raw``, ``getRawPointer``, etc.). These methods break
+encapsulation, and may be removed in a future release (i.e. LLVM 4.0).
+
+``AttrBuilder``
+===============
+
+Lastly, we have a "builder" class to help create the ``AttributeSet`` object
+without having to create several different intermediate uniqued
+``AttributeSet`` objects. The ``AttrBuilder`` class allows you to add and
+remove attributes at will. The attributes won't be uniqued until you call the
+appropriate ``AttributeSet::get`` method.
+
+An ``AttrBuilder`` object is *not* designed to be passed around by value. It
+should be passed by reference.
+
+Note: It is advised that you do *not* use the ``AttrBuilder::addRawValue()``
+method or the ``AttrBuilder(uint64_t Val)`` constructor. These are for
+backwards compatibility and may be removed in a future release (i.e. LLVM 4.0).
+
+And that's basically it! A lot of functionality is hidden behind these classes,
+but the interfaces are pretty straight forward.
+
Added: www-releases/trunk/3.5.1/docs/_sources/HowToUseInstrMappings.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/HowToUseInstrMappings.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/HowToUseInstrMappings.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/HowToUseInstrMappings.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,175 @@
+===============================
+How To Use Instruction Mappings
+===============================
+
+.. 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.
Added: www-releases/trunk/3.5.1/docs/_sources/InAlloca.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/InAlloca.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/InAlloca.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/InAlloca.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,160 @@
+==========================================
+Design and Usage of the InAlloca Attribute
+==========================================
+
+Introduction
+============
+
+The :ref:`inalloca <attr_inalloca>` attribute is designed to allow
+taking the address of an aggregate argument that is being passed by
+value through memory. Primarily, this feature is required for
+compatibility with the Microsoft C++ ABI. Under that ABI, class
+instances that are passed by value are constructed directly into
+argument stack memory. Prior to the addition of inalloca, calls in LLVM
+were indivisible instructions. There was no way to perform intermediate
+work, such as object construction, between the first stack adjustment
+and the final control transfer. With inalloca, all arguments passed in
+memory are modelled as a single alloca, which can be stored to prior to
+the call. Unfortunately, this complicated feature comes with a large
+set of restrictions designed to bound the lifetime of the argument
+memory around the call.
+
+For now, it is recommended that frontends and optimizers avoid producing
+this construct, primarily because it forces the use of a base pointer.
+This feature may grow in the future to allow general mid-level
+optimization, but for now, it should be regarded as less efficient than
+passing by value with a copy.
+
+Intended Usage
+==============
+
+The example below is the intended LLVM IR lowering for some C++ code
+that passes two default-constructed ``Foo`` objects to ``g`` in the
+32-bit Microsoft C++ ABI.
+
+.. code-block:: c++
+
+ // Foo is non-trivial.
+ struct Foo { int a, b; Foo(); ~Foo(); Foo(const Foo &); };
+ void g(Foo a, Foo b);
+ void f() {
+ g(Foo(), Foo());
+ }
+
+.. code-block:: llvm
+
+ %struct.Foo = type { i32, i32 }
+ declare void @Foo_ctor(%struct.Foo* %this)
+ declare void @Foo_dtor(%struct.Foo* %this)
+ declare void @g(<{ %struct.Foo, %struct.Foo }>* inalloca %memargs)
+
+ define void @f() {
+ entry:
+ %base = call i8* @llvm.stacksave()
+ %memargs = alloca <{ %struct.Foo, %struct.Foo }>
+ %b = getelementptr <{ %struct.Foo, %struct.Foo }>* %memargs, i32 1
+ call void @Foo_ctor(%struct.Foo* %b)
+
+ ; If a's ctor throws, we must destruct b.
+ %a = getelementptr <{ %struct.Foo, %struct.Foo }>* %memargs, i32 0
+ invoke void @Foo_ctor(%struct.Foo* %a)
+ to label %invoke.cont unwind %invoke.unwind
+
+ invoke.cont:
+ call void @g(<{ %struct.Foo, %struct.Foo }>* inalloca %memargs)
+ call void @llvm.stackrestore(i8* %base)
+ ...
+
+ invoke.unwind:
+ call void @Foo_dtor(%struct.Foo* %b)
+ call void @llvm.stackrestore(i8* %base)
+ ...
+ }
+
+To avoid stack leaks, the frontend saves the current stack pointer with
+a call to :ref:`llvm.stacksave <int_stacksave>`. Then, it allocates the
+argument stack space with alloca and calls the default constructor. The
+default constructor could throw an exception, so the frontend has to
+create a landing pad. The frontend has to destroy the already
+constructed argument ``b`` before restoring the stack pointer. If the
+constructor does not unwind, ``g`` is called. In the Microsoft C++ ABI,
+``g`` will destroy its arguments, and then the stack is restored in
+``f``.
+
+Design Considerations
+=====================
+
+Lifetime
+--------
+
+The biggest design consideration for this feature is object lifetime.
+We cannot model the arguments as static allocas in the entry block,
+because all calls need to use the memory at the top of the stack to pass
+arguments. We cannot vend pointers to that memory at function entry
+because after code generation they will alias.
+
+The rule against allocas between argument allocations and the call site
+avoids this problem, but it creates a cleanup problem. Cleanup and
+lifetime is handled explicitly with stack save and restore calls. In
+the future, we may want to introduce a new construct such as ``freea``
+or ``afree`` to make it clear that this stack adjusting cleanup is less
+powerful than a full stack save and restore.
+
+Nested Calls and Copy Elision
+-----------------------------
+
+We also want to be able to support copy elision into these argument
+slots. This means we have to support multiple live argument
+allocations.
+
+Consider the evaluation of:
+
+.. code-block:: c++
+
+ // Foo is non-trivial.
+ struct Foo { int a; Foo(); Foo(const &Foo); ~Foo(); };
+ Foo bar(Foo b);
+ int main() {
+ bar(bar(Foo()));
+ }
+
+In this case, we want to be able to elide copies into ``bar``'s argument
+slots. That means we need to have more than one set of argument frames
+active at the same time. First, we need to allocate the frame for the
+outer call so we can pass it in as the hidden struct return pointer to
+the middle call. Then we do the same for the middle call, allocating a
+frame and passing its address to ``Foo``'s default constructor. By
+wrapping the evaluation of the inner ``bar`` with stack save and
+restore, we can have multiple overlapping active call frames.
+
+Callee-cleanup Calling Conventions
+----------------------------------
+
+Another wrinkle is the existence of callee-cleanup conventions. On
+Windows, all methods and many other functions adjust the stack to clear
+the memory used to pass their arguments. In some sense, this means that
+the allocas are automatically cleared by the call. However, LLVM
+instead models this as a write of undef to all of the inalloca values
+passed to the call instead of a stack adjustment. Frontends should
+still restore the stack pointer to avoid a stack leak.
+
+Exceptions
+----------
+
+There is also the possibility of an exception. If argument evaluation
+or copy construction throws an exception, the landing pad must do
+cleanup, which includes adjusting the stack pointer to avoid a stack
+leak. This means the cleanup of the stack memory cannot be tied to the
+call itself. There needs to be a separate IR-level instruction that can
+perform independent cleanup of arguments.
+
+Efficiency
+----------
+
+Eventually, it should be possible to generate efficient code for this
+construct. In particular, using inalloca should not require a base
+pointer. If the backend can prove that all points in the CFG only have
+one possible stack level, then it can address the stack directly from
+the stack pointer. While this is not yet implemented, the plan is that
+the inalloca attribute should not change much, but the frontend IR
+generation recommendations may change.
Added: www-releases/trunk/3.5.1/docs/_sources/LLVMBuild.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/LLVMBuild.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/LLVMBuild.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/LLVMBuild.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,325 @@
+===============
+LLVMBuild Guide
+===============
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+This document describes the ``LLVMBuild`` 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.
+
+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.
+
+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
+``LLVMBuild.txt`` 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.
+
+Project Organization
+====================
+
+The source code for LLVM projects using the LLVMBuild system (LLVM,
+Clang, and LLDB) is organized into *components*, 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).
+
+For the most part, the project contents are organized around defining
+one main component per each subdirectory. Each such directory contains
+an ``LLVMBuild.txt`` which contains the component definitions.
+
+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 ``LLVMBuild.txt``
+description file.
+
+Build Integration
+=================
+
+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
+:doc:`Makefiles <MakefileGuide>` and :doc:`CMake <CMake>`).
+
+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 ``LLVMBuild.txt`` files change.
+
+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 ``LLVMBuild.txt`` description files
+(although we have not reached this goal yet).
+
+For more information on the utility tool we provide to help interfacing
+with the build system, please see the :doc:`llvm-build
+<CommandGuide/llvm-build>` documentation.
+
+Component Overview
+==================
+
+As mentioned earlier, LLVM projects are organized into logical
+*components*. 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.
+
+LLVM primarily uses the following types of components:
+
+- *Libraries* - 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.
+- *Build Tools* - 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 :doc:`TableGen/index`
+ to generate a variety of source files.
+- *Tools* - Command line applications which are built using the LLVM
+ component libraries. Most LLVM tools are small and are primarily
+ frontends to the library interfaces.
+
+Components are described using ``LLVMBuild.txt`` files in the directories
+that define the component. See the `LLVMBuild Format Reference`_ section
+for information on the exact format of these files.
+
+LLVMBuild Format Reference
+==========================
+
+LLVMBuild files are written in a simple variant of the INI or configuration
+file format (`Wikipedia entry`_). 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:
+
+.. _Wikipedia entry: http://en.wikipedia.org/wiki/INI_file
+
+.. code-block:: ini
+
+ ; Comments start with a semi-colon.
+
+ ; Sections are declared using square brackets.
+ [component_0]
+
+ ; 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.
+ property_name = property_value
+ list_property_name = value_1 value_2 ... value_n
+ boolean_property_name = 1 (or 0)
+
+LLVMBuild files are expected to define a strict set of sections and
+properties. A typical component description file for a library
+component would look like the following example:
+
+.. code-block:: ini
+
+ [component_0]
+ type = Library
+ name = Linker
+ parent = Libraries
+ required_libraries = Archive BitReader Core Support TransformUtils
+
+A full description of the exact sections and properties which are
+allowed follows.
+
+Each file may define exactly one common component, named ``common``. The
+common component may define the following properties:
+
+- ``subdirectories`` **[optional]**
+
+ If given, a list of the names of the subdirectories from the current
+ subpath to search for additional LLVMBuild files.
+
+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).
+
+.. warning::
+
+ Section names not matching this format (or the ``common`` section) are
+ currently unused and are disallowed.
+
+Every component is defined by the properties in the section. The exact
+list of properties that are allowed depends on the component type.
+Components **may not** define any properties other than those expected
+by the component type.
+
+Every component must define the following properties:
+
+- ``type`` **[required]**
+
+ The type of the component. Supported component types are detailed
+ below. Most components will define additional properties which may be
+ required or optional.
+
+- ``name`` **[required]**
+
+ The name of the component. Names are required to be unique across the
+ entire project.
+
+- ``parent`` **[required]**
+
+ 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.
+
+ Components may reference the root pseudo component using ``$ROOT`` to
+ indicate they should logically be grouped at the top-level.
+
+Components may define the following properties:
+
+- ``dependencies`` **[optional]**
+
+ If specified, a list of names of components which *must* 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.
+
+ .. note::
+
+ ``Group`` and ``LibraryGroup`` components have no semantics for the
+ actual build, and are not allowed to specify dependencies.
+
+The following section lists the available component types, as well as
+the properties which are associated with that component.
+
+- ``type = Group``
+
+ 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.
+
+ ``Group`` components have no additionally properties.
+
+- ``type = Library``
+
+ Library components define an individual library which should be built
+ from the source code in the component directory.
+
+ Components with this type use the following properties:
+
+ - ``library_name`` **[optional]**
+
+ 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.
+
+ - ``required_libraries`` **[optional]**
+
+ 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 ``required_libraries`` for the components the tool needs.
+
+ - ``add_to_library_groups`` **[optional]**
+
+ 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 ``X86`` target might define a library
+ group for all of the ``X86`` components. That library group might
+ then be included in the ``all-targets`` library group.
+
+ - ``installed`` **[optional]** **[boolean]**
+
+ Whether this library is installed. Libraries that are not installed
+ are only reported by ``llvm-config`` when it is run as part of a
+ development directory.
+
+- ``type = LibraryGroup``
+
+ ``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".
+
+ Components with this type use the following properties:
+
+ - ``required_libraries`` **[optional]**
+
+ See the ``Library`` type for a description of this property.
+
+ - ``add_to_library_groups`` **[optional]**
+
+ See the ``Library`` type for a description of this property.
+
+- ``type = TargetGroup``
+
+ ``TargetGroup`` components are an extension of ``LibraryGroup``\s,
+ specifically for defining LLVM targets (which are handled specially in a
+ few places).
+
+ The name of the component should always be the name of the target.
+
+ Components with this type use the ``LibraryGroup`` properties in
+ addition to:
+
+ - ``has_asmparser`` **[optional]** **[boolean]**
+
+ Whether this target defines an assembly parser.
+
+ - ``has_asmprinter`` **[optional]** **[boolean]**
+
+ Whether this target defines an assembly printer.
+
+ - ``has_disassembler`` **[optional]** **[boolean]**
+
+ Whether this target defines a disassembler.
+
+ - ``has_jit`` **[optional]** **[boolean]**
+
+ Whether this target supports JIT compilation.
+
+- ``type = Tool``
+
+ ``Tool`` components define standalone command line tools which should be
+ built from the source code in the component directory and linked.
+
+ Components with this type use the following properties:
+
+ - ``required_libraries`` **[optional]**
+
+ If given, a list of the names of ``Library`` or ``LibraryGroup``
+ components which this tool is required to be linked with.
+
+ .. note::
+
+ The values should be the component names, which may not always
+ match up with the actual library names on disk.
+
+ Build systems are expected to properly include all of the libraries
+ required by the linked components (i.e., the transitive closure of
+ ``required_libraries``).
+
+ 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 ``dependencies``.
+
+- ``type = BuildTool``
+
+ ``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 targeted). 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.
+
+ ``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.
+
Added: www-releases/trunk/3.5.1/docs/_sources/LangRef.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/LangRef.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/LangRef.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/LangRef.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,9348 @@
+==============================
+LLVM Language Reference Manual
+==============================
+
+.. contents::
+ :local:
+ :depth: 4
+
+Abstract
+========
+
+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.
+
+Introduction
+============
+
+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.
+
+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.
+
+.. _wellformed:
+
+Well-Formedness
+---------------
+
+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:
+
+.. code-block:: llvm
+
+ %x = add i32 1, %x
+
+because the definition of ``%x`` does not dominate all of its uses. The
+LLVM infrastructure provides a verification pass that may be used to
+verify that an LLVM module is well formed. This pass is automatically
+run by the parser after parsing input assembly and by the optimizer
+before it outputs bitcode. The violations pointed out by the verifier
+pass indicate bugs in transformation passes or input to the parser.
+
+.. _identifiers:
+
+Identifiers
+===========
+
+LLVM identifiers come in two basic types: global and local. Global
+identifiers (functions, global variables) begin with the ``'@'``
+character. Local identifiers (register names, types) begin with the
+``'%'`` character. Additionally, there are three different formats for
+identifiers, for different purposes:
+
+#. Named values are represented as a string of characters with their
+ prefix. For example, ``%foo``, ``@DivisionByZero``,
+ ``%a.really.long.identifier``. The actual regular expression used is
+ '``[%@][a-zA-Z$._][a-zA-Z$._0-9]*``'. Identifiers which require other
+ characters in their names can be surrounded with quotes. Special
+ characters may be escaped using ``"\xx"`` where ``xx`` is the ASCII
+ code for the character in hexadecimal. In this way, any character can
+ be used in a name value, even quotes themselves.
+#. Unnamed values are represented as an unsigned numeric value with
+ their prefix. For example, ``%12``, ``@2``, ``%44``.
+#. Constants, which are described in the section Constants_ below.
+
+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.
+
+Reserved words in LLVM are very similar to reserved words in other
+languages. There are keywords for different opcodes ('``add``',
+'``bitcast``', '``ret``', etc...), for primitive type names ('``void``',
+'``i32``', etc...), and others. These reserved words cannot conflict
+with variable names, because none of them start with a prefix character
+(``'%'`` or ``'@'``).
+
+Here is an example of LLVM code to multiply the integer variable
+'``%X``' by 8:
+
+The easy way:
+
+.. code-block:: llvm
+
+ %result = mul i32 %X, 8
+
+After strength reduction:
+
+.. code-block:: llvm
+
+ %result = shl i32 %X, 3
+
+And the hard way:
+
+.. code-block:: llvm
+
+ %0 = add i32 %X, %X ; yields i32:%0
+ %1 = add i32 %0, %0 ; yields i32:%1
+ %result = add i32 %1, %1
+
+This last way of multiplying ``%X`` by 8 illustrates several important
+lexical features of LLVM:
+
+#. Comments are delimited with a '``;``' and go until the end of line.
+#. Unnamed temporaries are created when the result of a computation is
+ not assigned to a named value.
+#. Unnamed temporaries are numbered sequentially (using a per-function
+ incrementing counter, starting with 0). Note that basic blocks are
+ included in this numbering. For example, if the entry basic block is not
+ given a label name, then it will get number 0.
+
+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.
+
+High Level Structure
+====================
+
+Module Structure
+----------------
+
+LLVM programs are composed of ``Module``'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:
+
+.. code-block:: llvm
+
+ ; Declare the string constant as a global constant.
+ @.str = private unnamed_addr constant [13 x i8] c"hello world\0A\00"
+
+ ; External declaration of the puts function
+ declare i32 @puts(i8* nocapture) nounwind
+
+ ; Definition of main function
+ define i32 @main() { ; i32()*
+ ; Convert [13 x i8]* to i8 *...
+ %cast210 = getelementptr [13 x i8]* @.str, i64 0, i64 0
+
+ ; Call puts function to write out the string to stdout.
+ call i32 @puts(i8* %cast210)
+ ret i32 0
+ }
+
+ ; Named metadata
+ !1 = metadata !{i32 42}
+ !foo = !{!1, null}
+
+This example is made up of a :ref:`global variable <globalvars>` named
+"``.str``", an external declaration of the "``puts``" function, a
+:ref:`function definition <functionstructure>` for "``main``" and
+:ref:`named metadata <namedmetadatastructure>` "``foo``".
+
+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 :ref:`linkage types <linkage>`.
+
+.. _linkage:
+
+Linkage Types
+-------------
+
+All Global Variables and Functions have one of the following types of
+linkage:
+
+``private``
+ Global values with "``private``" linkage are only directly
+ accessible by objects in the current module. In particular, linking
+ code into a module with an private global value may cause the
+ private to be renamed as necessary to 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.
+``internal``
+ Similar to private, but the value shows as a local symbol
+ (``STB_LOCAL`` in the case of ELF) in the object file. This
+ corresponds to the notion of the '``static``' keyword in C.
+``available_externally``
+ Globals with "``available_externally``" 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 ``available_externally`` linkage
+ are allowed to be discarded at will, and are otherwise the same as
+ ``linkonce_odr``. This linkage type is only allowed on definitions,
+ not declarations.
+``linkonce``
+ Globals with "``linkonce``" 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 ``linkonce`` globals are allowed to be discarded. Note
+ that ``linkonce`` 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
+ "``linkonce_odr``" linkage.
+``weak``
+ "``weak``" linkage has the same merging semantics as ``linkonce``
+ linkage, except that unreferenced globals with ``weak`` linkage may
+ not be discarded. This is used for globals that are declared "weak"
+ in C source code.
+``common``
+ "``common``" linkage is most similar to "``weak``" linkage, but they
+ are used for tentative definitions in C, such as "``int X;``" at
+ global scope. Symbols with "``common``" linkage are merged in the
+ same way as ``weak symbols``, and they may not be deleted if
+ unreferenced. ``common`` symbols may not have an explicit section,
+ must have a zero initializer, and may not be marked
+ ':ref:`constant <globalvars>`'. Functions and aliases may not have
+ common linkage.
+
+.. _linkage_appending:
+
+``appending``
+ "``appending``" 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.
+``extern_weak``
+ 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.
+``linkonce_odr``, ``weak_odr``
+ Some languages allow differing globals to be merged, such as two
+ functions with different semantics. Other languages, such as
+ ``C++``, ensure that only equivalent globals are ever merged (the
+ "one definition rule" --- "ODR"). Such languages can use the
+ ``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the
+ global will only be merged with equivalent globals. These linkage
+ types are otherwise the same as their non-``odr`` versions.
+``external``
+ 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.
+
+It is illegal for a function *declaration* to have any linkage type
+other than ``external`` or ``extern_weak``.
+
+.. _callingconv:
+
+Calling Conventions
+-------------------
+
+LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and
+:ref:`invokes <i_invoke>` 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:
+
+"``ccc``" - The C calling convention
+ 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).
+"``fastcc``" - The fast calling convention
+ 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). `Tail calls can only
+ be optimized when this, the GHC or the HiPE convention is
+ used. <CodeGenerator.html#id80>`_ This calling convention does not
+ support varargs and requires the prototype of all callees to exactly
+ match the prototype of the function definition.
+"``coldcc``" - The cold calling convention
+ 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. Furthermore the inliner doesn't consider such function
+ calls for inlining.
+"``cc 10``" - GHC convention
+ This calling convention has been implemented specifically for use by
+ the `Glasgow Haskell Compiler (GHC) <http://www.haskell.org/ghc>`_.
+ 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 *register pinning* performance technique often
+ used when implementing functional programming languages. At the
+ moment only X86 supports this convention and it has the following
+ limitations:
+
+ - On *X86-32* only supports up to 4 bit type parameters. No
+ floating point types are supported.
+ - On *X86-64* only supports up to 10 bit type parameters and 6
+ floating point parameters.
+
+ This calling convention supports `tail call
+ optimization <CodeGenerator.html#id80>`_ but requires both the
+ caller and callee are using it.
+"``cc 11``" - The HiPE calling convention
+ This calling convention has been implemented specifically for use by
+ the `High-Performance Erlang
+ (HiPE) <http://www.it.uu.se/research/group/hipe/>`_ compiler, *the*
+ native code compiler of the `Ericsson's Open Source Erlang/OTP
+ system <http://www.erlang.org/download.shtml>`_. It uses more
+ registers for argument passing than the ordinary C calling
+ convention and defines no callee-saved registers. The calling
+ convention properly supports `tail call
+ optimization <CodeGenerator.html#id80>`_ but requires that both the
+ caller and the callee use it. It uses a *register pinning*
+ mechanism, similar to GHC's convention, for keeping frequently
+ accessed runtime components pinned to specific hardware registers.
+ At the moment only X86 supports this convention (both 32 and 64
+ bit).
+"``webkit_jscc``" - WebKit's JavaScript calling convention
+ This calling convention has been implemented for `WebKit FTL JIT
+ <https://trac.webkit.org/wiki/FTLJIT>`_. It passes arguments on the
+ stack right to left (as cdecl does), and returns a value in the
+ platform's customary return register.
+"``anyregcc``" - Dynamic calling convention for code patching
+ This is a special convention that supports patching an arbitrary code
+ sequence in place of a call site. This convention forces the call
+ arguments into registers but allows them to be dynamcially
+ allocated. This can currently only be used with calls to
+ llvm.experimental.patchpoint because only this intrinsic records
+ the location of its arguments in a side table. See :doc:`StackMaps`.
+"``preserve_mostcc``" - The `PreserveMost` calling convention
+ This calling convention attempts to make the code in the caller as little
+ intrusive as possible. This calling convention behaves identical to the `C`
+ calling convention on how arguments and return values are passed, but it
+ uses a different set of caller/callee-saved registers. This alleviates the
+ burden of saving and recovering a large register set before and after the
+ call in the caller. If the arguments are passed in callee-saved registers,
+ then they will be preserved by the callee across the call. This doesn't
+ apply for values returned in callee-saved registers.
+
+ - On X86-64 the callee preserves all general purpose registers, except for
+ R11. R11 can be used as a scratch register. Floating-point registers
+ (XMMs/YMMs) are not preserved and need to be saved by the caller.
+
+ The idea behind this convention is to support calls to runtime functions
+ that have a hot path and a cold path. The hot path is usually a small piece
+ of code that doesn't many registers. The cold path might need to call out to
+ another function and therefore only needs to preserve the caller-saved
+ registers, which haven't already been saved by the caller. The
+ `PreserveMost` calling convention is very similar to the `cold` calling
+ convention in terms of caller/callee-saved registers, but they are used for
+ different types of function calls. `coldcc` is for function calls that are
+ rarely executed, whereas `preserve_mostcc` function calls are intended to be
+ on the hot path and definitely executed a lot. Furthermore `preserve_mostcc`
+ doesn't prevent the inliner from inlining the function call.
+
+ This calling convention will be used by a future version of the ObjectiveC
+ runtime and should therefore still be considered experimental at this time.
+ Although this convention was created to optimize certain runtime calls to
+ the ObjectiveC runtime, it is not limited to this runtime and might be used
+ by other runtimes in the future too. The current implementation only
+ supports X86-64, but the intention is to support more architectures in the
+ future.
+"``preserve_allcc``" - The `PreserveAll` calling convention
+ This calling convention attempts to make the code in the caller even less
+ intrusive than the `PreserveMost` calling convention. This calling
+ convention also behaves identical to the `C` calling convention on how
+ arguments and return values are passed, but it uses a different set of
+ caller/callee-saved registers. This removes the burden of saving and
+ recovering a large register set before and after the call in the caller. If
+ the arguments are passed in callee-saved registers, then they will be
+ preserved by the callee across the call. This doesn't apply for values
+ returned in callee-saved registers.
+
+ - On X86-64 the callee preserves all general purpose registers, except for
+ R11. R11 can be used as a scratch register. Furthermore it also preserves
+ all floating-point registers (XMMs/YMMs).
+
+ The idea behind this convention is to support calls to runtime functions
+ that don't need to call out to any other functions.
+
+ This calling convention, like the `PreserveMost` calling convention, will be
+ used by a future version of the ObjectiveC runtime and should be considered
+ experimental at this time.
+"``cc <n>``" - Numbered convention
+ Any calling convention may be specified by number, allowing
+ target-specific calling conventions to be used. Target specific
+ calling conventions start at 64.
+
+More calling conventions can be added/defined on an as-needed basis, to
+support Pascal conventions or any other well-known target-independent
+convention.
+
+.. _visibilitystyles:
+
+Visibility Styles
+-----------------
+
+All Global Variables and Functions have one of the following visibility
+styles:
+
+"``default``" - Default style
+ 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.
+"``hidden``" - Hidden style
+ 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.
+"``protected``" - Protected style
+ 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.
+
+A symbol with ``internal`` or ``private`` linkage must have ``default``
+visibility.
+
+.. _dllstorageclass:
+
+DLL Storage Classes
+-------------------
+
+All Global Variables, Functions and Aliases can have one of the following
+DLL storage class:
+
+``dllimport``
+ "``dllimport``" 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 ``__imp_`` and the function or variable name.
+``dllexport``
+ "``dllexport``" causes the compiler to provide a global pointer to a pointer
+ in a DLL, so that it can be referenced with the ``dllimport`` attribute. On
+ Microsoft Windows targets, the pointer name is formed by combining
+ ``__imp_`` and the function or variable name. Since this storage class
+ exists for defining a dll interface, the compiler, assembler and linker know
+ it is externally referenced and must refrain from deleting the symbol.
+
+.. _tls_model:
+
+Thread Local Storage Models
+---------------------------
+
+A variable may be defined as ``thread_local``, 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:
+
+``localdynamic``
+ For variables that are only used within the current shared library.
+``initialexec``
+ For variables in modules that will not be loaded dynamically.
+``localexec``
+ For variables defined in the executable and only used within it.
+
+If no explicit model is given, the "general dynamic" model is used.
+
+The models correspond to the ELF TLS models; see `ELF Handling For
+Thread-Local Storage <http://people.redhat.com/drepper/tls.pdf>`_ 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.
+
+A model can also be specified in a alias, but then it only governs how
+the alias is accessed. It will not have any effect in the aliasee.
+
+.. _namedtypes:
+
+Structure Types
+---------------
+
+LLVM IR allows you to specify both "identified" and "literal" :ref:`structure
+types <t_struct>`. Literal types are uniqued structurally, but identified types
+are never uniqued. An :ref:`opaque structural type <t_opaque>` can also be used
+to forward declare a type which is not yet available.
+
+An example of a identified structure specification is:
+
+.. code-block:: llvm
+
+ %mytype = type { %mytype*, i32 }
+
+Prior to the LLVM 3.0 release, identified types were structurally uniqued. Only
+literal types are uniqued in recent versions of LLVM.
+
+.. _globalvars:
+
+Global Variables
+----------------
+
+Global variables define regions of memory allocated at compilation time
+instead of run-time.
+
+Global variables definitions must be initialized.
+
+Global variables in other translation units can also be declared, in which
+case they don't have an initializer.
+
+Either global variable definitions or declarations may have an explicit section
+to be placed in and may have an optional explicit alignment specified.
+
+A variable may be defined as a global ``constant``, which indicates that
+the contents of the variable will **never** 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.
+
+LLVM explicitly allows *declarations* 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.
+
+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.
+
+Global variables can be marked with ``unnamed_addr`` 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 *can* be
+merged with a ``unnamed_addr`` constant, the result being a constant
+whose address is significant.
+
+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.
+
+LLVM allows an explicit section to be specified for globals. If the
+target supports it, it will emit globals to the section specified.
+Additionally, the global can placed in a comdat if the target has the necessary
+support.
+
+By default, global initializers are optimized by assuming that global
+variables defined within the module are not modified from their
+initial values before the start of the global initializer. This is
+true even for variables potentially accessible from outside the
+module, including those with external linkage or appearing in
+``@llvm.used`` or dllexported variables. This assumption may be suppressed
+by marking the variable with ``externally_initialized``.
+
+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. The maximum alignment is ``1 << 29``.
+
+Globals can also have a :ref:`DLL storage class <dllstorageclass>`.
+
+Variables and aliasaes can have a
+:ref:`Thread Local Storage Model <tls_model>`.
+
+Syntax::
+
+ [@<GlobalVarName> =] [Linkage] [Visibility] [DLLStorageClass] [ThreadLocal]
+ [unnamed_addr] [AddrSpace] [ExternallyInitialized]
+ <global | constant> <Type> [<InitializerConstant>]
+ [, section "name"] [, align <Alignment>]
+
+For example, the following defines a global in a numbered address space
+with an initializer, section, and alignment:
+
+.. code-block:: llvm
+
+ @G = addrspace(5) constant float 1.0, section "foo", align 4
+
+The following example just declares a global variable
+
+.. code-block:: llvm
+
+ @G = external global i32
+
+The following example defines a thread-local global with the
+``initialexec`` TLS model:
+
+.. code-block:: llvm
+
+ @G = thread_local(initialexec) global i32 0, align 4
+
+.. _functionstructure:
+
+Functions
+---------
+
+LLVM function definitions consist of the "``define``" keyword, an
+optional :ref:`linkage type <linkage>`, an optional :ref:`visibility
+style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`,
+an optional :ref:`calling convention <callingconv>`,
+an optional ``unnamed_addr`` attribute, a return type, an optional
+:ref:`parameter attribute <paramattrs>` for the return type, a function
+name, a (possibly empty) argument list (each with optional :ref:`parameter
+attributes <paramattrs>`), optional :ref:`function attributes <fnattrs>`,
+an optional section, an optional alignment,
+an optional :ref:`comdat <langref_comdats>`,
+an optional :ref:`garbage collector name <gc>`, an optional :ref:`prefix <prefixdata>`, an opening
+curly brace, a list of basic blocks, and a closing curly brace.
+
+LLVM function declarations consist of the "``declare``" keyword, an
+optional :ref:`linkage type <linkage>`, an optional :ref:`visibility
+style <visibility>`, an optional :ref:`DLL storage class <dllstorageclass>`,
+an optional :ref:`calling convention <callingconv>`,
+an optional ``unnamed_addr`` attribute, a return type, an optional
+:ref:`parameter attribute <paramattrs>` for the return type, a function
+name, a possibly empty list of arguments, an optional alignment, an optional
+:ref:`garbage collector name <gc>` and an optional :ref:`prefix <prefixdata>`.
+
+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 :ref:`terminator <terminators>` instruction (such as a branch or
+function return). If an explicit label is not provided, a block is assigned an
+implicit numbered label, using the next value from the same counter as used for
+unnamed temporaries (:ref:`see above<identifiers>`). For example, if a function
+entry block does not have an explicit label, it will be assigned label "%0",
+then the first unnamed temporary in that block will be "%1", etc.
+
+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 :ref:`PHI nodes <i_phi>`.
+
+LLVM allows an explicit section to be specified for functions. If the
+target supports it, it will emit functions to the section specified.
+Additionally, the function can placed in a COMDAT.
+
+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.
+
+If the ``unnamed_addr`` attribute is given, the address is know to not
+be significant and two identical functions can be merged.
+
+Syntax::
+
+ define [linkage] [visibility] [DLLStorageClass]
+ [cconv] [ret attrs]
+ <ResultType> @<FunctionName> ([argument list])
+ [unnamed_addr] [fn Attrs] [section "name"] [comdat $<ComdatName>]
+ [align N] [gc] [prefix Constant] { ... }
+
+.. _langref_aliases:
+
+Aliases
+-------
+
+Aliases, unlike function or variables, don't create any new data. They
+are just a new symbol and metadata for an existing position.
+
+Aliases have a name and an aliasee that is either a global value or a
+constant expression.
+
+Aliases may have an optional :ref:`linkage type <linkage>`, an optional
+:ref:`visibility style <visibility>`, an optional :ref:`DLL storage class
+<dllstorageclass>` and an optional :ref:`tls model <tls_model>`.
+
+Syntax::
+
+ @<Name> = [Visibility] [DLLStorageClass] [ThreadLocal] [unnamed_addr] alias [Linkage] <AliaseeTy> @<Aliasee>
+
+The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``,
+``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers
+might not correctly handle dropping a weak symbol that is aliased.
+
+Alias that are not ``unnamed_addr`` are guaranteed to have the same address as
+the aliasee expression. ``unnamed_addr`` ones are only guaranteed to point
+to the same content.
+
+Since aliases are only a second name, some restrictions apply, of which
+some can only be checked when producing an object file:
+
+* The expression defining the aliasee must be computable at assembly
+ time. Since it is just a name, no relocations can be used.
+
+* No alias in the expression can be weak as the possibility of the
+ intermediate alias being overridden cannot be represented in an
+ object file.
+
+* No global value in the expression can be a declaration, since that
+ would require a relocation, which is not possible.
+
+.. _langref_comdats:
+
+Comdats
+-------
+
+Comdat IR provides access to COFF and ELF object file COMDAT functionality.
+
+Comdats have a name which represents the COMDAT key. All global objects which
+specify this key will only end up in the final object file if the linker chooses
+that key over some other key. Aliases are placed in the same COMDAT that their
+aliasee computes to, if any.
+
+Comdats have a selection kind to provide input on how the linker should
+choose between keys in two different object files.
+
+Syntax::
+
+ $<Name> = comdat SelectionKind
+
+The selection kind must be one of the following:
+
+``any``
+ The linker may choose any COMDAT key, the choice is arbitrary.
+``exactmatch``
+ The linker may choose any COMDAT key but the sections must contain the
+ same data.
+``largest``
+ The linker will choose the section containing the largest COMDAT key.
+``noduplicates``
+ The linker requires that only section with this COMDAT key exist.
+``samesize``
+ The linker may choose any COMDAT key but the sections must contain the
+ same amount of data.
+
+Note that the Mach-O platform doesn't support COMDATs and ELF only supports
+``any`` as a selection kind.
+
+Here is an example of a COMDAT group where a function will only be selected if
+the COMDAT key's section is the largest:
+
+.. code-block:: llvm
+
+ $foo = comdat largest
+ @foo = global i32 2, comdat $foo
+
+ define void @bar() comdat $foo {
+ ret void
+ }
+
+In a COFF object file, this will create a COMDAT section with selection kind
+``IMAGE_COMDAT_SELECT_LARGEST`` containing the contents of the ``@foo`` symbol
+and another COMDAT section with selection kind
+``IMAGE_COMDAT_SELECT_ASSOCIATIVE`` which is associated with the first COMDAT
+section and contains the contents of the ``@baz`` symbol.
+
+There are some restrictions on the properties of the global object.
+It, or an alias to it, must have the same name as the COMDAT group when
+targeting COFF.
+The contents and size of this object may be used during link-time to determine
+which COMDAT groups get selected depending on the selection kind.
+Because the name of the object must match the name of the COMDAT group, the
+linkage of the global object must not be local; local symbols can get renamed
+if a collision occurs in the symbol table.
+
+The combined use of COMDATS and section attributes may yield surprising results.
+For example:
+
+.. code-block:: llvm
+
+ $foo = comdat any
+ $bar = comdat any
+ @g1 = global i32 42, section "sec", comdat $foo
+ @g2 = global i32 42, section "sec", comdat $bar
+
+From the object file perspective, this requires the creation of two sections
+with the same name. This is necessary because both globals belong to different
+COMDAT groups and COMDATs, at the object file level, are represented by
+sections.
+
+Note that certain IR constructs like global variables and functions may create
+COMDATs in the object file in addition to any which are specified using COMDAT
+IR. This arises, for example, when a global variable has linkonce_odr linkage.
+
+.. _namedmetadatastructure:
+
+Named Metadata
+--------------
+
+Named metadata is a collection of metadata. :ref:`Metadata
+nodes <metadata>` (but not metadata strings) are the only valid
+operands for a named metadata.
+
+Syntax::
+
+ ; 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}
+
+.. _paramattrs:
+
+Parameter Attributes
+--------------------
+
+The return type and each parameter of a function type may have a set of
+*parameter attributes* 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.
+
+Parameter attributes are simple keywords that follow the type specified.
+If multiple parameter attributes are needed, they are space separated.
+For example:
+
+.. code-block:: llvm
+
+ declare i32 @printf(i8* noalias nocapture, ...)
+ declare i32 @atoi(i8 zeroext)
+ declare signext i8 @returns_signed_char()
+
+Note that any attributes for the function result (``nounwind``,
+``readonly``) come immediately after the argument list.
+
+Currently, only the following parameter attributes are defined:
+
+``zeroext``
+ 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).
+``signext``
+ 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).
+``inreg``
+ 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.
+``byval``
+ 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, ``readonly`` functions should not write to
+ ``byval`` parameters). This is not a valid attribute for return
+ values.
+
+ 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.
+
+.. _attr_inalloca:
+
+``inalloca``
+
+ The ``inalloca`` argument attribute allows the caller to take the
+ address of outgoing stack arguments. An ``inalloca`` argument must
+ be a pointer to stack memory produced by an ``alloca`` instruction.
+ The alloca, or argument allocation, must also be tagged with the
+ inalloca keyword. Only the last argument may have the ``inalloca``
+ attribute, and that argument is guaranteed to be passed in memory.
+
+ An argument allocation may be used by a call at most once because
+ the call may deallocate it. The ``inalloca`` attribute cannot be
+ used in conjunction with other attributes that affect argument
+ storage, like ``inreg``, ``nest``, ``sret``, or ``byval``. The
+ ``inalloca`` attribute also disables LLVM's implicit lowering of
+ large aggregate return values, which means that frontend authors
+ must lower them with ``sret`` pointers.
+
+ When the call site is reached, the argument allocation must have
+ been the most recent stack allocation that is still live, or the
+ results are undefined. It is possible to allocate additional stack
+ space after an argument allocation and before its call site, but it
+ must be cleared off with :ref:`llvm.stackrestore
+ <int_stackrestore>`.
+
+ See :doc:`InAlloca` for more information on how to use this
+ attribute.
+
+``sret``
+ 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
+ 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.
+
+.. _noalias:
+
+``noalias``
+ This indicates that pointer values :ref:`based <pointeraliasing>` on
+ the argument or return value do not alias pointer values which are
+ not *based* 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 ``noalias`` 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 :ref:`alias
+ analysis <Must, May, or No>`.
+
+ Note that this definition of ``noalias`` is intentionally similar
+ to the definition of ``restrict`` in C99 for function arguments,
+ though it is slightly weaker.
+
+ For function return values, C99's ``restrict`` is not meaningful,
+ while LLVM's ``noalias`` is.
+``nocapture``
+ 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.
+
+.. _nest:
+
+``nest``
+ This indicates that the pointer parameter can be excised using the
+ :ref:`trampoline intrinsics <int_trampoline>`. This is not a valid
+ attribute for return values and can only be applied to one parameter.
+
+``returned``
+ This indicates that the function always returns the argument as its return
+ value. This is an optimization hint to the code generator when generating
+ the caller, allowing tail call optimization and omission of register saves
+ and restores in some cases; it is not checked or enforced when generating
+ the callee. The parameter and the function return type must be valid
+ operands for the :ref:`bitcast instruction <i_bitcast>`. This is not a
+ valid attribute for return values and can only be applied to one parameter.
+
+``nonnull``
+ This indicates that the parameter or return pointer is not null. This
+ attribute may only be applied to pointer typed parameters. This is not
+ checked or enforced by LLVM, the caller must ensure that the pointer
+ passed in is non-null, or the callee must ensure that the returned pointer
+ is non-null.
+
+``dereferenceable(<n>)``
+ This indicates that the parameter or return pointer is dereferenceable. This
+ attribute may only be applied to pointer typed parameters. A pointer that
+ is dereferenceable can be loaded from speculatively without a risk of
+ trapping. The number of bytes known to be dereferenceable must be provided
+ in parentheses. It is legal for the number of bytes to be less than the
+ size of the pointee type. The ``nonnull`` attribute does not imply
+ dereferenceability (consider a pointer to one element past the end of an
+ array), however ``dereferenceable(<n>)`` does imply ``nonnull`` in
+ ``addrspace(0)`` (which is the default address space).
+
+.. _gc:
+
+Garbage Collector Names
+-----------------------
+
+Each function may specify a garbage collector name, which is simply a
+string:
+
+.. code-block:: llvm
+
+ define void @f() gc "name" { ... }
+
+The compiler declares the supported values of *name*. Specifying a
+collector which will cause the compiler to alter its output in order to
+support the named garbage collection algorithm.
+
+.. _prefixdata:
+
+Prefix Data
+-----------
+
+Prefix data is data associated with a function which the code generator
+will emit immediately before the function body. The purpose of this feature
+is to allow frontends to associate language-specific runtime metadata with
+specific functions and make it available through the function pointer while
+still allowing the function pointer to be called. To access the data for a
+given function, a program may bitcast the function pointer to a pointer to
+the constant's type. This implies that the IR symbol points to the start
+of the prefix data.
+
+To maintain the semantics of ordinary function calls, the prefix data must
+have a particular format. Specifically, it must begin with a sequence of
+bytes which decode to a sequence of machine instructions, valid for the
+module's target, which transfer control to the point immediately succeeding
+the prefix data, without performing any other visible action. This allows
+the inliner and other passes to reason about the semantics of the function
+definition without needing to reason about the prefix data. Obviously this
+makes the format of the prefix data highly target dependent.
+
+Prefix data is laid out as if it were an initializer for a global variable
+of the prefix data's type. No padding is automatically placed between the
+prefix data and the function body. If padding is required, it must be part
+of the prefix data.
+
+A trivial example of valid prefix data for the x86 architecture is ``i8 144``,
+which encodes the ``nop`` instruction:
+
+.. code-block:: llvm
+
+ define void @f() prefix i8 144 { ... }
+
+Generally prefix data can be formed by encoding a relative branch instruction
+which skips the metadata, as in this example of valid prefix data for the
+x86_64 architecture, where the first two bytes encode ``jmp .+10``:
+
+.. code-block:: llvm
+
+ %0 = type <{ i8, i8, i8* }>
+
+ define void @f() prefix %0 <{ i8 235, i8 8, i8* @md}> { ... }
+
+A function may have prefix data but no body. This has similar semantics
+to the ``available_externally`` linkage in that the data may be used by the
+optimizers but will not be emitted in the object file.
+
+.. _attrgrp:
+
+Attribute Groups
+----------------
+
+Attribute groups are groups of attributes that are referenced by objects within
+the IR. They are important for keeping ``.ll`` files readable, because a lot of
+functions will use the same set of attributes. In the degenerative case of a
+``.ll`` file that corresponds to a single ``.c`` file, the single attribute
+group will capture the important command line flags used to build that file.
+
+An attribute group is a module-level object. To use an attribute group, an
+object references the attribute group's ID (e.g. ``#37``). An object may refer
+to more than one attribute group. In that situation, the attributes from the
+different groups are merged.
+
+Here is an example of attribute groups for a function that should always be
+inlined, has a stack alignment of 4, and which shouldn't use SSE instructions:
+
+.. code-block:: llvm
+
+ ; Target-independent attributes:
+ attributes #0 = { alwaysinline alignstack=4 }
+
+ ; Target-dependent attributes:
+ attributes #1 = { "no-sse" }
+
+ ; Function @f has attributes: alwaysinline, alignstack=4, and "no-sse".
+ define void @f() #0 #1 { ... }
+
+.. _fnattrs:
+
+Function Attributes
+-------------------
+
+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 function
+attributes can have the same function type.
+
+Function attributes are simple keywords that follow the type specified.
+If multiple attributes are needed, they are space separated. For
+example:
+
+.. code-block:: llvm
+
+ define void @f() noinline { ... }
+ define void @f() alwaysinline { ... }
+ define void @f() alwaysinline optsize { ... }
+ define void @f() optsize { ... }
+
+``alignstack(<n>)``
+ 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.
+``alwaysinline``
+ 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.
+``builtin``
+ This indicates that the callee function at a call site should be
+ recognized as a built-in function, even though the function's declaration
+ uses the ``nobuiltin`` attribute. This is only valid at call sites for
+ direct calls to functions which are declared with the ``nobuiltin``
+ attribute.
+``cold``
+ This attribute indicates that this function is rarely called. When
+ computing edge weights, basic blocks post-dominated by a cold
+ function call are also considered to be cold; and, thus, given low
+ weight.
+``inlinehint``
+ 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.
+``jumptable``
+ This attribute indicates that the function should be added to a
+ jump-instruction table at code-generation time, and that all address-taken
+ references to this function should be replaced with a reference to the
+ appropriate jump-instruction-table function pointer. Note that this creates
+ a new pointer for the original function, which means that code that depends
+ on function-pointer identity can break. So, any function annotated with
+ ``jumptable`` must also be ``unnamed_addr``.
+``minsize``
+ This attribute suggests that optimization passes and code generator
+ passes make choices that keep the code size of this function as small
+ as possible and perform optimizations that may sacrifice runtime
+ performance in order to minimize the size of the generated code.
+``naked``
+ This attribute disables prologue / epilogue emission for the
+ function. This can have very system-specific consequences.
+``nobuiltin``
+ This indicates that the callee function at a call site is not recognized as
+ a built-in function. LLVM will retain the original call and not replace it
+ with equivalent code based on the semantics of the built-in function, unless
+ the call site uses the ``builtin`` attribute. This is valid at call sites
+ and on function declarations and definitions.
+``noduplicate``
+ This attribute indicates that calls to the function cannot be
+ duplicated. A call to a ``noduplicate`` function may be moved
+ within its parent function, but may not be duplicated within
+ its parent function.
+
+ A function containing a ``noduplicate`` call may still
+ be an inlining candidate, provided that the call is not
+ duplicated by inlining. That implies that the function has
+ internal linkage and only has one call site, so the original
+ call is dead after inlining.
+``noimplicitfloat``
+ This attributes disables implicit floating point instructions.
+``noinline``
+ This attribute indicates that the inliner should never inline this
+ function in any situation. This attribute may not be used together
+ with the ``alwaysinline`` attribute.
+``nonlazybind``
+ 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.
+``noredzone``
+ This attribute indicates that the code generator should not use a
+ red zone, even if the target-specific ABI normally permits it.
+``noreturn``
+ This function attribute indicates that the function never returns
+ normally. This produces undefined behavior at runtime if the
+ function ever does dynamically return.
+``nounwind``
+ 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.
+``optnone``
+ This function attribute indicates that the function is not optimized
+ by any optimization or code generator passes with the
+ exception of interprocedural optimization passes.
+ This attribute cannot be used together with the ``alwaysinline``
+ attribute; this attribute is also incompatible
+ with the ``minsize`` attribute and the ``optsize`` attribute.
+
+ This attribute requires the ``noinline`` attribute to be specified on
+ the function as well, so the function is never inlined into any caller.
+ Only functions with the ``alwaysinline`` attribute are valid
+ candidates for inlining into the body of this function.
+``optsize``
+ 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 as
+ long as they do not significantly impact runtime performance.
+``readnone``
+ On a function, 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 ``byval`` arguments) and never changes any state visible
+ to callers. This means that it cannot unwind exceptions by calling
+ the ``C++`` exception throwing methods.
+
+ On an argument, this attribute indicates that the function does not
+ dereference that pointer argument, even though it may read or write the
+ memory that the pointer points to if accessed through other pointers.
+``readonly``
+ On a function, this attribute indicates that the function does not write
+ through any pointer arguments (including ``byval`` 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 ``C++`` exception throwing
+ methods.
+
+ On an argument, this attribute indicates that the function does not write
+ through this pointer argument, even though it may write to the memory that
+ the pointer points to.
+``returns_twice``
+ This attribute indicates that this function can return twice. The C
+ ``setjmp`` is an example of such a function. The compiler disables
+ some optimizations (like tail calls) in the caller of these
+ functions.
+``sanitize_address``
+ This attribute indicates that AddressSanitizer checks
+ (dynamic address safety analysis) are enabled for this function.
+``sanitize_memory``
+ This attribute indicates that MemorySanitizer checks (dynamic detection
+ of accesses to uninitialized memory) are enabled for this function.
+``sanitize_thread``
+ This attribute indicates that ThreadSanitizer checks
+ (dynamic thread safety analysis) are enabled for this function.
+``ssp``
+ 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. The heuristic used will enable protectors for functions with:
+
+ - Character arrays larger than ``ssp-buffer-size`` (default 8).
+ - Aggregates containing character arrays larger than ``ssp-buffer-size``.
+ - Calls to alloca() with variable sizes or constant sizes greater than
+ ``ssp-buffer-size``.
+
+ Variables that are identified as requiring a protector will be arranged
+ on the stack such that they are adjacent to the stack protector guard.
+
+ If a function that has an ``ssp`` attribute is inlined into a
+ function that doesn't have an ``ssp`` attribute, then the resulting
+ function will have an ``ssp`` attribute.
+``sspreq``
+ This attribute indicates that the function should *always* emit a
+ stack smashing protector. This overrides the ``ssp`` function
+ attribute.
+
+ Variables that are identified as requiring a protector will be arranged
+ on the stack such that they are adjacent to the stack protector guard.
+ The specific layout rules are:
+
+ #. Large arrays and structures containing large arrays
+ (``>= ssp-buffer-size``) are closest to the stack protector.
+ #. Small arrays and structures containing small arrays
+ (``< ssp-buffer-size``) are 2nd closest to the protector.
+ #. Variables that have had their address taken are 3rd closest to the
+ protector.
+
+ If a function that has an ``sspreq`` attribute is inlined into a
+ function that doesn't have an ``sspreq`` attribute or which has an
+ ``ssp`` or ``sspstrong`` attribute, then the resulting function will have
+ an ``sspreq`` attribute.
+``sspstrong``
+ This attribute indicates that the function should emit a stack smashing
+ protector. This attribute causes a strong heuristic to be used when
+ determining if a function needs stack protectors. The strong heuristic
+ will enable protectors for functions with:
+
+ - Arrays of any size and type
+ - Aggregates containing an array of any size and type.
+ - Calls to alloca().
+ - Local variables that have had their address taken.
+
+ Variables that are identified as requiring a protector will be arranged
+ on the stack such that they are adjacent to the stack protector guard.
+ The specific layout rules are:
+
+ #. Large arrays and structures containing large arrays
+ (``>= ssp-buffer-size``) are closest to the stack protector.
+ #. Small arrays and structures containing small arrays
+ (``< ssp-buffer-size``) are 2nd closest to the protector.
+ #. Variables that have had their address taken are 3rd closest to the
+ protector.
+
+ This overrides the ``ssp`` function attribute.
+
+ If a function that has an ``sspstrong`` attribute is inlined into a
+ function that doesn't have an ``sspstrong`` attribute, then the
+ resulting function will have an ``sspstrong`` attribute.
+``uwtable``
+ 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.
+
+.. _moduleasm:
+
+Module-Level Inline Assembly
+----------------------------
+
+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 ``.ll`` file if desired. The syntax is very simple:
+
+.. code-block:: llvm
+
+ module asm "inline asm code goes here"
+ module asm "more can go here"
+
+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.
+
+The inline asm code is simply printed to the machine code .s file when
+assembly code is generated.
+
+.. _langref_datalayout:
+
+Data Layout
+-----------
+
+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:
+
+.. code-block:: llvm
+
+ target datalayout = "layout specification"
+
+The *layout specification* 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:
+
+``E``
+ Specifies that the target lays out data in big-endian form. That is,
+ the bits with the most significance have the lowest address
+ location.
+``e``
+ Specifies that the target lays out data in little-endian form. That
+ is, the bits with the least significance have the lowest address
+ location.
+``S<size>``
+ 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.
+``p[n]:<size>:<abi>:<pref>``
+ This specifies the *size* of a pointer and its ``<abi>`` and
+ ``<pref>``\erred alignments for address space ``n``. All sizes are in
+ bits. The address space, ``n`` is optional, and if not specified,
+ denotes the default address space 0. The value of ``n`` must be
+ in the range [1,2^23).
+``i<size>:<abi>:<pref>``
+ This specifies the alignment for an integer type of a given bit
+ ``<size>``. The value of ``<size>`` must be in the range [1,2^23).
+``v<size>:<abi>:<pref>``
+ This specifies the alignment for a vector type of a given bit
+ ``<size>``.
+``f<size>:<abi>:<pref>``
+ This specifies the alignment for a floating point type of a given bit
+ ``<size>``. Only values of ``<size>`` 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.
+``a:<abi>:<pref>``
+ This specifies the alignment for an object of aggregate type.
+``m:<mangling>``
+ If present, specifies that llvm names are mangled in the output. The
+ options are
+
+ * ``e``: ELF mangling: Private symbols get a ``.L`` prefix.
+ * ``m``: Mips mangling: Private symbols get a ``$`` prefix.
+ * ``o``: Mach-O mangling: Private symbols get ``L`` prefix. Other
+ symbols get a ``_`` prefix.
+ * ``w``: Windows COFF prefix: Similar to Mach-O, but stdcall and fastcall
+ functions also get a suffix based on the frame size.
+``n<size1>:<size2>:<size3>...``
+ 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.
+
+On every specification that takes a ``<abi>:<pref>``, specifying the
+``<pref>`` alignment is optional. If omitted, the preceding ``:``
+should be omitted too and ``<pref>`` will be equal to ``<abi>``.
+
+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 ``datalayout`` keyword. The default
+specifications are given in this list:
+
+- ``E`` - big endian
+- ``p:64:64:64`` - 64-bit pointers with 64-bit alignment.
+- ``p[n]:64:64:64`` - Other address spaces are assumed to be the
+ same as the default address space.
+- ``S0`` - natural stack alignment is unspecified
+- ``i1:8:8`` - i1 is 8-bit (byte) aligned
+- ``i8:8:8`` - i8 is 8-bit (byte) aligned
+- ``i16:16:16`` - i16 is 16-bit aligned
+- ``i32:32:32`` - i32 is 32-bit aligned
+- ``i64:32:64`` - i64 has ABI alignment of 32-bits but preferred
+ alignment of 64-bits
+- ``f16:16:16`` - half is 16-bit aligned
+- ``f32:32:32`` - float is 32-bit aligned
+- ``f64:64:64`` - double is 64-bit aligned
+- ``f128:128:128`` - quad is 128-bit aligned
+- ``v64:64:64`` - 64-bit vector is 64-bit aligned
+- ``v128:128:128`` - 128-bit vector is 128-bit aligned
+- ``a:0:64`` - aggregates are 64-bit aligned
+
+When LLVM is determining the alignment for a given type, it uses the
+following rules:
+
+#. If the type sought is an exact match for one of the specifications,
+ that specification is used.
+#. 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).
+#. 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.
+
+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.
+
+Instead, if specified, the target data layout is required to match what
+the ultimate *code generator* 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.
+
+.. _langref_triple:
+
+Target Triple
+-------------
+
+A module may specify a target triple string that describes the target
+host. The syntax for the target triple is simply:
+
+.. code-block:: llvm
+
+ target triple = "x86_64-apple-macosx10.7.0"
+
+The *target triple* string consists of a series of identifiers delimited
+by the minus sign character ('-'). The canonical forms are:
+
+::
+
+ ARCHITECTURE-VENDOR-OPERATING_SYSTEM
+ ARCHITECTURE-VENDOR-OPERATING_SYSTEM-ENVIRONMENT
+
+This information is passed along to the backend so that it generates
+code for the proper architecture. It's possible to override this on the
+command line with the ``-mtriple`` command line option.
+
+.. _pointeraliasing:
+
+Pointer Aliasing Rules
+----------------------
+
+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:
+
+- A pointer value is associated with the addresses associated with any
+ value it is *based* on.
+- An address of a global variable is associated with the address range
+ of the variable's storage.
+- The result value of an allocation instruction is associated with the
+ address range of the allocated storage.
+- A null pointer in the default address-space is associated with no
+ address.
+- 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.
+
+A pointer value is *based* on another pointer value according to the
+following rules:
+
+- A pointer value formed from a ``getelementptr`` operation is *based*
+ on the first operand of the ``getelementptr``.
+- The result value of a ``bitcast`` is *based* on the operand of the
+ ``bitcast``.
+- A pointer value formed by an ``inttoptr`` is *based* on all pointer
+ values that contribute (directly or indirectly) to the computation of
+ the pointer's value.
+- The "*based* on" relationship is transitive.
+
+Note that this definition of *"based"* is intentionally similar to the
+definition of *"based"* in C99, though it is slightly weaker.
+
+LLVM IR does not associate types with memory. The result type of a
+``load`` 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 ``store`` similarly only indicates the size and
+alignment of the store.
+
+Consequently, type-based alias analysis, aka TBAA, aka
+``-fstrict-aliasing``, is not applicable to general unadorned LLVM IR.
+:ref:`Metadata <metadata>` may be used to encode additional information
+which specialized optimization passes may use to implement type-based
+alias analysis.
+
+.. _volatile:
+
+Volatile Memory Accesses
+------------------------
+
+Certain memory accesses, such as :ref:`load <i_load>`'s,
+:ref:`store <i_store>`'s, and :ref:`llvm.memcpy <int_memcpy>`'s may be
+marked ``volatile``. The optimizers must not change the number of
+volatile operations or change their order of execution relative to other
+volatile operations. The optimizers *may* change the order of volatile
+operations relative to non-volatile operations. This is not Java's
+"volatile" and has no cross-thread synchronization behavior.
+
+IR-level volatile loads and stores cannot safely be optimized into
+llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are
+flagged volatile. Likewise, the backend should never split or merge
+target-legal volatile load/store instructions.
+
+.. admonition:: Rationale
+
+ Platforms may rely on volatile loads and stores of natively supported
+ data width to be executed as single instruction. For example, in C
+ this holds for an l-value of volatile primitive type with native
+ hardware support, but not necessarily for aggregate types. The
+ frontend upholds these expectations, which are intentionally
+ unspecified in the IR. The rules above ensure that IR transformation
+ do not violate the frontend's contract with the language.
+
+.. _memmodel:
+
+Memory Model for Concurrent Operations
+--------------------------------------
+
+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.
+
+For a more informal introduction to this model, see the :doc:`Atomics`.
+
+We define a *happens-before* partial order as the least partial order
+that
+
+- Is a superset of single-thread program order, and
+- When a *synchronizes-with* ``b``, includes an edge from ``a`` to
+ ``b``. *Synchronizes-with* pairs are introduced by platform-specific
+ techniques, like pthread locks, thread creation, thread joining,
+ etc., and by atomic instructions. (See also :ref:`Atomic Memory Ordering
+ Constraints <ordering>`).
+
+Note that program order does not introduce *happens-before* edges
+between a thread and signals executing inside that thread.
+
+Every (defined) read operation (load instructions, memcpy, atomic
+loads/read-modify-writes, etc.) R 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 R, R\ :sub:`byte`
+may see any write to the same byte, except:
+
+- If write\ :sub:`1` happens before write\ :sub:`2`, and
+ write\ :sub:`2` happens before R\ :sub:`byte`, then
+ R\ :sub:`byte` does not see write\ :sub:`1`.
+- If R\ :sub:`byte` happens before write\ :sub:`3`, then
+ R\ :sub:`byte` does not see write\ :sub:`3`.
+
+Given that definition, R\ :sub:`byte` is defined as follows:
+
+- If R is volatile, the result is target-dependent. (Volatile is
+ supposed to give guarantees which can support ``sig_atomic_t`` 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.)
+- Otherwise, if there is no write to the same byte that happens before
+ R\ :sub:`byte`, R\ :sub:`byte` returns ``undef`` for that byte.
+- Otherwise, if R\ :sub:`byte` may see exactly one write,
+ R\ :sub:`byte` returns the value written by that write.
+- Otherwise, if R is atomic, and all the writes R\ :sub:`byte` may
+ see are atomic, it chooses one of the values written. See the :ref:`Atomic
+ Memory Ordering Constraints <ordering>` section for additional
+ constraints on how the choice is made.
+- Otherwise R\ :sub:`byte` returns ``undef``.
+
+R returns the value composed of the series of bytes it read. This
+implies that some bytes within the value may be ``undef`` **without**
+the entire value being ``undef``. 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.
+
+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.)
+
+.. _ordering:
+
+Atomic Memory Ordering Constraints
+----------------------------------
+
+Atomic instructions (:ref:`cmpxchg <i_cmpxchg>`,
+:ref:`atomicrmw <i_atomicrmw>`, :ref:`fence <i_fence>`,
+:ref:`atomic load <i_load>`, and :ref:`atomic store <i_store>`) take
+ordering parameters that determine which other atomic instructions on
+the same address they *synchronize with*. 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 :doc:`atomics guide <Atomics>`).
+:ref:`fence <i_fence>` instructions treat these orderings somewhat
+differently since they don't take an address. See that instruction's
+documentation for details.
+
+For a simpler introduction to the ordering constraints, see the
+:doc:`Atomics`.
+
+``unordered``
+ 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.
+``monotonic``
+ In addition to the guarantees of ``unordered``, there is a single
+ total order for modifications by ``monotonic`` 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 (:ref:`cmpxchg <i_cmpxchg>` and
+ :ref:`atomicrmw <i_atomicrmw>`) 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 ``monotonic`` (or
+ stronger) operations on the same address. If an address is written
+ ``monotonic``-ally by one thread, and other threads ``monotonic``-ally
+ read that address repeatedly, the other threads must eventually see
+ the write. This corresponds to the C++0x/C1x
+ ``memory_order_relaxed``.
+``acquire``
+ In addition to the guarantees of ``monotonic``, a
+ *synchronizes-with* edge may be formed with a ``release`` operation.
+ This is intended to model C++'s ``memory_order_acquire``.
+``release``
+ In addition to the guarantees of ``monotonic``, if this operation
+ writes a value which is subsequently read by an ``acquire``
+ operation, it *synchronizes-with* that operation. (This isn't a
+ complete description; see the C++0x definition of a release
+ sequence.) This corresponds to the C++0x/C1x
+ ``memory_order_release``.
+``acq_rel`` (acquire+release)
+ Acts as both an ``acquire`` and ``release`` operation on its
+ address. This corresponds to the C++0x/C1x ``memory_order_acq_rel``.
+``seq_cst`` (sequentially consistent)
+ In addition to the guarantees of ``acq_rel`` (``acquire`` for an
+ operation which only reads, ``release`` 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 *happens-before* 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
+ ``memory_order_seq_cst`` and Java volatile.
+
+.. _singlethread:
+
+If an atomic operation is marked ``singlethread``, it only *synchronizes
+with* or participates in modification and seq\_cst total orderings with
+other operations running in the same thread (for example, in signal
+handlers).
+
+.. _fastmath:
+
+Fast-Math Flags
+---------------
+
+LLVM IR floating-point binary ops (:ref:`fadd <i_fadd>`,
+:ref:`fsub <i_fsub>`, :ref:`fmul <i_fmul>`, :ref:`fdiv <i_fdiv>`,
+:ref:`frem <i_frem>`) have the following flags that can set to enable
+otherwise unsafe floating point operations
+
+``nnan``
+ No NaNs - Allow optimizations to assume the arguments and result are not
+ NaN. Such optimizations are required to retain defined behavior over
+ NaNs, but the value of the result is undefined.
+
+``ninf``
+ No Infs - Allow optimizations to assume the arguments and result are not
+ +/-Inf. Such optimizations are required to retain defined behavior over
+ +/-Inf, but the value of the result is undefined.
+
+``nsz``
+ No Signed Zeros - Allow optimizations to treat the sign of a zero
+ argument or result as insignificant.
+
+``arcp``
+ Allow Reciprocal - Allow optimizations to use the reciprocal of an
+ argument rather than perform division.
+
+``fast``
+ Fast - Allow algebraically equivalent transformations that may
+ dramatically change results in floating point (e.g. reassociate). This
+ flag implies all the others.
+
+.. _typesystem:
+
+Type System
+===========
+
+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.
+
+.. _t_void:
+
+Void Type
+---------
+
+:Overview:
+
+
+The void type does not represent any value and has no size.
+
+:Syntax:
+
+
+::
+
+ void
+
+
+.. _t_function:
+
+Function Type
+-------------
+
+:Overview:
+
+
+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 void type or first class type --- except for :ref:`label <t_label>`
+and :ref:`metadata <t_metadata>` types.
+
+:Syntax:
+
+::
+
+ <returntype> (<parameter list>)
+
+...where '``<parameter list>``' is a comma-separated list of type
+specifiers. Optionally, the parameter list may include a type ``...``, which
+indicates that the function takes a variable number of arguments. Variable
+argument functions can access their arguments with the :ref:`variable argument
+handling intrinsic <int_varargs>` functions. '``<returntype>``' is any type
+except :ref:`label <t_label>` and :ref:`metadata <t_metadata>`.
+
+:Examples:
+
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``i32 (i32)`` | function taking an ``i32``, returning an ``i32`` |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``float (i16, i32 *) *`` | :ref:`Pointer <t_pointer>` to a function that takes an ``i16`` and a :ref:`pointer <t_pointer>` to ``i32``, returning ``float``. |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``i32 (i8*, ...)`` | A vararg function that takes at least one :ref:`pointer <t_pointer>` to ``i8`` (char in C), which returns an integer. This is the signature for ``printf`` in LLVM. |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``{i32, i32} (i32)`` | A function taking an ``i32``, returning a :ref:`structure <t_struct>` containing two ``i32`` values |
++---------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. _t_firstclass:
+
+First Class Types
+-----------------
+
+The :ref:`first class <t_firstclass>` types are perhaps the most important.
+Values of these types are the only ones which can be produced by
+instructions.
+
+.. _t_single_value:
+
+Single Value Types
+^^^^^^^^^^^^^^^^^^
+
+These are the types that are valid in registers from CodeGen's perspective.
+
+.. _t_integer:
+
+Integer Type
+""""""""""""
+
+:Overview:
+
+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`\ -1 (about 8 million) can be specified.
+
+:Syntax:
+
+::
+
+ iN
+
+The number of bits the integer will occupy is specified by the ``N``
+value.
+
+Examples:
+*********
+
++----------------+------------------------------------------------+
+| ``i1`` | a single-bit integer. |
++----------------+------------------------------------------------+
+| ``i32`` | a 32-bit integer. |
++----------------+------------------------------------------------+
+| ``i1942652`` | a really big integer of over 1 million bits. |
++----------------+------------------------------------------------+
+
+.. _t_floating:
+
+Floating Point Types
+""""""""""""""""""""
+
+.. list-table::
+ :header-rows: 1
+
+ * - Type
+ - Description
+
+ * - ``half``
+ - 16-bit floating point value
+
+ * - ``float``
+ - 32-bit floating point value
+
+ * - ``double``
+ - 64-bit floating point value
+
+ * - ``fp128``
+ - 128-bit floating point value (112-bit mantissa)
+
+ * - ``x86_fp80``
+ - 80-bit floating point value (X87)
+
+ * - ``ppc_fp128``
+ - 128-bit floating point value (two 64-bits)
+
+X86_mmx Type
+""""""""""""
+
+:Overview:
+
+The x86_mmx 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.
+
+:Syntax:
+
+::
+
+ x86_mmx
+
+
+.. _t_pointer:
+
+Pointer Type
+""""""""""""
+
+:Overview:
+
+The pointer type is used to specify memory locations. Pointers are
+commonly used to reference objects in memory.
+
+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.
+
+Note that LLVM does not permit pointers to void (``void*``) nor does it
+permit pointers to labels (``label*``). Use ``i8*`` instead.
+
+:Syntax:
+
+::
+
+ <type> *
+
+:Examples:
+
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+| ``[4 x i32]*`` | A :ref:`pointer <t_pointer>` to :ref:`array <t_array>` of four ``i32`` values. |
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+| ``i32 (i32*) *`` | A :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32*``, returning an ``i32``. |
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+| ``i32 addrspace(5)*`` | A :ref:`pointer <t_pointer>` to an ``i32`` value that resides in address space #5. |
++-------------------------+--------------------------------------------------------------------------------------------------------------+
+
+.. _t_vector:
+
+Vector Type
+"""""""""""
+
+:Overview:
+
+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 :ref:`first class <t_firstclass>`.
+
+:Syntax:
+
+::
+
+ < <# elements> x <elementtype> >
+
+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.
+
+:Examples:
+
++-------------------+--------------------------------------------------+
+| ``<4 x i32>`` | Vector of 4 32-bit integer values. |
++-------------------+--------------------------------------------------+
+| ``<8 x float>`` | Vector of 8 32-bit floating-point values. |
++-------------------+--------------------------------------------------+
+| ``<2 x i64>`` | Vector of 2 64-bit integer values. |
++-------------------+--------------------------------------------------+
+| ``<4 x i64*>`` | Vector of 4 pointers to 64-bit integer values. |
++-------------------+--------------------------------------------------+
+
+.. _t_label:
+
+Label Type
+^^^^^^^^^^
+
+:Overview:
+
+The label type represents code labels.
+
+:Syntax:
+
+::
+
+ label
+
+.. _t_metadata:
+
+Metadata Type
+^^^^^^^^^^^^^
+
+:Overview:
+
+The metadata type represents embedded metadata. No derived types may be
+created from metadata except for :ref:`function <t_function>` arguments.
+
+:Syntax:
+
+::
+
+ metadata
+
+.. _t_aggregate:
+
+Aggregate Types
+^^^^^^^^^^^^^^^
+
+Aggregate Types are a subset of derived types that can contain multiple
+member types. :ref:`Arrays <t_array>` and :ref:`structs <t_struct>` are
+aggregate types. :ref:`Vectors <t_vector>` are not considered to be
+aggregate types.
+
+.. _t_array:
+
+Array Type
+""""""""""
+
+:Overview:
+
+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.
+
+:Syntax:
+
+::
+
+ [<# elements> x <elementtype>]
+
+The number of elements is a constant integer value; ``elementtype`` may
+be any type with a size.
+
+:Examples:
+
++------------------+--------------------------------------+
+| ``[40 x i32]`` | Array of 40 32-bit integer values. |
++------------------+--------------------------------------+
+| ``[41 x i32]`` | Array of 41 32-bit integer values. |
++------------------+--------------------------------------+
+| ``[4 x i8]`` | Array of 4 8-bit integer values. |
++------------------+--------------------------------------+
+
+Here are some examples of multidimensional arrays:
+
++-----------------------------+----------------------------------------------------------+
+| ``[3 x [4 x i32]]`` | 3x4 array of 32-bit integer values. |
++-----------------------------+----------------------------------------------------------+
+| ``[12 x [10 x float]]`` | 12x10 array of single precision floating point values. |
++-----------------------------+----------------------------------------------------------+
+| ``[2 x [3 x [4 x i16]]]`` | 2x3x4 array of 16-bit integer values. |
++-----------------------------+----------------------------------------------------------+
+
+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 "``{ i32, [0 x float]}``", for
+example.
+
+.. _t_struct:
+
+Structure Type
+""""""""""""""
+
+:Overview:
+
+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.
+
+Structures in memory are accessed using '``load``' and '``store``' by
+getting a pointer to a field with the '``getelementptr``' instruction.
+Structures in registers are accessed using the '``extractvalue``' and
+'``insertvalue``' instructions.
+
+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.
+
+Structures can either be "literal" or "identified". A literal structure
+is defined inline with other types (e.g. ``{i32, i32}*``) 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.
+
+:Syntax:
+
+::
+
+ %T1 = type { <type list> } ; Identified normal struct type
+ %T2 = type <{ <type list> }> ; Identified packed struct type
+
+:Examples:
+
++------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``{ i32, i32, i32 }`` | A triple of three ``i32`` values |
++------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``{ float, i32 (i32) * }`` | A pair, where the first element is a ``float`` and the second element is a :ref:`pointer <t_pointer>` to a :ref:`function <t_function>` that takes an ``i32``, returning an ``i32``. |
++------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``<{ i8, i32 }>`` | A packed struct known to be 5 bytes in size. |
++------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+.. _t_opaque:
+
+Opaque Structure Types
+""""""""""""""""""""""
+
+:Overview:
+
+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.
+
+:Syntax:
+
+::
+
+ %X = type opaque
+ %52 = type opaque
+
+:Examples:
+
++--------------+-------------------+
+| ``opaque`` | An opaque type. |
++--------------+-------------------+
+
+.. _constants:
+
+Constants
+=========
+
+LLVM has several different basic types of constants. This section
+describes them all and their syntax.
+
+Simple Constants
+----------------
+
+**Boolean constants**
+ The two strings '``true``' and '``false``' are both valid constants
+ of the ``i1`` type.
+**Integer constants**
+ Standard integers (such as '4') are constants of the
+ :ref:`integer <t_integer>` type. Negative numbers may be used with
+ integer types.
+**Floating point constants**
+ 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 :ref:`floating
+ point <t_floating>` type.
+**Null pointer constants**
+ The identifier '``null``' is recognized as a null pointer constant
+ and must be of :ref:`pointer type <t_pointer>`.
+
+The one non-intuitive notation for constants is the hexadecimal form of
+floating point constants. For example, the form
+'``double 0x432ff973cafa8000``' is equivalent to (but harder to read
+than) '``double 4.5e+15``'. 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.
+
+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 IEEE 754 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 ``0xK`` followed by 20 hexadecimal digits. The
+128-bit format used by PowerPC (two adjacent doubles) is represented by
+``0xM`` followed by 32 hexadecimal digits. The IEEE 128-bit format is
+represented by ``0xL`` followed by 32 hexadecimal digits. 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 ``0xH``
+followed by 4 hexadecimal digits. All hexadecimal formats are big-endian
+(sign bit at the left).
+
+There are no constants of type x86_mmx.
+
+.. _complexconstants:
+
+Complex Constants
+-----------------
+
+Complex constants are a (potentially recursive) combination of simple
+constants and smaller complex constants.
+
+**Structure constants**
+ Structure constants are represented with notation similar to
+ structure type definitions (a comma separated list of elements,
+ surrounded by braces (``{}``)). For example:
+ "``{ i32 4, float 17.0, i32* @G }``", where "``@G``" is declared as
+ "``@G = external global i32``". Structure constants must have
+ :ref:`structure type <t_struct>`, and the number and types of elements
+ must match those specified by the type.
+**Array constants**
+ Array constants are represented with notation similar to array type
+ definitions (a comma separated list of elements, surrounded by
+ square brackets (``[]``)). For example:
+ "``[ i32 42, i32 11, i32 74 ]``". Array constants must have
+ :ref:`array type <t_array>`, and the number and types of elements must
+ match those specified by the type.
+**Vector constants**
+ Vector constants are represented with notation similar to vector
+ type definitions (a comma separated list of elements, surrounded by
+ less-than/greater-than's (``<>``)). For example:
+ "``< i32 42, i32 11, i32 74, i32 100 >``". Vector constants
+ must have :ref:`vector type <t_vector>`, and the number and types of
+ elements must match those specified by the type.
+**Zero initialization**
+ The string '``zeroinitializer``' can be used to zero initialize a
+ value to zero of *any* type, including scalar and
+ :ref:`aggregate <t_aggregate>` 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.
+**Metadata node**
+ A metadata node is a structure-like constant with :ref:`metadata
+ type <t_metadata>`. For example:
+ "``metadata !{ i32 0, metadata !"test" }``". 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.
+
+Global Variable and Function Addresses
+--------------------------------------
+
+The addresses of :ref:`global variables <globalvars>` and
+:ref:`functions <functionstructure>` are always implicitly valid
+(link-time) constants. These constants are explicitly referenced when
+the :ref:`identifier for the global <identifiers>` is used and always have
+:ref:`pointer <t_pointer>` type. For example, the following is a legal LLVM
+file:
+
+.. code-block:: llvm
+
+ @X = global i32 17
+ @Y = global i32 42
+ @Z = global [2 x i32*] [ i32* @X, i32* @Y ]
+
+.. _undefvalues:
+
+Undefined Values
+----------------
+
+The string '``undef``' 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 '``label``'
+or '``void``') and be used anywhere a constant is permitted.
+
+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):
+
+.. code-block:: llvm
+
+ %A = add %X, undef
+ %B = sub %X, undef
+ %C = xor %X, undef
+ Safe:
+ %A = undef
+ %B = undef
+ %C = undef
+
+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.
+
+.. code-block:: llvm
+
+ %A = or %X, undef
+ %B = and %X, undef
+ Safe:
+ %A = -1
+ %B = 0
+ Unsafe:
+ %A = undef
+ %B = undef
+
+These logical operations have bits that are not always affected by the
+input. For example, if ``%X`` has a zero bit, then the output of the
+'``and``' operation will always be a zero for that bit, no matter what
+the corresponding bit from the '``undef``' is. As such, it is unsafe to
+optimize or assume that the result of the '``and``' is '``undef``'.
+However, it is safe to assume that all bits of the '``undef``' could be
+0, and optimize the '``and``' to 0. Likewise, it is safe to assume that
+all the bits of the '``undef``' operand to the '``or``' could be set,
+allowing the '``or``' to be folded to -1.
+
+.. code-block:: llvm
+
+ %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
+
+This set of examples shows that undefined '``select``' (and conditional
+branch) conditions can go *either way*, but they have to come from one
+of the two operands. In the ``%A`` example, if ``%X`` and ``%Y`` were
+both known to have a clear low bit, then ``%A`` would have to have a
+cleared low bit. However, in the ``%C`` example, the optimizer is
+allowed to assume that the '``undef``' operand could be the same as
+``%Y``, allowing the whole '``select``' to be eliminated.
+
+.. code-block:: llvm
+
+ %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
+
+This example points out that two '``undef``' operands are not
+necessarily the same. This can be surprising to people (and also matches
+C semantics) where they assume that "``X^X``" is always zero, even if
+``X`` is undefined. This isn't true for a number of reasons, but the
+short answer is that an '``undef``' "variable" can arbitrarily change
+its value over its "live range". This is true because the variable
+doesn't actually *have a live range*. 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, ``%A`` and
+``%C`` need to have the same semantics or the core LLVM "replace all
+uses with" concept would not hold.
+
+.. code-block:: llvm
+
+ %A = fdiv undef, %X
+ %B = fdiv %X, undef
+ Safe:
+ %A = undef
+ b: unreachable
+
+These examples show the crucial difference between an *undefined value*
+and *undefined behavior*. An undefined value (like '``undef``') is
+allowed to have an arbitrary bit-pattern. This means that the ``%A``
+operation can be constant folded to '``undef``', because the '``undef``'
+could be an SNaN, and ``fdiv`` is not (currently) defined on SNaN's.
+However, in the second example, we can make a more aggressive
+assumption: because the ``undef`` is allowed to be an arbitrary value,
+we are allowed to assume that it could be zero. Since a divide by zero
+has *undefined behavior*, 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.
+
+.. code-block:: llvm
+
+ a: store undef -> %X
+ b: store %X -> undef
+ Safe:
+ a: <deleted>
+ b: unreachable
+
+These examples reiterate the ``fdiv`` example: a store *of* an undefined
+value can be assumed to not have any effect; we can assume that the
+value is overwritten with bits that happen to match what was already
+there. However, a store *to* an undefined location could clobber
+arbitrary memory, therefore, it has undefined behavior.
+
+.. _poisonvalues:
+
+Poison Values
+-------------
+
+Poison values are similar to :ref:`undef values <undefvalues>`, 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.
+
+There is currently no way of representing a poison value in the IR; they
+only exist when produced by operations such as :ref:`add <i_add>` with
+the ``nsw`` flag.
+
+Poison value behavior is defined in terms of value *dependence*:
+
+- Values other than :ref:`phi <i_phi>` nodes depend on their operands.
+- :ref:`Phi <i_phi>` nodes depend on the operand corresponding to
+ their dynamic predecessor basic block.
+- Function arguments depend on the corresponding actual argument values
+ in the dynamic callers of their functions.
+- :ref:`Call <i_call>` instructions depend on the :ref:`ret <i_ret>`
+ instructions that dynamically transfer control back to them.
+- :ref:`Invoke <i_invoke>` instructions depend on the
+ :ref:`ret <i_ret>`, :ref:`resume <i_resume>`, or exception-throwing
+ call instructions that dynamically transfer control back to them.
+- 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
+ :ref:`@llvm.memcpy <int_memcpy>`.)
+- 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 :ref:`volatile
+ operations <volatile>`.)
+- An instruction *control-depends* on a :ref:`terminator
+ instruction <terminators>` 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.
+- Additionally, an instruction also *control-depends* 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.
+- Dependence is transitive.
+
+Poison Values have the same behavior as :ref:`undef values <undefvalues>`,
+with the additional affect that any instruction which has a *dependence*
+on a poison value has undefined behavior.
+
+Here are some examples:
+
+.. code-block:: llvm
+
+ 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).
+
+.. _blockaddress:
+
+Addresses of Basic Blocks
+-------------------------
+
+``blockaddress(@function, %block)``
+
+The '``blockaddress``' 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.
+
+This value only has defined behavior when used as an operand to the
+':ref:`indirectbr <i_indirectbr>`' 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 ``ptrtoint`` and arithmetic to be performed on these values so
+long as the original value is reconstituted before the ``indirectbr``
+instruction.
+
+Finally, some targets may provide defined semantics when using the value
+as the operand to an inline assembly, but that is target specific.
+
+.. _constantexprs:
+
+Constant Expressions
+--------------------
+
+Constant expressions are used to allow expressions involving other
+constants to be used as constants. Constant expressions may be of any
+:ref:`first class <t_firstclass>` 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:
+
+``trunc (CST to TYPE)``
+ 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.
+``zext (CST to TYPE)``
+ 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.
+``sext (CST to TYPE)``
+ 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.
+``fptrunc (CST to TYPE)``
+ 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.
+``fpext (CST to TYPE)``
+ 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.
+``fptoui (CST to TYPE)``
+ 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.
+``fptosi (CST to TYPE)``
+ 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.
+``uitofp (CST to TYPE)``
+ 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.
+``sitofp (CST to TYPE)``
+ 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.
+``ptrtoint (CST to TYPE)``
+ Convert a pointer typed constant to the corresponding integer
+ constant. ``TYPE`` must be an integer type. ``CST`` must be of
+ pointer type. The ``CST`` value is zero extended, truncated, or
+ unchanged to make it fit in ``TYPE``.
+``inttoptr (CST to TYPE)``
+ 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 *really* dangerous!
+``bitcast (CST to TYPE)``
+ Convert a constant, CST, to another TYPE. The constraints of the
+ operands are the same as those for the :ref:`bitcast
+ instruction <i_bitcast>`.
+``addrspacecast (CST to TYPE)``
+ Convert a constant pointer or constant vector of pointer, CST, to another
+ TYPE in a different address space. The constraints of the operands are the
+ same as those for the :ref:`addrspacecast instruction <i_addrspacecast>`.
+``getelementptr (CSTPTR, IDX0, IDX1, ...)``, ``getelementptr inbounds (CSTPTR, IDX0, IDX1, ...)``
+ Perform the :ref:`getelementptr operation <i_getelementptr>` on
+ constants. As with the :ref:`getelementptr <i_getelementptr>`
+ instruction, the index list may have zero or more indexes, which are
+ required to make sense for the type of "CSTPTR".
+``select (COND, VAL1, VAL2)``
+ Perform the :ref:`select operation <i_select>` on constants.
+``icmp COND (VAL1, VAL2)``
+ Performs the :ref:`icmp operation <i_icmp>` on constants.
+``fcmp COND (VAL1, VAL2)``
+ Performs the :ref:`fcmp operation <i_fcmp>` on constants.
+``extractelement (VAL, IDX)``
+ Perform the :ref:`extractelement operation <i_extractelement>` on
+ constants.
+``insertelement (VAL, ELT, IDX)``
+ Perform the :ref:`insertelement operation <i_insertelement>` on
+ constants.
+``shufflevector (VEC1, VEC2, IDXMASK)``
+ Perform the :ref:`shufflevector operation <i_shufflevector>` on
+ constants.
+``extractvalue (VAL, IDX0, IDX1, ...)``
+ Perform the :ref:`extractvalue operation <i_extractvalue>` on
+ constants. The index list is interpreted in a similar manner as
+ indices in a ':ref:`getelementptr <i_getelementptr>`' operation. At
+ least one index value must be specified.
+``insertvalue (VAL, ELT, IDX0, IDX1, ...)``
+ Perform the :ref:`insertvalue operation <i_insertvalue>` on constants.
+ The index list is interpreted in a similar manner as indices in a
+ ':ref:`getelementptr <i_getelementptr>`' operation. At least one index
+ value must be specified.
+``OPCODE (LHS, RHS)``
+ Perform the specified operation of the LHS and RHS constants. OPCODE
+ may be any of the :ref:`binary <binaryops>` or :ref:`bitwise
+ binary <bitwiseops>` 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).
+
+Other Values
+============
+
+.. _inlineasmexprs:
+
+Inline Assembler Expressions
+----------------------------
+
+LLVM supports inline assembler expressions (as opposed to :ref:`Module-Level
+Inline Assembly <moduleasm>`) 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:
+
+.. code-block:: llvm
+
+ i32 (i32) asm "bswap $0", "=r,r"
+
+Inline assembler expressions may **only** be used as the callee operand
+of a :ref:`call <i_call>` or an :ref:`invoke <i_invoke>` instruction.
+Thus, typically we have:
+
+.. code-block:: llvm
+
+ %X = call i32 asm "bswap $0", "=r,r"(i32 %Y)
+
+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
+'``sideeffect``' keyword, like so:
+
+.. code-block:: llvm
+
+ call void asm sideeffect "eieio", ""()
+
+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 '``alignstack``' keyword is present:
+
+.. code-block:: llvm
+
+ call void asm alignstack "eieio", ""()
+
+Inline asms also support using non-standard assembly dialects. The
+assumed dialect is ATT. When the '``inteldialect``' keyword is present,
+the inline asm is using the Intel dialect. Currently, ATT and Intel are
+the only supported dialects. An example is:
+
+.. code-block:: llvm
+
+ call void asm inteldialect "eieio", ""()
+
+If multiple keywords appear the '``sideeffect``' keyword must come
+first, the '``alignstack``' keyword second and the '``inteldialect``'
+keyword last.
+
+Inline Asm Metadata
+^^^^^^^^^^^^^^^^^^^
+
+The call instructions that wrap inline asm nodes may have a
+"``!srcloc``" 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 ``LLVMContext``
+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:
+
+.. code-block:: llvm
+
+ call void asm sideeffect "something bad", ""(), !srcloc !42
+ ...
+ !42 = !{ i32 1234567 }
+
+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.
+
+.. _metadata:
+
+Metadata Nodes and Metadata Strings
+-----------------------------------
+
+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 ``metadata`` type and is identified in syntax by a
+preceding exclamation point ('``!``').
+
+A metadata string is a string surrounded by double quotes. It can
+contain any character by escaping non-printable characters with
+"``\xx``" where "``xx``" is the two digit hex code. For example:
+"``!"test\00"``".
+
+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:
+
+.. code-block:: llvm
+
+ !{ metadata !"test\00", i32 10}
+
+A :ref:`named metadata <namedmetadatastructure>` is a collection of
+metadata nodes, which can be looked up in the module symbol table. For
+example:
+
+.. code-block:: llvm
+
+ !foo = metadata !{!4, !3}
+
+Metadata can be used as function arguments. Here ``llvm.dbg.value``
+function is using two metadata arguments:
+
+.. code-block:: llvm
+
+ call void @llvm.dbg.value(metadata !24, i64 0, metadata !25)
+
+Metadata can be attached with an instruction. Here metadata ``!21`` is
+attached to the ``add`` instruction using the ``!dbg`` identifier:
+
+.. code-block:: llvm
+
+ %indvar.next = add i64 %indvar, 1, !dbg !21
+
+More information about specific metadata nodes recognized by the
+optimizers and code generator is found below.
+
+'``tbaa``' Metadata
+^^^^^^^^^^^^^^^^^^^
+
+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.
+
+The current metadata format is very simple. TBAA metadata nodes have up
+to three fields, e.g.:
+
+.. code-block:: llvm
+
+ !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 }
+
+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.
+
+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.
+
+If the third field is present, it's an integer which if equal to 1
+indicates that the type is "constant" (meaning
+``pointsToConstantMemory`` should return true; see `other useful
+AliasAnalysis methods <AliasAnalysis.html#OtherItfs>`_).
+
+'``tbaa.struct``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :ref:`llvm.memcpy <int_memcpy>` 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.
+
+``!tbaa.struct`` metadata can describe which memory subregions in a
+memcpy are padding and what the TBAA tags of the struct are.
+
+The current metadata format is very simple. ``!tbaa.struct`` 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.:
+
+.. code-block:: llvm
+
+ !4 = metadata !{ i64 0, i64 4, metadata !1, i64 8, i64 4, metadata !2 }
+
+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.
+
+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.
+
+'``fpmath``' Metadata
+^^^^^^^^^^^^^^^^^^^^^
+
+``fpmath`` 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:
+
+ If ``x`` is a real number that lies between two finite consecutive
+ floating-point numbers ``a`` and ``b``, without being equal to one
+ of them, then ``ulp(x) = |b - a|``, otherwise ``ulp(x)`` is the
+ distance between the two non-equal finite floating-point numbers
+ nearest ``x``. Moreover, ``ulp(NaN)`` is ``NaN``.
+
+The metadata node shall consist of a single positive floating point
+number representing the maximum relative error, for example:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ float 2.5 } ; maximum acceptable inaccuracy is 2.5 ULPs
+
+'``range``' Metadata
+^^^^^^^^^^^^^^^^^^^^
+
+``range`` metadata may be attached only to ``load``, ``call`` and ``invoke`` of
+integer types. It expresses the possible ranges the loaded value or the value
+returned by the called function at this call site is in. The ranges are
+represented with a flattened list of integers. The loaded value or the value
+returned is known to be in the union of the ranges defined by each consecutive
+pair. Each pair has the following properties:
+
+- The type must match the type loaded by the instruction.
+- The pair ``a,b`` represents the range ``[a,b)``.
+- Both ``a`` and ``b`` are constants.
+- The range is allowed to wrap.
+- The range should not represent the full or empty set. That is,
+ ``a!=b``.
+
+In addition, the pairs must be in signed order of the lower bound and
+they must be non-contiguous.
+
+Examples:
+
+.. code-block:: llvm
+
+ %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 = call i8 @foo(), !range !2 ; Can only be 0, 1, 3, 4 or 5
+ %d = invoke i8 @bar() to label %cont
+ unwind label %lpad, !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 }
+
+'``llvm.loop``'
+^^^^^^^^^^^^^^^
+
+It is sometimes useful to attach information to loop constructs. Currently,
+loop metadata is implemented as metadata attached to the branch instruction
+in the loop latch block. This type of metadata refer to a metadata node that is
+guaranteed to be separate for each loop. The loop identifier metadata is
+specified with the name ``llvm.loop``.
+
+The loop identifier metadata is implemented using a metadata that refers to
+itself to avoid merging it with any other identifier metadata, e.g.,
+during module linkage or function inlining. That is, each loop should refer
+to their own identification metadata even if they reside in separate functions.
+The following example contains loop identifier metadata for two separate loop
+constructs:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ metadata !0 }
+ !1 = metadata !{ metadata !1 }
+
+The loop identifier metadata can be used to specify additional
+per-loop metadata. Any operands after the first operand can be treated
+as user-defined metadata. For example the ``llvm.loop.interleave.count``
+suggests an interleave factor to the loop interleaver:
+
+.. code-block:: llvm
+
+ br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
+ ...
+ !0 = metadata !{ metadata !0, metadata !1 }
+ !1 = metadata !{ metadata !"llvm.loop.interleave.count", i32 4 }
+
+'``llvm.loop.vectorize``' and '``llvm.loop.interleave``'
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Metadata prefixed with ``llvm.loop.vectorize`` or ``llvm.loop.interleave`` are
+used to control per-loop vectorization and interleaving parameters such as
+vectorization width and interleave count. These metadata should be used in
+conjunction with ``llvm.loop`` loop identification metadata. The
+``llvm.loop.vectorize`` and ``llvm.loop.interleave`` metadata are only
+optimization hints and the optimizer will only interleave and vectorize loops if
+it believes it is safe to do so. The ``llvm.mem.parallel_loop_access`` metadata
+which contains information about loop-carried memory dependencies can be helpful
+in determining the safety of these transformations.
+
+'``llvm.loop.interleave.count``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata suggests an interleave count to the loop interleaver.
+The first operand is the string ``llvm.loop.interleave.count`` and the
+second operand is an integer specifying the interleave count. For
+example:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ metadata !"llvm.loop.interleave.count", i32 4 }
+
+Note that setting ``llvm.loop.interleave.count`` to 1 disables interleaving
+multiple iterations of the loop. If ``llvm.loop.interleave.count`` is set to 0
+then the interleave count will be determined automatically.
+
+'``llvm.loop.vectorize.enable``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata selectively enables or disables vectorization for the loop. The
+first operand is the string ``llvm.loop.vectorize.enable`` and the second operand
+is a bit. If the bit operand value is 1 vectorization is enabled. A value of
+0 disables vectorization:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ metadata !"llvm.loop.vectorize.enable", i1 0 }
+ !1 = metadata !{ metadata !"llvm.loop.vectorize.enable", i1 1 }
+
+'``llvm.loop.vectorize.width``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This metadata sets the target width of the vectorizer. The first
+operand is the string ``llvm.loop.vectorize.width`` and the second
+operand is an integer specifying the width. For example:
+
+.. code-block:: llvm
+
+ !0 = metadata !{ metadata !"llvm.loop.vectorize.width", i32 4 }
+
+Note that setting ``llvm.loop.vectorize.width`` to 1 disables
+vectorization of the loop. If ``llvm.loop.vectorize.width`` is set to
+0 or if the loop does not have this metadata the width will be
+determined automatically.
+
+'``llvm.mem``'
+^^^^^^^^^^^^^^^
+
+Metadata types used to annotate memory accesses with information helpful
+for optimizations are prefixed with ``llvm.mem``.
+
+'``llvm.mem.parallel_loop_access``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``llvm.mem.parallel_loop_access`` metadata refers to a loop identifier,
+or metadata containing a list of loop identifiers for nested loops.
+The metadata is attached to memory accessing instructions and denotes that
+no loop carried memory dependence exist between it and other instructions denoted
+with the same loop identifier.
+
+Precisely, given two instructions ``m1`` and ``m2`` that both have the
+``llvm.mem.parallel_loop_access`` metadata, with ``L1`` and ``L2`` being the
+set of loops associated with that metadata, respectively, then there is no loop
+carried dependence between ``m1`` and ``m2`` for loops in both ``L1`` and
+``L2``.
+
+As a special case, if all memory accessing instructions in a loop have
+``llvm.mem.parallel_loop_access`` metadata that refers to that loop, then the
+loop has no loop carried memory dependences and is considered to be a parallel
+loop.
+
+Note that if not all memory access instructions have such metadata referring to
+the loop, then the loop is considered not being trivially parallel. Additional
+memory dependence analysis is required to make that determination. As a fail
+safe mechanism, this causes loops that were originally parallel to be considered
+sequential (if optimization passes that are unaware of the parallel semantics
+insert new memory instructions into the loop body).
+
+Example of a loop that is considered parallel due to its correct use of
+both ``llvm.loop`` and ``llvm.mem.parallel_loop_access``
+metadata types that refer to the same loop identifier metadata.
+
+.. code-block:: llvm
+
+ for.body:
+ ...
+ %val0 = load i32* %arrayidx, !llvm.mem.parallel_loop_access !0
+ ...
+ store i32 %val0, i32* %arrayidx1, !llvm.mem.parallel_loop_access !0
+ ...
+ br i1 %exitcond, label %for.end, label %for.body, !llvm.loop !0
+
+ for.end:
+ ...
+ !0 = metadata !{ metadata !0 }
+
+It is also possible to have nested parallel loops. In that case the
+memory accesses refer to a list of loop identifier metadata nodes instead of
+the loop identifier metadata node directly:
+
+.. code-block:: llvm
+
+ outer.for.body:
+ ...
+ %val1 = load i32* %arrayidx3, !llvm.mem.parallel_loop_access !2
+ ...
+ br label %inner.for.body
+
+ inner.for.body:
+ ...
+ %val0 = load i32* %arrayidx1, !llvm.mem.parallel_loop_access !0
+ ...
+ store i32 %val0, i32* %arrayidx2, !llvm.mem.parallel_loop_access !0
+ ...
+ br i1 %exitcond, label %inner.for.end, label %inner.for.body, !llvm.loop !1
+
+ inner.for.end:
+ ...
+ store i32 %val1, i32* %arrayidx4, !llvm.mem.parallel_loop_access !2
+ ...
+ br i1 %exitcond, label %outer.for.end, label %outer.for.body, !llvm.loop !2
+
+ outer.for.end: ; preds = %for.body
+ ...
+ !0 = metadata !{ metadata !1, metadata !2 } ; a list of loop identifiers
+ !1 = metadata !{ metadata !1 } ; an identifier for the inner loop
+ !2 = metadata !{ metadata !2 } ; an identifier for the outer loop
+
+Module Flags Metadata
+=====================
+
+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 ``llvm.module.flags`` 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.
+
+The ``llvm.module.flags`` metadata contains a list of metadata triplets.
+Each triplet has the following form:
+
+- The first element is a *behavior* 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.
+- The second element is a metadata string that is a unique ID for the
+ metadata. Each module may only have one flag entry for each unique ID (not
+ including entries with the **Require** behavior).
+- The third element is the value of the flag.
+
+When two (or more) modules are merged together, the resulting
+``llvm.module.flags`` metadata is the union of the modules' flags. That is, for
+each unique metadata ID string, there will be exactly one entry in the merged
+modules ``llvm.module.flags`` metadata table, and the value for that entry will
+be determined by the merge behavior flag, as described below. The only exception
+is that entries with the *Require* behavior are always preserved.
+
+The following behaviors are supported:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 10 90
+
+ * - Value
+ - Behavior
+
+ * - 1
+ - **Error**
+ Emits an error if two values disagree, otherwise the resulting value
+ is that of the operands.
+
+ * - 2
+ - **Warning**
+ Emits a warning if two values disagree. The result value will be the
+ operand for the flag from the first module being linked.
+
+ * - 3
+ - **Require**
+ Adds a requirement that another module flag be present and have a
+ specified value after linking is performed. The value must be a
+ metadata pair, where the first element of the pair is the ID of the
+ module flag to be restricted, and the second element of the pair is
+ the value the module flag should be restricted to. This behavior can
+ be used to restrict the allowable results (via triggering of an
+ error) of linking IDs with the **Override** behavior.
+
+ * - 4
+ - **Override**
+ Uses the specified value, regardless of the behavior or value of the
+ other module. If both modules specify **Override**, but the values
+ differ, an error will be emitted.
+
+ * - 5
+ - **Append**
+ Appends the two values, which are required to be metadata nodes.
+
+ * - 6
+ - **AppendUnique**
+ Appends the two values, which are required to be metadata
+ nodes. However, duplicate entries in the second list are dropped
+ during the append operation.
+
+It is an error for a particular unique flag ID to have multiple behaviors,
+except in the case of **Require** (which adds restrictions on another metadata
+value) or **Override**.
+
+An example of module flags:
+
+.. code-block:: llvm
+
+ !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 }
+
+- Metadata ``!0`` has the ID ``!"foo"`` and the value '1'. The behavior
+ if two or more ``!"foo"`` flags are seen is to emit an error if their
+ values are not equal.
+
+- Metadata ``!1`` has the ID ``!"bar"`` and the value '37'. The
+ behavior if two or more ``!"bar"`` flags are seen is to use the value
+ '37'.
+
+- Metadata ``!2`` has the ID ``!"qux"`` and the value '42'. The
+ behavior if two or more ``!"qux"`` flags are seen is to emit a
+ warning if their values are not equal.
+
+- Metadata ``!3`` has the ID ``!"qux"`` and the value:
+
+ ::
+
+ metadata !{ metadata !"foo", i32 1 }
+
+ The behavior is to emit an error if the ``llvm.module.flags`` does not
+ contain a flag with the ID ``!"foo"`` that has the value '1' after linking is
+ performed.
+
+Objective-C Garbage Collection Module Flags Metadata
+----------------------------------------------------
+
+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.
+
+The Objective-C garbage collection module flags metadata consists of the
+following key-value pairs:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Key
+ - Value
+
+ * - ``Objective-C Version``
+ - **[Required]** --- The Objective-C ABI version. Valid values are 1 and 2.
+
+ * - ``Objective-C Image Info Version``
+ - **[Required]** --- The version of the image info section. Currently
+ always 0.
+
+ * - ``Objective-C Image Info Section``
+ - **[Required]** --- The section to place the metadata. Valid values are
+ ``"__OBJC, __image_info, regular"`` for Objective-C ABI version 1, and
+ ``"__DATA,__objc_imageinfo, regular, no_dead_strip"`` for
+ Objective-C ABI version 2.
+
+ * - ``Objective-C Garbage Collection``
+ - **[Required]** --- Specifies whether garbage collection is supported or
+ not. Valid values are 0, for no garbage collection, and 2, for garbage
+ collection supported.
+
+ * - ``Objective-C GC Only``
+ - **[Optional]** --- Specifies that only garbage collection is supported.
+ If present, its value must be 6. This flag requires that the
+ ``Objective-C Garbage Collection`` flag have the value 2.
+
+Some important flag interactions:
+
+- If a module with ``Objective-C Garbage Collection`` set to 0 is
+ merged with a module with ``Objective-C Garbage Collection`` set to
+ 2, then the resulting module has the
+ ``Objective-C Garbage Collection`` flag set to 0.
+- A module with ``Objective-C Garbage Collection`` set to 0 cannot be
+ merged with a module with ``Objective-C GC Only`` set to 6.
+
+Automatic Linker Flags Module Flags Metadata
+--------------------------------------------
+
+Some targets support embedding flags to the linker inside individual object
+files. Typically this is used in conjunction with language extensions which
+allow source files to explicitly declare the libraries they depend on, and have
+these automatically be transmitted to the linker via object files.
+
+These flags are encoded in the IR using metadata in the module flags section,
+using the ``Linker Options`` key. The merge behavior for this flag is required
+to be ``AppendUnique``, and the value for the key is expected to be a metadata
+node which should be a list of other metadata nodes, each of which should be a
+list of metadata strings defining linker options.
+
+For example, the following metadata section specifies two separate sets of
+linker options, presumably to link against ``libz`` and the ``Cocoa``
+framework::
+
+ !0 = metadata !{ i32 6, metadata !"Linker Options",
+ metadata !{
+ metadata !{ metadata !"-lz" },
+ metadata !{ metadata !"-framework", metadata !"Cocoa" } } }
+ !llvm.module.flags = !{ !0 }
+
+The metadata encoding as lists of lists of options, as opposed to a collapsed
+list of options, is chosen so that the IR encoding can use multiple option
+strings to specify e.g., a single library, while still having that specifier be
+preserved as an atomic element that can be recognized by a target specific
+assembly writer or object file emitter.
+
+Each individual option is required to be either a valid option for the target's
+linker, or an option that is reserved by the target specific assembly writer or
+object file emitter. No other aspect of these options is defined by the IR.
+
+C type width Module Flags Metadata
+----------------------------------
+
+The ARM backend emits a section into each generated object file describing the
+options that it was compiled with (in a compiler-independent way) to prevent
+linking incompatible objects, and to allow automatic library selection. Some
+of these options are not visible at the IR level, namely wchar_t width and enum
+width.
+
+To pass this information to the backend, these options are encoded in module
+flags metadata, using the following key-value pairs:
+
+.. list-table::
+ :header-rows: 1
+ :widths: 30 70
+
+ * - Key
+ - Value
+
+ * - short_wchar
+ - * 0 --- sizeof(wchar_t) == 4
+ * 1 --- sizeof(wchar_t) == 2
+
+ * - short_enum
+ - * 0 --- Enums are at least as large as an ``int``.
+ * 1 --- Enums are stored in the smallest integer type which can
+ represent all of its values.
+
+For example, the following metadata section specifies that the module was
+compiled with a ``wchar_t`` width of 4 bytes, and the underlying type of an
+enum is the smallest type which can represent all of its values::
+
+ !llvm.module.flags = !{!0, !1}
+ !0 = metadata !{i32 1, metadata !"short_wchar", i32 1}
+ !1 = metadata !{i32 1, metadata !"short_enum", i32 0}
+
+.. _intrinsicglobalvariables:
+
+Intrinsic Global Variables
+==========================
+
+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
+"``llvm.metadata``". This section and all globals that start with
+"``llvm.``" are reserved for use by LLVM.
+
+.. _gv_llvmused:
+
+The '``llvm.used``' Global Variable
+-----------------------------------
+
+The ``@llvm.used`` global is an array which has
+:ref:`appending linkage <linkage_appending>`. This array contains a list of
+pointers to named global variables, functions and aliases which may optionally
+have a pointer cast formed of bitcast or getelementptr. For example, a legal
+use of it is:
+
+.. code-block:: llvm
+
+ @X = global i8 4
+ @Y = global i32 123
+
+ @llvm.used = appending global [2 x i8*] [
+ i8* @X,
+ i8* bitcast (i32* @Y to i8*)
+ ], section "llvm.metadata"
+
+If a symbol appears in the ``@llvm.used`` list, then the compiler, assembler,
+and linker are required to treat the symbol as if there is a reference to the
+symbol that it cannot see (which is why they have to be named). For example, if
+a variable has internal linkage and no references other than that from the
+``@llvm.used`` 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 "``attribute((used))``" in GNU C.
+
+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.
+
+.. _gv_llvmcompilerused:
+
+The '``llvm.compiler.used``' Global Variable
+--------------------------------------------
+
+The ``@llvm.compiler.used`` directive is the same as the ``@llvm.used``
+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 ``@llvm.used``.
+
+This is a rare construct that should only be used in rare circumstances,
+and should not be exposed to source languages.
+
+.. _gv_llvmglobalctors:
+
+The '``llvm.global_ctors``' Global Variable
+-------------------------------------------
+
+.. code-block:: llvm
+
+ %0 = type { i32, void ()*, i8* }
+ @llvm.global_ctors = appending global [1 x %0] [%0 { i32 65535, void ()* @ctor, i8* @data }]
+
+The ``@llvm.global_ctors`` array contains a list of constructor
+functions, priorities, and an optional associated global or function.
+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.
+
+If the third field is present, non-null, and points to a global variable
+or function, the initializer function will only run if the associated
+data from the current module is not discarded.
+
+.. _llvmglobaldtors:
+
+The '``llvm.global_dtors``' Global Variable
+-------------------------------------------
+
+.. code-block:: llvm
+
+ %0 = type { i32, void ()*, i8* }
+ @llvm.global_dtors = appending global [1 x %0] [%0 { i32 65535, void ()* @dtor, i8* @data }]
+
+The ``@llvm.global_dtors`` array contains a list of destructor
+functions, priorities, and an optional associated global or function.
+The functions referenced by this array will be called in descending
+order of priority (i.e. highest first) when the module is unloaded. The
+order of functions with the same priority is not defined.
+
+If the third field is present, non-null, and points to a global variable
+or function, the destructor function will only run if the associated
+data from the current module is not discarded.
+
+Instruction Reference
+=====================
+
+The LLVM instruction set consists of several different classifications
+of instructions: :ref:`terminator instructions <terminators>`, :ref:`binary
+instructions <binaryops>`, :ref:`bitwise binary
+instructions <bitwiseops>`, :ref:`memory instructions <memoryops>`, and
+:ref:`other instructions <otherops>`.
+
+.. _terminators:
+
+Terminator Instructions
+-----------------------
+
+As mentioned :ref:`previously <functionstructure>`, 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 '``void``' value: they produce
+control flow, not values (the one exception being the
+':ref:`invoke <i_invoke>`' instruction).
+
+The terminator instructions are: ':ref:`ret <i_ret>`',
+':ref:`br <i_br>`', ':ref:`switch <i_switch>`',
+':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`',
+':ref:`resume <i_resume>`', and ':ref:`unreachable <i_unreachable>`'.
+
+.. _i_ret:
+
+'``ret``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ ret <type> <value> ; Return a value from a non-void function
+ ret void ; Return from void function
+
+Overview:
+"""""""""
+
+The '``ret``' instruction is used to return control flow (and optionally
+a value) from a function back to the caller.
+
+There are two forms of the '``ret``' instruction: one that returns a
+value and then causes control flow, and one that just causes control
+flow to occur.
+
+Arguments:
+""""""""""
+
+The '``ret``' instruction optionally accepts a single argument, the
+return value. The type of the return value must be a ':ref:`first
+class <t_firstclass>`' type.
+
+A function is not :ref:`well formed <wellformed>` if it it has a non-void
+return type and contains a '``ret``' 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 '``ret``' instruction with a return
+value.
+
+Semantics:
+""""""""""
+
+When the '``ret``' instruction is executed, control flow returns back to
+the calling function's context. If the caller is a
+":ref:`call <i_call>`" instruction, execution continues at the
+instruction after the call. If the caller was an
+":ref:`invoke <i_invoke>`" 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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ ret i32 5 ; Return an integer value of 5
+ ret void ; Return from a void function
+ ret { i32, i8 } { i32 4, i8 2 } ; Return a struct of values 4 and 2
+
+.. _i_br:
+
+'``br``' Instruction
+^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ br i1 <cond>, label <iftrue>, label <iffalse>
+ br label <dest> ; Unconditional branch
+
+Overview:
+"""""""""
+
+The '``br``' 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.
+
+Arguments:
+""""""""""
+
+The conditional branch form of the '``br``' instruction takes a single
+'``i1``' value and two '``label``' values. The unconditional form of the
+'``br``' instruction takes a single '``label``' value as a target.
+
+Semantics:
+""""""""""
+
+Upon execution of a conditional '``br``' instruction, the '``i1``'
+argument is evaluated. If the value is ``true``, control flows to the
+'``iftrue``' ``label`` argument. If "cond" is ``false``, control flows
+to the '``iffalse``' ``label`` argument.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ Test:
+ %cond = icmp eq i32 %a, %b
+ br i1 %cond, label %IfEqual, label %IfUnequal
+ IfEqual:
+ ret i32 1
+ IfUnequal:
+ ret i32 0
+
+.. _i_switch:
+
+'``switch``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ switch <intty> <value>, label <defaultdest> [ <intty> <val>, label <dest> ... ]
+
+Overview:
+"""""""""
+
+The '``switch``' instruction is used to transfer control flow to one of
+several different places. It is a generalization of the '``br``'
+instruction, allowing a branch to occur to one of many possible
+destinations.
+
+Arguments:
+""""""""""
+
+The '``switch``' instruction uses three parameters: an integer
+comparison value '``value``', a default '``label``' destination, and an
+array of pairs of comparison value constants and '``label``'s. The table
+is not allowed to contain duplicate constant entries.
+
+Semantics:
+""""""""""
+
+The ``switch`` instruction specifies a table of values and destinations.
+When the '``switch``' 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.
+
+Implementation:
+"""""""""""""""
+
+Depending on properties of the target machine and the particular
+``switch`` 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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ ; Emulate a conditional br instruction
+ %Val = zext i1 %value to i32
+ switch i32 %Val, label %truedest [ i32 0, label %falsedest ]
+
+ ; Emulate an unconditional br instruction
+ switch i32 0, label %dest [ ]
+
+ ; Implement a jump table:
+ switch i32 %val, label %otherwise [ i32 0, label %onzero
+ i32 1, label %onone
+ i32 2, label %ontwo ]
+
+.. _i_indirectbr:
+
+'``indirectbr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ indirectbr <somety>* <address>, [ label <dest1>, label <dest2>, ... ]
+
+Overview:
+"""""""""
+
+The '``indirectbr``' instruction implements an indirect branch to a
+label within the current function, whose address is specified by
+"``address``". Address must be derived from a
+:ref:`blockaddress <blockaddress>` constant.
+
+Arguments:
+""""""""""
+
+The '``address``' 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.
+
+This destination list is required so that dataflow analysis has an
+accurate understanding of the CFG.
+
+Semantics:
+""""""""""
+
+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.
+
+Implementation:
+"""""""""""""""
+
+This is typically implemented with a jump through a register.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ indirectbr i8* %Addr, [ label %bb1, label %bb2, label %bb3 ]
+
+.. _i_invoke:
+
+'``invoke``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = invoke [cconv] [ret attrs] <ptr to function ty> <function ptr val>(<function args>) [fn attrs]
+ to label <normal label> unwind label <exception label>
+
+Overview:
+"""""""""
+
+The '``invoke``' instruction causes control to transfer to a specified
+function, with the possibility of control flow transfer to either the
+'``normal``' label or the '``exception``' label. If the callee function
+returns with the "``ret``" instruction, control flow will return to the
+"normal" label. If the callee (or any indirect callees) returns via the
+":ref:`resume <i_resume>`" instruction or other exception handling
+mechanism, control is interrupted and continued at the dynamically
+nearest "exception" label.
+
+The '``exception``' label is a `landing
+pad <ExceptionHandling.html#overview>`_ for the exception. As such,
+'``exception``' label is required to have the
+":ref:`landingpad <i_landingpad>`" instruction, which contains the
+information about the behavior of the program after unwinding happens,
+as its first non-PHI instruction. The restrictions on the
+"``landingpad``" instruction's tightly couples it to the "``invoke``"
+instruction, so that the important information contained within the
+"``landingpad``" instruction can't be lost through normal code motion.
+
+Arguments:
+""""""""""
+
+This instruction requires several arguments:
+
+#. The optional "cconv" marker indicates which :ref:`calling
+ convention <callingconv>` the call should use. If none is
+ specified, the call defaults to using C calling conventions.
+#. The optional :ref:`Parameter Attributes <paramattrs>` list for return
+ values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
+ are valid here.
+#. '``ptr to function ty``': shall be the signature of the pointer to
+ function value being invoked. In most cases, this is a direct
+ function invocation, but indirect ``invoke``'s are just as possible,
+ branching off an arbitrary pointer to function value.
+#. '``function ptr val``': An LLVM value containing a pointer to a
+ function to be invoked.
+#. '``function args``': argument list whose types match the function
+ signature argument types and parameter attributes. All arguments must
+ be of :ref:`first class <t_firstclass>` type. If the function signature
+ indicates the function accepts a variable number of arguments, the
+ extra arguments can be specified.
+#. '``normal label``': the label reached when the called function
+ executes a '``ret``' instruction.
+#. '``exception label``': the label reached when a callee returns via
+ the :ref:`resume <i_resume>` instruction or other exception handling
+ mechanism.
+#. The optional :ref:`function attributes <fnattrs>` list. Only
+ '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
+ attributes are valid here.
+
+Semantics:
+""""""""""
+
+This instruction is designed to operate as a standard '``call``'
+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.
+
+This instruction is used in languages with destructors to ensure that
+proper cleanup is performed in the case of either a ``longjmp`` or a
+thrown exception. Additionally, this is important for implementation of
+'``catch``' clauses in high-level languages that support them.
+
+For the purposes of the SSA form, the definition of the value returned
+by the '``invoke``' 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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %retval = invoke i32 @Test(i32 15) to label %Continue
+ unwind label %TestCleanup ; i32:retval set
+ %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue
+ unwind label %TestCleanup ; i32:retval set
+
+.. _i_resume:
+
+'``resume``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ resume <type> <value>
+
+Overview:
+"""""""""
+
+The '``resume``' instruction is a terminator instruction that has no
+successors.
+
+Arguments:
+""""""""""
+
+The '``resume``' instruction requires one argument, which must have the
+same type as the result of any '``landingpad``' instruction in the same
+function.
+
+Semantics:
+""""""""""
+
+The '``resume``' instruction resumes propagation of an existing
+(in-flight) exception whose unwinding was interrupted with a
+:ref:`landingpad <i_landingpad>` instruction.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ resume { i8*, i32 } %exn
+
+.. _i_unreachable:
+
+'``unreachable``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ unreachable
+
+Overview:
+"""""""""
+
+The '``unreachable``' 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.
+
+Semantics:
+""""""""""
+
+The '``unreachable``' instruction has no defined semantics.
+
+.. _binaryops:
+
+Binary Operations
+-----------------
+
+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 :ref:`vector <t_vector>` data type. The
+result value has the same type as its operands.
+
+There are several different binary operators:
+
+.. _i_add:
+
+'``add``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = add <ty> <op1>, <op2> ; yields ty:result
+ <result> = add nuw <ty> <op1>, <op2> ; yields ty:result
+ <result> = add nsw <ty> <op1>, <op2> ; yields ty:result
+ <result> = add nuw nsw <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``add``' instruction returns the sum of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``add``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the integer sum of the two operands.
+
+If the sum has unsigned overflow, the result returned is the
+mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
+the result.
+
+Because LLVM integers use a two's complement representation, this
+instruction is appropriate for both signed and unsigned integers.
+
+``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
+respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
+result value of the ``add`` is a :ref:`poison value <poisonvalues>` if
+unsigned and/or signed overflow, respectively, occurs.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = add i32 4, %var ; yields i32:result = 4 + %var
+
+.. _i_fadd:
+
+'``fadd``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fadd [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``fadd``' instruction returns the sum of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``fadd``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the floating point sum of the two operands. This
+instruction can also take any number of :ref:`fast-math flags <fastmath>`,
+which are optimization hints to enable otherwise unsafe floating point
+optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fadd float 4.0, %var ; yields float:result = 4.0 + %var
+
+'``sub``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = sub <ty> <op1>, <op2> ; yields ty:result
+ <result> = sub nuw <ty> <op1>, <op2> ; yields ty:result
+ <result> = sub nsw <ty> <op1>, <op2> ; yields ty:result
+ <result> = sub nuw nsw <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``sub``' instruction returns the difference of its two operands.
+
+Note that the '``sub``' instruction is used to represent the '``neg``'
+instruction present in most other intermediate representations.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``sub``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the integer difference of the two operands.
+
+If the difference has unsigned overflow, the result returned is the
+mathematical result modulo 2\ :sup:`n`\ , where n is the bit width of
+the result.
+
+Because LLVM integers use a two's complement representation, this
+instruction is appropriate for both signed and unsigned integers.
+
+``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
+respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
+result value of the ``sub`` is a :ref:`poison value <poisonvalues>` if
+unsigned and/or signed overflow, respectively, occurs.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = sub i32 4, %var ; yields i32:result = 4 - %var
+ <result> = sub i32 0, %val ; yields i32:result = -%var
+
+.. _i_fsub:
+
+'``fsub``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fsub [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``fsub``' instruction returns the difference of its two operands.
+
+Note that the '``fsub``' instruction is used to represent the '``fneg``'
+instruction present in most other intermediate representations.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``fsub``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the floating point difference of the two operands.
+This instruction can also take any number of :ref:`fast-math
+flags <fastmath>`, which are optimization hints to enable otherwise
+unsafe floating point optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fsub float 4.0, %var ; yields float:result = 4.0 - %var
+ <result> = fsub float -0.0, %val ; yields float:result = -%var
+
+'``mul``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = mul <ty> <op1>, <op2> ; yields ty:result
+ <result> = mul nuw <ty> <op1>, <op2> ; yields ty:result
+ <result> = mul nsw <ty> <op1>, <op2> ; yields ty:result
+ <result> = mul nuw nsw <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``mul``' instruction returns the product of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``mul``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the integer product of the two operands.
+
+If the result of the multiplication has unsigned overflow, the result
+returned is the mathematical result modulo 2\ :sup:`n`\ , where n is the
+bit width of the result.
+
+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. ``i32`` * ``i32`` -> ``i64``) is needed, the operands should be
+sign-extended or zero-extended as appropriate to the width of the full
+product.
+
+``nuw`` and ``nsw`` stand for "No Unsigned Wrap" and "No Signed Wrap",
+respectively. If the ``nuw`` and/or ``nsw`` keywords are present, the
+result value of the ``mul`` is a :ref:`poison value <poisonvalues>` if
+unsigned and/or signed overflow, respectively, occurs.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = mul i32 4, %var ; yields i32:result = 4 * %var
+
+.. _i_fmul:
+
+'``fmul``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fmul [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``fmul``' instruction returns the product of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``fmul``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the floating point product of the two operands.
+This instruction can also take any number of :ref:`fast-math
+flags <fastmath>`, which are optimization hints to enable otherwise
+unsafe floating point optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fmul float 4.0, %var ; yields float:result = 4.0 * %var
+
+'``udiv``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = udiv <ty> <op1>, <op2> ; yields ty:result
+ <result> = udiv exact <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``udiv``' instruction returns the quotient of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``udiv``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the unsigned integer quotient of the two operands.
+
+Note that unsigned integer division and signed integer division are
+distinct operations; for signed integer division, use '``sdiv``'.
+
+Division by zero leads to undefined behavior.
+
+If the ``exact`` keyword is present, the result value of the ``udiv`` is
+a :ref:`poison value <poisonvalues>` if %op1 is not a multiple of %op2 (as
+such, "((a udiv exact b) mul b) == a").
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = udiv i32 4, %var ; yields i32:result = 4 / %var
+
+'``sdiv``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = sdiv <ty> <op1>, <op2> ; yields ty:result
+ <result> = sdiv exact <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``sdiv``' instruction returns the quotient of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``sdiv``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the signed integer quotient of the two operands
+rounded towards zero.
+
+Note that signed integer division and unsigned integer division are
+distinct operations; for unsigned integer division, use '``udiv``'.
+
+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.
+
+If the ``exact`` keyword is present, the result value of the ``sdiv`` is
+a :ref:`poison value <poisonvalues>` if the result would be rounded.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = sdiv i32 4, %var ; yields i32:result = 4 / %var
+
+.. _i_fdiv:
+
+'``fdiv``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fdiv [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``fdiv``' instruction returns the quotient of its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``fdiv``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The value produced is the floating point quotient of the two operands.
+This instruction can also take any number of :ref:`fast-math
+flags <fastmath>`, which are optimization hints to enable otherwise
+unsafe floating point optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fdiv float 4.0, %var ; yields float:result = 4.0 / %var
+
+'``urem``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = urem <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``urem``' instruction returns the remainder from the unsigned
+division of its two arguments.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``urem``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+This instruction returns the unsigned integer *remainder* of a division.
+This instruction always performs an unsigned division to get the
+remainder.
+
+Note that unsigned integer remainder and signed integer remainder are
+distinct operations; for signed integer remainder, use '``srem``'.
+
+Taking the remainder of a division by zero leads to undefined behavior.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = urem i32 4, %var ; yields i32:result = 4 % %var
+
+'``srem``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = srem <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``srem``' instruction returns the remainder from the signed
+division of its two operands. This instruction can also take
+:ref:`vector <t_vector>` versions of the values in which case the elements
+must be integers.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``srem``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+This instruction returns the *remainder* of a division (where the result
+is either zero or has the same sign as the dividend, ``op1``), not the
+*modulo* operator (where the result is either zero or has the same sign
+as the divisor, ``op2``) of a value. For more information about the
+difference, see `The Math
+Forum <http://mathforum.org/dr.math/problems/anne.4.28.99.html>`_. For a
+table of how this is implemented in various languages, please see
+`Wikipedia: modulo
+operation <http://en.wikipedia.org/wiki/Modulo_operation>`_.
+
+Note that signed integer remainder and unsigned integer remainder are
+distinct operations; for unsigned integer remainder, use '``urem``'.
+
+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.)
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = srem i32 4, %var ; yields i32:result = 4 % %var
+
+.. _i_frem:
+
+'``frem``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = frem [fast-math flags]* <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``frem``' instruction returns the remainder from the division of
+its two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``frem``' instruction must be :ref:`floating
+point <t_floating>` or :ref:`vector <t_vector>` of floating point values.
+Both arguments must have identical types.
+
+Semantics:
+""""""""""
+
+This instruction returns the *remainder* of a division. The remainder
+has the same sign as the dividend. This instruction can also take any
+number of :ref:`fast-math flags <fastmath>`, which are optimization hints
+to enable otherwise unsafe floating point optimizations:
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = frem float 4.0, %var ; yields float:result = 4.0 % %var
+
+.. _bitwiseops:
+
+Bitwise Binary Operations
+-------------------------
+
+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.
+
+'``shl``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = shl <ty> <op1>, <op2> ; yields ty:result
+ <result> = shl nuw <ty> <op1>, <op2> ; yields ty:result
+ <result> = shl nsw <ty> <op1>, <op2> ; yields ty:result
+ <result> = shl nuw nsw <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``shl``' instruction returns the first operand shifted to the left
+a specified number of bits.
+
+Arguments:
+""""""""""
+
+Both arguments to the '``shl``' instruction must be the same
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
+'``op2``' is treated as an unsigned value.
+
+Semantics:
+""""""""""
+
+The value produced is ``op1`` \* 2\ :sup:`op2` mod 2\ :sup:`n`,
+where ``n`` is the width of the result. If ``op2`` is (statically or
+dynamically) negative or equal to or larger than the number of bits in
+``op1``, the result is undefined. If the arguments are vectors, each
+vector element of ``op1`` is shifted by the corresponding shift amount
+in ``op2``.
+
+If the ``nuw`` keyword is present, then the shift produces a :ref:`poison
+value <poisonvalues>` if it shifts out any non-zero bits. If the
+``nsw`` keyword is present, then the shift produces a :ref:`poison
+value <poisonvalues>` 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)).
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = shl i32 4, %var ; yields i32: 4 << %var
+ <result> = shl i32 4, 2 ; yields i32: 16
+ <result> = shl i32 1, 10 ; yields i32: 1024
+ <result> = shl i32 1, 32 ; undefined
+ <result> = shl <2 x i32> < i32 1, i32 1>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 2, i32 4>
+
+'``lshr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = lshr <ty> <op1>, <op2> ; yields ty:result
+ <result> = lshr exact <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``lshr``' instruction (logical shift right) returns the first
+operand shifted to the right a specified number of bits with zero fill.
+
+Arguments:
+""""""""""
+
+Both arguments to the '``lshr``' instruction must be the same
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
+'``op2``' is treated as an unsigned value.
+
+Semantics:
+""""""""""
+
+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 ``op2`` is (statically or dynamically) equal to or larger
+than the number of bits in ``op1``, the result is undefined. If the
+arguments are vectors, each vector element of ``op1`` is shifted by the
+corresponding shift amount in ``op2``.
+
+If the ``exact`` keyword is present, the result value of the ``lshr`` is
+a :ref:`poison value <poisonvalues>` if any of the bits shifted out are
+non-zero.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = lshr i32 4, 1 ; yields i32:result = 2
+ <result> = lshr i32 4, 2 ; yields i32:result = 1
+ <result> = lshr i8 4, 3 ; yields i8:result = 0
+ <result> = lshr i8 -2, 1 ; yields i8:result = 0x7F
+ <result> = lshr i32 1, 32 ; undefined
+ <result> = lshr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 2> ; yields: result=<2 x i32> < i32 0x7FFFFFFF, i32 1>
+
+'``ashr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = ashr <ty> <op1>, <op2> ; yields ty:result
+ <result> = ashr exact <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``ashr``' instruction (arithmetic shift right) returns the first
+operand shifted to the right a specified number of bits with sign
+extension.
+
+Arguments:
+""""""""""
+
+Both arguments to the '``ashr``' instruction must be the same
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer type.
+'``op2``' is treated as an unsigned value.
+
+Semantics:
+""""""""""
+
+This instruction always performs an arithmetic shift right operation,
+The most significant bits of the result will be filled with the sign bit
+of ``op1``. If ``op2`` is (statically or dynamically) equal to or larger
+than the number of bits in ``op1``, the result is undefined. If the
+arguments are vectors, each vector element of ``op1`` is shifted by the
+corresponding shift amount in ``op2``.
+
+If the ``exact`` keyword is present, the result value of the ``ashr`` is
+a :ref:`poison value <poisonvalues>` if any of the bits shifted out are
+non-zero.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = ashr i32 4, 1 ; yields i32:result = 2
+ <result> = ashr i32 4, 2 ; yields i32:result = 1
+ <result> = ashr i8 4, 3 ; yields i8:result = 0
+ <result> = ashr i8 -2, 1 ; yields i8:result = -1
+ <result> = ashr i32 1, 32 ; undefined
+ <result> = ashr <2 x i32> < i32 -2, i32 4>, < i32 1, i32 3> ; yields: result=<2 x i32> < i32 -1, i32 0>
+
+'``and``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = and <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``and``' instruction returns the bitwise logical and of its two
+operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``and``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The truth table used for the '``and``' instruction is:
+
++-----+-----+-----+
+| In0 | In1 | Out |
++-----+-----+-----+
+| 0 | 0 | 0 |
++-----+-----+-----+
+| 0 | 1 | 0 |
++-----+-----+-----+
+| 1 | 0 | 0 |
++-----+-----+-----+
+| 1 | 1 | 1 |
++-----+-----+-----+
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = and i32 4, %var ; yields i32:result = 4 & %var
+ <result> = and i32 15, 40 ; yields i32:result = 8
+ <result> = and i32 4, 8 ; yields i32:result = 0
+
+'``or``' Instruction
+^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = or <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``or``' instruction returns the bitwise logical inclusive or of its
+two operands.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``or``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The truth table used for the '``or``' instruction is:
+
++-----+-----+-----+
+| In0 | In1 | Out |
++-----+-----+-----+
+| 0 | 0 | 0 |
++-----+-----+-----+
+| 0 | 1 | 1 |
++-----+-----+-----+
+| 1 | 0 | 1 |
++-----+-----+-----+
+| 1 | 1 | 1 |
++-----+-----+-----+
+
+Example:
+""""""""
+
+::
+
+ <result> = or i32 4, %var ; yields i32:result = 4 | %var
+ <result> = or i32 15, 40 ; yields i32:result = 47
+ <result> = or i32 4, 8 ; yields i32:result = 12
+
+'``xor``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = xor <ty> <op1>, <op2> ; yields ty:result
+
+Overview:
+"""""""""
+
+The '``xor``' instruction returns the bitwise logical exclusive or of
+its two operands. The ``xor`` is used to implement the "one's
+complement" operation, which is the "~" operator in C.
+
+Arguments:
+""""""""""
+
+The two arguments to the '``xor``' instruction must be
+:ref:`integer <t_integer>` or :ref:`vector <t_vector>` of integer values. Both
+arguments must have identical types.
+
+Semantics:
+""""""""""
+
+The truth table used for the '``xor``' instruction is:
+
++-----+-----+-----+
+| In0 | In1 | Out |
++-----+-----+-----+
+| 0 | 0 | 0 |
++-----+-----+-----+
+| 0 | 1 | 1 |
++-----+-----+-----+
+| 1 | 0 | 1 |
++-----+-----+-----+
+| 1 | 1 | 0 |
++-----+-----+-----+
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = xor i32 4, %var ; yields i32:result = 4 ^ %var
+ <result> = xor i32 15, 40 ; yields i32:result = 39
+ <result> = xor i32 4, 8 ; yields i32:result = 12
+ <result> = xor i32 %V, -1 ; yields i32:result = ~%V
+
+Vector Operations
+-----------------
+
+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.
+
+.. _i_extractelement:
+
+'``extractelement``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = extractelement <n x <ty>> <val>, <ty2> <idx> ; yields <ty>
+
+Overview:
+"""""""""
+
+The '``extractelement``' instruction extracts a single scalar element
+from a vector at a specified index.
+
+Arguments:
+""""""""""
+
+The first operand of an '``extractelement``' instruction is a value of
+:ref:`vector <t_vector>` type. The second operand is an index indicating
+the position from which to extract the element. The index may be a
+variable of any integer type.
+
+Semantics:
+""""""""""
+
+The result is a scalar of the same type as the element type of ``val``.
+Its value is the value at position ``idx`` of ``val``. If ``idx``
+exceeds the length of ``val``, the results are undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = extractelement <4 x i32> %vec, i32 0 ; yields i32
+
+.. _i_insertelement:
+
+'``insertelement``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = insertelement <n x <ty>> <val>, <ty> <elt>, <ty2> <idx> ; yields <n x <ty>>
+
+Overview:
+"""""""""
+
+The '``insertelement``' instruction inserts a scalar element into a
+vector at a specified index.
+
+Arguments:
+""""""""""
+
+The first operand of an '``insertelement``' instruction is a value of
+:ref:`vector <t_vector>` 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 of any integer type.
+
+Semantics:
+""""""""""
+
+The result is a vector of the same type as ``val``. Its element values
+are those of ``val`` except at position ``idx``, where it gets the value
+``elt``. If ``idx`` exceeds the length of ``val``, the results are
+undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = insertelement <4 x i32> %vec, i32 1, i32 0 ; yields <4 x i32>
+
+.. _i_shufflevector:
+
+'``shufflevector``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = shufflevector <n x <ty>> <v1>, <n x <ty>> <v2>, <m x i32> <mask> ; yields <m x <ty>>
+
+Overview:
+"""""""""
+
+The '``shufflevector``' 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.
+
+Arguments:
+""""""""""
+
+The first two operands of a '``shufflevector``' 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.
+
+The shuffle mask operand is required to be a constant vector with either
+constant integer or undef values.
+
+Semantics:
+""""""""""
+
+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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> %v2,
+ <4 x i32> <i32 0, i32 4, i32 1, i32 5> ; yields <4 x i32>
+ <result> = shufflevector <4 x i32> %v1, <4 x i32> undef,
+ <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32> - Identity shuffle.
+ <result> = shufflevector <8 x i32> %v1, <8 x i32> undef,
+ <4 x i32> <i32 0, i32 1, i32 2, i32 3> ; yields <4 x i32>
+ <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 > ; yields <8 x i32>
+
+Aggregate Operations
+--------------------
+
+LLVM supports several instructions for working with
+:ref:`aggregate <t_aggregate>` values.
+
+.. _i_extractvalue:
+
+'``extractvalue``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = extractvalue <aggregate type> <val>, <idx>{, <idx>}*
+
+Overview:
+"""""""""
+
+The '``extractvalue``' instruction extracts the value of a member field
+from an :ref:`aggregate <t_aggregate>` value.
+
+Arguments:
+""""""""""
+
+The first operand of an '``extractvalue``' instruction is a value of
+:ref:`struct <t_struct>` or :ref:`array <t_array>` type. The operands are
+constant indices to specify which value to extract in a similar manner
+as indices in a '``getelementptr``' instruction.
+
+The major differences to ``getelementptr`` indexing are:
+
+- Since the value being indexed is not a pointer, the first index is
+ omitted and assumed to be zero.
+- At least one index must be specified.
+- Not only struct indices but also array indices must be in bounds.
+
+Semantics:
+""""""""""
+
+The result is the value at the position in the aggregate specified by
+the index operands.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = extractvalue {i32, float} %agg, 0 ; yields i32
+
+.. _i_insertvalue:
+
+'``insertvalue``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = insertvalue <aggregate type> <val>, <ty> <elt>, <idx>{, <idx>}* ; yields <aggregate type>
+
+Overview:
+"""""""""
+
+The '``insertvalue``' instruction inserts a value into a member field in
+an :ref:`aggregate <t_aggregate>` value.
+
+Arguments:
+""""""""""
+
+The first operand of an '``insertvalue``' instruction is a value of
+:ref:`struct <t_struct>` or :ref:`array <t_array>` 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 '``extractvalue``' instruction. The value
+to insert must have the same type as the value identified by the
+indices.
+
+Semantics:
+""""""""""
+
+The result is an aggregate of the same type as ``val``. Its value is
+that of ``val`` except that the value at the position specified by the
+indices is that of ``elt``.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %agg1 = insertvalue {i32, float} undef, i32 1, 0 ; yields {i32 1, float undef}
+ %agg2 = insertvalue {i32, float} %agg1, float %val, 1 ; yields {i32 1, float %val}
+ %agg3 = insertvalue {i32, {float}} %agg1, float %val, 1, 0 ; yields {i32 1, float %val}
+
+.. _memoryops:
+
+Memory Access and Addressing Operations
+---------------------------------------
+
+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.
+
+.. _i_alloca:
+
+'``alloca``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = alloca [inalloca] <type> [, <ty> <NumElements>] [, align <alignment>] ; yields type*:result
+
+Overview:
+"""""""""
+
+The '``alloca``' 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).
+
+Arguments:
+""""""""""
+
+The '``alloca``' instruction allocates ``sizeof(<type>)*NumElements``
+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. The
+alignment may not be greater than ``1 << 29``. If not specified, or if
+zero, the target can choose to align the allocation on any convenient
+boundary compatible with the type.
+
+'``type``' may be any sized type.
+
+Semantics:
+""""""""""
+
+Memory is allocated; a pointer is returned. The operation is undefined
+if there is insufficient stack space for the allocation. '``alloca``'d
+memory is automatically released when the function returns. The
+'``alloca``' instruction is commonly used to represent automatic
+variables that must have an address available. When the function returns
+(either with the ``ret`` or ``resume`` 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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %ptr = alloca i32 ; yields i32*:ptr
+ %ptr = alloca i32, i32 4 ; yields i32*:ptr
+ %ptr = alloca i32, i32 4, align 1024 ; yields i32*:ptr
+ %ptr = alloca i32, align 1024 ; yields i32*:ptr
+
+.. _i_load:
+
+'``load``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <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 }
+
+Overview:
+"""""""""
+
+The '``load``' instruction is used to read from memory.
+
+Arguments:
+""""""""""
+
+The argument to the ``load`` instruction specifies the memory address
+from which to load. The pointer must point to a :ref:`first
+class <t_firstclass>` type. If the ``load`` is marked as ``volatile``,
+then the optimizer is not allowed to modify the number or order of
+execution of this ``load`` with other :ref:`volatile
+operations <volatile>`.
+
+If the ``load`` is marked as ``atomic``, it takes an extra
+:ref:`ordering <ordering>` and optional ``singlethread`` argument. The
+``release`` and ``acq_rel`` orderings are not valid on ``load``
+instructions. Atomic loads produce :ref:`defined <memmodel>` 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.
+``align`` 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. ``!nontemporal`` does not have
+any defined semantics for atomic loads.
+
+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 undefined behavior. Underestimating the alignment
+may produce less efficient code. An alignment of 1 is always safe. The
+maximum possible alignment is ``1 << 29``.
+
+The optional ``!nontemporal`` metadata must reference a single
+metadata name ``<index>`` corresponding to a metadata node with one
+``i32`` entry of value 1. The existence of the ``!nontemporal``
+metadata 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.
+
+The optional ``!invariant.load`` metadata must reference a single
+metadata name ``<index>`` corresponding to a metadata node with no
+entries. The existence of the ``!invariant.load`` metadata 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.
+
+Semantics:
+""""""""""
+
+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 ``i24`` reads at most three bytes. When loading a
+value of a type like ``i20`` 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.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %ptr = alloca i32 ; yields i32*:ptr
+ store i32 3, i32* %ptr ; yields void
+ %val = load i32* %ptr ; yields i32:val = i32 3
+
+.. _i_store:
+
+'``store``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ store [volatile] <ty> <value>, <ty>* <pointer>[, align <alignment>][, !nontemporal !<index>] ; yields void
+ store atomic [volatile] <ty> <value>, <ty>* <pointer> [singlethread] <ordering>, align <alignment> ; yields void
+
+Overview:
+"""""""""
+
+The '``store``' instruction is used to write to memory.
+
+Arguments:
+""""""""""
+
+There are two arguments to the ``store`` instruction: a value to store
+and an address at which to store it. The type of the ``<pointer>``
+operand must be a pointer to the :ref:`first class <t_firstclass>` type of
+the ``<value>`` operand. If the ``store`` is marked as ``volatile``,
+then the optimizer is not allowed to modify the number or order of
+execution of this ``store`` with other :ref:`volatile
+operations <volatile>`.
+
+If the ``store`` is marked as ``atomic``, it takes an extra
+:ref:`ordering <ordering>` and optional ``singlethread`` argument. The
+``acquire`` and ``acq_rel`` orderings aren't valid on ``store``
+instructions. Atomic loads produce :ref:`defined <memmodel>` 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.
+``align`` 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. ``!nontemporal`` does not
+have any defined semantics for atomic stores.
+
+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 undefined behavior. Underestimating the
+alignment may produce less efficient code. An alignment of 1 is always
+safe. The maximum possible alignment is ``1 << 29``.
+
+The optional ``!nontemporal`` metadata must reference a single metadata
+name ``<index>`` corresponding to a metadata node with one ``i32`` entry of
+value 1. The existence of the ``!nontemporal`` metadata 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.
+
+Semantics:
+""""""""""
+
+The contents of memory are updated to contain ``<value>`` at the
+location specified by the ``<pointer>`` operand. If ``<value>`` 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 ``i24`` writes at most three bytes. When writing a
+value of a type like ``i20`` 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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %ptr = alloca i32 ; yields i32*:ptr
+ store i32 3, i32* %ptr ; yields void
+ %val = load i32* %ptr ; yields i32:val = i32 3
+
+.. _i_fence:
+
+'``fence``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ fence [singlethread] <ordering> ; yields void
+
+Overview:
+"""""""""
+
+The '``fence``' instruction is used to introduce happens-before edges
+between operations.
+
+Arguments:
+""""""""""
+
+'``fence``' instructions take an :ref:`ordering <ordering>` argument which
+defines what *synchronizes-with* edges they add. They can only be given
+``acquire``, ``release``, ``acq_rel``, and ``seq_cst`` orderings.
+
+Semantics:
+""""""""""
+
+A fence A which has (at least) ``release`` ordering semantics
+*synchronizes with* a fence B with (at least) ``acquire`` ordering
+semantics if and only if there exist atomic operations X and Y, both
+operating on some atomic object M, such that A is sequenced before X, X
+modifies M (either directly or through some side effect of a sequence
+headed by X), Y is sequenced before B, and Y observes M. This provides a
+*happens-before* dependency between A and B. Rather than an explicit
+``fence``, one (but not both) of the atomic operations X or Y might
+provide a ``release`` or ``acquire`` (resp.) ordering constraint and
+still *synchronize-with* the explicit ``fence`` and establish the
+*happens-before* edge.
+
+A ``fence`` which has ``seq_cst`` ordering, in addition to having both
+``acquire`` and ``release`` semantics specified above, participates in
+the global program order of other ``seq_cst`` operations and/or fences.
+
+The optional ":ref:`singlethread <singlethread>`" argument specifies
+that the fence only synchronizes with other fences in the same thread.
+(This is useful for interacting with signal handlers.)
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ fence acquire ; yields void
+ fence singlethread seq_cst ; yields void
+
+.. _i_cmpxchg:
+
+'``cmpxchg``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ cmpxchg [weak] [volatile] <ty>* <pointer>, <ty> <cmp>, <ty> <new> [singlethread] <success ordering> <failure ordering> ; yields { ty, i1 }
+
+Overview:
+"""""""""
+
+The '``cmpxchg``' 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 tries to store a new value into the memory.
+
+Arguments:
+""""""""""
+
+There are three arguments to the '``cmpxchg``' 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 '<cmp>' 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. '<cmp>' and '<new>' must have the same
+type, and the type of '<pointer>' must be a pointer to that type. If the
+``cmpxchg`` is marked as ``volatile``, then the optimizer is not allowed
+to modify the number or order of execution of this ``cmpxchg`` with
+other :ref:`volatile operations <volatile>`.
+
+The success and failure :ref:`ordering <ordering>` arguments specify how this
+``cmpxchg`` synchronizes with other atomic operations. Both ordering parameters
+must be at least ``monotonic``, the ordering constraint on failure must be no
+stronger than that on success, and the failure ordering cannot be either
+``release`` or ``acq_rel``.
+
+The optional "``singlethread``" argument declares that the ``cmpxchg``
+is only atomic with respect to code (usually signal handlers) running in
+the same thread as the ``cmpxchg``. Otherwise the cmpxchg is atomic with
+respect to all other code in the system.
+
+The pointer passed into cmpxchg must have alignment greater than or
+equal to the size in memory of the operand.
+
+Semantics:
+""""""""""
+
+The contents of memory at the location specified by the '``<pointer>``' operand
+is read and compared to '``<cmp>``'; if the read value is the equal, the
+'``<new>``' is written. The original value at the location is returned, together
+with a flag indicating success (true) or failure (false).
+
+If the cmpxchg operation is marked as ``weak`` then a spurious failure is
+permitted: the operation may not write ``<new>`` even if the comparison
+matched.
+
+If the cmpxchg operation is strong (the default), the i1 value is 1 if and only
+if the value loaded equals ``cmp``.
+
+A successful ``cmpxchg`` is a read-modify-write instruction for the purpose of
+identifying release sequences. A failed ``cmpxchg`` is equivalent to an atomic
+load with an ordering parameter determined the second ordering parameter.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ entry:
+ %orig = atomic load i32* %ptr unordered ; yields i32
+ br label %loop
+
+ loop:
+ %cmp = phi i32 [ %orig, %entry ], [%old, %loop]
+ %squared = mul i32 %cmp, %cmp
+ %val_success = cmpxchg i32* %ptr, i32 %cmp, i32 %squared acq_rel monotonic ; yields { i32, i1 }
+ %value_loaded = extractvalue { i32, i1 } %val_success, 0
+ %success = extractvalue { i32, i1 } %val_success, 1
+ br i1 %success, label %done, label %loop
+
+ done:
+ ...
+
+.. _i_atomicrmw:
+
+'``atomicrmw``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ atomicrmw [volatile] <operation> <ty>* <pointer>, <ty> <value> [singlethread] <ordering> ; yields ty
+
+Overview:
+"""""""""
+
+The '``atomicrmw``' instruction is used to atomically modify memory.
+
+Arguments:
+""""""""""
+
+There are three arguments to the '``atomicrmw``' 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:
+
+- xchg
+- add
+- sub
+- and
+- nand
+- or
+- xor
+- max
+- min
+- umax
+- umin
+
+The type of '<value>' 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 '``<pointer>``' operand must
+be a pointer to that type. If the ``atomicrmw`` is marked as
+``volatile``, then the optimizer is not allowed to modify the number or
+order of execution of this ``atomicrmw`` with other :ref:`volatile
+operations <volatile>`.
+
+Semantics:
+""""""""""
+
+The contents of memory at the location specified by the '``<pointer>``'
+operand are atomically read, modified, and written back. The original
+value at the location is returned. The modification is specified by the
+operation argument:
+
+- xchg: ``*ptr = val``
+- add: ``*ptr = *ptr + val``
+- sub: ``*ptr = *ptr - val``
+- and: ``*ptr = *ptr & val``
+- nand: ``*ptr = ~(*ptr & val)``
+- or: ``*ptr = *ptr | val``
+- xor: ``*ptr = *ptr ^ val``
+- max: ``*ptr = *ptr > val ? *ptr : val`` (using a signed comparison)
+- min: ``*ptr = *ptr < val ? *ptr : val`` (using a signed comparison)
+- umax: ``*ptr = *ptr > val ? *ptr : val`` (using an unsigned
+ comparison)
+- umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned
+ comparison)
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %old = atomicrmw add i32* %ptr, i32 1 acquire ; yields i32
+
+.. _i_getelementptr:
+
+'``getelementptr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = getelementptr <pty>* <ptrval>{, <ty> <idx>}*
+ <result> = getelementptr inbounds <pty>* <ptrval>{, <ty> <idx>}*
+ <result> = getelementptr <ptr vector> ptrval, <vector index type> idx
+
+Overview:
+"""""""""
+
+The '``getelementptr``' instruction is used to get the address of a
+subelement of an :ref:`aggregate <t_aggregate>` data structure. It performs
+address calculation only and does not access memory.
+
+Arguments:
+""""""""""
+
+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.
+
+The type of each index argument depends on the type it is indexing into.
+When indexing into a (optionally packed) structure, only ``i32`` integer
+**constants** are allowed (when using a vector of indices they must all
+be the **same** ``i32`` integer constant). 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.
+
+For example, let's consider a C code fragment and how it gets compiled
+to LLVM:
+
+.. code-block:: c
+
+ 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];
+ }
+
+The LLVM code generated by Clang is:
+
+.. code-block:: llvm
+
+ %struct.RT = type { i8, [10 x [20 x i32]], i8 }
+ %struct.ST = type { 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
+ }
+
+Semantics:
+""""""""""
+
+In the example above, the first index is indexing into the
+'``%struct.ST*``' type, which is a pointer, yielding a '``%struct.ST``'
+= '``{ i32, double, %struct.RT }``' type, a structure. The second index
+indexes into the third element of the structure, yielding a
+'``%struct.RT``' = '``{ i8 , [10 x [20 x i32]], i8 }``' type, another
+structure. The third index indexes into the second element of the
+structure, yielding a '``[10 x [20 x i32]]``' type, an array. The two
+dimensions of the array are subscripted into, yielding an '``i32``'
+type. The '``getelementptr``' instruction returns a pointer to this
+element, thus computing a value of '``i32*``' type.
+
+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:
+
+.. code-block:: llvm
+
+ define i32* @foo(%struct.ST* %s) {
+ %t1 = getelementptr %struct.ST* %s, i32 1 ; yields %struct.ST*:%t1
+ %t2 = getelementptr %struct.ST* %t1, i32 0, i32 2 ; yields %struct.RT*:%t2
+ %t3 = getelementptr %struct.RT* %t2, i32 0, i32 1 ; yields [10 x [20 x i32]]*:%t3
+ %t4 = getelementptr [10 x [20 x i32]]* %t3, i32 0, i32 5 ; yields [20 x i32]*:%t4
+ %t5 = getelementptr [20 x i32]* %t4, i32 0, i32 13 ; yields i32*:%t5
+ ret i32* %t5
+ }
+
+If the ``inbounds`` keyword is present, the result value of the
+``getelementptr`` is a :ref:`poison value <poisonvalues>` if the base
+pointer is not an *in bounds* 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 *in bounds* address of that
+allocated object. The *in bounds* 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
+``inbounds`` keyword applies to each of the computations element-wise.
+
+If the ``inbounds`` 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
+``getelementptr`` 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
+:ref:`Pointer Aliasing Rules <pointeraliasing>` section for more
+information.
+
+The getelementptr instruction is often confusing. For some more insight
+into how it works, see :doc:`the getelementptr FAQ <GetElementPtr>`.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ ; yields [12 x i8]*:aptr
+ %aptr = getelementptr {i32, [12 x i8]}* %saptr, i64 0, i32 1
+ ; yields i8*:vptr
+ %vptr = getelementptr {i32, <2 x i8>}* %svptr, i64 0, i32 1, i32 1
+ ; yields i8*:eptr
+ %eptr = getelementptr [12 x i8]* %aptr, i64 0, i32 1
+ ; yields i32*:iptr
+ %iptr = getelementptr [10 x i32]* @arr, i16 0, i16 0
+
+In cases where the pointer argument is a vector of pointers, each index
+must be a vector with the same number of elements. For example:
+
+.. code-block:: llvm
+
+ %A = getelementptr <4 x i8*> %ptrs, <4 x i64> %offsets,
+
+Conversion Operations
+---------------------
+
+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.
+
+'``trunc .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = trunc <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``trunc``' instruction truncates its operand to the type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``trunc``' instruction takes a value to trunc, and a type to trunc
+it to. Both types must be of :ref:`integer <t_integer>` types, or vectors
+of the same number of integers. The bit size of the ``value`` must be
+larger than the bit size of the destination type, ``ty2``. Equal sized
+types are not allowed.
+
+Semantics:
+""""""""""
+
+The '``trunc``' instruction truncates the high order bits in ``value``
+and converts the remaining bits to ``ty2``. Since the source size must
+be larger than the destination size, ``trunc`` cannot be a *no-op cast*.
+It will always truncate bits.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = trunc i32 257 to i8 ; yields i8:1
+ %Y = trunc i32 123 to i1 ; yields i1:true
+ %Z = trunc i32 122 to i1 ; yields i1:false
+ %W = trunc <2 x i16> <i16 8, i16 7> to <2 x i8> ; yields <i8 8, i8 7>
+
+'``zext .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = zext <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``zext``' instruction zero extends its operand to type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``zext``' instruction takes a value to cast, and a type to cast it
+to. Both types must be of :ref:`integer <t_integer>` types, or vectors of
+the same number of integers. The bit size of the ``value`` must be
+smaller than the bit size of the destination type, ``ty2``.
+
+Semantics:
+""""""""""
+
+The ``zext`` fills the high order bits of the ``value`` with zero bits
+until it reaches the size of the destination type, ``ty2``.
+
+When zero extending from i1, the result will always be either 0 or 1.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = zext i32 257 to i64 ; yields i64:257
+ %Y = zext i1 true to i32 ; yields i32:1
+ %Z = zext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
+
+'``sext .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = sext <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``sext``' sign extends ``value`` to the type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``sext``' instruction takes a value to cast, and a type to cast it
+to. Both types must be of :ref:`integer <t_integer>` types, or vectors of
+the same number of integers. The bit size of the ``value`` must be
+smaller than the bit size of the destination type, ``ty2``.
+
+Semantics:
+""""""""""
+
+The '``sext``' instruction performs a sign extension by copying the sign
+bit (highest order bit) of the ``value`` until it reaches the bit size
+of the type ``ty2``.
+
+When sign extending from i1, the extension always results in -1 or 0.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = sext i8 -1 to i16 ; yields i16 :65535
+ %Y = sext i1 true to i32 ; yields i32:-1
+ %Z = sext <2 x i16> <i16 8, i16 7> to <2 x i32> ; yields <i32 8, i32 7>
+
+'``fptrunc .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fptrunc <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``fptrunc``' instruction truncates ``value`` to type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``fptrunc``' instruction takes a :ref:`floating point <t_floating>`
+value to cast and a :ref:`floating point <t_floating>` type to cast it to.
+The size of ``value`` must be larger than the size of ``ty2``. This
+implies that ``fptrunc`` cannot be used to make a *no-op cast*.
+
+Semantics:
+""""""""""
+
+The '``fptrunc``' instruction truncates a ``value`` from a larger
+:ref:`floating point <t_floating>` type to a smaller :ref:`floating
+point <t_floating>` type. If the value cannot fit within the
+destination type, ``ty2``, then the results are undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = fptrunc double 123.0 to float ; yields float:123.0
+ %Y = fptrunc double 1.0E+300 to float ; yields undefined
+
+'``fpext .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fpext <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``fpext``' extends a floating point ``value`` to a larger floating
+point value.
+
+Arguments:
+""""""""""
+
+The '``fpext``' instruction takes a :ref:`floating point <t_floating>`
+``value`` to cast, and a :ref:`floating point <t_floating>` type to cast it
+to. The source type must be smaller than the destination type.
+
+Semantics:
+""""""""""
+
+The '``fpext``' instruction extends the ``value`` from a smaller
+:ref:`floating point <t_floating>` type to a larger :ref:`floating
+point <t_floating>` type. The ``fpext`` cannot be used to make a
+*no-op cast* because it always changes bits. Use ``bitcast`` to make a
+*no-op cast* for a floating point cast.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = fpext float 3.125 to double ; yields double:3.125000e+00
+ %Y = fpext double %X to fp128 ; yields fp128:0xL00000000000000004000900000000000
+
+'``fptoui .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fptoui <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``fptoui``' converts a floating point ``value`` to its unsigned
+integer equivalent of type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``fptoui``' instruction takes a value to cast, which must be a
+scalar or vector :ref:`floating point <t_floating>` value, and a type to
+cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
+``ty`` is a vector floating point type, ``ty2`` must be a vector integer
+type with the same number of elements as ``ty``
+
+Semantics:
+""""""""""
+
+The '``fptoui``' instruction converts its :ref:`floating
+point <t_floating>` operand into the nearest (rounding towards zero)
+unsigned integer value. If the value cannot fit in ``ty2``, the results
+are undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = fptoui double 123.0 to i32 ; yields i32:123
+ %Y = fptoui float 1.0E+300 to i1 ; yields undefined:1
+ %Z = fptoui float 1.04E+17 to i8 ; yields undefined:1
+
+'``fptosi .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fptosi <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``fptosi``' instruction converts :ref:`floating point <t_floating>`
+``value`` to type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``fptosi``' instruction takes a value to cast, which must be a
+scalar or vector :ref:`floating point <t_floating>` value, and a type to
+cast it to ``ty2``, which must be an :ref:`integer <t_integer>` type. If
+``ty`` is a vector floating point type, ``ty2`` must be a vector integer
+type with the same number of elements as ``ty``
+
+Semantics:
+""""""""""
+
+The '``fptosi``' instruction converts its :ref:`floating
+point <t_floating>` operand into the nearest (rounding towards zero)
+signed integer value. If the value cannot fit in ``ty2``, the results
+are undefined.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = fptosi double -123.0 to i32 ; yields i32:-123
+ %Y = fptosi float 1.0E-247 to i1 ; yields undefined:1
+ %Z = fptosi float 1.04E+17 to i8 ; yields undefined:1
+
+'``uitofp .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = uitofp <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``uitofp``' instruction regards ``value`` as an unsigned integer
+and converts that value to the ``ty2`` type.
+
+Arguments:
+""""""""""
+
+The '``uitofp``' instruction takes a value to cast, which must be a
+scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
+``ty2``, which must be an :ref:`floating point <t_floating>` type. If
+``ty`` is a vector integer type, ``ty2`` must be a vector floating point
+type with the same number of elements as ``ty``
+
+Semantics:
+""""""""""
+
+The '``uitofp``' 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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = uitofp i32 257 to float ; yields float:257.0
+ %Y = uitofp i8 -1 to double ; yields double:255.0
+
+'``sitofp .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = sitofp <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``sitofp``' instruction regards ``value`` as a signed integer and
+converts that value to the ``ty2`` type.
+
+Arguments:
+""""""""""
+
+The '``sitofp``' instruction takes a value to cast, which must be a
+scalar or vector :ref:`integer <t_integer>` value, and a type to cast it to
+``ty2``, which must be an :ref:`floating point <t_floating>` type. If
+``ty`` is a vector integer type, ``ty2`` must be a vector floating point
+type with the same number of elements as ``ty``
+
+Semantics:
+""""""""""
+
+The '``sitofp``' 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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = sitofp i32 257 to float ; yields float:257.0
+ %Y = sitofp i8 -1 to double ; yields double:-1.0
+
+.. _i_ptrtoint:
+
+'``ptrtoint .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = ptrtoint <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``ptrtoint``' instruction converts the pointer or a vector of
+pointers ``value`` to the integer (or vector of integers) type ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``ptrtoint``' instruction takes a ``value`` to cast, which must be
+a a value of type :ref:`pointer <t_pointer>` or a vector of pointers, and a
+type to cast it to ``ty2``, which must be an :ref:`integer <t_integer>` or
+a vector of integers type.
+
+Semantics:
+""""""""""
+
+The '``ptrtoint``' instruction converts ``value`` to integer type
+``ty2`` by interpreting the pointer value as an integer and either
+truncating or zero extending that value to the size of the integer type.
+If ``value`` is smaller than ``ty2`` then a zero extension is done. If
+``value`` is larger than ``ty2`` then a truncation is done. If they are
+the same size, then nothing is done (*no-op cast*) other than a type
+change.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = ptrtoint i32* %P to i8 ; yields truncation on 32-bit architecture
+ %Y = ptrtoint i32* %P to i64 ; yields zero extension on 32-bit architecture
+ %Z = ptrtoint <4 x i32*> %P to <4 x i64>; yields vector zero extension for a vector of addresses on 32-bit architecture
+
+.. _i_inttoptr:
+
+'``inttoptr .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = inttoptr <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``inttoptr``' instruction converts an integer ``value`` to a
+pointer type, ``ty2``.
+
+Arguments:
+""""""""""
+
+The '``inttoptr``' instruction takes an :ref:`integer <t_integer>` value to
+cast, and a type to cast it to, which must be a :ref:`pointer <t_pointer>`
+type.
+
+Semantics:
+""""""""""
+
+The '``inttoptr``' instruction converts ``value`` to type ``ty2`` by
+applying either a zero extension or a truncation depending on the size
+of the integer ``value``. If ``value`` is larger than the size of a
+pointer then a truncation is done. If ``value`` is smaller than the size
+of a pointer then a zero extension is done. If they are the same size,
+nothing is done (*no-op cast*).
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = inttoptr i32 255 to i32* ; yields zero extension on 64-bit architecture
+ %Y = inttoptr i32 255 to i32* ; yields no-op on 32-bit architecture
+ %Z = inttoptr i64 0 to i32* ; yields truncation on 32-bit architecture
+ %Z = inttoptr <4 x i32> %G to <4 x i8*>; yields truncation of vector G to four pointers
+
+.. _i_bitcast:
+
+'``bitcast .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = bitcast <ty> <value> to <ty2> ; yields ty2
+
+Overview:
+"""""""""
+
+The '``bitcast``' instruction converts ``value`` to type ``ty2`` without
+changing any bits.
+
+Arguments:
+""""""""""
+
+The '``bitcast``' 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 :ref:`first class <t_firstclass>` type. The
+bit sizes of ``value`` and the destination type, ``ty2``, must be
+identical. If the source type is a pointer, the destination type must
+also be a pointer of the same size. This instruction supports bitwise
+conversion of vectors to integers and to vectors of other types (as
+long as they have the same size).
+
+Semantics:
+""""""""""
+
+The '``bitcast``' instruction converts ``value`` to type ``ty2``. It
+is always a *no-op cast* because no bits change with this
+conversion. The conversion is done as if the ``value`` had been stored
+to memory and read back as type ``ty2``. Pointer (or vector of
+pointers) types may only be converted to other pointer (or vector of
+pointers) types with the same address space through this instruction.
+To convert pointers to other types, use the :ref:`inttoptr <i_inttoptr>`
+or :ref:`ptrtoint <i_ptrtoint>` instructions first.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = bitcast i8 255 to i8 ; yields i8 :-1
+ %Y = bitcast i32* %x to sint* ; yields sint*:%x
+ %Z = bitcast <2 x int> %V to i64; ; yields i64: %V
+ %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>
+
+.. _i_addrspacecast:
+
+'``addrspacecast .. to``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = addrspacecast <pty> <ptrval> to <pty2> ; yields pty2
+
+Overview:
+"""""""""
+
+The '``addrspacecast``' instruction converts ``ptrval`` from ``pty`` in
+address space ``n`` to type ``pty2`` in address space ``m``.
+
+Arguments:
+""""""""""
+
+The '``addrspacecast``' instruction takes a pointer or vector of pointer value
+to cast and a pointer type to cast it to, which must have a different
+address space.
+
+Semantics:
+""""""""""
+
+The '``addrspacecast``' instruction converts the pointer value
+``ptrval`` to type ``pty2``. It can be a *no-op cast* or a complex
+value modification, depending on the target and the address space
+pair. Pointer conversions within the same address space must be
+performed with the ``bitcast`` instruction. Note that if the address space
+conversion is legal then both result and operand refer to the same memory
+location.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = addrspacecast i32* %x to i32 addrspace(1)* ; yields i32 addrspace(1)*:%x
+ %Y = addrspacecast i32 addrspace(1)* %y to i64 addrspace(2)* ; yields i64 addrspace(2)*:%y
+ %Z = addrspacecast <4 x i32*> %z to <4 x float addrspace(3)*> ; yields <4 x float addrspace(3)*>:%z
+
+.. _otherops:
+
+Other Operations
+----------------
+
+The instructions in this category are the "miscellaneous" instructions,
+which defy better classification.
+
+.. _i_icmp:
+
+'``icmp``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = icmp <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result
+
+Overview:
+"""""""""
+
+The '``icmp``' 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.
+
+Arguments:
+""""""""""
+
+The '``icmp``' 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:
+
+#. ``eq``: equal
+#. ``ne``: not equal
+#. ``ugt``: unsigned greater than
+#. ``uge``: unsigned greater or equal
+#. ``ult``: unsigned less than
+#. ``ule``: unsigned less or equal
+#. ``sgt``: signed greater than
+#. ``sge``: signed greater or equal
+#. ``slt``: signed less than
+#. ``sle``: signed less or equal
+
+The remaining two arguments must be :ref:`integer <t_integer>` or
+:ref:`pointer <t_pointer>` or integer :ref:`vector <t_vector>` typed. They
+must also be identical types.
+
+Semantics:
+""""""""""
+
+The '``icmp``' compares ``op1`` and ``op2`` according to the condition
+code given as ``cond``. The comparison performed always yields either an
+:ref:`i1 <t_integer>` or vector of ``i1`` result, as follows:
+
+#. ``eq``: yields ``true`` if the operands are equal, ``false``
+ otherwise. No sign interpretation is necessary or performed.
+#. ``ne``: yields ``true`` if the operands are unequal, ``false``
+ otherwise. No sign interpretation is necessary or performed.
+#. ``ugt``: interprets the operands as unsigned values and yields
+ ``true`` if ``op1`` is greater than ``op2``.
+#. ``uge``: interprets the operands as unsigned values and yields
+ ``true`` if ``op1`` is greater than or equal to ``op2``.
+#. ``ult``: interprets the operands as unsigned values and yields
+ ``true`` if ``op1`` is less than ``op2``.
+#. ``ule``: interprets the operands as unsigned values and yields
+ ``true`` if ``op1`` is less than or equal to ``op2``.
+#. ``sgt``: interprets the operands as signed values and yields ``true``
+ if ``op1`` is greater than ``op2``.
+#. ``sge``: interprets the operands as signed values and yields ``true``
+ if ``op1`` is greater than or equal to ``op2``.
+#. ``slt``: interprets the operands as signed values and yields ``true``
+ if ``op1`` is less than ``op2``.
+#. ``sle``: interprets the operands as signed values and yields ``true``
+ if ``op1`` is less than or equal to ``op2``.
+
+If the operands are :ref:`pointer <t_pointer>` typed, the pointer values
+are compared as if they were integers.
+
+If the operands are integer vectors, then they are compared element by
+element. The result is an ``i1`` vector with the same number of elements
+as the values being compared. Otherwise, the result is an ``i1``.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = icmp eq i32 4, 5 ; yields: result=false
+ <result> = icmp ne float* %X, %X ; yields: result=false
+ <result> = icmp ult i16 4, 5 ; yields: result=true
+ <result> = icmp sgt i16 4, 5 ; yields: result=false
+ <result> = icmp ule i16 -4, 5 ; yields: result=false
+ <result> = icmp sge i16 4, 5 ; yields: result=false
+
+Note that the code generator does not yet support vector types with the
+``icmp`` instruction.
+
+.. _i_fcmp:
+
+'``fcmp``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = fcmp <cond> <ty> <op1>, <op2> ; yields i1 or <N x i1>:result
+
+Overview:
+"""""""""
+
+The '``fcmp``' instruction returns a boolean value or vector of boolean
+values based on comparison of its operands.
+
+If the operands are floating point scalars, then the result type is a
+boolean (:ref:`i1 <t_integer>`).
+
+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.
+
+Arguments:
+""""""""""
+
+The '``fcmp``' 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:
+
+#. ``false``: no comparison, always returns false
+#. ``oeq``: ordered and equal
+#. ``ogt``: ordered and greater than
+#. ``oge``: ordered and greater than or equal
+#. ``olt``: ordered and less than
+#. ``ole``: ordered and less than or equal
+#. ``one``: ordered and not equal
+#. ``ord``: ordered (no nans)
+#. ``ueq``: unordered or equal
+#. ``ugt``: unordered or greater than
+#. ``uge``: unordered or greater than or equal
+#. ``ult``: unordered or less than
+#. ``ule``: unordered or less than or equal
+#. ``une``: unordered or not equal
+#. ``uno``: unordered (either nans)
+#. ``true``: no comparison, always returns true
+
+*Ordered* means that neither operand is a QNAN while *unordered* means
+that either operand may be a QNAN.
+
+Each of ``val1`` and ``val2`` arguments must be either a :ref:`floating
+point <t_floating>` type or a :ref:`vector <t_vector>` of floating point
+type. They must have identical types.
+
+Semantics:
+""""""""""
+
+The '``fcmp``' instruction compares ``op1`` and ``op2`` according to the
+condition code given as ``cond``. If the operands are vectors, then the
+vectors are compared element by element. Each comparison performed
+always yields an :ref:`i1 <t_integer>` result, as follows:
+
+#. ``false``: always yields ``false``, regardless of operands.
+#. ``oeq``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is equal to ``op2``.
+#. ``ogt``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is greater than ``op2``.
+#. ``oge``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is greater than or equal to ``op2``.
+#. ``olt``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is less than ``op2``.
+#. ``ole``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is less than or equal to ``op2``.
+#. ``one``: yields ``true`` if both operands are not a QNAN and ``op1``
+ is not equal to ``op2``.
+#. ``ord``: yields ``true`` if both operands are not a QNAN.
+#. ``ueq``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ equal to ``op2``.
+#. ``ugt``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ greater than ``op2``.
+#. ``uge``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ greater than or equal to ``op2``.
+#. ``ult``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ less than ``op2``.
+#. ``ule``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ less than or equal to ``op2``.
+#. ``une``: yields ``true`` if either operand is a QNAN or ``op1`` is
+ not equal to ``op2``.
+#. ``uno``: yields ``true`` if either operand is a QNAN.
+#. ``true``: always yields ``true``, regardless of operands.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ <result> = fcmp oeq float 4.0, 5.0 ; yields: result=false
+ <result> = fcmp one float 4.0, 5.0 ; yields: result=true
+ <result> = fcmp olt float 4.0, 5.0 ; yields: result=true
+ <result> = fcmp ueq double 1.0, 2.0 ; yields: result=false
+
+Note that the code generator does not yet support vector types with the
+``fcmp`` instruction.
+
+.. _i_phi:
+
+'``phi``' Instruction
+^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = phi <ty> [ <val0>, <label0>], ...
+
+Overview:
+"""""""""
+
+The '``phi``' instruction is used to implement the Ï node in the SSA
+graph representing the function.
+
+Arguments:
+""""""""""
+
+The type of the incoming values is specified with the first type field.
+After this, the '``phi``' instruction takes a list of pairs as
+arguments, with one pair for each predecessor basic block of the current
+block. Only values of :ref:`first class <t_firstclass>` type may be used as
+the value arguments to the PHI node. Only labels may be used as the
+label arguments.
+
+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.
+
+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 '``invoke``'
+instruction's return value on the same edge).
+
+Semantics:
+""""""""""
+
+At runtime, the '``phi``' instruction logically takes on the value
+specified by the pair corresponding to the predecessor basic block that
+executed just prior to the current block.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ Loop: ; Infinite loop that counts from 0 on up...
+ %indvar = phi i32 [ 0, %LoopHeader ], [ %nextindvar, %Loop ]
+ %nextindvar = add i32 %indvar, 1
+ br label %Loop
+
+.. _i_select:
+
+'``select``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = select selty <cond>, <ty> <val1>, <ty> <val2> ; yields ty
+
+ selty is either i1 or {<N x i1>}
+
+Overview:
+"""""""""
+
+The '``select``' instruction is used to choose one value based on a
+condition, without IR-level branching.
+
+Arguments:
+""""""""""
+
+The '``select``' instruction requires an 'i1' value or a vector of 'i1'
+values indicating the condition, and two values of the same :ref:`first
+class <t_firstclass>` type. If the val1/val2 are vectors and the
+condition is a scalar, then entire vectors are selected, not individual
+elements.
+
+Semantics:
+""""""""""
+
+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.
+
+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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %X = select i1 true, i8 17, i8 42 ; yields i8:17
+
+.. _i_call:
+
+'``call``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <result> = [tail | musttail] call [cconv] [ret attrs] <ty> [<fnty>*] <fnptrval>(<function args>) [fn attrs]
+
+Overview:
+"""""""""
+
+The '``call``' instruction represents a simple function call.
+
+Arguments:
+""""""""""
+
+This instruction requires several arguments:
+
+#. The optional ``tail`` and ``musttail`` markers indicate that the optimizers
+ should perform tail call optimization. The ``tail`` marker is a hint that
+ `can be ignored <CodeGenerator.html#sibcallopt>`_. The ``musttail`` marker
+ means that the call must be tail call optimized in order for the program to
+ be correct. The ``musttail`` marker provides these guarantees:
+
+ #. The call will not cause unbounded stack growth if it is part of a
+ recursive cycle in the call graph.
+ #. Arguments with the :ref:`inalloca <attr_inalloca>` attribute are
+ forwarded in place.
+
+ Both markers imply that the callee does not access allocas or varargs from
+ the caller. Calls marked ``musttail`` must obey the following additional
+ rules:
+
+ - The call must immediately precede a :ref:`ret <i_ret>` instruction,
+ or a pointer bitcast followed by a ret instruction.
+ - The ret instruction must return the (possibly bitcasted) value
+ produced by the call or void.
+ - The caller and callee prototypes must match. Pointer types of
+ parameters or return types may differ in pointee type, but not
+ in address space.
+ - The calling conventions of the caller and callee must match.
+ - All ABI-impacting function attributes, such as sret, byval, inreg,
+ returned, and inalloca, must match.
+
+ Tail call optimization for calls marked ``tail`` is guaranteed to occur if
+ the following conditions are met:
+
+ - Caller and callee both have the calling convention ``fastcc``.
+ - The call is in tail position (ret immediately follows call and ret
+ uses value of call or is void).
+ - Option ``-tailcallopt`` is enabled, or
+ ``llvm::GuaranteedTailCallOpt`` is ``true``.
+ - `Platform-specific constraints are
+ met. <CodeGenerator.html#tailcallopt>`_
+
+#. The optional "cconv" marker indicates which :ref:`calling
+ convention <callingconv>` 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.
+#. The optional :ref:`Parameter Attributes <paramattrs>` list for return
+ values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
+ are valid here.
+#. '``ty``': the type of the call instruction itself which is also the
+ type of the return value. Functions that return no value are marked
+ ``void``.
+#. '``fnty``': 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.
+#. '``fnptrval``': An LLVM value containing a pointer to a function to
+ be invoked. In most cases, this is a direct function invocation, but
+ indirect ``call``'s are just as possible, calling an arbitrary pointer
+ to function value.
+#. '``function args``': argument list whose types match the function
+ signature argument types and parameter attributes. All arguments must
+ be of :ref:`first class <t_firstclass>` type. If the function signature
+ indicates the function accepts a variable number of arguments, the
+ extra arguments can be specified.
+#. The optional :ref:`function attributes <fnattrs>` list. Only
+ '``noreturn``', '``nounwind``', '``readonly``' and '``readnone``'
+ attributes are valid here.
+
+Semantics:
+""""""""""
+
+The '``call``' instruction is used to cause control flow to transfer to
+a specified function, with its incoming arguments bound to the specified
+values. Upon a '``ret``' 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.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ %retval = call i32 @test(i32 %argc)
+ call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42) ; yields i32
+ %X = tail call i32 @foo() ; yields i32
+ %Y = tail call fastcc i32 @foo() ; yields i32
+ call void %foo(i8 97 signext)
+
+ %struct.A = type { i32, i8 }
+ %r = call %struct.A @foo() ; yields { i32, i8 }
+ %gr = extractvalue %struct.A %r, 0 ; yields i32
+ %gr1 = extractvalue %struct.A %r, 1 ; yields i8
+ %Z = call void @foo() noreturn ; indicates that %foo never returns normally
+ %ZZ = call zeroext i32 @bar() ; Return value is %zero extended
+
+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.
+
+.. _i_va_arg:
+
+'``va_arg``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <resultval> = va_arg <va_list*> <arglist>, <argty>
+
+Overview:
+"""""""""
+
+The '``va_arg``' instruction is used to access arguments passed through
+the "variable argument" area of a function call. It is used to implement
+the ``va_arg`` macro in C.
+
+Arguments:
+""""""""""
+
+This instruction takes a ``va_list*`` value and the type of the
+argument. It returns a value of the specified argument type and
+increments the ``va_list`` to point to the next argument. The actual
+type of ``va_list`` is target specific.
+
+Semantics:
+""""""""""
+
+The '``va_arg``' instruction loads an argument of the specified type
+from the specified ``va_list`` and causes the ``va_list`` to point to
+the next argument. For more information, see the variable argument
+handling :ref:`Intrinsic Functions <int_varargs>`.
+
+It is legal for this instruction to be called in a function which does
+not take a variable number of arguments, for example, the ``vfprintf``
+function.
+
+``va_arg`` is an LLVM instruction instead of an :ref:`intrinsic
+function <intrinsics>` because it takes a type as an argument.
+
+Example:
+""""""""
+
+See the :ref:`variable argument processing <int_varargs>` section.
+
+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.
+
+.. _i_landingpad:
+
+'``landingpad``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ <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>
+
+Overview:
+"""""""""
+
+The '``landingpad``' instruction is used by `LLVM's exception handling
+system <ExceptionHandling.html#overview>`_ to specify that a basic block
+is a landing pad --- one where the exception lands, and corresponds to the
+code found in the ``catch`` portion of a ``try``/``catch`` sequence. It
+defines values supplied by the personality function (``pers_fn``) upon
+re-entry to the function. The ``resultval`` has the type ``resultty``.
+
+Arguments:
+""""""""""
+
+This instruction takes a ``pers_fn`` value. This is the personality
+function associated with the unwinding mechanism. The optional
+``cleanup`` flag indicates that the landing pad block is a cleanup.
+
+A ``clause`` begins with the clause type --- ``catch`` or ``filter`` --- and
+contains the global variable representing the "type" that may be caught
+or filtered respectively. Unlike the ``catch`` clause, the ``filter``
+clause takes an array constant as its argument. Use
+"``[0 x i8**] undef``" for a filter which cannot throw. The
+'``landingpad``' instruction must contain *at least* one ``clause`` or
+the ``cleanup`` flag.
+
+Semantics:
+""""""""""
+
+The '``landingpad``' instruction defines the values which are set by the
+personality function (``pers_fn``) upon re-entry to the function, and
+therefore the "result type" of the ``landingpad`` instruction. As with
+calling conventions, how the personality function results are
+represented in LLVM IR is target specific.
+
+The clauses are applied in order from top to bottom. If two
+``landingpad`` 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 ``clause`` in turn. If it doesn't
+match any of the clauses, and the ``cleanup`` flag is not set, then
+unwinding continues further up the call stack.
+
+The ``landingpad`` instruction has several restrictions:
+
+- A landing pad block is a basic block which is the unwind destination
+ of an '``invoke``' instruction.
+- A landing pad block must have a '``landingpad``' instruction as its
+ first non-PHI instruction.
+- There can be only one '``landingpad``' instruction within the landing
+ pad block.
+- A basic block that is not a landing pad block may not include a
+ '``landingpad``' instruction.
+- All '``landingpad``' instructions in a function must have the same
+ personality function.
+
+Example:
+""""""""
+
+.. code-block:: llvm
+
+ ;; 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]
+
+.. _intrinsics:
+
+Intrinsic Functions
+===================
+
+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...).
+
+Intrinsic function names must all start with an "``llvm.``" 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.
+
+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.
+
+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
+``llvm.ctpop`` 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 ``i8 @llvm.ctpop.i8(i8 %val)`` and
+``i29 @llvm.ctpop.i29(i29 %val)``. 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.
+
+To learn how to add an intrinsic function, please see the `Extending
+LLVM Guide <ExtendingLLVM.html>`_.
+
+.. _int_varargs:
+
+Variable Argument Handling Intrinsics
+-------------------------------------
+
+Variable argument support is defined in LLVM with the
+:ref:`va_arg <i_va_arg>` instruction and these three intrinsic
+functions. These functions are related to the similarly named macros
+defined in the ``<stdarg.h>`` header file.
+
+All of these functions operate on arguments that use a target-specific
+value type "``va_list``". 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.
+
+This example shows how the :ref:`va_arg <i_va_arg>` instruction and the
+variable argument handling intrinsic functions are used.
+
+.. code-block:: llvm
+
+ 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*)
+
+.. _int_va_start:
+
+'``llvm.va_start``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.va_start(i8* <arglist>)
+
+Overview:
+"""""""""
+
+The '``llvm.va_start``' intrinsic initializes ``*<arglist>`` for
+subsequent use by ``va_arg``.
+
+Arguments:
+""""""""""
+
+The argument is a pointer to a ``va_list`` element to initialize.
+
+Semantics:
+""""""""""
+
+The '``llvm.va_start``' intrinsic works just like the ``va_start`` macro
+available in C. In a target-dependent way, it initializes the
+``va_list`` element to which the argument points, so that the next call
+to ``va_arg`` will produce the first variable argument passed to the
+function. Unlike the C ``va_start`` macro, this intrinsic does not need
+to know the last argument of the function as the compiler can figure
+that out.
+
+'``llvm.va_end``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.va_end(i8* <arglist>)
+
+Overview:
+"""""""""
+
+The '``llvm.va_end``' intrinsic destroys ``*<arglist>``, which has been
+initialized previously with ``llvm.va_start`` or ``llvm.va_copy``.
+
+Arguments:
+""""""""""
+
+The argument is a pointer to a ``va_list`` to destroy.
+
+Semantics:
+""""""""""
+
+The '``llvm.va_end``' intrinsic works just like the ``va_end`` macro
+available in C. In a target-dependent way, it destroys the ``va_list``
+element to which the argument points. Calls to
+:ref:`llvm.va_start <int_va_start>` and
+:ref:`llvm.va_copy <int_va_copy>` must be matched exactly with calls to
+``llvm.va_end``.
+
+.. _int_va_copy:
+
+'``llvm.va_copy``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.va_copy(i8* <destarglist>, i8* <srcarglist>)
+
+Overview:
+"""""""""
+
+The '``llvm.va_copy``' intrinsic copies the current argument position
+from the source argument list to the destination argument list.
+
+Arguments:
+""""""""""
+
+The first argument is a pointer to a ``va_list`` element to initialize.
+The second argument is a pointer to a ``va_list`` element to copy from.
+
+Semantics:
+""""""""""
+
+The '``llvm.va_copy``' intrinsic works just like the ``va_copy`` macro
+available in C. In a target-dependent way, it copies the source
+``va_list`` element into the destination ``va_list`` element. This
+intrinsic is necessary because the `` llvm.va_start`` intrinsic may be
+arbitrarily complex and require, for example, memory allocation.
+
+Accurate Garbage Collection Intrinsics
+--------------------------------------
+
+LLVM support for `Accurate Garbage Collection <GarbageCollection.html>`_
+(GC) requires the implementation and generation of these intrinsics.
+These intrinsics allow identification of :ref:`GC roots on the
+stack <int_gcroot>`, as well as garbage collector implementations that
+require :ref:`read <int_gcread>` and :ref:`write <int_gcwrite>` 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 `Accurate Garbage Collection with
+LLVM <GarbageCollection.html>`_.
+
+The garbage collection intrinsics only operate on objects in the generic
+address space (address space zero).
+
+.. _int_gcroot:
+
+'``llvm.gcroot``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.gcroot(i8** %ptrloc, i8* %metadata)
+
+Overview:
+"""""""""
+
+The '``llvm.gcroot``' intrinsic declares the existence of a GC root to
+the code generator, and allows some metadata to be associated with it.
+
+Arguments:
+""""""""""
+
+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.
+
+Semantics:
+""""""""""
+
+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 '``llvm.gcroot``' intrinsic may only be used in a function which
+:ref:`specifies a GC algorithm <gc>`.
+
+.. _int_gcread:
+
+'``llvm.gcread``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.gcread(i8* %ObjPtr, i8** %Ptr)
+
+Overview:
+"""""""""
+
+The '``llvm.gcread``' intrinsic identifies reads of references from heap
+locations, allowing garbage collector implementations that require read
+barriers.
+
+Arguments:
+""""""""""
+
+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).
+
+Semantics:
+""""""""""
+
+The '``llvm.gcread``' 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 '``llvm.gcread``'
+intrinsic may only be used in a function which :ref:`specifies a GC
+algorithm <gc>`.
+
+.. _int_gcwrite:
+
+'``llvm.gcwrite``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.gcwrite(i8* %P1, i8* %Obj, i8** %P2)
+
+Overview:
+"""""""""
+
+The '``llvm.gcwrite``' intrinsic identifies writes of references to heap
+locations, allowing garbage collector implementations that require write
+barriers (such as generational or reference counting collectors).
+
+Arguments:
+""""""""""
+
+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.
+
+Semantics:
+""""""""""
+
+The '``llvm.gcwrite``' 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 '``llvm.gcwrite``'
+intrinsic may only be used in a function which :ref:`specifies a GC
+algorithm <gc>`.
+
+Code Generator Intrinsics
+-------------------------
+
+These intrinsics are provided by LLVM to expose special features that
+may only be implemented with code generator support.
+
+'``llvm.returnaddress``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8 *@llvm.returnaddress(i32 <level>)
+
+Overview:
+"""""""""
+
+The '``llvm.returnaddress``' intrinsic attempts to compute a
+target-specific value indicating the return address of the current
+function or one of its callers.
+
+Arguments:
+""""""""""
+
+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 **required** to be a constant integer
+value.
+
+Semantics:
+""""""""""
+
+The '``llvm.returnaddress``' 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.
+
+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.
+
+'``llvm.frameaddress``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.frameaddress(i32 <level>)
+
+Overview:
+"""""""""
+
+The '``llvm.frameaddress``' intrinsic attempts to return the
+target-specific frame pointer value for the specified stack frame.
+
+Arguments:
+""""""""""
+
+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 **required** to be a constant integer
+value.
+
+Semantics:
+""""""""""
+
+The '``llvm.frameaddress``' 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.
+
+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.
+
+.. _int_read_register:
+.. _int_write_register:
+
+'``llvm.read_register``' and '``llvm.write_register``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i32 @llvm.read_register.i32(metadata)
+ declare i64 @llvm.read_register.i64(metadata)
+ declare void @llvm.write_register.i32(metadata, i32 @value)
+ declare void @llvm.write_register.i64(metadata, i64 @value)
+ !0 = metadata !{metadata !"sp\00"}
+
+Overview:
+"""""""""
+
+The '``llvm.read_register``' and '``llvm.write_register``' intrinsics
+provides access to the named register. The register must be valid on
+the architecture being compiled to. The type needs to be compatible
+with the register being read.
+
+Semantics:
+""""""""""
+
+The '``llvm.read_register``' intrinsic returns the current value of the
+register, where possible. The '``llvm.write_register``' intrinsic sets
+the current value of the register, where possible.
+
+This is useful to implement named register global variables that need
+to always be mapped to a specific register, as is common practice on
+bare-metal programs including OS kernels.
+
+The compiler doesn't check for register availability or use of the used
+register in surrounding code, including inline assembly. Because of that,
+allocatable registers are not supported.
+
+Warning: So far it only works with the stack pointer on selected
+architectures (ARM, AArch64, PowerPC and x86_64). Significant amount of
+work is needed to support other registers and even more so, allocatable
+registers.
+
+.. _int_stacksave:
+
+'``llvm.stacksave``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.stacksave()
+
+Overview:
+"""""""""
+
+The '``llvm.stacksave``' intrinsic is used to remember the current state
+of the function stack, for use with
+:ref:`llvm.stackrestore <int_stackrestore>`. This is useful for
+implementing language features like scoped automatic variable sized
+arrays in C99.
+
+Semantics:
+""""""""""
+
+This intrinsic returns a opaque pointer value that can be passed to
+:ref:`llvm.stackrestore <int_stackrestore>`. When an
+``llvm.stackrestore`` intrinsic is executed with a value saved from
+``llvm.stacksave``, it effectively restores the state of the stack to
+the state it was in when the ``llvm.stacksave`` intrinsic executed. In
+practice, this pops any :ref:`alloca <i_alloca>` blocks from the stack that
+were allocated after the ``llvm.stacksave`` was executed.
+
+.. _int_stackrestore:
+
+'``llvm.stackrestore``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.stackrestore(i8* %ptr)
+
+Overview:
+"""""""""
+
+The '``llvm.stackrestore``' intrinsic is used to restore the state of
+the function stack to the state it was in when the corresponding
+:ref:`llvm.stacksave <int_stacksave>` intrinsic executed. This is
+useful for implementing language features like scoped automatic variable
+sized arrays in C99.
+
+Semantics:
+""""""""""
+
+See the description for :ref:`llvm.stacksave <int_stacksave>`.
+
+'``llvm.prefetch``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.prefetch(i8* <address>, i32 <rw>, i32 <locality>, i32 <cache type>)
+
+Overview:
+"""""""""
+
+The '``llvm.prefetch``' 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.
+
+Arguments:
+""""""""""
+
+``address`` is the address to be prefetched, ``rw`` is the specifier
+determining if the fetch should be for a read (0) or write (1), and
+``locality`` is a temporal locality specifier ranging from (0) - no
+locality, to (3) - extremely local keep in cache. The ``cache type``
+specifies whether the prefetch is performed on the data (1) or
+instruction (0) cache. The ``rw``, ``locality`` and ``cache type``
+arguments must be constant integers.
+
+Semantics:
+""""""""""
+
+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.
+
+'``llvm.pcmarker``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.pcmarker(i32 <id>)
+
+Overview:
+"""""""""
+
+The '``llvm.pcmarker``' 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.
+
+Arguments:
+""""""""""
+
+``id`` is a numerical id identifying the marker.
+
+Semantics:
+""""""""""
+
+This intrinsic does not modify the behavior of the program. Backends
+that do not support this intrinsic may ignore it.
+
+'``llvm.readcyclecounter``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i64 @llvm.readcyclecounter()
+
+Overview:
+"""""""""
+
+The '``llvm.readcyclecounter``' 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.
+
+Semantics:
+""""""""""
+
+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.
+
+Note that runtime support may be conditional on the privilege-level code is
+running at and the host platform.
+
+'``llvm.clear_cache``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.clear_cache(i8*, i8*)
+
+Overview:
+"""""""""
+
+The '``llvm.clear_cache``' intrinsic ensures visibility of modifications
+in the specified range to the execution unit of the processor. On
+targets with non-unified instruction and data cache, the implementation
+flushes the instruction cache.
+
+Semantics:
+""""""""""
+
+On platforms with coherent instruction and data caches (e.g. x86), this
+intrinsic is a nop. On platforms with non-coherent instruction and data
+cache (e.g. ARM, MIPS), the intrinsic is lowered either to appropriate
+instructions or a system call, if cache flushing requires special
+privileges.
+
+The default behavior is to emit a call to ``__clear_cache`` from the run
+time library.
+
+This instrinsic does *not* empty the instruction pipeline. Modifications
+of the current function are outside the scope of the intrinsic.
+
+Standard C Library Intrinsics
+-----------------------------
+
+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.
+
+.. _int_memcpy:
+
+'``llvm.memcpy``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.memcpy`` on any
+integer bit width and for different address spaces. Not all targets
+support all bit widths however.
+
+::
+
+ 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>)
+
+Overview:
+"""""""""
+
+The '``llvm.memcpy.*``' intrinsics copy a block of memory from the
+source location to the destination location.
+
+Note that, unlike the standard libc function, the ``llvm.memcpy.*``
+intrinsics do not return a value, takes extra alignment/isvolatile
+arguments and the pointers can be in specified address spaces.
+
+Arguments:
+""""""""""
+
+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.
+
+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.
+
+If the ``isvolatile`` parameter is ``true``, the ``llvm.memcpy`` call is
+a :ref:`volatile operation <volatile>`. The detailed access behavior is not
+very cleanly specified and it is unwise to depend on it.
+
+Semantics:
+""""""""""
+
+The '``llvm.memcpy.*``' 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 (both meaning no alignment).
+
+'``llvm.memmove``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+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.
+
+::
+
+ 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>)
+
+Overview:
+"""""""""
+
+The '``llvm.memmove.*``' intrinsics move a block of memory from the
+source location to the destination location. It is similar to the
+'``llvm.memcpy``' intrinsic but allows the two memory locations to
+overlap.
+
+Note that, unlike the standard libc function, the ``llvm.memmove.*``
+intrinsics do not return a value, takes extra alignment/isvolatile
+arguments and the pointers can be in specified address spaces.
+
+Arguments:
+""""""""""
+
+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.
+
+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.
+
+If the ``isvolatile`` parameter is ``true``, the ``llvm.memmove`` call
+is a :ref:`volatile operation <volatile>`. The detailed access behavior is
+not very cleanly specified and it is unwise to depend on it.
+
+Semantics:
+""""""""""
+
+The '``llvm.memmove.*``' 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 (both meaning no alignment).
+
+'``llvm.memset.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+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.
+
+::
+
+ 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>)
+
+Overview:
+"""""""""
+
+The '``llvm.memset.*``' intrinsics fill a block of memory with a
+particular byte value.
+
+Note that, unlike the standard libc function, the ``llvm.memset``
+intrinsic does not return a value and takes extra alignment/volatile
+arguments. Also, the destination can be in an arbitrary address space.
+
+Arguments:
+""""""""""
+
+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.
+
+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.
+
+If the ``isvolatile`` parameter is ``true``, the ``llvm.memset`` call is
+a :ref:`volatile operation <volatile>`. The detailed access behavior is not
+very cleanly specified and it is unwise to depend on it.
+
+Semantics:
+""""""""""
+
+The '``llvm.memset.*``' 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 (both meaning no alignment).
+
+'``llvm.sqrt.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.sqrt`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.sqrt``' intrinsics return the sqrt of the specified operand,
+returning the same value as the libm '``sqrt``' functions would. Unlike
+``sqrt`` in libm, however, ``llvm.sqrt`` 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).
+``llvm.sqrt(-0.0)`` is defined to return -0.0 like IEEE sqrt.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the sqrt of the specified operand if it is a
+nonnegative floating point number.
+
+'``llvm.powi.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.powi`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.powi.*``' 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.
+
+Arguments:
+""""""""""
+
+The second argument is an integer power, and the first is a value to
+raise to that power.
+
+Semantics:
+""""""""""
+
+This function returns the first value raised to the second power with an
+unspecified sequence of rounding operations.
+
+'``llvm.sin.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.sin`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.sin.*``' intrinsics return the sine of the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the sine of the specified operand, returning the
+same values as the libm ``sin`` functions would, and handles error
+conditions in the same way.
+
+'``llvm.cos.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.cos`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.cos.*``' intrinsics return the cosine of the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the cosine of the specified operand, returning the
+same values as the libm ``cos`` functions would, and handles error
+conditions in the same way.
+
+'``llvm.pow.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.pow`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.pow.*``' intrinsics return the first operand raised to the
+specified (positive or negative) power.
+
+Arguments:
+""""""""""
+
+The second argument is a floating point power, and the first is a value
+to raise to that power.
+
+Semantics:
+""""""""""
+
+This function returns the first value raised to the second power,
+returning the same values as the libm ``pow`` functions would, and
+handles error conditions in the same way.
+
+'``llvm.exp.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.exp`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.exp.*``' intrinsics perform the exp function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``exp`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.exp2.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.exp2`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.exp2.f32(float %Val)
+ declare double @llvm.exp2.f64(double %Val)
+ declare x86_fp80 @llvm.exp2.f80(x86_fp80 %Val)
+ declare fp128 @llvm.exp2.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.exp2.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.exp2.*``' intrinsics perform the exp2 function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``exp2`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.log.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.log`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.log.*``' intrinsics perform the log function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``log`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.log10.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.log10`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.log10.f32(float %Val)
+ declare double @llvm.log10.f64(double %Val)
+ declare x86_fp80 @llvm.log10.f80(x86_fp80 %Val)
+ declare fp128 @llvm.log10.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.log10.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.log10.*``' intrinsics perform the log10 function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``log10`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.log2.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.log2`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.log2.f32(float %Val)
+ declare double @llvm.log2.f64(double %Val)
+ declare x86_fp80 @llvm.log2.f80(x86_fp80 %Val)
+ declare fp128 @llvm.log2.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.log2.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.log2.*``' intrinsics perform the log2 function.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``log2`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.fma.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.fma`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.fma.*``' intrinsics perform the fused multiply-add
+operation.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``fma`` functions
+would, and does not set errno.
+
+'``llvm.fabs.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.fabs`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.fabs.*``' intrinsics return the absolute value of the
+operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``fabs`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.copysign.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.copysign`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.copysign.f32(float %Mag, float %Sgn)
+ declare double @llvm.copysign.f64(double %Mag, double %Sgn)
+ declare x86_fp80 @llvm.copysign.f80(x86_fp80 %Mag, x86_fp80 %Sgn)
+ declare fp128 @llvm.copysign.f128(fp128 %Mag, fp128 %Sgn)
+ declare ppc_fp128 @llvm.copysign.ppcf128(ppc_fp128 %Mag, ppc_fp128 %Sgn)
+
+Overview:
+"""""""""
+
+The '``llvm.copysign.*``' intrinsics return a value with the magnitude of the
+first operand and the sign of the second operand.
+
+Arguments:
+""""""""""
+
+The arguments and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``copysign``
+functions would, and handles error conditions in the same way.
+
+'``llvm.floor.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.floor`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.floor.*``' intrinsics return the floor of the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``floor`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.ceil.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.ceil`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.ceil.f32(float %Val)
+ declare double @llvm.ceil.f64(double %Val)
+ declare x86_fp80 @llvm.ceil.f80(x86_fp80 %Val)
+ declare fp128 @llvm.ceil.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.ceil.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.ceil.*``' intrinsics return the ceiling of the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``ceil`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.trunc.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.trunc`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.trunc.f32(float %Val)
+ declare double @llvm.trunc.f64(double %Val)
+ declare x86_fp80 @llvm.trunc.f80(x86_fp80 %Val)
+ declare fp128 @llvm.trunc.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.trunc.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.trunc.*``' intrinsics returns the operand rounded to the
+nearest integer not larger in magnitude than the operand.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``trunc`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.rint.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.rint`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.rint.f32(float %Val)
+ declare double @llvm.rint.f64(double %Val)
+ declare x86_fp80 @llvm.rint.f80(x86_fp80 %Val)
+ declare fp128 @llvm.rint.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.rint.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.rint.*``' intrinsics returns the operand rounded to the
+nearest integer. It may raise an inexact floating-point exception if the
+operand isn't an integer.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``rint`` functions
+would, and handles error conditions in the same way.
+
+'``llvm.nearbyint.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.nearbyint`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.nearbyint.f32(float %Val)
+ declare double @llvm.nearbyint.f64(double %Val)
+ declare x86_fp80 @llvm.nearbyint.f80(x86_fp80 %Val)
+ declare fp128 @llvm.nearbyint.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.nearbyint.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.nearbyint.*``' intrinsics returns the operand rounded to the
+nearest integer.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``nearbyint``
+functions would, and handles error conditions in the same way.
+
+'``llvm.round.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.round`` on any
+floating point or vector of floating point type. Not all targets support
+all types however.
+
+::
+
+ declare float @llvm.round.f32(float %Val)
+ declare double @llvm.round.f64(double %Val)
+ declare x86_fp80 @llvm.round.f80(x86_fp80 %Val)
+ declare fp128 @llvm.round.f128(fp128 %Val)
+ declare ppc_fp128 @llvm.round.ppcf128(ppc_fp128 %Val)
+
+Overview:
+"""""""""
+
+The '``llvm.round.*``' intrinsics returns the operand rounded to the
+nearest integer.
+
+Arguments:
+""""""""""
+
+The argument and return value are floating point numbers of the same
+type.
+
+Semantics:
+""""""""""
+
+This function returns the same values as the libm ``round``
+functions would, and handles error conditions in the same way.
+
+Bit Manipulation Intrinsics
+---------------------------
+
+LLVM provides intrinsics for a few important bit manipulation
+operations. These allow efficient code generation for some algorithms.
+
+'``llvm.bswap.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+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).
+
+::
+
+ declare i16 @llvm.bswap.i16(i16 <id>)
+ declare i32 @llvm.bswap.i32(i32 <id>)
+ declare i64 @llvm.bswap.i64(i64 <id>)
+
+Overview:
+"""""""""
+
+The '``llvm.bswap``' 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.
+
+Semantics:
+""""""""""
+
+The ``llvm.bswap.i16`` intrinsic returns an i16 value that has the high
+and low byte of the input i16 swapped. Similarly, the ``llvm.bswap.i32``
+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
+``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this
+concept to additional even-byte lengths (6 bytes, 8 bytes and more,
+respectively).
+
+'``llvm.ctpop.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+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.
+
+::
+
+ 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>)
+
+Overview:
+"""""""""
+
+The '``llvm.ctpop``' family of intrinsics counts the number of bits set
+in a value.
+
+Arguments:
+""""""""""
+
+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.
+
+Semantics:
+""""""""""
+
+The '``llvm.ctpop``' intrinsic counts the 1's in a variable, or within
+each element of a vector.
+
+'``llvm.ctlz.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.ctlz`` on any
+integer bit width, or any vector whose elements are integers. Not all
+targets support all bit widths or vector types, however.
+
+::
+
+ 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>)
+
+Overview:
+"""""""""
+
+The '``llvm.ctlz``' family of intrinsic functions counts the number of
+leading zeros in a variable.
+
+Arguments:
+""""""""""
+
+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.
+
+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.
+
+Semantics:
+""""""""""
+
+The '``llvm.ctlz``' intrinsic counts the leading (most significant)
+zeros in a variable, or within each element of the vector. If
+``src == 0`` then the result is the size in bits of the type of ``src``
+if ``is_zero_undef == 0`` and ``undef`` otherwise. For example,
+``llvm.ctlz(i32 2) = 30``.
+
+'``llvm.cttz.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.cttz`` on any
+integer bit width, or any vector of integer elements. Not all targets
+support all bit widths or vector types, however.
+
+::
+
+ 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>)
+
+Overview:
+"""""""""
+
+The '``llvm.cttz``' family of intrinsic functions counts the number of
+trailing zeros.
+
+Arguments:
+""""""""""
+
+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.
+
+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.
+
+Semantics:
+""""""""""
+
+The '``llvm.cttz``' intrinsic counts the trailing (least significant)
+zeros in a variable, or within each element of a vector. If ``src == 0``
+then the result is the size in bits of the type of ``src`` if
+``is_zero_undef == 0`` and ``undef`` otherwise. For example,
+``llvm.cttz(2) = 1``.
+
+Arithmetic with Overflow Intrinsics
+-----------------------------------
+
+LLVM provides intrinsics for some arithmetic with overflow operations.
+
+'``llvm.sadd.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow``
+on any integer bit width.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.sadd.with.overflow``' family of intrinsic functions perform
+a signed addition of the two arguments, and indicate whether an overflow
+occurred during the signed summation.
+
+Arguments:
+""""""""""
+
+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
+``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
+addition.
+
+Semantics:
+""""""""""
+
+The '``llvm.sadd.with.overflow``' 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.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %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
+
+'``llvm.uadd.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow``
+on any integer bit width.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.uadd.with.overflow``' family of intrinsic functions perform
+an unsigned addition of the two arguments, and indicate whether a carry
+occurred during the unsigned summation.
+
+Arguments:
+""""""""""
+
+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
+``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
+addition.
+
+Semantics:
+""""""""""
+
+The '``llvm.uadd.with.overflow``' 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.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %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
+
+'``llvm.ssub.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow``
+on any integer bit width.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.ssub.with.overflow``' family of intrinsic functions perform
+a signed subtraction of the two arguments, and indicate whether an
+overflow occurred during the signed subtraction.
+
+Arguments:
+""""""""""
+
+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
+``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
+subtraction.
+
+Semantics:
+""""""""""
+
+The '``llvm.ssub.with.overflow``' 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.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %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
+
+'``llvm.usub.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow``
+on any integer bit width.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.usub.with.overflow``' family of intrinsic functions perform
+an unsigned subtraction of the two arguments, and indicate whether an
+overflow occurred during the unsigned subtraction.
+
+Arguments:
+""""""""""
+
+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
+``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
+subtraction.
+
+Semantics:
+""""""""""
+
+The '``llvm.usub.with.overflow``' 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.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %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
+
+'``llvm.smul.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow``
+on any integer bit width.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.smul.with.overflow``' family of intrinsic functions perform
+a signed multiplication of the two arguments, and indicate whether an
+overflow occurred during the signed multiplication.
+
+Arguments:
+""""""""""
+
+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
+``i1``. ``%a`` and ``%b`` are the two values that will undergo signed
+multiplication.
+
+Semantics:
+""""""""""
+
+The '``llvm.smul.with.overflow``' 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.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %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
+
+'``llvm.umul.with.overflow.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow``
+on any integer bit width.
+
+::
+
+ 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)
+
+Overview:
+"""""""""
+
+The '``llvm.umul.with.overflow``' family of intrinsic functions perform
+a unsigned multiplication of the two arguments, and indicate whether an
+overflow occurred during the unsigned multiplication.
+
+Arguments:
+""""""""""
+
+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
+``i1``. ``%a`` and ``%b`` are the two values that will undergo unsigned
+multiplication.
+
+Semantics:
+""""""""""
+
+The '``llvm.umul.with.overflow``' 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.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %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
+
+Specialised Arithmetic Intrinsics
+---------------------------------
+
+'``llvm.fmuladd.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare float @llvm.fmuladd.f32(float %a, float %b, float %c)
+ declare double @llvm.fmuladd.f64(double %a, double %b, double %c)
+
+Overview:
+"""""""""
+
+The '``llvm.fmuladd.*``' intrinsic functions represent multiply-add
+expressions that can be fused if the code generator determines that (a) the
+target instruction set has support for a fused operation, and (b) that the
+fused operation is more efficient than the equivalent, separate pair of mul
+and add instructions.
+
+Arguments:
+""""""""""
+
+The '``llvm.fmuladd.*``' intrinsics each take three arguments: two
+multiplicands, a and b, and an addend c.
+
+Semantics:
+""""""""""
+
+The expression:
+
+::
+
+ %0 = call float @llvm.fmuladd.f32(%a, %b, %c)
+
+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. This never sets errno, just as '``llvm.fma.*``'.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %r2 = call float @llvm.fmuladd.f32(float %a, float %b, float %c) ; yields float:r2 = (a * b) + c
+
+Half Precision Floating Point Intrinsics
+----------------------------------------
+
+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.
+
+This means that code must first load the half-precision floating point
+value as an i16, then convert it to float with
+:ref:`llvm.convert.from.fp16 <int_convert_from_fp16>`. 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
+:ref:`llvm.convert.to.fp16 <int_convert_to_fp16>`, then storing as an
+i16 value.
+
+.. _int_convert_to_fp16:
+
+'``llvm.convert.to.fp16``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i16 @llvm.convert.to.fp16.f32(float %a)
+ declare i16 @llvm.convert.to.fp16.f64(double %a)
+
+Overview:
+"""""""""
+
+The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a
+conventional floating point type to half precision floating point format.
+
+Arguments:
+""""""""""
+
+The intrinsic function contains single argument - the value to be
+converted.
+
+Semantics:
+""""""""""
+
+The '``llvm.convert.to.fp16``' intrinsic function performs a conversion from a
+conventional floating point format to half precision floating point format. The
+return value is an ``i16`` which contains the converted number.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %res = call i16 @llvm.convert.to.fp16.f32(float %a)
+ store i16 %res, i16* @x, align 2
+
+.. _int_convert_from_fp16:
+
+'``llvm.convert.from.fp16``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare float @llvm.convert.from.fp16.f32(i16 %a)
+ declare double @llvm.convert.from.fp16.f64(i16 %a)
+
+Overview:
+"""""""""
+
+The '``llvm.convert.from.fp16``' intrinsic function performs a
+conversion from half precision floating point format to single precision
+floating point format.
+
+Arguments:
+""""""""""
+
+The intrinsic function contains single argument - the value to be
+converted.
+
+Semantics:
+""""""""""
+
+The '``llvm.convert.from.fp16``' 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 ``i16`` value.
+
+Examples:
+"""""""""
+
+.. code-block:: llvm
+
+ %a = load i16* @x, align 2
+ %res = call float @llvm.convert.from.fp16(i16 %a)
+
+Debugger Intrinsics
+-------------------
+
+The LLVM debugger intrinsics (which all start with ``llvm.dbg.``
+prefix), are described in the `LLVM Source Level
+Debugging <SourceLevelDebugging.html#format_common_intrinsics>`_
+document.
+
+Exception Handling Intrinsics
+-----------------------------
+
+The LLVM exception handling intrinsics (which all start with
+``llvm.eh.`` prefix), are described in the `LLVM Exception
+Handling <ExceptionHandling.html#format_common_intrinsics>`_ document.
+
+.. _int_trampoline:
+
+Trampoline Intrinsics
+---------------------
+
+These intrinsics make it possible to excise one parameter, marked with
+the :ref:`nest <nest>` 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.
+
+For example, if the function is ``i32 f(i8* nest %c, i32 %x, i32 %y)``
+then the resulting function pointer has signature ``i32 (i32, i32)*``.
+It can be created as follows:
+
+.. code-block:: llvm
+
+ %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)*
+
+The call ``%val = call i32 %fp(i32 %x, i32 %y)`` is then equivalent to
+``%val = call i32 %f(i8* %nval, i32 %x, i32 %y)``.
+
+.. _int_it:
+
+'``llvm.init.trampoline``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.init.trampoline(i8* <tramp>, i8* <func>, i8* <nval>)
+
+Overview:
+"""""""""
+
+This fills the memory pointed to by ``tramp`` with executable code,
+turning it into a trampoline.
+
+Arguments:
+""""""""""
+
+The ``llvm.init.trampoline`` intrinsic takes three arguments, all
+pointers. The ``tramp`` 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 ``func`` argument must hold a function
+bitcast to an ``i8*``.
+
+Semantics:
+""""""""""
+
+The block of memory pointed to by ``tramp`` is filled with target
+dependent code, turning it into a function. Then ``tramp`` needs to be
+passed to :ref:`llvm.adjust.trampoline <int_at>` to get a pointer which can
+be :ref:`bitcast (to a new function) and called <int_trampoline>`. The new
+function's signature is the same as that of ``func`` with any arguments
+marked with the ``nest`` attribute removed. At most one such ``nest``
+argument is allowed, and it must be of pointer type. Calling the new
+function is equivalent to calling ``func`` with the same argument list,
+but with ``nval`` used for the missing ``nest`` argument. If, after
+calling ``llvm.init.trampoline``, the memory pointed to by ``tramp`` is
+modified, then the effect of any later call to the returned function
+pointer is undefined.
+
+.. _int_at:
+
+'``llvm.adjust.trampoline``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i8* @llvm.adjust.trampoline(i8* <tramp>)
+
+Overview:
+"""""""""
+
+This performs any required machine-specific adjustment to the address of
+a trampoline (passed as ``tramp``).
+
+Arguments:
+""""""""""
+
+``tramp`` must point to a block of memory which already has trampoline
+code filled in by a previous call to
+:ref:`llvm.init.trampoline <int_it>`.
+
+Semantics:
+""""""""""
+
+On some architectures the address of the code to be executed needs to be
+different than the address where the trampoline is actually stored. This
+intrinsic returns the executable address corresponding to ``tramp``
+after performing the required machine specific adjustments. The pointer
+returned can then be :ref:`bitcast and executed <int_trampoline>`.
+
+Memory Use Markers
+------------------
+
+This class of intrinsics provides information about the lifetime of
+memory objects and ranges where variables are immutable.
+
+.. _int_lifestart:
+
+'``llvm.lifetime.start``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.lifetime.start(i64 <size>, i8* nocapture <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.lifetime.start``' intrinsic specifies the start of a memory
+object's lifetime.
+
+Arguments:
+""""""""""
+
+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.
+
+Semantics:
+""""""""""
+
+This intrinsic indicates that before this point in the code, the value
+of the memory pointed to by ``ptr`` 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 ``'undef'``.
+
+.. _int_lifeend:
+
+'``llvm.lifetime.end``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.lifetime.end``' intrinsic specifies the end of a memory
+object's lifetime.
+
+Arguments:
+""""""""""
+
+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.
+
+Semantics:
+""""""""""
+
+This intrinsic indicates that after this point in the code, the value of
+the memory pointed to by ``ptr`` 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.
+
+'``llvm.invariant.start``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare {}* @llvm.invariant.start(i64 <size>, i8* nocapture <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.invariant.start``' intrinsic specifies that the contents of
+a memory object will not change.
+
+Arguments:
+""""""""""
+
+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.
+
+Semantics:
+""""""""""
+
+This intrinsic indicates that until an ``llvm.invariant.end`` that uses
+the return value, the referenced memory location is constant and
+unchanging.
+
+'``llvm.invariant.end``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.invariant.end({}* <start>, i64 <size>, i8* nocapture <ptr>)
+
+Overview:
+"""""""""
+
+The '``llvm.invariant.end``' intrinsic specifies that the contents of a
+memory object are mutable.
+
+Arguments:
+""""""""""
+
+The first argument is the matching ``llvm.invariant.start`` 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.
+
+Semantics:
+""""""""""
+
+This intrinsic indicates that the memory is mutable again.
+
+General Intrinsics
+------------------
+
+This class of intrinsics is designed to be generic and has no specific
+purpose.
+
+'``llvm.var.annotation``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.var.annotation(i8* <val>, i8* <str>, i8* <str>, i32 <int>)
+
+Overview:
+"""""""""
+
+The '``llvm.var.annotation``' intrinsic.
+
+Arguments:
+""""""""""
+
+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.
+
+Semantics:
+""""""""""
+
+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.
+
+'``llvm.ptr.annotation.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use '``llvm.ptr.annotation``' on a
+pointer to an integer of any width. *NOTE* you must specify an address space for
+the pointer. The identifier for the default address space is the integer
+'``0``'.
+
+::
+
+ declare i8* @llvm.ptr.annotation.p<address space>i8(i8* <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i16* @llvm.ptr.annotation.p<address space>i16(i16* <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i32* @llvm.ptr.annotation.p<address space>i32(i32* <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i64* @llvm.ptr.annotation.p<address space>i64(i64* <val>, i8* <str>, i8* <str>, i32 <int>)
+ declare i256* @llvm.ptr.annotation.p<address space>i256(i256* <val>, i8* <str>, i8* <str>, i32 <int>)
+
+Overview:
+"""""""""
+
+The '``llvm.ptr.annotation``' intrinsic.
+
+Arguments:
+""""""""""
+
+The first argument is a pointer to an integer value of arbitrary bitwidth
+(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.
+
+Semantics:
+""""""""""
+
+This intrinsic allows annotation of a pointer to an integer 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.
+
+'``llvm.annotation.*``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use '``llvm.annotation``' on
+any integer bit width.
+
+::
+
+ 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>)
+
+Overview:
+"""""""""
+
+The '``llvm.annotation``' intrinsic.
+
+Arguments:
+""""""""""
+
+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.
+
+Semantics:
+""""""""""
+
+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.
+
+'``llvm.trap``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.trap() noreturn nounwind
+
+Overview:
+"""""""""
+
+The '``llvm.trap``' intrinsic.
+
+Arguments:
+""""""""""
+
+None.
+
+Semantics:
+""""""""""
+
+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 ``abort()`` function.
+
+'``llvm.debugtrap``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.debugtrap() nounwind
+
+Overview:
+"""""""""
+
+The '``llvm.debugtrap``' intrinsic.
+
+Arguments:
+""""""""""
+
+None.
+
+Semantics:
+""""""""""
+
+This intrinsic is lowered to code which is intended to cause an
+execution trap with the intention of requesting the attention of a
+debugger.
+
+'``llvm.stackprotector``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.stackprotector(i8* <guard>, i8** <slot>)
+
+Overview:
+"""""""""
+
+The ``llvm.stackprotector`` intrinsic takes the ``guard`` and stores it
+onto the stack at ``slot``. The stack slot is adjusted to ensure that it
+is placed on the stack before local variables.
+
+Arguments:
+""""""""""
+
+The ``llvm.stackprotector`` intrinsic requires two pointer arguments.
+The first argument is the value loaded from the stack guard
+``@__stack_chk_guard``. The second variable is an ``alloca`` that has
+enough space to hold the value of the guard.
+
+Semantics:
+""""""""""
+
+This intrinsic causes the prologue/epilogue inserter to force the position of
+the ``AllocaInst`` 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 by ``llvm.stackprotectorcheck``. If they are
+different, then ``llvm.stackprotectorcheck`` causes the program to abort by
+calling the ``__stack_chk_fail()`` function.
+
+'``llvm.stackprotectorcheck``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.stackprotectorcheck(i8** <guard>)
+
+Overview:
+"""""""""
+
+The ``llvm.stackprotectorcheck`` intrinsic compares ``guard`` against an already
+created stack protector and if they are not equal calls the
+``__stack_chk_fail()`` function.
+
+Arguments:
+""""""""""
+
+The ``llvm.stackprotectorcheck`` intrinsic requires one pointer argument, the
+the variable ``@__stack_chk_guard``.
+
+Semantics:
+""""""""""
+
+This intrinsic is provided to perform the stack protector check by comparing
+``guard`` with the stack slot created by ``llvm.stackprotector`` and if the
+values do not match call the ``__stack_chk_fail()`` function.
+
+The reason to provide this as an IR level intrinsic instead of implementing it
+via other IR operations is that in order to perform this operation at the IR
+level without an intrinsic, one would need to create additional basic blocks to
+handle the success/failure cases. This makes it difficult to stop the stack
+protector check from disrupting sibling tail calls in Codegen. With this
+intrinsic, we are able to generate the stack protector basic blocks late in
+codegen after the tail call decision has occurred.
+
+'``llvm.objectsize``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>)
+ declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>)
+
+Overview:
+"""""""""
+
+The ``llvm.objectsize`` 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.
+
+Arguments:
+""""""""""
+
+The ``llvm.objectsize`` intrinsic takes two arguments. The first
+argument is a pointer to or into the ``object``. The second argument is
+a boolean and determines whether ``llvm.objectsize`` returns 0 (if true)
+or -1 (if false) when the object size is unknown. The second argument
+only accepts constants.
+
+Semantics:
+""""""""""
+
+The ``llvm.objectsize`` intrinsic is lowered to a constant representing
+the size of the object concerned. If the size cannot be determined at
+compile time, ``llvm.objectsize`` returns ``i32/i64 -1 or 0`` (depending
+on the ``min`` argument).
+
+'``llvm.expect``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.expect`` on any
+integer bit width.
+
+::
+
+ declare i1 @llvm.expect.i1(i1 <val>, i1 <expected_val>)
+ declare i32 @llvm.expect.i32(i32 <val>, i32 <expected_val>)
+ declare i64 @llvm.expect.i64(i64 <val>, i64 <expected_val>)
+
+Overview:
+"""""""""
+
+The ``llvm.expect`` intrinsic provides information about expected (the
+most probable) value of ``val``, which can be used by optimizers.
+
+Arguments:
+""""""""""
+
+The ``llvm.expect`` 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.
+
+Semantics:
+""""""""""
+
+This intrinsic is lowered to the ``val``.
+
+'``llvm.donothing``' Intrinsic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+ declare void @llvm.donothing() nounwind readnone
+
+Overview:
+"""""""""
+
+The ``llvm.donothing`` intrinsic doesn't perform any operation. It's the
+only intrinsic that can be called with an invoke instruction.
+
+Arguments:
+""""""""""
+
+None.
+
+Semantics:
+""""""""""
+
+This intrinsic does nothing, and it's removed by optimizers and ignored
+by codegen.
+
+Stack Map Intrinsics
+--------------------
+
+LLVM provides experimental intrinsics to support runtime patching
+mechanisms commonly desired in dynamic language JITs. These intrinsics
+are described in :doc:`StackMaps`.
Added: www-releases/trunk/3.5.1/docs/_sources/Lexicon.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/Lexicon.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/Lexicon.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/Lexicon.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,222 @@
+================
+The LLVM Lexicon
+================
+
+.. note::
+
+ This document is a work in progress!
+
+Definitions
+===========
+
+A
+-
+
+**ADCE**
+ Aggressive Dead Code Elimination
+
+**AST**
+ Abstract Syntax Tree.
+
+ Due to Clang's influence (mostly the fact that parsing and semantic
+ analysis are so intertwined for C and especially C++), the typical
+ working definition of AST in the LLVM community is roughly "the
+ compiler's first complete symbolic (as opposed to textual)
+ representation of an input program".
+ As such, an "AST" might be a more general graph instead of a "tree"
+ (consider the symbolic representation for the type of a typical "linked
+ list node"). This working definition is closer to what some authors
+ call an "annotated abstract syntax tree".
+
+ Consult your favorite compiler book or search engine for more details.
+
+B
+-
+
+.. _lexicon-bb-vectorization:
+
+**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 computationally
+ 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#iterating-over-def-use-use-def-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
+
+**SLP**
+ Superword-Level Parallelism, same as :ref:`Basic-Block Vectorization
+ <lexicon-bb-vectorization>`.
+
+**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.5.1/docs/_sources/LinkTimeOptimization.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/LinkTimeOptimization.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/LinkTimeOptimization.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/LinkTimeOptimization.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,299 @@
+======================================================
+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();
+ }
+
+To compile, run:
+
+.. code-block:: console
+
+ % 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()``.
+
+* 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.5.1/docs/_sources/MCJITDesignAndImplementation.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/MCJITDesignAndImplementation.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/MCJITDesignAndImplementation.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/MCJITDesignAndImplementation.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,180 @@
+===============================
+MCJIT Design and Implementation
+===============================
+
+Introduction
+============
+
+This document describes the internal workings of the MCJIT execution
+engine and the RuntimeDyld component. It is intended as a high level
+overview of the implementation, showing the flow and interactions of
+objects throughout the code generation and dynamic loading process.
+
+Engine Creation
+===============
+
+In most cases, an EngineBuilder object is used to create an instance of
+the MCJIT execution engine. The EngineBuilder takes an llvm::Module
+object as an argument to its constructor. The client may then set various
+options that we control the later be passed along to the MCJIT engine,
+including the selection of MCJIT as the engine type to be created.
+Of particular interest is the EngineBuilder::setMCJITMemoryManager
+function. If the client does not explicitly create a memory manager at
+this time, a default memory manager (specifically SectionMemoryManager)
+will be created when the MCJIT engine is instantiated.
+
+Once the options have been set, a client calls EngineBuilder::create to
+create an instance of the MCJIT engine. If the client does not use the
+form of this function that takes a TargetMachine as a parameter, a new
+TargetMachine will be created based on the target triple associated with
+the Module that was used to create the EngineBuilder.
+
+.. image:: MCJIT-engine-builder.png
+
+EngineBuilder::create will call the static MCJIT::createJIT function,
+passing in its pointers to the module, memory manager and target machine
+objects, all of which will subsequently be owned by the MCJIT object.
+
+The MCJIT class has a member variable, Dyld, which contains an instance of
+the RuntimeDyld wrapper class. This member will be used for
+communications between MCJIT and the actual RuntimeDyldImpl object that
+gets created when an object is loaded.
+
+.. image:: MCJIT-creation.png
+
+Upon creation, MCJIT holds a pointer to the Module object that it received
+from EngineBuilder but it does not immediately generate code for this
+module. Code generation is deferred until either the
+MCJIT::finalizeObject method is called explicitly or a function such as
+MCJIT::getPointerToFunction is called which requires the code to have been
+generated.
+
+Code Generation
+===============
+
+When code generation is triggered, as described above, MCJIT will first
+attempt to retrieve an object image from its ObjectCache member, if one
+has been set. If a cached object image cannot be retrieved, MCJIT will
+call its emitObject method. MCJIT::emitObject uses a local PassManager
+instance and creates a new ObjectBufferStream instance, both of which it
+passes to TargetManager::addPassesToEmitMC before calling PassManager::run
+on the Module with which it was created.
+
+.. image:: MCJIT-load.png
+
+The PassManager::run call causes the MC code generation mechanisms to emit
+a complete relocatable binary object image (either in either ELF or MachO
+format, depending on the target) into the ObjectBufferStream object, which
+is flushed to complete the process. If an ObjectCache is being used, the
+image will be passed to the ObjectCache here.
+
+At this point, the ObjectBufferStream contains the raw object image.
+Before the code can be executed, the code and data sections from this
+image must be loaded into suitable memory, relocations must be applied and
+memory permission and code cache invalidation (if required) must be completed.
+
+Object Loading
+==============
+
+Once an object image has been obtained, either through code generation or
+having been retrieved from an ObjectCache, it is passed to RuntimeDyld to
+be loaded. The RuntimeDyld wrapper class examines the object to determine
+its file format and creates an instance of either RuntimeDyldELF or
+RuntimeDyldMachO (both of which derive from the RuntimeDyldImpl base
+class) and calls the RuntimeDyldImpl::loadObject method to perform that
+actual loading.
+
+.. image:: MCJIT-dyld-load.png
+
+RuntimeDyldImpl::loadObject begins by creating an ObjectImage instance
+from the ObjectBuffer it received. ObjectImage, which wraps the
+ObjectFile class, is a helper class which parses the binary object image
+and provides access to the information contained in the format-specific
+headers, including section, symbol and relocation information.
+
+RuntimeDyldImpl::loadObject then iterates through the symbols in the
+image. Information about common symbols is collected for later use. For
+each function or data symbol, the associated section is loaded into memory
+and the symbol is stored in a symbol table map data structure. When the
+iteration is complete, a section is emitted for the common symbols.
+
+Next, RuntimeDyldImpl::loadObject iterates through the sections in the
+object image and for each section iterates through the relocations for
+that sections. For each relocation, it calls the format-specific
+processRelocationRef method, which will examine the relocation and store
+it in one of two data structures, a section-based relocation list map and
+an external symbol relocation map.
+
+.. image:: MCJIT-load-object.png
+
+When RuntimeDyldImpl::loadObject returns, all of the code and data
+sections for the object will have been loaded into memory allocated by the
+memory manager and relocation information will have been prepared, but the
+relocations have not yet been applied and the generated code is still not
+ready to be executed.
+
+[Currently (as of August 2013) the MCJIT engine will immediately apply
+relocations when loadObject completes. However, this shouldn't be
+happening. Because the code may have been generated for a remote target,
+the client should be given a chance to re-map the section addresses before
+relocations are applied. It is possible to apply relocations multiple
+times, but in the case where addresses are to be re-mapped, this first
+application is wasted effort.]
+
+Address Remapping
+=================
+
+At any time after initial code has been generated and before
+finalizeObject is called, the client can remap the address of sections in
+the object. Typically this is done because the code was generated for an
+external process and is being mapped into that process' address space.
+The client remaps the section address by calling MCJIT::mapSectionAddress.
+This should happen before the section memory is copied to its new
+location.
+
+When MCJIT::mapSectionAddress is called, MCJIT passes the call on to
+RuntimeDyldImpl (via its Dyld member). RuntimeDyldImpl stores the new
+address in an internal data structure but does not update the code at this
+time, since other sections are likely to change.
+
+When the client is finished remapping section addresses, it will call
+MCJIT::finalizeObject to complete the remapping process.
+
+Final Preparations
+==================
+
+When MCJIT::finalizeObject is called, MCJIT calls
+RuntimeDyld::resolveRelocations. This function will attempt to locate any
+external symbols and then apply all relocations for the object.
+
+External symbols are resolved by calling the memory manager's
+getPointerToNamedFunction method. The memory manager will return the
+address of the requested symbol in the target address space. (Note, this
+may not be a valid pointer in the host process.) RuntimeDyld will then
+iterate through the list of relocations it has stored which are associated
+with this symbol and invoke the resolveRelocation method which, through an
+format-specific implementation, will apply the relocation to the loaded
+section memory.
+
+Next, RuntimeDyld::resolveRelocations iterates through the list of
+sections and for each section iterates through a list of relocations that
+have been saved which reference that symbol and call resolveRelocation for
+each entry in this list. The relocation list here is a list of
+relocations for which the symbol associated with the relocation is located
+in the section associated with the list. Each of these locations will
+have a target location at which the relocation will be applied that is
+likely located in a different section.
+
+.. image:: MCJIT-resolve-relocations.png
+
+Once relocations have been applied as described above, MCJIT calls
+RuntimeDyld::getEHFrameSection, and if a non-zero result is returned
+passes the section data to the memory manager's registerEHFrames method.
+This allows the memory manager to call any desired target-specific
+functions, such as registering the EH frame information with a debugger.
+
+Finally, MCJIT calls the memory manager's finalizeMemory method. In this
+method, the memory manager will invalidate the target code cache, if
+necessary, and apply final permissions to the memory pages it has
+allocated for code and data memory.
+
Added: www-releases/trunk/3.5.1/docs/_sources/MakefileGuide.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/MakefileGuide.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/MakefileGuide.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/MakefileGuide.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,916 @@
+===================
+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 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 (C).
+
+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
+ BUILD_ARCHIVE = 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. :ref:`Pass
+documentation <writing-an-llvm-pass-makefile>` has an example of why you might
+want to do this.
+
+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 used 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 ``BUILD_ARCHIVE`` 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 :doc:`Testing Guide <TestingGuide>` 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 the :doc:`Lit <CommandGuide/lit>` testing
+tool to run a suite of feature and regression tests. Other projects may choose
+to use :program:`lit` 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.
+
+``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.
+
+``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 it is
+ 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.
+
+``CPPFLAGS``
+ Additional flags passed to the C/C++ preprocessor.
+
+``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.
+
+``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
+ 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
+ ObjectsLO
+ ObjectsO
+ ObjMakefiles
+ ParallelTargets
+ PreConditions
+ ProjLibsOptions
+ ProjLibsPaths
+ ProjUsedLibs
+ Ranlib
+ RecursiveTargets
+ SrcMakefiles
+ Strip
+ StripWarnMsg
+ TableGen
+ TDFiles
+ ToolBuildPath
+ TopLevelTargets
+ UserTargets
Added: www-releases/trunk/3.5.1/docs/_sources/MarkedUpDisassembly.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/MarkedUpDisassembly.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/MarkedUpDisassembly.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/MarkedUpDisassembly.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,86 @@
+=======================================
+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.5.1/docs/_sources/NVPTXUsage.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/NVPTXUsage.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/NVPTXUsage.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/NVPTXUsage.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,980 @@
+=============================
+User Guide for NVPTX Back-end
+=============================
+
+.. contents::
+ :local:
+ :depth: 3
+
+
+Introduction
+============
+
+To support GPU programming, the NVPTX back-end supports a subset of LLVM IR
+along with a defined set of conventions used to represent GPU programming
+concepts. This document provides an overview of the general usage of the back-
+end, including a description of the conventions used and the set of accepted
+LLVM IR.
+
+.. note::
+
+ This document assumes a basic familiarity with CUDA and the PTX
+ assembly language. Information about the CUDA Driver API and the PTX assembly
+ language can be found in the `CUDA documentation
+ <http://docs.nvidia.com/cuda/index.html>`_.
+
+
+
+Conventions
+===========
+
+Marking Functions as Kernels
+----------------------------
+
+In PTX, there are two types of functions: *device functions*, which are only
+callable by device code, and *kernel functions*, which are callable by host
+code. By default, the back-end will emit device functions. Metadata is used to
+declare a function as a kernel function. This metadata is attached to the
+``nvvm.annotations`` named metadata object, and has the following format:
+
+.. code-block:: llvm
+
+ !0 = metadata !{<function-ref>, metadata !"kernel", i32 1}
+
+The first parameter is a reference to the kernel function. The following
+example shows a kernel function calling a device function in LLVM IR. The
+function ``@my_kernel`` is callable from host code, but ``@my_fmad`` is not.
+
+.. code-block:: llvm
+
+ define float @my_fmad(float %x, float %y, float %z) {
+ %mul = fmul float %x, %y
+ %add = fadd float %mul, %z
+ ret float %add
+ }
+
+ define void @my_kernel(float* %ptr) {
+ %val = load float* %ptr
+ %ret = call float @my_fmad(float %val, float %val, float %val)
+ store float %ret, float* %ptr
+ ret void
+ }
+
+ !nvvm.annotations = !{!1}
+ !1 = metadata !{void (float*)* @my_kernel, metadata !"kernel", i32 1}
+
+When compiled, the PTX kernel functions are callable by host-side code.
+
+
+.. _address_spaces:
+
+Address Spaces
+--------------
+
+The NVPTX back-end uses the following address space mapping:
+
+ ============= ======================
+ Address Space Memory Space
+ ============= ======================
+ 0 Generic
+ 1 Global
+ 2 Internal Use
+ 3 Shared
+ 4 Constant
+ 5 Local
+ ============= ======================
+
+Every global variable and pointer type is assigned to one of these address
+spaces, with 0 being the default address space. Intrinsics are provided which
+can be used to convert pointers between the generic and non-generic address
+spaces.
+
+As an example, the following IR will define an array ``@g`` that resides in
+global device memory.
+
+.. code-block:: llvm
+
+ @g = internal addrspace(1) global [4 x i32] [ i32 0, i32 1, i32 2, i32 3 ]
+
+LLVM IR functions can read and write to this array, and host-side code can
+copy data to it by name with the CUDA Driver API.
+
+Note that since address space 0 is the generic space, it is illegal to have
+global variables in address space 0. Address space 0 is the default address
+space in LLVM, so the ``addrspace(N)`` annotation is *required* for global
+variables.
+
+
+Triples
+-------
+
+The NVPTX target uses the module triple to select between 32/64-bit code
+generation and the driver-compiler interface to use. The triple architecture
+can be one of ``nvptx`` (32-bit PTX) or ``nvptx64`` (64-bit PTX). The
+operating system should be one of ``cuda`` or ``nvcl``, which determines the
+interface used by the generated code to communicate with the driver. Most
+users will want to use ``cuda`` as the operating system, which makes the
+generated PTX compatible with the CUDA Driver API.
+
+Example: 32-bit PTX for CUDA Driver API: ``nvptx-nvidia-cuda``
+
+Example: 64-bit PTX for CUDA Driver API: ``nvptx64-nvidia-cuda``
+
+
+
+.. _nvptx_intrinsics:
+
+NVPTX Intrinsics
+================
+
+Address Space Conversion
+------------------------
+
+'``llvm.nvvm.ptr.*.to.gen``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+These are overloaded intrinsics. You can use these on any pointer types.
+
+.. code-block:: llvm
+
+ declare i8* @llvm.nvvm.ptr.global.to.gen.p0i8.p1i8(i8 addrspace(1)*)
+ declare i8* @llvm.nvvm.ptr.shared.to.gen.p0i8.p3i8(i8 addrspace(3)*)
+ declare i8* @llvm.nvvm.ptr.constant.to.gen.p0i8.p4i8(i8 addrspace(4)*)
+ declare i8* @llvm.nvvm.ptr.local.to.gen.p0i8.p5i8(i8 addrspace(5)*)
+
+Overview:
+"""""""""
+
+The '``llvm.nvvm.ptr.*.to.gen``' intrinsics convert a pointer in a non-generic
+address space to a generic address space pointer.
+
+Semantics:
+""""""""""
+
+These intrinsics modify the pointer value to be a valid generic address space
+pointer.
+
+
+'``llvm.nvvm.ptr.gen.to.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+These are overloaded intrinsics. You can use these on any pointer types.
+
+.. code-block:: llvm
+
+ declare i8* @llvm.nvvm.ptr.gen.to.global.p1i8.p0i8(i8 addrspace(1)*)
+ declare i8* @llvm.nvvm.ptr.gen.to.shared.p3i8.p0i8(i8 addrspace(3)*)
+ declare i8* @llvm.nvvm.ptr.gen.to.constant.p4i8.p0i8(i8 addrspace(4)*)
+ declare i8* @llvm.nvvm.ptr.gen.to.local.p5i8.p0i8(i8 addrspace(5)*)
+
+Overview:
+"""""""""
+
+The '``llvm.nvvm.ptr.gen.to.*``' intrinsics convert a pointer in the generic
+address space to a pointer in the target address space. Note that these
+intrinsics are only useful if the address space of the target address space of
+the pointer is known. It is not legal to use address space conversion
+intrinsics to convert a pointer from one non-generic address space to another
+non-generic address space.
+
+Semantics:
+""""""""""
+
+These intrinsics modify the pointer value to be a valid pointer in the target
+non-generic address space.
+
+
+Reading PTX Special Registers
+-----------------------------
+
+'``llvm.nvvm.read.ptx.sreg.*``'
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+.. code-block:: llvm
+
+ declare i32 @llvm.nvvm.read.ptx.sreg.tid.x()
+ declare i32 @llvm.nvvm.read.ptx.sreg.tid.y()
+ declare i32 @llvm.nvvm.read.ptx.sreg.tid.z()
+ declare i32 @llvm.nvvm.read.ptx.sreg.ntid.x()
+ declare i32 @llvm.nvvm.read.ptx.sreg.ntid.y()
+ declare i32 @llvm.nvvm.read.ptx.sreg.ntid.z()
+ declare i32 @llvm.nvvm.read.ptx.sreg.ctaid.x()
+ declare i32 @llvm.nvvm.read.ptx.sreg.ctaid.y()
+ declare i32 @llvm.nvvm.read.ptx.sreg.ctaid.z()
+ declare i32 @llvm.nvvm.read.ptx.sreg.nctaid.x()
+ declare i32 @llvm.nvvm.read.ptx.sreg.nctaid.y()
+ declare i32 @llvm.nvvm.read.ptx.sreg.nctaid.z()
+ declare i32 @llvm.nvvm.read.ptx.sreg.warpsize()
+
+Overview:
+"""""""""
+
+The '``@llvm.nvvm.read.ptx.sreg.*``' intrinsics provide access to the PTX
+special registers, in particular the kernel launch bounds. These registers
+map in the following way to CUDA builtins:
+
+ ============ =====================================
+ CUDA Builtin PTX Special Register Intrinsic
+ ============ =====================================
+ ``threadId`` ``@llvm.nvvm.read.ptx.sreg.tid.*``
+ ``blockIdx`` ``@llvm.nvvm.read.ptx.sreg.ctaid.*``
+ ``blockDim`` ``@llvm.nvvm.read.ptx.sreg.ntid.*``
+ ``gridDim`` ``@llvm.nvvm.read.ptx.sreg.nctaid.*``
+ ============ =====================================
+
+
+Barriers
+--------
+
+'``llvm.nvvm.barrier0``'
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+.. code-block:: llvm
+
+ declare void @llvm.nvvm.barrier0()
+
+Overview:
+"""""""""
+
+The '``@llvm.nvvm.barrier0()``' intrinsic emits a PTX ``bar.sync 0``
+instruction, equivalent to the ``__syncthreads()`` call in CUDA.
+
+
+Other Intrinsics
+----------------
+
+For the full set of NVPTX intrinsics, please see the
+``include/llvm/IR/IntrinsicsNVVM.td`` file in the LLVM source tree.
+
+
+.. _libdevice:
+
+Linking with Libdevice
+======================
+
+The CUDA Toolkit comes with an LLVM bitcode library called ``libdevice`` that
+implements many common mathematical functions. This library can be used as a
+high-performance math library for any compilers using the LLVM NVPTX target.
+The library can be found under ``nvvm/libdevice/`` in the CUDA Toolkit and
+there is a separate version for each compute architecture.
+
+For a list of all math functions implemented in libdevice, see
+`libdevice Users Guide <http://docs.nvidia.com/cuda/libdevice-users-guide/index.html>`_.
+
+To accommodate various math-related compiler flags that can affect code
+generation of libdevice code, the library code depends on a special LLVM IR
+pass (``NVVMReflect``) to handle conditional compilation within LLVM IR. This
+pass looks for calls to the ``@__nvvm_reflect`` function and replaces them
+with constants based on the defined reflection parameters. Such conditional
+code often follows a pattern:
+
+.. code-block:: c++
+
+ float my_function(float a) {
+ if (__nvvm_reflect("FASTMATH"))
+ return my_function_fast(a);
+ else
+ return my_function_precise(a);
+ }
+
+The default value for all unspecified reflection parameters is zero.
+
+The ``NVVMReflect`` pass should be executed early in the optimization
+pipeline, immediately after the link stage. The ``internalize`` pass is also
+recommended to remove unused math functions from the resulting PTX. For an
+input IR module ``module.bc``, the following compilation flow is recommended:
+
+1. Save list of external functions in ``module.bc``
+2. Link ``module.bc`` with ``libdevice.compute_XX.YY.bc``
+3. Internalize all functions not in list from (1)
+4. Eliminate all unused internal functions
+5. Run ``NVVMReflect`` pass
+6. Run standard optimization pipeline
+
+.. note::
+
+ ``linkonce`` and ``linkonce_odr`` linkage types are not suitable for the
+ libdevice functions. It is possible to link two IR modules that have been
+ linked against libdevice using different reflection variables.
+
+Since the ``NVVMReflect`` pass replaces conditionals with constants, it will
+often leave behind dead code of the form:
+
+.. code-block:: llvm
+
+ entry:
+ ..
+ br i1 true, label %foo, label %bar
+ foo:
+ ..
+ bar:
+ ; Dead code
+ ..
+
+Therefore, it is recommended that ``NVVMReflect`` is executed early in the
+optimization pipeline before dead-code elimination.
+
+
+Reflection Parameters
+---------------------
+
+The libdevice library currently uses the following reflection parameters to
+control code generation:
+
+==================== ======================================================
+Flag Description
+==================== ======================================================
+``__CUDA_FTZ=[0,1]`` Use optimized code paths that flush subnormals to zero
+==================== ======================================================
+
+
+Invoking NVVMReflect
+--------------------
+
+To ensure that all dead code caused by the reflection pass is eliminated, it
+is recommended that the reflection pass is executed early in the LLVM IR
+optimization pipeline. The pass takes an optional mapping of reflection
+parameter name to an integer value. This mapping can be specified as either a
+command-line option to ``opt`` or as an LLVM ``StringMap<int>`` object when
+programmatically creating a pass pipeline.
+
+With ``opt``:
+
+.. code-block:: text
+
+ # opt -nvvm-reflect -nvvm-reflect-list=<var>=<value>,<var>=<value> module.bc -o module.reflect.bc
+
+
+With programmatic pass pipeline:
+
+.. code-block:: c++
+
+ extern ModulePass *llvm::createNVVMReflectPass(const StringMap<int>& Mapping);
+
+ StringMap<int> ReflectParams;
+ ReflectParams["__CUDA_FTZ"] = 1;
+ Passes.add(createNVVMReflectPass(ReflectParams));
+
+
+
+Executing PTX
+=============
+
+The most common way to execute PTX assembly on a GPU device is to use the CUDA
+Driver API. This API is a low-level interface to the GPU driver and allows for
+JIT compilation of PTX code to native GPU machine code.
+
+Initializing the Driver API:
+
+.. code-block:: c++
+
+ CUdevice device;
+ CUcontext context;
+
+ // Initialize the driver API
+ cuInit(0);
+ // Get a handle to the first compute device
+ cuDeviceGet(&device, 0);
+ // Create a compute device context
+ cuCtxCreate(&context, 0, device);
+
+JIT compiling a PTX string to a device binary:
+
+.. code-block:: c++
+
+ CUmodule module;
+ CUfunction funcion;
+
+ // JIT compile a null-terminated PTX string
+ cuModuleLoadData(&module, (void*)PTXString);
+
+ // Get a handle to the "myfunction" kernel function
+ cuModuleGetFunction(&function, module, "myfunction");
+
+For full examples of executing PTX assembly, please see the `CUDA Samples
+<https://developer.nvidia.com/cuda-downloads>`_ distribution.
+
+
+Common Issues
+=============
+
+ptxas complains of undefined function: __nvvm_reflect
+-----------------------------------------------------
+
+When linking with libdevice, the ``NVVMReflect`` pass must be used. See
+:ref:`libdevice` for more information.
+
+
+Tutorial: A Simple Compute Kernel
+=================================
+
+To start, let us take a look at a simple compute kernel written directly in
+LLVM IR. The kernel implements vector addition, where each thread computes one
+element of the output vector C from the input vectors A and B. To make this
+easier, we also assume that only a single CTA (thread block) will be launched,
+and that it will be one dimensional.
+
+
+The Kernel
+----------
+
+.. code-block:: llvm
+
+ target datalayout = "e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"
+ target triple = "nvptx64-nvidia-cuda"
+
+ ; Intrinsic to read X component of thread ID
+ declare i32 @llvm.nvvm.read.ptx.sreg.tid.x() readnone nounwind
+
+ define void @kernel(float addrspace(1)* %A,
+ float addrspace(1)* %B,
+ float addrspace(1)* %C) {
+ entry:
+ ; What is my ID?
+ %id = tail call i32 @llvm.nvvm.read.ptx.sreg.tid.x() readnone nounwind
+
+ ; Compute pointers into A, B, and C
+ %ptrA = getelementptr float addrspace(1)* %A, i32 %id
+ %ptrB = getelementptr float addrspace(1)* %B, i32 %id
+ %ptrC = getelementptr float addrspace(1)* %C, i32 %id
+
+ ; Read A, B
+ %valA = load float addrspace(1)* %ptrA, align 4
+ %valB = load float addrspace(1)* %ptrB, align 4
+
+ ; Compute C = A + B
+ %valC = fadd float %valA, %valB
+
+ ; Store back to C
+ store float %valC, float addrspace(1)* %ptrC, align 4
+
+ ret void
+ }
+
+ !nvvm.annotations = !{!0}
+ !0 = metadata !{void (float addrspace(1)*,
+ float addrspace(1)*,
+ float addrspace(1)*)* @kernel, metadata !"kernel", i32 1}
+
+
+We can use the LLVM ``llc`` tool to directly run the NVPTX code generator:
+
+.. code-block:: text
+
+ # llc -mcpu=sm_20 kernel.ll -o kernel.ptx
+
+
+.. note::
+
+ If you want to generate 32-bit code, change ``p:64:64:64`` to ``p:32:32:32``
+ in the module data layout string and use ``nvptx-nvidia-cuda`` as the
+ target triple.
+
+
+The output we get from ``llc`` (as of LLVM 3.4):
+
+.. code-block:: text
+
+ //
+ // Generated by LLVM NVPTX Back-End
+ //
+
+ .version 3.1
+ .target sm_20
+ .address_size 64
+
+ // .globl kernel
+ // @kernel
+ .visible .entry kernel(
+ .param .u64 kernel_param_0,
+ .param .u64 kernel_param_1,
+ .param .u64 kernel_param_2
+ )
+ {
+ .reg .f32 %f<4>;
+ .reg .s32 %r<2>;
+ .reg .s64 %rl<8>;
+
+ // BB#0: // %entry
+ ld.param.u64 %rl1, [kernel_param_0];
+ mov.u32 %r1, %tid.x;
+ mul.wide.s32 %rl2, %r1, 4;
+ add.s64 %rl3, %rl1, %rl2;
+ ld.param.u64 %rl4, [kernel_param_1];
+ add.s64 %rl5, %rl4, %rl2;
+ ld.param.u64 %rl6, [kernel_param_2];
+ add.s64 %rl7, %rl6, %rl2;
+ ld.global.f32 %f1, [%rl3];
+ ld.global.f32 %f2, [%rl5];
+ add.f32 %f3, %f1, %f2;
+ st.global.f32 [%rl7], %f3;
+ ret;
+ }
+
+
+Dissecting the Kernel
+---------------------
+
+Now let us dissect the LLVM IR that makes up this kernel.
+
+Data Layout
+^^^^^^^^^^^
+
+The data layout string determines the size in bits of common data types, their
+ABI alignment, and their storage size. For NVPTX, you should use one of the
+following:
+
+32-bit PTX:
+
+.. code-block:: llvm
+
+ target datalayout = "e-p:32:32:32-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"
+
+64-bit PTX:
+
+.. code-block:: llvm
+
+ target datalayout = "e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"
+
+
+Target Intrinsics
+^^^^^^^^^^^^^^^^^
+
+In this example, we use the ``@llvm.nvvm.read.ptx.sreg.tid.x`` intrinsic to
+read the X component of the current thread's ID, which corresponds to a read
+of register ``%tid.x`` in PTX. The NVPTX back-end supports a large set of
+intrinsics. A short list is shown below; please see
+``include/llvm/IR/IntrinsicsNVVM.td`` for the full list.
+
+
+================================================ ====================
+Intrinsic CUDA Equivalent
+================================================ ====================
+``i32 @llvm.nvvm.read.ptx.sreg.tid.{x,y,z}`` threadIdx.{x,y,z}
+``i32 @llvm.nvvm.read.ptx.sreg.ctaid.{x,y,z}`` blockIdx.{x,y,z}
+``i32 @llvm.nvvm.read.ptx.sreg.ntid.{x,y,z}`` blockDim.{x,y,z}
+``i32 @llvm.nvvm.read.ptx.sreg.nctaid.{x,y,z}`` gridDim.{x,y,z}
+``void @llvm.cuda.syncthreads()`` __syncthreads()
+================================================ ====================
+
+
+Address Spaces
+^^^^^^^^^^^^^^
+
+You may have noticed that all of the pointer types in the LLVM IR example had
+an explicit address space specifier. What is address space 1? NVIDIA GPU
+devices (generally) have four types of memory:
+
+- Global: Large, off-chip memory
+- Shared: Small, on-chip memory shared among all threads in a CTA
+- Local: Per-thread, private memory
+- Constant: Read-only memory shared across all threads
+
+These different types of memory are represented in LLVM IR as address spaces.
+There is also a fifth address space used by the NVPTX code generator that
+corresponds to the "generic" address space. This address space can represent
+addresses in any other address space (with a few exceptions). This allows
+users to write IR functions that can load/store memory using the same
+instructions. Intrinsics are provided to convert pointers between the generic
+and non-generic address spaces.
+
+See :ref:`address_spaces` and :ref:`nvptx_intrinsics` for more information.
+
+
+Kernel Metadata
+^^^^^^^^^^^^^^^
+
+In PTX, a function can be either a `kernel` function (callable from the host
+program), or a `device` function (callable only from GPU code). You can think
+of `kernel` functions as entry-points in the GPU program. To mark an LLVM IR
+function as a `kernel` function, we make use of special LLVM metadata. The
+NVPTX back-end will look for a named metadata node called
+``nvvm.annotations``. This named metadata must contain a list of metadata that
+describe the IR. For our purposes, we need to declare a metadata node that
+assigns the "kernel" attribute to the LLVM IR function that should be emitted
+as a PTX `kernel` function. These metadata nodes take the form:
+
+.. code-block:: text
+
+ metadata !{<function ref>, metadata !"kernel", i32 1}
+
+For the previous example, we have:
+
+.. code-block:: llvm
+
+ !nvvm.annotations = !{!0}
+ !0 = metadata !{void (float addrspace(1)*,
+ float addrspace(1)*,
+ float addrspace(1)*)* @kernel, metadata !"kernel", i32 1}
+
+Here, we have a single metadata declaration in ``nvvm.annotations``. This
+metadata annotates our ``@kernel`` function with the ``kernel`` attribute.
+
+
+Running the Kernel
+------------------
+
+Generating PTX from LLVM IR is all well and good, but how do we execute it on
+a real GPU device? The CUDA Driver API provides a convenient mechanism for
+loading and JIT compiling PTX to a native GPU device, and launching a kernel.
+The API is similar to OpenCL. A simple example showing how to load and
+execute our vector addition code is shown below. Note that for brevity this
+code does not perform much error checking!
+
+.. note::
+
+ You can also use the ``ptxas`` tool provided by the CUDA Toolkit to offline
+ compile PTX to machine code (SASS) for a specific GPU architecture. Such
+ binaries can be loaded by the CUDA Driver API in the same way as PTX. This
+ can be useful for reducing startup time by precompiling the PTX kernels.
+
+
+.. code-block:: c++
+
+ #include <iostream>
+ #include <fstream>
+ #include <cassert>
+ #include "cuda.h"
+
+
+ void checkCudaErrors(CUresult err) {
+ assert(err == CUDA_SUCCESS);
+ }
+
+ /// main - Program entry point
+ int main(int argc, char **argv) {
+ CUdevice device;
+ CUmodule cudaModule;
+ CUcontext context;
+ CUfunction function;
+ CUlinkState linker;
+ int devCount;
+
+ // CUDA initialization
+ checkCudaErrors(cuInit(0));
+ checkCudaErrors(cuDeviceGetCount(&devCount));
+ checkCudaErrors(cuDeviceGet(&device, 0));
+
+ char name[128];
+ checkCudaErrors(cuDeviceGetName(name, 128, device));
+ std::cout << "Using CUDA Device [0]: " << name << "\n";
+
+ int devMajor, devMinor;
+ checkCudaErrors(cuDeviceComputeCapability(&devMajor, &devMinor, device));
+ std::cout << "Device Compute Capability: "
+ << devMajor << "." << devMinor << "\n";
+ if (devMajor < 2) {
+ std::cerr << "ERROR: Device 0 is not SM 2.0 or greater\n";
+ return 1;
+ }
+
+ std::ifstream t("kernel.ptx");
+ if (!t.is_open()) {
+ std::cerr << "kernel.ptx not found\n";
+ return 1;
+ }
+ std::string str((std::istreambuf_iterator<char>(t)),
+ std::istreambuf_iterator<char>());
+
+ // Create driver context
+ checkCudaErrors(cuCtxCreate(&context, 0, device));
+
+ // Create module for object
+ checkCudaErrors(cuModuleLoadDataEx(&cudaModule, str.c_str(), 0, 0, 0));
+
+ // Get kernel function
+ checkCudaErrors(cuModuleGetFunction(&function, cudaModule, "kernel"));
+
+ // Device data
+ CUdeviceptr devBufferA;
+ CUdeviceptr devBufferB;
+ CUdeviceptr devBufferC;
+
+ checkCudaErrors(cuMemAlloc(&devBufferA, sizeof(float)*16));
+ checkCudaErrors(cuMemAlloc(&devBufferB, sizeof(float)*16));
+ checkCudaErrors(cuMemAlloc(&devBufferC, sizeof(float)*16));
+
+ float* hostA = new float[16];
+ float* hostB = new float[16];
+ float* hostC = new float[16];
+
+ // Populate input
+ for (unsigned i = 0; i != 16; ++i) {
+ hostA[i] = (float)i;
+ hostB[i] = (float)(2*i);
+ hostC[i] = 0.0f;
+ }
+
+ checkCudaErrors(cuMemcpyHtoD(devBufferA, &hostA[0], sizeof(float)*16));
+ checkCudaErrors(cuMemcpyHtoD(devBufferB, &hostB[0], sizeof(float)*16));
+
+
+ unsigned blockSizeX = 16;
+ unsigned blockSizeY = 1;
+ unsigned blockSizeZ = 1;
+ unsigned gridSizeX = 1;
+ unsigned gridSizeY = 1;
+ unsigned gridSizeZ = 1;
+
+ // Kernel parameters
+ void *KernelParams[] = { &devBufferA, &devBufferB, &devBufferC };
+
+ std::cout << "Launching kernel\n";
+
+ // Kernel launch
+ checkCudaErrors(cuLaunchKernel(function, gridSizeX, gridSizeY, gridSizeZ,
+ blockSizeX, blockSizeY, blockSizeZ,
+ 0, NULL, KernelParams, NULL));
+
+ // Retrieve device data
+ checkCudaErrors(cuMemcpyDtoH(&hostC[0], devBufferC, sizeof(float)*16));
+
+
+ std::cout << "Results:\n";
+ for (unsigned i = 0; i != 16; ++i) {
+ std::cout << hostA[i] << " + " << hostB[i] << " = " << hostC[i] << "\n";
+ }
+
+
+ // Clean up after ourselves
+ delete [] hostA;
+ delete [] hostB;
+ delete [] hostC;
+
+ // Clean-up
+ checkCudaErrors(cuMemFree(devBufferA));
+ checkCudaErrors(cuMemFree(devBufferB));
+ checkCudaErrors(cuMemFree(devBufferC));
+ checkCudaErrors(cuModuleUnload(cudaModule));
+ checkCudaErrors(cuCtxDestroy(context));
+
+ return 0;
+ }
+
+
+You will need to link with the CUDA driver and specify the path to cuda.h.
+
+.. code-block:: text
+
+ # clang++ sample.cpp -o sample -O2 -g -I/usr/local/cuda-5.5/include -lcuda
+
+We don't need to specify a path to ``libcuda.so`` since this is installed in a
+system location by the driver, not the CUDA toolkit.
+
+If everything goes as planned, you should see the following output when
+running the compiled program:
+
+.. code-block:: text
+
+ Using CUDA Device [0]: GeForce GTX 680
+ Device Compute Capability: 3.0
+ Launching kernel
+ Results:
+ 0 + 0 = 0
+ 1 + 2 = 3
+ 2 + 4 = 6
+ 3 + 6 = 9
+ 4 + 8 = 12
+ 5 + 10 = 15
+ 6 + 12 = 18
+ 7 + 14 = 21
+ 8 + 16 = 24
+ 9 + 18 = 27
+ 10 + 20 = 30
+ 11 + 22 = 33
+ 12 + 24 = 36
+ 13 + 26 = 39
+ 14 + 28 = 42
+ 15 + 30 = 45
+
+.. note::
+
+ You will likely see a different device identifier based on your hardware
+
+
+Tutorial: Linking with Libdevice
+================================
+
+In this tutorial, we show a simple example of linking LLVM IR with the
+libdevice library. We will use the same kernel as the previous tutorial,
+except that we will compute ``C = pow(A, B)`` instead of ``C = A + B``.
+Libdevice provides an ``__nv_powf`` function that we will use.
+
+.. code-block:: llvm
+
+ target datalayout = "e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"
+ target triple = "nvptx64-nvidia-cuda"
+
+ ; Intrinsic to read X component of thread ID
+ declare i32 @llvm.nvvm.read.ptx.sreg.tid.x() readnone nounwind
+ ; libdevice function
+ declare float @__nv_powf(float, float)
+
+ define void @kernel(float addrspace(1)* %A,
+ float addrspace(1)* %B,
+ float addrspace(1)* %C) {
+ entry:
+ ; What is my ID?
+ %id = tail call i32 @llvm.nvvm.read.ptx.sreg.tid.x() readnone nounwind
+
+ ; Compute pointers into A, B, and C
+ %ptrA = getelementptr float addrspace(1)* %A, i32 %id
+ %ptrB = getelementptr float addrspace(1)* %B, i32 %id
+ %ptrC = getelementptr float addrspace(1)* %C, i32 %id
+
+ ; Read A, B
+ %valA = load float addrspace(1)* %ptrA, align 4
+ %valB = load float addrspace(1)* %ptrB, align 4
+
+ ; Compute C = pow(A, B)
+ %valC = call float @__nv_powf(float %valA, float %valB)
+
+ ; Store back to C
+ store float %valC, float addrspace(1)* %ptrC, align 4
+
+ ret void
+ }
+
+ !nvvm.annotations = !{!0}
+ !0 = metadata !{void (float addrspace(1)*,
+ float addrspace(1)*,
+ float addrspace(1)*)* @kernel, metadata !"kernel", i32 1}
+
+
+To compile this kernel, we perform the following steps:
+
+1. Link with libdevice
+2. Internalize all but the public kernel function
+3. Run ``NVVMReflect`` and set ``__CUDA_FTZ`` to 0
+4. Optimize the linked module
+5. Codegen the module
+
+
+These steps can be performed by the LLVM ``llvm-link``, ``opt``, and ``llc``
+tools. In a complete compiler, these steps can also be performed entirely
+programmatically by setting up an appropriate pass configuration (see
+:ref:`libdevice`).
+
+.. code-block:: text
+
+ # llvm-link t2.bc libdevice.compute_20.10.bc -o t2.linked.bc
+ # opt -internalize -internalize-public-api-list=kernel -nvvm-reflect-list=__CUDA_FTZ=0 -nvvm-reflect -O3 t2.linked.bc -o t2.opt.bc
+ # llc -mcpu=sm_20 t2.opt.bc -o t2.ptx
+
+.. note::
+
+ The ``-nvvm-reflect-list=_CUDA_FTZ=0`` is not strictly required, as any
+ undefined variables will default to zero. It is shown here for evaluation
+ purposes.
+
+
+This gives us the following PTX (excerpt):
+
+.. code-block:: text
+
+ //
+ // Generated by LLVM NVPTX Back-End
+ //
+
+ .version 3.1
+ .target sm_20
+ .address_size 64
+
+ // .globl kernel
+ // @kernel
+ .visible .entry kernel(
+ .param .u64 kernel_param_0,
+ .param .u64 kernel_param_1,
+ .param .u64 kernel_param_2
+ )
+ {
+ .reg .pred %p<30>;
+ .reg .f32 %f<111>;
+ .reg .s32 %r<21>;
+ .reg .s64 %rl<8>;
+
+ // BB#0: // %entry
+ ld.param.u64 %rl2, [kernel_param_0];
+ mov.u32 %r3, %tid.x;
+ ld.param.u64 %rl3, [kernel_param_1];
+ mul.wide.s32 %rl4, %r3, 4;
+ add.s64 %rl5, %rl2, %rl4;
+ ld.param.u64 %rl6, [kernel_param_2];
+ add.s64 %rl7, %rl3, %rl4;
+ add.s64 %rl1, %rl6, %rl4;
+ ld.global.f32 %f1, [%rl5];
+ ld.global.f32 %f2, [%rl7];
+ setp.eq.f32 %p1, %f1, 0f3F800000;
+ setp.eq.f32 %p2, %f2, 0f00000000;
+ or.pred %p3, %p1, %p2;
+ @%p3 bra BB0_1;
+ bra.uni BB0_2;
+ BB0_1:
+ mov.f32 %f110, 0f3F800000;
+ st.global.f32 [%rl1], %f110;
+ ret;
+ BB0_2: // %__nv_isnanf.exit.i
+ abs.f32 %f4, %f1;
+ setp.gtu.f32 %p4, %f4, 0f7F800000;
+ @%p4 bra BB0_4;
+ // BB#3: // %__nv_isnanf.exit5.i
+ abs.f32 %f5, %f2;
+ setp.le.f32 %p5, %f5, 0f7F800000;
+ @%p5 bra BB0_5;
+ BB0_4: // %.critedge1.i
+ add.f32 %f110, %f1, %f2;
+ st.global.f32 [%rl1], %f110;
+ ret;
+ BB0_5: // %__nv_isinff.exit.i
+
+ ...
+
+ BB0_26: // %__nv_truncf.exit.i.i.i.i.i
+ mul.f32 %f90, %f107, 0f3FB8AA3B;
+ cvt.rzi.f32.f32 %f91, %f90;
+ mov.f32 %f92, 0fBF317200;
+ fma.rn.f32 %f93, %f91, %f92, %f107;
+ mov.f32 %f94, 0fB5BFBE8E;
+ fma.rn.f32 %f95, %f91, %f94, %f93;
+ mul.f32 %f89, %f95, 0f3FB8AA3B;
+ // inline asm
+ ex2.approx.ftz.f32 %f88,%f89;
+ // inline asm
+ add.f32 %f96, %f91, 0f00000000;
+ ex2.approx.f32 %f97, %f96;
+ mul.f32 %f98, %f88, %f97;
+ setp.lt.f32 %p15, %f107, 0fC2D20000;
+ selp.f32 %f99, 0f00000000, %f98, %p15;
+ setp.gt.f32 %p16, %f107, 0f42D20000;
+ selp.f32 %f110, 0f7F800000, %f99, %p16;
+ setp.eq.f32 %p17, %f110, 0f7F800000;
+ @%p17 bra BB0_28;
+ // BB#27:
+ fma.rn.f32 %f110, %f110, %f108, %f110;
+ BB0_28: // %__internal_accurate_powf.exit.i
+ setp.lt.f32 %p18, %f1, 0f00000000;
+ setp.eq.f32 %p19, %f3, 0f3F800000;
+ and.pred %p20, %p18, %p19;
+ @!%p20 bra BB0_30;
+ bra.uni BB0_29;
+ BB0_29:
+ mov.b32 %r9, %f110;
+ xor.b32 %r10, %r9, -2147483648;
+ mov.b32 %f110, %r10;
+ BB0_30: // %__nv_powf.exit
+ st.global.f32 [%rl1], %f110;
+ ret;
+ }
+
Added: www-releases/trunk/3.5.1/docs/_sources/Packaging.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/Packaging.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/Packaging.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/Packaging.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,73 @@
+========================
+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.5.1/docs/_sources/Passes.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/Passes.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/Passes.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/Passes.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,1193 @@
+..
+ 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";
+ }
+ @x = map { s/^\d\d\d//; $_ } sort @x;
+ @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'
+
+====================================
+LLVM's Analysis and Transform Passes
+====================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+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. The table of contents above
+provides a quick summary of each pass and links to the more complete pass
+description later in the document.
+
+Analysis Passes
+===============
+
+This section describes the LLVM Analysis Passes.
+
+``-aa-eval``: Exhaustive Alias Analysis Precision Evaluator
+-----------------------------------------------------------
+
+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.
+
+This is inspired and adapted from code by: Naveen Neelakantam, Francesco
+Spadini, and Wojciech Stryjewski.
+
+``-basicaa``: Basic Alias Analysis (stateless AA impl)
+------------------------------------------------------
+
+A basic alias analysis pass that implements identities (two different globals
+cannot alias, etc), but does no stateful analysis.
+
+``-basiccg``: Basic CallGraph Construction
+------------------------------------------
+
+Yet to be written.
+
+``-count-aa``: Count Alias Analysis Query Responses
+---------------------------------------------------
+
+A pass which can be used to count how many alias queries are being made and how
+the alias analysis implementation being used responds.
+
+``-da``: Dependence Analysis
+----------------------------
+
+Dependence analysis framework, which is used to detect dependences in memory
+accesses.
+
+``-debug-aa``: AA use debugger
+------------------------------
+
+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.
+
+Yes keeping track of every value in the program is expensive, but this is a
+debugging pass.
+
+``-domfrontier``: Dominance Frontier Construction
+-------------------------------------------------
+
+This pass is a simple dominator construction algorithm for finding forward
+dominator frontiers.
+
+``-domtree``: Dominator Tree Construction
+-----------------------------------------
+
+This pass is a simple dominator construction algorithm for finding forward
+dominators.
+
+
+``-dot-callgraph``: Print Call Graph to "dot" file
+--------------------------------------------------
+
+This pass, only available in ``opt``, prints the call graph into a ``.dot``
+graph. This graph can then be processed with the "dot" tool to convert it to
+postscript or some other suitable format.
+
+``-dot-cfg``: Print CFG of function to "dot" file
+-------------------------------------------------
+
+This pass, only available in ``opt``, prints the control flow graph into a
+``.dot`` graph. This graph can then be processed with the :program:`dot` tool
+to convert it to postscript or some other suitable format.
+
+``-dot-cfg-only``: Print CFG of function to "dot" file (with no function bodies)
+--------------------------------------------------------------------------------
+
+This pass, only available in ``opt``, prints the control flow graph into a
+``.dot`` graph, omitting the function bodies. This graph can then be processed
+with the :program:`dot` tool to convert it to postscript or some other suitable
+format.
+
+``-dot-dom``: Print dominance tree of function to "dot" file
+------------------------------------------------------------
+
+This pass, only available in ``opt``, prints the dominator tree into a ``.dot``
+graph. This graph can then be processed with the :program:`dot` tool to
+convert it to postscript or some other suitable format.
+
+``-dot-dom-only``: Print dominance tree of function to "dot" file (with no function bodies)
+-------------------------------------------------------------------------------------------
+
+This pass, only available in ``opt``, prints the dominator tree into a ``.dot``
+graph, omitting the function bodies. This graph can then be processed with the
+:program:`dot` tool to convert it to postscript or some other suitable format.
+
+``-dot-postdom``: Print postdominance tree of function to "dot" file
+--------------------------------------------------------------------
+
+This pass, only available in ``opt``, prints the post dominator tree into a
+``.dot`` graph. This graph can then be processed with the :program:`dot` tool
+to convert it to postscript or some other suitable format.
+
+``-dot-postdom-only``: Print postdominance tree of function to "dot" file (with no function bodies)
+---------------------------------------------------------------------------------------------------
+
+This pass, only available in ``opt``, prints the post dominator tree into a
+``.dot`` graph, omitting the function bodies. This graph can then be processed
+with the :program:`dot` tool to convert it to postscript or some other suitable
+format.
+
+``-globalsmodref-aa``: Simple mod/ref analysis for globals
+----------------------------------------------------------
+
+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.
+
+``-instcount``: Counts the various types of ``Instruction``\ s
+--------------------------------------------------------------
+
+This pass collects the count of all instructions and reports them.
+
+``-intervals``: Interval Partition Construction
+-----------------------------------------------
+
+This analysis calculates and represents the interval partition of a function,
+or a preexisting interval partition.
+
+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).
+
+``-iv-users``: Induction Variable Users
+---------------------------------------
+
+Bookkeeping for "interesting" users of expressions computed from induction
+variables.
+
+``-lazy-value-info``: Lazy Value Information Analysis
+-----------------------------------------------------
+
+Interface for lazy computation of value constraint information.
+
+``-libcall-aa``: LibCall Alias Analysis
+---------------------------------------
+
+LibCall Alias Analysis.
+
+``-lint``: Statically lint-checks LLVM IR
+-----------------------------------------
+
+This pass statically checks for common and easily-identified constructs which
+produce undefined or likely unintended behavior in LLVM IR.
+
+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.
+
+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.
+
+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.
+
+This code may be run before :ref:`instcombine <passes-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.
+
+``-loops``: Natural Loop Information
+------------------------------------
+
+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.
+
+``-memdep``: Memory Dependence Analysis
+---------------------------------------
+
+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.
+
+``-module-debuginfo``: Decodes module-level debug info
+------------------------------------------------------
+
+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.
+
+``-no-aa``: No Alias Analysis (always returns 'may' alias)
+----------------------------------------------------------
+
+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.
+
+``-postdomfrontier``: Post-Dominance Frontier Construction
+----------------------------------------------------------
+
+This pass is a simple post-dominator construction algorithm for finding
+post-dominator frontiers.
+
+``-postdomtree``: Post-Dominator Tree Construction
+--------------------------------------------------
+
+This pass is a simple post-dominator construction algorithm for finding
+post-dominators.
+
+``-print-alias-sets``: Alias Set Printer
+----------------------------------------
+
+Yet to be written.
+
+``-print-callgraph``: Print a call graph
+----------------------------------------
+
+This pass, only available in ``opt``, prints the call graph to standard error
+in a human-readable form.
+
+``-print-callgraph-sccs``: Print SCCs of the Call Graph
+-------------------------------------------------------
+
+This pass, only available in ``opt``, prints the SCCs of the call graph to
+standard error in a human-readable form.
+
+``-print-cfg-sccs``: Print SCCs of each function CFG
+----------------------------------------------------
+
+This pass, only available in ``opt``, printsthe SCCs of each function CFG to
+standard error in a human-readable fom.
+
+``-print-dom-info``: Dominator Info Printer
+-------------------------------------------
+
+Dominator Info Printer.
+
+``-print-externalfnconstants``: Print external fn callsites passed constants
+----------------------------------------------------------------------------
+
+This pass, only available in ``opt``, 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.
+
+``-print-function``: Print function to stderr
+---------------------------------------------
+
+The ``PrintFunctionPass`` class is designed to be pipelined with other
+``FunctionPasses``, and prints out the functions of the module as they are
+processed.
+
+``-print-module``: Print module to stderr
+-----------------------------------------
+
+This pass simply prints out the entire module when it is executed.
+
+.. _passes-print-used-types:
+
+``-print-used-types``: Find Used Types
+--------------------------------------
+
+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.
+
+``-regions``: Detect single entry single exit regions
+-----------------------------------------------------
+
+The ``RegionInfo`` 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.
+
+``-scalar-evolution``: Scalar Evolution Analysis
+------------------------------------------------
+
+The ``ScalarEvolution`` 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 ``SCEV`` class.
+Given this analysis, trip counts of loops and other important properties can be
+obtained.
+
+This analysis is primarily useful for induction variable substitution and
+strength reduction.
+
+``-scev-aa``: ScalarEvolution-based Alias Analysis
+--------------------------------------------------
+
+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.
+
+``-targetdata``: Target Data Layout
+-----------------------------------
+
+Provides other passes access to information on how the size and alignment
+required by the target ABI for various data types.
+
+Transform Passes
+================
+
+This section describes the LLVM Transform Passes.
+
+``-adce``: Aggressive Dead Code Elimination
+-------------------------------------------
+
+ADCE aggressively tries to eliminate code. This pass is similar to :ref:`DCE
+<passes-dce>` but it assumes that values are dead until proven otherwise. This
+is similar to :ref:`SCCP <passes-sccp>`, except applied to the liveness of
+values.
+
+``-always-inline``: Inliner for ``always_inline`` functions
+-----------------------------------------------------------
+
+A custom inliner that handles only functions that are marked as "always
+inline".
+
+``-argpromotion``: Promote 'by reference' arguments to scalars
+--------------------------------------------------------------
+
+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).
+
+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!
+
+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.
+
+``-bb-vectorize``: Basic-Block Vectorization
+--------------------------------------------
+
+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.
+
+``-block-placement``: Profile Guided Basic Block Placement
+----------------------------------------------------------
+
+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.
+
+``-break-crit-edges``: Break critical edges in CFG
+--------------------------------------------------
+
+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.
+
+``-codegenprepare``: Optimize for code generation
+-------------------------------------------------
+
+This pass munges the code in the input function to better prepare it for
+SelectionDAG-based code generation. This works around limitations in its
+basic-block-at-a-time approach. It should eventually be removed.
+
+``-constmerge``: Merge Duplicate Global Constants
+-------------------------------------------------
+
+Merges duplicate global constants together into a single constant that is
+shared. This is useful because some passes (i.e., TraceValues) insert a lot of
+string constants into the program, regardless of whether or not an existing
+string is available.
+
+``-constprop``: Simple constant propagation
+-------------------------------------------
+
+This pass 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:
+
+.. code-block:: llvm
+
+ add i32 1, 2
+
+becomes
+
+.. code-block:: llvm
+
+ i32 3
+
+NOTE: this pass has a habit of making definitions be dead. It is a good idea
+to run a :ref:`Dead Instruction Elimination <passes-die>` pass sometime after
+running this pass.
+
+.. _passes-dce:
+
+``-dce``: Dead Code Elimination
+-------------------------------
+
+Dead code elimination is similar to :ref:`dead instruction elimination
+<passes-die>`, but it rechecks instructions that were used by removed
+instructions to see if they are newly dead.
+
+``-deadargelim``: Dead Argument Elimination
+-------------------------------------------
+
+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.
+
+This pass is often useful as a cleanup pass to run after aggressive
+interprocedural passes, which add possibly-dead arguments.
+
+``-deadtypeelim``: Dead Type Elimination
+----------------------------------------
+
+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 :ref:`find used types
+<passes-print-used-types>` pass.
+
+.. _passes-die:
+
+``-die``: Dead Instruction Elimination
+--------------------------------------
+
+Dead instruction elimination performs a single pass over the function, removing
+instructions that are obviously dead.
+
+``-dse``: Dead Store Elimination
+--------------------------------
+
+A trivial dead store elimination that only considers basic-block local
+redundant stores.
+
+.. _passes-functionattrs:
+
+``-functionattrs``: Deduce function attributes
+----------------------------------------------
+
+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.
+
+``-globaldce``: Dead Global Elimination
+---------------------------------------
+
+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.
+
+``-globalopt``: Global Variable Optimizer
+-----------------------------------------
+
+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.
+
+``-gvn``: Global Value Numbering
+--------------------------------
+
+This pass performs global value numbering to eliminate fully and partially
+redundant instructions. It also performs redundant load elimination.
+
+.. _passes-indvars:
+
+``-indvars``: Canonicalize Induction Variables
+----------------------------------------------
+
+This transformation analyzes and transforms the induction variables (and
+computations derived from them) into simpler forms suitable for subsequent
+analysis and transformation.
+
+This transformation makes the following changes to each loop with an
+identifiable induction variable:
+
+* All loops are transformed to have a *single* canonical induction variable
+ which starts at zero and steps by one.
+* The canonical induction variable is guaranteed to be the first PHI node in
+ the loop header block.
+* Any pointer arithmetic recurrences are raised to use array subscripts.
+
+If the trip count of a loop is computable, this pass also makes the following
+changes:
+
+* The exit condition for the loop is canonicalized to compare the induction
+ value against the exit value. This turns loops like:
+
+ .. code-block:: c++
+
+ for (i = 7; i*i < 1000; ++i)
+
+ into
+
+ .. code-block:: c++
+
+ for (i = 0; i != 25; ++i)
+
+* 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.
+
+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).
+
+``-inline``: Function Integration/Inlining
+------------------------------------------
+
+Bottom-up inlining of functions into callees.
+
+.. _passes-instcombine:
+
+``-instcombine``: Combine redundant instructions
+------------------------------------------------
+
+Combine instructions to form fewer, simple instructions. This pass does not
+modify the CFG. This pass is where algebraic simplification happens.
+
+This pass combines things like:
+
+.. code-block:: llvm
+
+ %Y = add i32 %X, 1
+ %Z = add i32 %Y, 1
+
+into:
+
+.. code-block:: llvm
+
+ %Z = add i32 %X, 2
+
+This is a simple worklist driven algorithm.
+
+This pass guarantees that the following canonicalizations are performed on the
+program:
+
+#. If a binary operator has a constant operand, it is moved to the right-hand
+ side.
+#. Bitwise operators with constant operands are always grouped so that shifts
+ are performed first, then ``or``\ s, then ``and``\ s, then ``xor``\ s.
+#. Compare instructions are converted from ``<``, ``>``, ``â¤``, or ``â¥`` to
+ ``=`` or ``â `` if possible.
+#. All ``cmp`` instructions on boolean values are replaced with logical
+ operations.
+#. ``add X, X`` is represented as ``mul X, 2`` â ``shl X, 1``
+#. Multiplies with a constant power-of-two argument are transformed into
+ shifts.
+#. ⦠etc.
+
+This pass can also simplify calls to specific well-known function calls (e.g.
+runtime library functions). For example, a call ``exit(3)`` that occurs within
+the ``main()`` function can be transformed into simply ``return 3``. Whether or
+not library calls are simplified is controlled by the
+:ref:`-functionattrs <passes-functionattrs>` pass and LLVM's knowledge of
+library calls on different targets.
+
+``-internalize``: Internalize Global Symbols
+--------------------------------------------
+
+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.
+
+``-ipconstprop``: Interprocedural constant propagation
+------------------------------------------------------
+
+This pass implements an *extremely* 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.
+
+``-ipsccp``: Interprocedural Sparse Conditional Constant Propagation
+--------------------------------------------------------------------
+
+An interprocedural variant of :ref:`Sparse Conditional Constant Propagation
+<passes-sccp>`.
+
+``-jump-threading``: Jump Threading
+-----------------------------------
+
+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.
+
+An example of when this can occur is code like this:
+
+.. code-block:: c++
+
+ if () { ...
+ X = 4;
+ }
+ if (X < 3) {
+
+In this case, the unconditional branch at the end of the first if can be
+revectored to the false side of the second if.
+
+``-lcssa``: Loop-Closed SSA Form Pass
+-------------------------------------
+
+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:
+
+.. code-block:: c++
+
+ 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
+
+This is still valid LLVM; the extra phi nodes are purely redundant, and will be
+trivially eliminated by ``InstCombine``. The major benefit of this
+transformation is that it makes many other loop optimizations, such as
+``LoopUnswitch``\ ing, simpler.
+
+.. _passes-licm:
+
+``-licm``: Loop Invariant Code Motion
+-------------------------------------
+
+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.
+
+This pass uses alias analysis for two purposes:
+
+#. 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.
+
+#. 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:
+
+ #. The pointer stored through is loop invariant.
+ #. There are no stores or loads in the loop which *may* alias the pointer.
+ There are no calls in the loop which mod/ref the pointer.
+
+ 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
+ :ref:`mem2reg <passes-mem2reg>` functionality to construct the appropriate
+ SSA form for the variable.
+
+``-loop-deletion``: Delete dead loops
+-------------------------------------
+
+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.
+
+.. _passes-loop-extract:
+
+``-loop-extract``: Extract loops into new functions
+---------------------------------------------------
+
+A pass wrapper around the ``ExtractLoop()`` scalar transformation to extract
+each top-level loop into its own new function. If the loop is the *only* loop
+in a given function, it is not touched. This is a pass most useful for
+debugging via bugpoint.
+
+``-loop-extract-single``: Extract at most one loop into a new function
+----------------------------------------------------------------------
+
+Similar to :ref:`Extract loops into new functions <passes-loop-extract>`, this
+pass extracts one natural loop from the program into a function if it can.
+This is used by :program:`bugpoint`.
+
+``-loop-reduce``: Loop Strength Reduction
+-----------------------------------------
+
+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.
+
+``-loop-rotate``: Rotate Loops
+------------------------------
+
+A simple loop rotation transformation.
+
+``-loop-simplify``: Canonicalize natural loops
+----------------------------------------------
+
+This pass performs several transformations to transform natural loops into a
+simpler form, which makes subsequent analyses and transformations simpler and
+more effective.
+
+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 :ref:`LICM <passes-licm>`.
+
+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.
+
+This pass also guarantees that loops will have exactly one backedge.
+
+Note that the :ref:`simplifycfg <passes-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.
+
+This pass obviously modifies the CFG, but updates loop information and
+dominator information.
+
+``-loop-unroll``: Unroll loops
+------------------------------
+
+This pass implements a simple loop unroller. It works best when loops have
+been canonicalized by the :ref:`indvars <passes-indvars>` pass, allowing it to
+determine the trip counts of loops easily.
+
+``-loop-unswitch``: Unswitch loops
+----------------------------------
+
+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:
+
+.. code-block:: c++
+
+ for (...) if (lic)
+ A for (...)
+ if (lic) A; B; C
+ B else
+ C for (...)
+ A; C
+
+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.
+
+This pass expects :ref:`LICM <passes-licm>` to be run before it to hoist
+invariant conditions out of the loop, to make the unswitching opportunity
+obvious.
+
+``-loweratomic``: Lower atomic intrinsics to non-atomic form
+------------------------------------------------------------
+
+This pass lowers atomic intrinsics to non-atomic form for use in a known
+non-preemptible environment.
+
+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.
+
+``-lowerinvoke``: Lower invokes to calls, for unwindless code generators
+------------------------------------------------------------------------
+
+This transformation is designed for use by code generators which do not yet
+support stack unwinding. This pass converts ``invoke`` instructions to
+``call`` instructions, so that any exception-handling ``landingpad`` blocks
+become dead code (which can be removed by running the ``-simplifycfg`` pass
+afterwards).
+
+``-lowerswitch``: Lower ``SwitchInst``\ s to branches
+-----------------------------------------------------
+
+Rewrites switch instructions with a sequence of branches, which allows targets
+to get away with not implementing the switch instruction until it is
+convenient.
+
+.. _passes-mem2reg:
+
+``-mem2reg``: Promote Memory to Register
+----------------------------------------
+
+This file promotes memory references to be register references. It promotes
+alloca instructions which only have loads and stores as uses. An ``alloca`` is
+transformed by using dominator frontiers to place phi nodes, then traversing
+the function in depth-first order to rewrite loads and stores as appropriate.
+This is just the standard SSA construction algorithm to construct "pruned" SSA
+form.
+
+``-memcpyopt``: MemCpy Optimization
+-----------------------------------
+
+This pass performs various transformations related to eliminating ``memcpy``
+calls, or transforming sets of stores into ``memset``\ s.
+
+``-mergefunc``: Merge Functions
+-------------------------------
+
+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.
+
+``-mergereturn``: Unify function exit nodes
+-------------------------------------------
+
+Ensure that functions have at most one ``ret`` instruction in them.
+Additionally, it keeps track of which node is the new exit node of the CFG.
+
+``-partial-inliner``: Partial Inliner
+-------------------------------------
+
+This pass performs partial inlining, typically by inlining an ``if`` statement
+that surrounds the body of the function.
+
+``-prune-eh``: Remove unused exception handling info
+----------------------------------------------------
+
+This file implements a simple interprocedural pass which walks the call-graph,
+turning invoke instructions into call instructions if and only if the callee
+cannot throw an exception. It implements this as a bottom-up traversal of the
+call-graph.
+
+``-reassociate``: Reassociate expressions
+-----------------------------------------
+
+This pass reassociates commutative expressions in an order that is designed to
+promote better constant propagation, GCSE, :ref:`LICM <passes-licm>`, PRE, etc.
+
+For example: 4 + (x + 5) â x + (4 + 5)
+
+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.
+
+``-reg2mem``: Demote all values to stack slots
+----------------------------------------------
+
+This file demotes all registers to memory references. It is intended to be the
+inverse of :ref:`mem2reg <passes-mem2reg>`. By converting to ``load``
+instructions, the only values live across basic blocks are ``alloca``
+instructions and ``load`` instructions before ``phi`` 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 ``alloca``
+instructions (and nothing else) are in the entry block.
+
+``-scalarrepl``: Scalar Replacement of Aggregates (DT)
+------------------------------------------------------
+
+The well-known scalar replacement of aggregates transformation. This transform
+breaks up ``alloca`` instructions of aggregate type (structure or array) into
+individual ``alloca`` instructions for each member if possible. Then, if
+possible, it transforms the individual ``alloca`` instructions into nice clean
+scalar SSA form.
+
+This combines a simple scalar replacement of aggregates algorithm with the
+:ref:`mem2reg <passes-mem2reg>` algorithm because they often interact,
+especially for C++ programs. As such, iterating between ``scalarrepl``, then
+:ref:`mem2reg <passes-mem2reg>` until we run out of things to promote works
+well.
+
+.. _passes-sccp:
+
+``-sccp``: Sparse Conditional Constant Propagation
+--------------------------------------------------
+
+Sparse conditional constant propagation and merging, which can be summarized
+as:
+
+* Assumes values are constant unless proven otherwise
+* Assumes BasicBlocks are dead unless proven otherwise
+* Proves values to be constant, and replaces them with constants
+* Proves conditional branches to be unconditional
+
+Note that this pass has a habit of making definitions be dead. It is a good
+idea to run a :ref:`DCE <passes-dce>` pass sometime after running this pass.
+
+.. _passes-simplifycfg:
+
+``-simplifycfg``: Simplify the CFG
+----------------------------------
+
+Performs dead code elimination and basic block merging. Specifically:
+
+* Removes basic blocks with no predecessors.
+* Merges a basic block into its predecessor if there is only one and the
+ predecessor only has one successor.
+* Eliminates PHI nodes for basic blocks with a single predecessor.
+* Eliminates a basic block that only contains an unconditional branch.
+
+``-sink``: Code sinking
+-----------------------
+
+This pass moves instructions into successor blocks, when possible, so that they
+aren't executed on paths where their results aren't needed.
+
+``-strip``: Strip all symbols from a module
+-------------------------------------------
+
+Performs code stripping. This transformation can delete:
+
+* names for virtual registers
+* symbols for internal globals and functions
+* debug information
+
+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.
+
+``-strip-dead-debug-info``: Strip debug info for unused symbols
+---------------------------------------------------------------
+
+.. FIXME: this description is the same as for -strip
+
+performs code stripping. this transformation can delete:
+
+* names for virtual registers
+* symbols for internal globals and functions
+* debug information
+
+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.
+
+``-strip-dead-prototypes``: Strip Unused Function Prototypes
+------------------------------------------------------------
+
+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).
+
+``-strip-debug-declare``: Strip all ``llvm.dbg.declare`` intrinsics
+-------------------------------------------------------------------
+
+.. FIXME: this description is the same as for -strip
+
+This pass implements code stripping. Specifically, it can delete:
+
+#. names for virtual registers
+#. symbols for internal globals and functions
+#. debug information
+
+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.
+
+``-strip-nondebug``: Strip all symbols, except dbg symbols, from a module
+-------------------------------------------------------------------------
+
+.. FIXME: this description is the same as for -strip
+
+This pass implements code stripping. Specifically, it can delete:
+
+#. names for virtual registers
+#. symbols for internal globals and functions
+#. debug information
+
+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.
+
+``-tailcallelim``: Tail Call Elimination
+----------------------------------------
+
+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:
+
+#. 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).
+#. 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 fib implementation into efficient code.
+#. 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 *all other* return instructions in the function return the
+ exact same value.
+#. 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).
+
+Utility Passes
+==============
+
+This section describes the LLVM Utility Passes.
+
+``-deadarghaX0r``: Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)
+------------------------------------------------------------------------
+
+Same as dead argument elimination, but deletes arguments to functions which are
+external. This is only for use by :doc:`bugpoint <Bugpoint>`.
+
+``-extract-blocks``: Extract Basic Blocks From Module (for bugpoint use)
+------------------------------------------------------------------------
+
+This pass is used by bugpoint to extract all blocks from the module into their
+own functions.
+
+``-instnamer``: Assign names to anonymous instructions
+------------------------------------------------------
+
+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.
+
+``-preverify``: Preliminary module verification
+-----------------------------------------------
+
+Ensures that the module is in the form required by the :ref:`Module Verifier
+<passes-verify>` pass. Running the verifier runs this pass automatically, so
+there should be no need to use it directly.
+
+.. _passes-verify:
+
+``-verify``: Module Verifier
+----------------------------
+
+Verifies an LLVM IR code. This is useful to run after an optimization which is
+undergoing testing. Note that llvm-as 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.
+
+#. Both of a binary operator's parameters are of the same type.
+#. Verify that the indices of mem access instructions match other operands.
+#. Verify that arithmetic and other things are only performed on first-class
+ types. Verify that shifts and logicals only happen on integrals f.e.
+#. All of the constants in a switch statement are of the correct type.
+#. The code is in valid SSA form.
+#. It is illegal to put a label into any other type (like a structure) or to
+ return one.
+#. Only phi nodes can be self referential: ``%x = add i32 %x``, ``%x`` is
+ invalid.
+#. PHI nodes must have an entry for each predecessor, with no extras.
+#. PHI nodes must be the first thing in a basic block, all grouped together.
+#. PHI nodes must have at least one entry.
+#. All basic blocks should only end with terminator insts, not contain them.
+#. The entry node to a function must not have predecessors.
+#. All Instructions must be embedded into a basic block.
+#. Functions cannot take a void-typed parameter.
+#. Verify that a function's argument list agrees with its declared type.
+#. It is illegal to specify a name for a void value.
+#. It is illegal to have an internal global value with no initializer.
+#. It is illegal to have a ``ret`` instruction that returns a value that does
+ not agree with the function return value type.
+#. Function call argument types match the function prototype.
+#. All other things that are tested by asserts spread about the code.
+
+Note that this does not provide full security verification (like Java), but
+instead just tries to ensure that code is well-formed.
+
+``-view-cfg``: View CFG of function
+-----------------------------------
+
+Displays the control flow graph using the GraphViz tool.
+
+``-view-cfg-only``: View CFG of function (with no function bodies)
+------------------------------------------------------------------
+
+Displays the control flow graph using the GraphViz tool, but omitting function
+bodies.
+
+``-view-dom``: View dominance tree of function
+----------------------------------------------
+
+Displays the dominator tree using the GraphViz tool.
+
+``-view-dom-only``: View dominance tree of function (with no function bodies)
+-----------------------------------------------------------------------------
+
+Displays the dominator tree using the GraphViz tool, but omitting function
+bodies.
+
+``-view-postdom``: View postdominance tree of function
+------------------------------------------------------
+
+Displays the post dominator tree using the GraphViz tool.
+
+``-view-postdom-only``: View postdominance tree of function (with no function bodies)
+-------------------------------------------------------------------------------------
+
+Displays the post dominator tree using the GraphViz tool, but omitting function
+bodies.
+
Added: www-releases/trunk/3.5.1/docs/_sources/Phabricator.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/Phabricator.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/Phabricator.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/Phabricator.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,139 @@
+=============================
+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`_ instance.
+
+While Phabricator is a useful tool for some, the relevant -commits mailing list
+is the system of record for all LLVM code review. The mailing list should be
+added as a subscriber on all reviews, and Phabricator users should be prepared
+to respond to free-form comments in mail sent to the commits list.
+
+Sign up
+-------
+
+To get started with Phabricator, navigate to `http://reviews.llvm.org`_ and
+click the power icon in the top right. You can register with a GitHub account,
+a Google account, or you can create your own profile.
+
+Make *sure* that the email address registered with Phabricator is subscribed
+to the relevant -commits mailing list. If your are not subscribed to the commit
+list, all mail sent by Phabricator on your behalf will be held for moderation.
+
+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 Diff*.
+* 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 Diff*.
+* 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.
+
+Note that as e-mail is the system of reference for code reviews, and some
+people prefer it over a web interface, we do not generate automated mail
+when a review changes state, for example by clicking "Accept Revision" in
+the web interface. Thus, please type LGTM into the comment box to accept
+a change from Phabricator.
+
+Committing a change
+-------------------
+
+Arcanist can manage the commit transparently. It will retrieve the description,
+reviewers, the ``Differential Revision``, etc from the review and commit it to the repository.
+
+::
+
+ arc patch D<Revision>
+ arc commit --revision D<Revision>
+
+
+When committing an LLVM change that has been reviewed using
+Phabricator, the convention is for the commit message to end with the
+line:
+
+::
+
+ Differential Revision: <URL>
+
+where ``<URL>`` is the URL for the code review, starting with
+``http://reviews.llvm.org/``.
+
+Note that Arcanist will add this automatically.
+
+This allows people reading the version history to see the review for
+context. This also allows Phabricator to detect the commit, close the
+review, and add a link from the review to the commit.
+
+Status
+------
+
+Please let us know whether you like it and what could be improved!
+
+.. _LLVM's Phabricator: http://reviews.llvm.org
+.. _`http://reviews.llvm.org`: http://reviews.llvm.org
+.. _Code Repository Browser: http://reviews.llvm.org/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.5.1/docs/_sources/ProgrammersManual.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/ProgrammersManual.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/ProgrammersManual.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/ProgrammersManual.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,3265 @@
+========================
+LLVM Programmer's Manual
+========================
+
+.. contents::
+ :local:
+
+.. warning::
+ This is always a work in progress.
+
+.. _introduction:
+
+Introduction
+============
+
+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.
+
+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 `doxygen
+<http://llvm.org/doxygen/>`__ sources are provided to make this as easy as
+possible.
+
+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 ``InstVisitor`` (`doxygen
+<http://llvm.org/doxygen/InstVisitor_8h-source.html>`__) template.
+
+.. _general:
+
+General Information
+===================
+
+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.
+
+.. _stl:
+
+The C++ Standard Template Library
+---------------------------------
+
+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.
+
+Here are some useful links:
+
+#. `cppreference.com
+ <http://en.cppreference.com/w/>`_ - an excellent
+ reference for the STL and other parts of the standard C++ library.
+
+#. `C++ In a Nutshell <http://www.tempest-sw.com/cpp/>`_ - 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.
+
+#. `C++ Frequently Asked Questions <http://www.parashift.com/c++-faq-lite/>`_.
+
+#. `SGI's STL Programmer's Guide <http://www.sgi.com/tech/stl/>`_ - Contains a
+ useful `Introduction to the STL
+ <http://www.sgi.com/tech/stl/stl_introduction.html>`_.
+
+#. `Bjarne Stroustrup's C++ Page
+ <http://www.research.att.com/%7Ebs/C++.html>`_.
+
+#. `Bruce Eckel's Thinking in C++, 2nd ed. Volume 2 Revision 4.0
+ (even better, get the book)
+ <http://www.mindview.net/Books/TICPP/ThinkingInCPP2e.html>`_.
+
+You are also encouraged to take a look at the :doc:`LLVM Coding Standards
+<CodingStandards>` guide which focuses on how to write maintainable code more
+than where to put your curly braces.
+
+.. _resources:
+
+Other useful references
+-----------------------
+
+#. `Using static and shared libraries across platforms
+ <http://www.fortran-2000.com/ArnaudRecipes/sharedlib.html>`_
+
+.. _apis:
+
+Important and useful LLVM APIs
+==============================
+
+Here we highlight some LLVM APIs that are generally useful and good to know
+about when writing transformations.
+
+.. _isa:
+
+The ``isa<>``, ``cast<>`` and ``dyn_cast<>`` templates
+------------------------------------------------------
+
+The LLVM source-base makes extensive use of a custom form of RTTI. These
+templates have many similarities to the C++ ``dynamic_cast<>`` operator, but
+they don't have some drawbacks (primarily stemming from the fact that
+``dynamic_cast<>`` 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 ``llvm/Support/Casting.h`` (`doxygen
+<http://llvm.org/doxygen/Casting_8h-source.html>`__) file (note that you very
+rarely have to include this file directly).
+
+``isa<>``:
+ The ``isa<>`` operator works exactly like the Java "``instanceof``" 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).
+
+``cast<>``:
+ The ``cast<>`` 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 ``isa<>`` and ``cast<>``
+ template is:
+
+ .. code-block:: c++
+
+ static bool isLoopInvariant(const Value *V, const Loop *L) {
+ if (isa<Constant>(V) || isa<Argument>(V) || isa<GlobalValue>(V))
+ return true;
+
+ // Otherwise, it must be an instruction...
+ return !L->contains(cast<Instruction>(V)->getParent());
+ }
+
+ Note that you should **not** use an ``isa<>`` test followed by a ``cast<>``,
+ for that use the ``dyn_cast<>`` operator.
+
+``dyn_cast<>``:
+ The ``dyn_cast<>`` 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 ``dynamic_cast<>`` operator in C++, and should be used in the same
+ circumstances. Typically, the ``dyn_cast<>`` operator is used in an ``if``
+ statement or some other flow control statement like this:
+
+ .. code-block:: c++
+
+ if (AllocationInst *AI = dyn_cast<AllocationInst>(Val)) {
+ // ...
+ }
+
+ This form of the ``if`` statement effectively combines together a call to
+ ``isa<>`` and a call to ``cast<>`` into one statement, which is very
+ convenient.
+
+ Note that the ``dyn_cast<>`` operator, like C++'s ``dynamic_cast<>`` or Java's
+ ``instanceof`` operator, can be abused. In particular, you should not use big
+ chained ``if/then/else`` 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 ``InstVisitor`` class to dispatch over the instruction
+ type directly.
+
+``cast_or_null<>``:
+ The ``cast_or_null<>`` operator works just like the ``cast<>`` 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.
+
+``dyn_cast_or_null<>``:
+ The ``dyn_cast_or_null<>`` operator works just like the ``dyn_cast<>``
+ 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.
+
+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
+:doc:`How to set up LLVM-style RTTI for your class hierarchy
+<HowToSetUpLLVMStyleRTTI>`
+
+.. _string_apis:
+
+Passing strings (the ``StringRef`` and ``Twine`` classes)
+---------------------------------------------------------
+
+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.
+
+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 ``const
+char *``, and taking a ``const std::string&`` requires clients to perform a heap
+allocation which is usually unnecessary. Instead, many LLVM APIs use a
+``StringRef`` or a ``const Twine&`` for passing strings efficiently.
+
+.. _StringRef:
+
+The ``StringRef`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``StringRef`` data type represents a reference to a constant string (a
+character array and a length) and supports the common operations available on
+``std::string``, but does not require heap allocation.
+
+It can be implicitly constructed using a C style null-terminated string, an
+``std::string``, or explicitly with a character pointer and length. For
+example, the ``StringRef`` find function is declared as:
+
+.. code-block:: c++
+
+ iterator find(StringRef Key);
+
+and clients can call it using any one of:
+
+.. code-block:: c++
+
+ Map.find("foo"); // Lookup "foo"
+ Map.find(std::string("bar")); // Lookup "bar"
+ Map.find(StringRef("\0baz", 4)); // Lookup "\0baz"
+
+Similarly, APIs which need to return a string may return a ``StringRef``
+instance, which can be used directly or converted to an ``std::string`` using
+the ``str`` member function. See ``llvm/ADT/StringRef.h`` (`doxygen
+<http://llvm.org/doxygen/classllvm_1_1StringRef_8h-source.html>`__) for more
+information.
+
+You should rarely use the ``StringRef`` 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.
+
+The ``Twine`` class
+^^^^^^^^^^^^^^^^^^^
+
+The ``Twine`` (`doxygen <http://llvm.org/doxygen/classllvm_1_1Twine.html>`__)
+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:
+
+.. code-block:: c++
+
+ New = CmpInst::Create(..., SO->getName() + ".cmp");
+
+The ``Twine`` class is effectively a lightweight `rope
+<http://en.wikipedia.org/wiki/Rope_(computer_science)>`_ 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
+``std::string``, or a ``StringRef``). 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 ``llvm/ADT/Twine.h`` (`doxygen
+<http://llvm.org/doxygen/Twine_8h_source.html>`__) and :ref:`here <dss_twine>`
+for more information.
+
+As with a ``StringRef``, ``Twine`` 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.
+
+.. _function_apis:
+
+Passing functions and other callable objects
+--------------------------------------------
+
+Sometimes you may want a function to be passed a callback object. In order to
+support lambda expressions and other function objects, you should not use the
+traditional C approach of taking a function pointer and an opaque cookie:
+
+.. code-block:: c++
+
+ void takeCallback(bool (*Callback)(Function *, void *), void *Cookie);
+
+Instead, use one of the following approaches:
+
+Function template
+^^^^^^^^^^^^^^^^^
+
+If you don't mind putting the definition of your function into a header file,
+make it a function template that is templated on the callable type.
+
+.. code-block:: c++
+
+ template<typename Callable>
+ void takeCallback(Callable Callback) {
+ Callback(1, 2, 3);
+ }
+
+The ``function_ref`` class template
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``function_ref``
+(`doxygen <http://llvm.org/doxygen/classllvm_1_1function_ref.html>`__) class
+template represents a reference to a callable object, templated over the type
+of the callable. This is a good choice for passing a callback to a function,
+if you don't need to hold onto the callback after the function returns. In this
+way, ``function_ref`` is to ``std::function`` as ``StringRef`` is to
+``std::string``.
+
+``function_ref<Ret(Param1, Param2, ...)>`` can be implicitly constructed from
+any callable object that can be called with arguments of type ``Param1``,
+``Param2``, ..., and returns a value that can be converted to type ``Ret``.
+For example:
+
+.. code-block:: c++
+
+ void visitBasicBlocks(Function *F, function_ref<bool (BasicBlock*)> Callback) {
+ for (BasicBlock &BB : *F)
+ if (Callback(&BB))
+ return;
+ }
+
+can be called using:
+
+.. code-block:: c++
+
+ visitBasicBlocks(F, [&](BasicBlock *BB) {
+ if (process(BB))
+ return isEmpty(BB);
+ return false;
+ });
+
+Note that a ``function_ref`` object contains pointers to external memory, so it
+is not generally safe to store an instance of the class (unless you know that
+the external storage will not be freed). If you need this ability, consider
+using ``std::function``. ``function_ref`` is small enough that it should always
+be passed by value.
+
+.. _DEBUG:
+
+The ``DEBUG()`` macro and ``-debug`` option
+-------------------------------------------
+
+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).
+
+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.
+
+The ``llvm/Support/Debug.h`` (`doxygen
+<http://llvm.org/doxygen/Debug_8h-source.html>`__) file provides a macro named
+``DEBUG()`` that is a much nicer solution to this problem. Basically, you can
+put arbitrary code into the argument of the ``DEBUG`` macro, and it is only
+executed if '``opt``' (or any other tool) is run with the '``-debug``' command
+line argument:
+
+.. code-block:: c++
+
+ DEBUG(errs() << "I am here!\n");
+
+Then you can run your pass like this:
+
+.. code-block:: none
+
+ $ opt < a.bc > /dev/null -mypass
+ <no output>
+ $ opt < a.bc > /dev/null -mypass -debug
+ I am here!
+
+Using the ``DEBUG()`` 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 ``DEBUG()`` 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!).
+
+One additional nice thing about the ``DEBUG()`` macro is that you can enable or
+disable it directly in gdb. Just use "``set DebugFlag=0``" or "``set
+DebugFlag=1``" from the gdb if the program is running. If the program hasn't
+been started yet, you can always just run it with ``-debug``.
+
+.. _DEBUG_TYPE:
+
+Fine grained debug info with ``DEBUG_TYPE`` and the ``-debug-only`` option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes you may find yourself in a situation where enabling ``-debug`` just
+turns on **too much** information (such as when working on the code generator).
+If you want to enable debug information with more fine-grained control, you
+can define the ``DEBUG_TYPE`` macro and use the ``-debug-only`` option as
+follows:
+
+.. code-block:: c++
+
+ #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");
+
+Then you can run your pass like this:
+
+.. code-block:: none
+
+ $ opt < a.bc > /dev/null -mypass
+ <no output>
+ $ 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
+
+Of course, in practice, you should only set ``DEBUG_TYPE`` at the top of a file,
+to specify the debug type for the entire module (if you do this before you
+``#include "llvm/Support/Debug.h"``, you don't have to insert the ugly
+``#undef``'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 ``-debug-type=InstrSched``, even if
+the source lives in multiple files.
+
+The ``DEBUG_WITH_TYPE`` macro is also available for situations where you would
+like to set ``DEBUG_TYPE``, but only for one specific ``DEBUG`` statement. It
+takes an additional first parameter, which is the type to use. For example, the
+preceding example could be written as:
+
+.. code-block:: c++
+
+ 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");
+
+.. _Statistic:
+
+The ``Statistic`` class & ``-stats`` option
+-------------------------------------------
+
+The ``llvm/ADT/Statistic.h`` (`doxygen
+<http://llvm.org/doxygen/Statistic_8h-source.html>`__) file provides a class
+named ``Statistic`` 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.
+
+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 ``Statistic`` 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.
+
+There are many examples of ``Statistic`` uses, but the basics of using it are as
+follows:
+
+#. Define your statistic like this:
+
+ .. code-block:: c++
+
+ #define DEBUG_TYPE "mypassname" // This goes before any #includes.
+ STATISTIC(NumXForms, "The # of times I did stuff");
+
+ The ``STATISTIC`` 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.
+
+#. Whenever you make a transformation, bump the counter:
+
+ .. code-block:: c++
+
+ ++NumXForms; // I did stuff!
+
+That's all you have to do. To get '``opt``' to print out the statistics
+gathered, use the '``-stats``' option:
+
+.. code-block:: none
+
+ $ opt -stats -mypassname < program.bc > /dev/null
+ ... statistics output ...
+
+When running ``opt`` on a C file from the SPEC benchmark suite, it gives a
+report that looks like this:
+
+.. code-block:: none
+
+ 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
+
+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.
+
+.. _ViewGraph:
+
+Viewing graphs while debugging code
+-----------------------------------
+
+Several of the important data structures in LLVM are graphs: for example CFGs
+made out of LLVM :ref:`BasicBlocks <BasicBlock>`, CFGs made out of LLVM
+:ref:`MachineBasicBlocks <MachineBasicBlock>`, and :ref:`Instruction Selection
+DAGs <SelectionDAG>`. In many cases, while debugging various parts of the
+compiler, it is nice to instantly visualize these graphs.
+
+LLVM provides several callbacks that are available in a debug build to do
+exactly that. If you call the ``Function::viewCFG()`` 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 ``Function::viewCFGOnly()`` (does
+not include the instructions), the ``MachineFunction::viewCFG()`` and
+``MachineFunction::viewCFGOnly()``, and the ``SelectionDAG::viewGraph()``
+methods. Within GDB, for example, you can usually use something like ``call
+DAG.viewGraph()`` to pop up a window. Alternatively, you can sprinkle calls to
+these functions in your code in places you want to debug.
+
+Getting this to work requires a small amount of setup. On Unix systems
+with X11, install the `graphviz <http://www.graphviz.org>`_ 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 `Graphviz program
+<http://www.pixelglow.com/graphviz/>`_ and add
+``/Applications/Graphviz.app/Contents/MacOS/`` (or wherever you install it) to
+your path. The programs need not be present when configuring, building or
+running LLVM and can simply be installed when needed during an active debug
+session.
+
+``SelectionDAG`` has been extended to make it easier to locate *interesting*
+nodes in large complex graphs. From gdb, if you ``call DAG.setGraphColor(node,
+"color")``, then the next ``call DAG.viewGraph()`` would highlight the node in
+the specified color (choices of colors can be found at `colors
+<http://www.graphviz.org/doc/info/colors.html>`_.) More complex node attributes
+can be provided with ``call DAG.setGraphAttrs(node, "attributes")`` (choices can
+be found at `Graph attributes <http://www.graphviz.org/doc/info/attrs.html>`_.)
+If you want to restart and clear all the current graph attributes, then you can
+``call DAG.clearGraphAttrs()``.
+
+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.
+
+.. _datastructure:
+
+Picking the Right Data Structure for a Task
+===========================================
+
+LLVM has a plethora of data structures in the ``llvm/ADT/`` directory, and we
+commonly use STL data structures. This section describes the trade-offs you
+should consider when you pick one.
+
+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:
+
+
+* a :ref:`map-like <ds_map>` container if you need efficient look-up of a
+ 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.
+
+* a :ref:`set-like <ds_set>` 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.
+
+* a :ref:`sequential <ds_sequential>` 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.
+
+* a :ref:`string <ds_string>` container is a specialized sequential container or
+ reference structure that is used for character or byte arrays.
+
+* a :ref:`bit <ds_bit>` 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.
+
+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
+:ref:`SmallVector <dss_smallvector>` than :ref:`vector <dss_vector>`. Doing so
+avoids (relatively) expensive malloc/free calls, which dwarf the cost of adding
+the elements to the container.
+
+.. _ds_sequential:
+
+Sequential Containers (std::vector, std::list, etc)
+---------------------------------------------------
+
+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.
+
+.. _dss_arrayref:
+
+llvm/ADT/ArrayRef.h
+^^^^^^^^^^^^^^^^^^^
+
+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.
+
+.. _dss_fixedarrays:
+
+Fixed Size Arrays
+^^^^^^^^^^^^^^^^^
+
+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.
+
+.. _dss_heaparrays:
+
+Heap Allocated Arrays
+^^^^^^^^^^^^^^^^^^^^^
+
+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 :ref:`SmallVector <dss_smallvector>`). 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).
+
+.. _dss_tinyptrvector:
+
+llvm/ADT/TinyPtrVector.h
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+``TinyPtrVector<Type>`` 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.
+
+Since this container is highly specialized, it is rarely used.
+
+.. _dss_smallvector:
+
+llvm/ADT/SmallVector.h
+^^^^^^^^^^^^^^^^^^^^^^
+
+``SmallVector<Type, N>`` is a simple class that looks and smells just like
+``vector<Type>``: 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.
+
+The advantage of SmallVector is that it allocates space for some number of
+elements (N) **in the object itself**. 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.
+
+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.
+
+SmallVector also provides a nice portable and efficient replacement for
+``alloca``.
+
+.. note::
+
+ Prefer to use ``SmallVectorImpl<T>`` as a parameter type.
+
+ In APIs that don't care about the "small size" (most?), prefer to use
+ the ``SmallVectorImpl<T>`` class, which is basically just the "vector
+ header" (and methods) without the elements allocated after it. Note that
+ ``SmallVector<T, N>`` inherits from ``SmallVectorImpl<T>`` so the
+ conversion is implicit and costs nothing. E.g.
+
+ .. code-block:: c++
+
+ // BAD: Clients cannot pass e.g. SmallVector<Foo, 4>.
+ hardcodedSmallSize(SmallVector<Foo, 2> &Out);
+ // GOOD: Clients can pass any SmallVector<Foo, N>.
+ allowsAnySmallSize(SmallVectorImpl<Foo> &Out);
+
+ void someFunc() {
+ SmallVector<Foo, 8> Vec;
+ hardcodedSmallSize(Vec); // Error.
+ allowsAnySmallSize(Vec); // Works.
+ }
+
+ Even though it has "``Impl``" in the name, this is so widely used that
+ it really isn't "private to the implementation" anymore. A name like
+ ``SmallVectorHeader`` would be more appropriate.
+
+.. _dss_vector:
+
+<vector>
+^^^^^^^^
+
+``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 :).
+
+One worthwhile note about std::vector: avoid code like this:
+
+.. code-block:: c++
+
+ for ( ... ) {
+ std::vector<foo> V;
+ // make use of V.
+ }
+
+Instead, write this as:
+
+.. code-block:: c++
+
+ std::vector<foo> V;
+ for ( ... ) {
+ // make use of V.
+ V.clear();
+ }
+
+Doing so will save (at least) one heap allocation and free per iteration of the
+loop.
+
+.. _dss_deque:
+
+<deque>
+^^^^^^^
+
+``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.
+
+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.
+
+.. _dss_list:
+
+<list>
+^^^^^^
+
+``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.
+
+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.
+
+.. _dss_ilist:
+
+llvm/ADT/ilist.h
+^^^^^^^^^^^^^^^^
+
+``ilist<T>`` 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.
+
+``ilist`` has the same drawbacks as ``std::list``, and additionally requires an
+``ilist_traits`` 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 ``ilist``\ s are guaranteed to support a constant-time splice
+operation.
+
+These properties are exactly what we want for things like ``Instruction``\ s and
+basic blocks, which is why these are implemented with ``ilist``\ s.
+
+Related classes of interest are explained in the following subsections:
+
+* :ref:`ilist_traits <dss_ilist_traits>`
+
+* :ref:`iplist <dss_iplist>`
+
+* :ref:`llvm/ADT/ilist_node.h <dss_ilist_node>`
+
+* :ref:`Sentinels <dss_ilist_sentinel>`
+
+.. _dss_packedvector:
+
+llvm/ADT/PackedVector.h
+^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+For example:
+
+.. code-block:: c++
+
+ 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'.
+ }
+
+.. _dss_ilist_traits:
+
+ilist_traits
+^^^^^^^^^^^^
+
+``ilist_traits<T>`` is ``ilist<T>``'s customization mechanism. ``iplist<T>``
+(and consequently ``ilist<T>``) publicly derive from this traits class.
+
+.. _dss_iplist:
+
+iplist
+^^^^^^
+
+``iplist<T>`` is ``ilist<T>``'s base and as such supports a slightly narrower
+interface. Notably, inserters from ``T&`` are absent.
+
+``ilist_traits<T>`` is a public base of this class and can be used for a wide
+variety of customizations.
+
+.. _dss_ilist_node:
+
+llvm/ADT/ilist_node.h
+^^^^^^^^^^^^^^^^^^^^^
+
+``ilist_node<T>`` implements a the forward and backward links that are expected
+by the ``ilist<T>`` (and analogous containers) in the default manner.
+
+``ilist_node<T>``\ s are meant to be embedded in the node type ``T``, usually
+``T`` publicly derives from ``ilist_node<T>``.
+
+.. _dss_ilist_sentinel:
+
+Sentinels
+^^^^^^^^^
+
+``ilist``\ 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 ``begin`` and ``end`` iterators, etc. Also, the
+``operator--`` must work correctly on the ``end`` iterator in the case of
+non-empty ``ilist``\ s.
+
+The only sensible solution to this problem is to allocate a so-called *sentinel*
+along with the intrusive list, which serves as the ``end`` iterator, providing
+the back-link to the last element. However conforming to the C++ convention it
+is illegal to ``operator++`` beyond the sentinel and it also must not be
+dereferenced.
+
+These constraints allow for some implementation freedom to the ``ilist`` how to
+allocate and store the sentinel. The corresponding policy is dictated by
+``ilist_traits<T>``. By default a ``T`` gets heap-allocated whenever the need
+for a sentinel arises.
+
+While the default policy is sufficient in most cases, it may break down when
+``T`` does not provide a default constructor. Also, in the case of many
+instances of ``ilist``\ s, the memory overhead of the associated sentinels is
+wasted. To alleviate the situation with numerous and voluminous
+``T``-sentinels, sometimes a trick is employed, leading to *ghostly sentinels*.
+
+Ghostly sentinels are obtained by specially-crafted ``ilist_traits<T>`` which
+superpose the sentinel with the ``ilist`` instance in memory. Pointer
+arithmetic is used to obtain the sentinel, which is relative to the ``ilist``'s
+``this`` pointer. The ``ilist`` 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.
+
+.. _dss_other:
+
+Other Sequential Container options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Other STL containers are available, such as ``std::string``.
+
+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.
+
+.. _ds_string:
+
+String-like containers
+----------------------
+
+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.
+
+Note that is is generally preferred to *not* pass strings around as ``const
+char*``'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 '``const char*``' is
+StringRef.
+
+For more information on choosing string containers for APIs, please see
+:ref:`Passing Strings <string_apis>`.
+
+.. _dss_stringref:
+
+llvm/ADT/StringRef.h
+^^^^^^^^^^^^^^^^^^^^
+
+The StringRef class is a simple value class that contains a pointer to a
+character and a length, and is quite related to the :ref:`ArrayRef
+<dss_arrayref>` 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.
+
+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.
+
+StringRef has a few major limitations which make more powerful string containers
+useful:
+
+#. 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).
+
+#. 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).
+
+#. 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.
+
+#. 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 :ref:`Twine <dss_twine>`
+ class.
+
+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.
+
+.. _dss_twine:
+
+llvm/ADT/Twine.h
+^^^^^^^^^^^^^^^^
+
+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.:
+
+.. code-block:: c++
+
+ void foo(const Twine &T);
+ ...
+ StringRef X = ...
+ unsigned i = ...
+ foo(X + "." + Twine(i));
+
+This example forms a string like "blarg.42" by concatenating the values
+together, and does not form intermediate strings containing "blarg" or "blarg.".
+
+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:
+
+.. code-block:: c++
+
+ void foo(const Twine &T);
+ ...
+ StringRef X = ...
+ unsigned i = ...
+ const Twine &Tmp = X + "." + Twine(i);
+ foo(Tmp);
+
+... 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.
+
+.. _dss_smallstring:
+
+llvm/ADT/SmallString.h
+^^^^^^^^^^^^^^^^^^^^^^
+
+SmallString is a subclass of :ref:`SmallVector <dss_smallvector>` 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.
+
+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.
+
+.. _dss_stdstring:
+
+std::string
+^^^^^^^^^^^
+
+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).
+
+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.
+
+.. _ds_set:
+
+Set-Like Containers (std::set, SmallSet, SetVector, etc)
+--------------------------------------------------------
+
+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.
+
+.. _dss_sortedvectorset:
+
+A sorted 'vector'
+^^^^^^^^^^^^^^^^^
+
+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 :ref:`sequential container <ds_sequential>`.
+
+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 search (e.g.
+``std::lower_bound``; if you want the whole range of elements comparing
+equal, use ``std::equal_range``).
+
+.. _dss_smallset:
+
+llvm/ADT/SmallSet.h
+^^^^^^^^^^^^^^^^^^^
+
+If you have a set-like data structure that is usually small and whose elements
+are reasonably small, a ``SmallSet<Type, N>`` 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, :ref:`SmallPtrSet
+<dss_smallptrset>`.
+
+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.
+
+.. _dss_smallptrset:
+
+llvm/ADT/SmallPtrSet.h
+^^^^^^^^^^^^^^^^^^^^^^
+
+SmallPtrSet has all the advantages of ``SmallSet`` (and a ``SmallSet`` of
+pointers is transparently implemented with a ``SmallPtrSet``), 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.
+
+Note that, unlike ``std::set``, the iterators of ``SmallPtrSet`` are invalidated
+whenever an insertion occurs. Also, the values visited by the iterators are not
+visited in sorted order.
+
+.. _dss_denseset:
+
+llvm/ADT/DenseSet.h
+^^^^^^^^^^^^^^^^^^^
+
+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 :ref:`SmallPtrSet <dss_smallptrset>` for
+pointers). Note that DenseSet has the same requirements for the value type that
+:ref:`DenseMap <dss_densemap>` has.
+
+.. _dss_sparseset:
+
+llvm/ADT/SparseSet.h
+^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+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.
+
+.. _dss_sparsemultiset:
+
+llvm/ADT/SparseMultiSet.h
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+SparseMultiSet adds multiset behavior to SparseSet, while retaining SparseSet's
+desirable attributes. Like SparseSet, it typically 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.
+
+SparseMultiSet is useful for algorithms that need very fast
+clear/find/insert/erase of the entire collection, and iteration over sets of
+elements sharing a key. It is often a more efficient choice than using composite
+data structures (e.g. vector-of-vectors, map-of-vectors). It is not intended for
+building composite data structures.
+
+.. _dss_FoldingSet:
+
+llvm/ADT/FoldingSet.h
+^^^^^^^^^^^^^^^^^^^^^
+
+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 :ref:`SmallVector <dss_smallvector>` as part of its ID
+process.
+
+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.
+
+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.
+
+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.
+
+.. _dss_set:
+
+<set>
+^^^^^
+
+``std::set`` 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.
+
+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.
+
+.. _dss_setvector:
+
+llvm/ADT/SetVector.h
+^^^^^^^^^^^^^^^^^^^^
+
+LLVM's ``SetVector<Type>`` is an adapter class that combines your choice of a
+set-like container along with a :ref:`Sequential Container <ds_sequential>` 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.
+
+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.
+
+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 its "pop_back" method, which is
+faster.
+
+``SetVector`` is an adapter class that defaults to using ``std::vector`` and a
+size 16 ``SmallSet`` for the underlying containers, so it is quite expensive.
+However, ``"llvm/ADT/SetVector.h"`` also provides a ``SmallSetVector`` class,
+which defaults to using a ``SmallVector`` and ``SmallSet`` of a specified size.
+If you use this, and if your sets are dynamically smaller than ``N``, you will
+save a lot of heap traffic.
+
+.. _dss_uniquevector:
+
+llvm/ADT/UniqueVector.h
+^^^^^^^^^^^^^^^^^^^^^^^
+
+UniqueVector is similar to :ref:`SetVector <dss_setvector>` 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.
+
+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.
+
+.. _dss_immutableset:
+
+llvm/ADT/ImmutableSet.h
+^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+There is no method for returning an element of the set, you can only check for
+membership.
+
+.. _dss_otherset:
+
+Other Set-Like Container Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+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.
+
+.. _ds_map:
+
+Map-Like Containers (std::map, DenseMap, etc)
+---------------------------------------------
+
+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. :)
+
+.. _dss_sortedvectormap:
+
+A sorted 'vector'
+^^^^^^^^^^^^^^^^^
+
+If your usage pattern follows a strict insert-then-query approach, you can
+trivially use the same approach as :ref:`sorted vectors for set-like containers
+<dss_sortedvectorset>`. 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.
+
+.. _dss_stringmap:
+
+llvm/ADT/StringMap.h
+^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+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 "``(char*)(&Value+1)``" points to the key string
+for a value.
+
+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).
+
+StringMap also provides query methods that take byte ranges, so it only ever
+copies a string if a value is inserted into the table.
+
+StringMap iteratation order, however, is not guaranteed to be deterministic, so
+any uses which require that should instead use a std::map.
+
+.. _dss_indexmap:
+
+llvm/ADT/IndexedMap.h
+^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+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).
+
+.. _dss_densemap:
+
+llvm/ADT/DenseMap.h
+^^^^^^^^^^^^^^^^^^^
+
+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.
+
+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.
+
+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.
+
+.. _dss_valuemap:
+
+llvm/IR/ValueMap.h
+^^^^^^^^^^^^^^^^^^^
+
+ValueMap is a wrapper around a :ref:`DenseMap <dss_densemap>` 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 ``Config``
+parameter to the ValueMap template.
+
+.. _dss_intervalmap:
+
+llvm/ADT/IntervalMap.h
+^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+The IntervalMap iterators are quite big, so they should not be passed around as
+STL iterators. The heavyweight iterators allow a smaller data structure.
+
+.. _dss_map:
+
+<map>
+^^^^^
+
+std::map has similar characteristics to :ref:`std::set <dss_set>`: 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.
+
+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).
+
+.. _dss_mapvector:
+
+llvm/ADT/MapVector.h
+^^^^^^^^^^^^^^^^^^^^
+
+``MapVector<KeyT,ValueT>`` 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.
+
+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 removing elements takes linear time. If it is
+necessary to remove elements, it's best to remove them in bulk using
+``remove_if()``.
+
+.. _dss_inteqclasses:
+
+llvm/ADT/IntEqClasses.h
+^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+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.
+
+.. _dss_immutablemap:
+
+llvm/ADT/ImmutableMap.h
+^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+.. _dss_othermap:
+
+Other Map-Like Container Options
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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.
+
+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.
+
+.. _ds_bit:
+
+Bit storage containers (BitVector, SparseBitVector)
+---------------------------------------------------
+
+Unlike the other containers, there are only two bit storage containers, and
+choosing when to use each is relatively straightforward.
+
+One additional option is ``std::vector<bool>``: 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.
+
+.. _dss_bitvector:
+
+BitVector
+^^^^^^^^^
+
+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 (i.e. a dense set).
+
+.. _dss_smallbitvector:
+
+SmallBitVector
+^^^^^^^^^^^^^^
+
+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.
+
+At this time, SmallBitVector does not support set operations (and, or, xor), and
+its operator[] does not provide an assignable lvalue.
+
+.. _dss_sparsebitvector:
+
+SparseBitVector
+^^^^^^^^^^^^^^^
+
+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).
+
+.. _common:
+
+Helpful Hints for Common Operations
+===================================
+
+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.
+
+Because this is a "how-to" section, you should also read about the main classes
+that you will be working with. The :ref:`Core LLVM Class Hierarchy Reference
+<coreclasses>` contains details and descriptions of the main classes that you
+should know about.
+
+.. _inspection:
+
+Basic Inspection and Traversal Routines
+---------------------------------------
+
+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 ``XXXbegin()`` function (or
+method) returns an iterator to the start of the sequence, the ``XXXend()``
+function returns an iterator pointing to one past the last valid element of the
+sequence, and there is some ``XXXiterator`` data type that is common between the
+two operations.
+
+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.
+
+.. _iterate_function:
+
+Iterating over the ``BasicBlock`` in a ``Function``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It's quite common to have a ``Function`` instance that you'd like to transform
+in some way; in particular, you'd like to manipulate its ``BasicBlock``\ s. To
+facilitate this, you'll need to iterate over all of the ``BasicBlock``\ s that
+constitute the ``Function``. The following is an example that prints the name
+of a ``BasicBlock`` and the number of ``Instruction``\ s it contains:
+
+.. code-block:: c++
+
+ // func is a pointer to a Function instance
+ for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i)
+ // Print out the name of the basic block if it has one, and then the
+ // number of instructions that it contains
+ errs() << "Basic block (name=" << i->getName() << ") has "
+ << i->size() << " instructions.\n";
+
+Note that i can be used as if it were a pointer for the purposes of invoking
+member functions of the ``Instruction`` class. This is because the indirection
+operator is overloaded for the iterator classes. In the above code, the
+expression ``i->size()`` is exactly equivalent to ``(*i).size()`` just like
+you'd expect.
+
+.. _iterate_basicblock:
+
+Iterating over the ``Instruction`` in a ``BasicBlock``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Just like when dealing with ``BasicBlock``\ s in ``Function``\ s, it's easy to
+iterate over the individual instructions that make up ``BasicBlock``\ s. Here's
+a code snippet that prints out each instruction in a ``BasicBlock``:
+
+.. code-block:: c++
+
+ // blk is a pointer to a BasicBlock instance
+ for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
+ // The next statement works since operator<<(ostream&,...)
+ // is overloaded for Instruction&
+ errs() << *i << "\n";
+
+
+However, this isn't really the best way to print out the contents of a
+``BasicBlock``! 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: ``errs() << *blk << "\n";``.
+
+.. _iterate_insiter:
+
+Iterating over the ``Instruction`` in a ``Function``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you're finding that you commonly iterate over a ``Function``'s
+``BasicBlock``\ s and then that ``BasicBlock``'s ``Instruction``\ s,
+``InstIterator`` should be used instead. You'll need to include
+``llvm/IR/InstIterator.h`` (`doxygen
+<http://llvm.org/doxygen/InstIterator_8h.html>`__) and then instantiate
+``InstIterator``\ 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:
+
+.. code-block:: c++
+
+ #include "llvm/IR/InstIterator.h"
+
+ // F is a pointer to a Function instance
+ for (inst_iterator I = inst_begin(F), E = inst_end(F); I != E; ++I)
+ errs() << *I << "\n";
+
+Easy, isn't it? You can also use ``InstIterator``\ 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 ``Function`` F, all you would need to do is
+something like:
+
+.. code-block:: c++
+
+ 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);
+
+The STL set ``worklist`` would now contain all instructions in the ``Function``
+pointed to by F.
+
+.. _iterate_convert:
+
+Turning an iterator into a class pointer (and vice-versa)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 ``i`` is a
+``BasicBlock::iterator`` and ``j`` is a ``BasicBlock::const_iterator``:
+
+.. code-block:: c++
+
+ Instruction& inst = *i; // Grab reference to instruction reference
+ Instruction* pinst = &*i; // Grab pointer to instruction reference
+ const Instruction& inst = *j;
+
+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 derferencing 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,
+
+.. code-block:: c++
+
+ Instruction *pinst = &*i;
+
+is semantically equivalent to
+
+.. code-block:: c++
+
+ Instruction *pinst = i;
+
+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:
+
+.. code-block:: c++
+
+ void printNextInstruction(Instruction* inst) {
+ BasicBlock::iterator it(inst);
+ ++it; // After this line, it refers to the instruction after *inst
+ if (it != inst->getParent()->end()) errs() << *it << "\n";
+ }
+
+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 ``B`` is a ``BasicBlock``, from compiling:
+
+.. code-block:: c++
+
+ llvm::SmallVector<llvm::Instruction *, 16>(B->begin(), B->end());
+
+Because of this, these implicit conversions may be removed some day, and
+``operator*`` changed to return a pointer instead of a reference.
+
+.. _iterate_complex:
+
+Finding call sites: a slightly more complex example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Say that you're writing a FunctionPass and would like to count all the locations
+in the entire module (that is, across every ``Function``) where a certain
+function (i.e., some ``Function *``) is already in scope. As you'll learn
+later, you may want to use an ``InstVisitor`` 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 ``InstVisitor`` around. In pseudo-code, this is what we
+want to do:
+
+.. code-block:: none
+
+ 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
+
+And the actual code is (remember, because we're writing a ``FunctionPass``, our
+``FunctionPass``-derived class simply has to override the ``runOnFunction``
+method):
+
+.. code-block:: c++
+
+ 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 (CallInst* callInst = dyn_cast<CallInst>(&*i)) {
+ // We know we've encountered a call instruction, so we
+ // need to determine if it's a call to the
+ // function pointed to by m_func or not.
+ if (callInst->getCalledFunction() == targetFunc)
+ ++callCounter;
+ }
+ }
+ }
+ }
+
+ private:
+ unsigned callCounter;
+ };
+
+.. _calls_and_invokes:
+
+Treating calls and invokes the same way
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+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 ``CallInst``\ s and
+``InvokeInst``\ s the same way, even though their most-specific common base
+class is ``Instruction``, which includes lots of less closely-related things.
+For these cases, LLVM provides a handy wrapper class called ``CallSite``
+(`doxygen <http://llvm.org/doxygen/classllvm_1_1CallSite.html>`__) It is
+essentially a wrapper around an ``Instruction`` pointer, with some methods that
+provide functionality common to ``CallInst``\ s and ``InvokeInst``\ s.
+
+This class has "value semantics": it should be passed by value, not by reference
+and it should not be dynamically allocated or deallocated using ``operator new``
+or ``operator delete``. 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.
+
+.. _iterate_chains:
+
+Iterating over def-use & use-def chains
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Frequently, we might have an instance of the ``Value`` class (`doxygen
+<http://llvm.org/doxygen/classllvm_1_1Value.html>`__) and we want to determine
+which ``User`` s use the ``Value``. The list of all ``User``\ s of a particular
+``Value`` is called a *def-use* chain. For example, let's say we have a
+``Function*`` named ``F`` to a particular function ``foo``. Finding all of the
+instructions that *use* ``foo`` is as simple as iterating over the *def-use*
+chain of ``F``:
+
+.. code-block:: c++
+
+ Function *F = ...;
+
+ for (User *U : GV->users()) {
+ if (Instruction *Inst = dyn_cast<Instruction>(U)) {
+ errs() << "F is used in instruction:\n";
+ errs() << *Inst << "\n";
+ }
+
+Alternatively, it's common to have an instance of the ``User`` Class (`doxygen
+<http://llvm.org/doxygen/classllvm_1_1User.html>`__) and need to know what
+``Value``\ s are used by it. The list of all ``Value``\ s used by a ``User`` is
+known as a *use-def* chain. Instances of class ``Instruction`` are common
+``User`` s, so we might want to iterate over all of the values that a particular
+instruction uses (that is, the operands of the particular ``Instruction``):
+
+.. code-block:: c++
+
+ Instruction *pi = ...;
+
+ for (Use &U : pi->operands()) {
+ Value *v = U.get();
+ // ...
+ }
+
+Declaring objects as ``const`` is an important tool of enforcing mutation free
+algorithms (such as analyses, etc.). For this purpose above iterators come in
+constant flavors as ``Value::const_use_iterator`` and
+``Value::const_op_iterator``. They automatically arise when calling
+``use/op_begin()`` on ``const Value*``\ s or ``const User*``\ s respectively.
+Upon dereferencing, they return ``const Use*``\ s. Otherwise the above patterns
+remain unchanged.
+
+.. _iterate_preds:
+
+Iterating over predecessors & successors of blocks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Iterating over the predecessors and successors of a block is quite easy with the
+routines defined in ``"llvm/Support/CFG.h"``. Just use code like this to
+iterate over all predecessors of BB:
+
+.. code-block:: c++
+
+ #include "llvm/Support/CFG.h"
+ BasicBlock *BB = ...;
+
+ for (pred_iterator PI = pred_begin(BB), E = pred_end(BB); PI != E; ++PI) {
+ BasicBlock *Pred = *PI;
+ // ...
+ }
+
+Similarly, to iterate over successors use ``succ_iterator/succ_begin/succ_end``.
+
+.. _simplechanges:
+
+Making simple changes
+---------------------
+
+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.
+
+.. _schanges_creating:
+
+Creating and inserting new ``Instruction``\ s
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*Instantiating Instructions*
+
+Creation of ``Instruction``\ s is straight-forward: simply call the constructor
+for the kind of instruction to instantiate and provide the necessary parameters.
+For example, an ``AllocaInst`` only *requires* a (const-ptr-to) ``Type``. Thus:
+
+.. code-block:: c++
+
+ AllocaInst* ai = new AllocaInst(Type::Int32Ty);
+
+will create an ``AllocaInst`` instance that represents the allocation of one
+integer in the current stack frame, at run time. Each ``Instruction`` subclass
+is likely to have varying default parameters which change the semantics of the
+instruction, so refer to the `doxygen documentation for the subclass of
+Instruction <http://llvm.org/doxygen/classllvm_1_1Instruction.html>`_ that
+you're interested in instantiating.
+
+*Naming values*
+
+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
+``Name`` (default) parameter of the ``Instruction`` 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 ``AllocaInst`` at
+the first point in the first ``BasicBlock`` of some ``Function``, and I'm
+intending to use it within the same ``Function``. I might do:
+
+.. code-block:: c++
+
+ AllocaInst* pa = new AllocaInst(Type::Int32Ty, 0, "indexLoc");
+
+where ``indexLoc`` is now the logical name of the instruction's execution value,
+which is a pointer to an integer on the run time stack.
+
+*Inserting instructions*
+
+There are essentially three ways to insert an ``Instruction`` into an existing
+sequence of instructions that form a ``BasicBlock``:
+
+* Insertion into an explicit instruction list
+
+ Given a ``BasicBlock* pb``, an ``Instruction* pi`` within that ``BasicBlock``,
+ and a newly-created instruction we wish to insert before ``*pi``, we do the
+ following:
+
+ .. code-block:: c++
+
+ BasicBlock *pb = ...;
+ Instruction *pi = ...;
+ Instruction *newInst = new Instruction(...);
+
+ pb->getInstList().insert(pi, newInst); // Inserts newInst before pi in pb
+
+ Appending to the end of a ``BasicBlock`` is so common that the ``Instruction``
+ class and ``Instruction``-derived classes provide constructors which take a
+ pointer to a ``BasicBlock`` to be appended to. For example code that looked
+ like:
+
+ .. code-block:: c++
+
+ BasicBlock *pb = ...;
+ Instruction *newInst = new Instruction(...);
+
+ pb->getInstList().push_back(newInst); // Appends newInst to pb
+
+ becomes:
+
+ .. code-block:: c++
+
+ BasicBlock *pb = ...;
+ Instruction *newInst = new Instruction(..., pb);
+
+ which is much cleaner, especially if you are creating long instruction
+ streams.
+
+* Insertion into an implicit instruction list
+
+ ``Instruction`` instances that are already in ``BasicBlock``\ 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 ``BasicBlock`` by doing:
+
+ .. code-block:: c++
+
+ Instruction *pi = ...;
+ Instruction *newInst = new Instruction(...);
+
+ pi->getParent()->getInstList().insert(pi, newInst);
+
+ In fact, this sequence of steps occurs so frequently that the ``Instruction``
+ class and ``Instruction``-derived classes provide constructors which take (as
+ a default parameter) a pointer to an ``Instruction`` which the newly-created
+ ``Instruction`` should precede. That is, ``Instruction`` constructors are
+ capable of inserting the newly-created instance into the ``BasicBlock`` of a
+ provided instruction, immediately before that instruction. Using an
+ ``Instruction`` constructor with a ``insertBefore`` (default) parameter, the
+ above code becomes:
+
+ .. code-block:: c++
+
+ Instruction* pi = ...;
+ Instruction* newInst = new Instruction(..., pi);
+
+ which is much cleaner, especially if you're creating a lot of instructions and
+ adding them to ``BasicBlock``\ s.
+
+* Insertion using an instance of ``IRBuilder``
+
+ Inserting several ``Instruction``\ s can be quite laborious using the previous
+ methods. The ``IRBuilder`` is a convenience class that can be used to add
+ several instructions to the end of a ``BasicBlock`` or before a particular
+ ``Instruction``. It also supports constant folding and renaming named
+ registers (see ``IRBuilder``'s template arguments).
+
+ The example below demonstrates a very simple use of the ``IRBuilder`` where
+ three instructions are inserted before the instruction ``pi``. The first two
+ instructions are Call instructions and third instruction multiplies the return
+ value of the two calls.
+
+ .. code-block:: c++
+
+ Instruction *pi = ...;
+ IRBuilder<> Builder(pi);
+ CallInst* callOne = Builder.CreateCall(...);
+ CallInst* callTwo = Builder.CreateCall(...);
+ Value* result = Builder.CreateMul(callOne, callTwo);
+
+ The example below is similar to the above example except that the created
+ ``IRBuilder`` inserts instructions at the end of the ``BasicBlock`` ``pb``.
+
+ .. code-block:: c++
+
+ BasicBlock *pb = ...;
+ IRBuilder<> Builder(pb);
+ CallInst* callOne = Builder.CreateCall(...);
+ CallInst* callTwo = Builder.CreateCall(...);
+ Value* result = Builder.CreateMul(callOne, callTwo);
+
+ See :doc:`tutorial/LangImpl3` for a practical use of the ``IRBuilder``.
+
+
+.. _schanges_deleting:
+
+Deleting Instructions
+^^^^^^^^^^^^^^^^^^^^^
+
+Deleting an instruction from an existing sequence of instructions that form a
+BasicBlock_ is very straight-forward: just call the instruction's
+``eraseFromParent()`` method. For example:
+
+.. code-block:: c++
+
+ Instruction *I = .. ;
+ I->eraseFromParent();
+
+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 ``removeFromParent()`` method.
+
+.. _schanges_replacing:
+
+Replacing an Instruction with another Value
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Replacing individual instructions
+"""""""""""""""""""""""""""""""""
+
+Including "`llvm/Transforms/Utils/BasicBlockUtils.h
+<http://llvm.org/doxygen/BasicBlockUtils_8h-source.html>`_" permits use of two
+very useful replace functions: ``ReplaceInstWithValue`` and
+``ReplaceInstWithInst``.
+
+.. _schanges_deleting_sub:
+
+Deleting Instructions
+"""""""""""""""""""""
+
+* ``ReplaceInstWithValue``
+
+ 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 ``AllocaInst`` that allocates memory
+ for a single integer with a null pointer to an integer.
+
+ .. code-block:: c++
+
+ AllocaInst* instToReplace = ...;
+ BasicBlock::iterator ii(instToReplace);
+
+ ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
+ Constant::getNullValue(PointerType::getUnqual(Type::Int32Ty)));
+
+* ``ReplaceInstWithInst``
+
+ 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
+ ``AllocaInst`` with another.
+
+ .. code-block:: c++
+
+ AllocaInst* instToReplace = ...;
+ BasicBlock::iterator ii(instToReplace);
+
+ ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
+ new AllocaInst(Type::Int32Ty, 0, "ptrToReplacedInt"));
+
+
+Replacing multiple uses of Users and Values
+"""""""""""""""""""""""""""""""""""""""""""
+
+You can use ``Value::replaceAllUsesWith`` and ``User::replaceUsesOfWith`` to
+change more than one use at a time. See the doxygen documentation for the
+`Value Class <http://llvm.org/doxygen/classllvm_1_1Value.html>`_ and `User Class
+<http://llvm.org/doxygen/classllvm_1_1User.html>`_, respectively, for more
+information.
+
+.. _schanges_deletingGV:
+
+Deleting GlobalVariables
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+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:
+
+.. code-block:: c++
+
+ GlobalVariable *GV = .. ;
+
+ GV->eraseFromParent();
+
+
+.. _create_types:
+
+How to Create Types
+-------------------
+
+In generating IR, you may need some complex types. If you know these types
+statically, you can use ``TypeBuilder<...>::get()``, defined in
+``llvm/Support/TypeBuilder.h``, to retrieve them. ``TypeBuilder`` has two forms
+depending on whether you're building types for cross-compilation or native
+library use. ``TypeBuilder<T, true>`` requires that ``T`` be independent of the
+host environment, meaning that it's built out of types from the ``llvm::types``
+(`doxygen <http://llvm.org/doxygen/namespacellvm_1_1types.html>`__) namespace
+and pointers, functions, arrays, etc. built of those. ``TypeBuilder<T, false>``
+additionally allows native C types whose size may depend on the host compiler.
+For example,
+
+.. code-block:: c++
+
+ FunctionType *ft = TypeBuilder<types::i<8>(types::i<32>*), true>::get();
+
+is easier to read and write than the equivalent
+
+.. code-block:: c++
+
+ std::vector<const Type*> params;
+ params.push_back(PointerType::getUnqual(Type::Int32Ty));
+ FunctionType *ft = FunctionType::get(Type::Int8Ty, params, false);
+
+See the `class comment
+<http://llvm.org/doxygen/TypeBuilder_8h-source.html#l00001>`_ for more details.
+
+.. _threading:
+
+Threads and LLVM
+================
+
+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.
+
+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 *must* adhere to the guidelines specified below to ensure
+proper operation in multithreaded mode.
+
+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.
+
+.. _shutdown:
+
+Ending Execution with ``llvm_shutdown()``
+-----------------------------------------
+
+When you are done using the LLVM APIs, you should call ``llvm_shutdown()`` to
+deallocate memory used for internal structures.
+
+.. _managedstatic:
+
+Lazy Initialization with ``ManagedStatic``
+------------------------------------------
+
+``ManagedStatic`` is a utility class in LLVM used to implement static
+initialization of static resources, such as the global type tables. In a
+single-threaded environment, it implements a simple lazy initialization scheme.
+When LLVM is compiled with support for multi-threading, however, it uses
+double-checked locking to implement thread-safe lazy initialization.
+
+.. _llvmcontext:
+
+Achieving Isolation with ``LLVMContext``
+----------------------------------------
+
+``LLVMContext`` 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, ``LLVMContext``
+exists to enable just this kind of scenario!
+
+Conceptually, ``LLVMContext`` provides isolation. Every LLVM entity
+(``Module``\ s, ``Value``\ s, ``Type``\ s, ``Constant``\ s, etc.) in LLVM's
+in-memory IR belongs to an ``LLVMContext``. Entities in different contexts
+*cannot* interact with each other: ``Module``\ s in different contexts cannot be
+linked together, ``Function``\ s cannot be added to ``Module``\ 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.
+
+In practice, very few places in the API require the explicit specification of a
+``LLVMContext``, other than the ``Type`` creation/lookup APIs. Because every
+``Type`` carries a reference to its owning context, most other entities can
+determine what context they belong to by looking at their own ``Type``. If you
+are adding new entities to LLVM IR, please try to maintain this interface
+design.
+
+For clients that do *not* require the benefits of isolation, LLVM provides a
+convenience API ``getGlobalContext()``. This returns a global, lazily
+initialized ``LLVMContext`` that may be used in situations where isolation is
+not a concern.
+
+.. _jitthreading:
+
+Threads and the JIT
+-------------------
+
+LLVM's "eager" JIT compiler is safe to use in threaded programs. Multiple
+threads can call ``ExecutionEngine::getPointerToFunction()`` or
+``ExecutionEngine::runFunction()`` 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 ``LLVMContext`` 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 *modifies* the IR by adding ``CallbackVH``\ s).
+Another way is to only call ``getPointerToFunction()`` from the
+``LLVMContext``'s thread.
+
+When the JIT is configured to compile lazily (using
+``ExecutionEngine::DisableLazyCompilation(false)``), there is currently a `race
+condition <http://llvm.org/bugs/show_bug.cgi?id=5184>`_ 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.
+
+.. _advanced:
+
+Advanced Topics
+===============
+
+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.
+
+.. _SymbolTable:
+
+The ``ValueSymbolTable`` class
+------------------------------
+
+The ``ValueSymbolTable`` (`doxygen
+<http://llvm.org/doxygen/classllvm_1_1ValueSymbolTable.html>`__) class provides
+a symbol table that the :ref:`Function <c_Function>` and Module_ classes use for
+naming value definitions. The symbol table can provide a name for any Value_.
+
+Note that the ``SymbolTable`` 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
+Value_\ s have names, and those without names (i.e. they have an empty name) do
+not exist in the symbol table.
+
+Symbol tables support iteration over the values in the symbol table with
+``begin/end/iterator`` and supports querying to see if a specific name is in the
+symbol table (with ``lookup``). The ``ValueSymbolTable`` class exposes no
+public mutator methods, instead, simply call ``setName`` on a value, which will
+autoinsert it into the appropriate symbol table.
+
+.. _UserLayout:
+
+The ``User`` and owned ``Use`` classes' memory layout
+-----------------------------------------------------
+
+The ``User`` (`doxygen <http://llvm.org/doxygen/classllvm_1_1User.html>`__)
+class provides a basis for expressing the ownership of ``User`` towards other
+`Value instance <http://llvm.org/doxygen/classllvm_1_1Value.html>`_\ s. The
+``Use`` (`doxygen <http://llvm.org/doxygen/classllvm_1_1Use.html>`__) helper
+class is employed to do the bookkeeping and to facilitate *O(1)* addition and
+removal.
+
+.. _Use2User:
+
+Interaction and relationship between ``User`` and ``Use`` objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A subclass of ``User`` can choose between incorporating its ``Use`` objects or
+refer to them out-of-line by means of a pointer. A mixed variant (some ``Use``
+s inline others hung off) is impractical and breaks the invariant that the
+``Use`` objects belonging to the same ``User`` form a contiguous array.
+
+We have 2 different layouts in the ``User`` (sub)classes:
+
+* Layout a)
+
+ The ``Use`` object(s) are inside (resp. at fixed offset) of the ``User``
+ object and there are a fixed number of them.
+
+* Layout b)
+
+ The ``Use`` object(s) are referenced by a pointer to an array from the
+ ``User`` object and there may be a variable number of them.
+
+As of v2.4 each layout still possesses a direct pointer to the start of the
+array of ``Use``\ s. Though not mandatory for layout a), we stick to this
+redundancy for the sake of simplicity. The ``User`` object also stores the
+number of ``Use`` objects it has. (Theoretically this information can also be
+calculated given the scheme presented below.)
+
+Special forms of allocation operators (``operator new``) enforce the following
+memory layouts:
+
+* Layout a) is modelled by prepending the ``User`` object by the ``Use[]``
+ array.
+
+ .. code-block:: none
+
+ ...---.---.---.---.-------...
+ | P | P | P | P | User
+ '''---'---'---'---'-------'''
+
+* Layout b) is modelled by pointing at the ``Use[]`` array.
+
+ .. code-block:: none
+
+ .-------...
+ | User
+ '-------'''
+ |
+ v
+ .---.---.---.---...
+ | P | P | P | P |
+ '---'---'---'---'''
+
+*(In the above figures* '``P``' *stands for the* ``Use**`` *that is stored in
+each* ``Use`` *object in the member* ``Use::Prev`` *)*
+
+.. _Waymarking:
+
+The waymarking algorithm
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since the ``Use`` objects are deprived of the direct (back)pointer to their
+``User`` objects, there must be a fast and exact method to recover it. This is
+accomplished by the following scheme:
+
+A bit-encoding in the 2 LSBits (least significant bits) of the ``Use::Prev``
+allows to find the start of the ``User`` object:
+
+* ``00`` --- binary digit 0
+
+* ``01`` --- binary digit 1
+
+* ``10`` --- stop and calculate (``s``)
+
+* ``11`` --- full stop (``S``)
+
+Given a ``Use*``, all we have to do is to walk till we get a stop and we either
+have a ``User`` immediately behind or we have to walk to the next stop picking
+up digits and calculating the offset:
+
+.. code-block:: none
+
+ .---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
+ | 1 | s | 1 | 0 | 1 | 0 | s | 1 | 1 | 0 | s | 1 | 1 | s | 1 | S | User (or User*)
+ '---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'----------------
+ |+15 |+10 |+6 |+3 |+1
+ | | | | | __>
+ | | | | __________>
+ | | | ______________________>
+ | | ______________________________________>
+ | __________________________________________________________>
+
+Only the significant number of bits need to be stored between the stops, so that
+the *worst case is 20 memory accesses* when there are 1000 ``Use`` objects
+associated with a ``User``.
+
+.. _ReferenceImpl:
+
+Reference implementation
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following literate Haskell fragment demonstrates the concept:
+
+.. code-block:: haskell
+
+ > 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 []
+ >
+
+Printing <test> gives: ``"1s100000s11010s10100s1111s1010s110s11s1S"``
+
+The reverse algorithm computes the length of the string just by examining a
+certain prefix:
+
+.. code-block:: haskell
+
+ > 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
+ >
+
+Now, as expected, printing <pref test> gives ``40``.
+
+We can *quickCheck* this with following property:
+
+.. code-block:: haskell
+
+ > testcase = dist 2000 []
+ > testcaseLength = length testcase
+ >
+ > identityProp n = n > 0 && n <= testcaseLength ==> length arr == pref arr
+ > where arr = takeLast n testcase
+ >
+
+As expected <quickCheck identityProp> gives:
+
+::
+
+ *Main> quickCheck identityProp
+ OK, passed 100 tests.
+
+Let's be a bit more exhaustive:
+
+.. code-block:: haskell
+
+ >
+ > deepCheck p = check (defaultConfig { configMaxTest = 500 }) p
+ >
+
+And here is the result of <deepCheck identityProp>:
+
+::
+
+ *Main> deepCheck identityProp
+ OK, passed 500 tests.
+
+.. _Tagging:
+
+Tagging considerations
+^^^^^^^^^^^^^^^^^^^^^^
+
+To maintain the invariant that the 2 LSBits of each ``Use**`` in ``Use`` never
+change after being set up, setters of ``Use::Prev`` must re-tag the new
+``Use**`` on every modification. Accordingly getters must strip the tag bits.
+
+For layout b) instead of the ``User`` we find a pointer (``User*`` with LSBit
+set). Following this pointer brings us to the ``User``. A portable trick
+ensures that the first bytes of ``User`` (if interpreted as a pointer) never has
+the LSBit set. (Portability is relying on the fact that all known compilers
+place the ``vptr`` in the first word of the instances.)
+
+.. _coreclasses:
+
+The Core LLVM Class Hierarchy Reference
+=======================================
+
+``#include "llvm/IR/Type.h"``
+
+header source: `Type.h <http://llvm.org/doxygen/Type_8h-source.html>`_
+
+doxygen info: `Type Clases <http://llvm.org/doxygen/classllvm_1_1Type.html>`_
+
+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 ``include/llvm/`` directory, and implemented in the ``lib/VMCore``
+directory.
+
+.. _Type:
+
+The Type class and Derived Types
+--------------------------------
+
+``Type`` is a superclass of all type classes. Every ``Value`` has a ``Type``.
+``Type`` cannot be instantiated directly but only through its subclasses.
+Certain primitive types (``VoidType``, ``LabelType``, ``FloatType`` and
+``DoubleType``) have hidden subclasses. They are hidden because they offer no
+useful functionality beyond what the ``Type`` class offers except to distinguish
+themselves from other subclasses of ``Type``.
+
+All other types are subclasses of ``DerivedType``. 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 ``Type*`` values, the types are identical
+if the pointers are identical.
+
+.. _m_Type:
+
+Important Public Methods
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``bool isIntegerTy() const``: Returns true for any integer type.
+
+* ``bool isFloatingPointTy()``: Return true if this is one of the five
+ floating point types.
+
+* ``bool isSized()``: Return true if the type has known size. Things
+ that don't have a size are abstract types, labels and void.
+
+.. _derivedtypes:
+
+Important Derived Types
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``IntegerType``
+ Subclass of DerivedType that represents integer types of any bit width. Any
+ bit width between ``IntegerType::MIN_INT_BITS`` (1) and
+ ``IntegerType::MAX_INT_BITS`` (~8 million) can be represented.
+
+ * ``static const IntegerType* get(unsigned NumBits)``: get an integer
+ type of a specific bit width.
+
+ * ``unsigned getBitWidth() const``: Get the bit width of an integer type.
+
+``SequentialType``
+ This is subclassed by ArrayType, PointerType and VectorType.
+
+ * ``const Type * getElementType() const``: Returns the type of each
+ of the elements in the sequential type.
+
+``ArrayType``
+ This is a subclass of SequentialType and defines the interface for array
+ types.
+
+ * ``unsigned getNumElements() const``: Returns the number of elements
+ in the array.
+
+``PointerType``
+ Subclass of SequentialType for pointer types.
+
+``VectorType``
+ 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.
+
+``StructType``
+ Subclass of DerivedTypes for struct types.
+
+.. _FunctionType:
+
+``FunctionType``
+ Subclass of DerivedTypes for function types.
+
+ * ``bool isVarArg() const``: Returns true if it's a vararg function.
+
+ * ``const Type * getReturnType() const``: Returns the return type of the
+ function.
+
+ * ``const Type * getParamType (unsigned i)``: Returns the type of the ith
+ parameter.
+
+ * ``const unsigned getNumParams() const``: Returns the number of formal
+ parameters.
+
+.. _Module:
+
+The ``Module`` class
+--------------------
+
+``#include "llvm/IR/Module.h"``
+
+header source: `Module.h <http://llvm.org/doxygen/Module_8h-source.html>`_
+
+doxygen info: `Module Class <http://llvm.org/doxygen/classllvm_1_1Module.html>`_
+
+The ``Module`` 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 ``Module`` class keeps track of a list of :ref:`Function
+<c_Function>`\ s, a list of GlobalVariable_\ s, and a SymbolTable_.
+Additionally, it contains a few helpful member functions that try to make common
+operations easy.
+
+.. _m_Module:
+
+Important Public Members of the ``Module`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``Module::Module(std::string name = "")``
+
+ Constructing a Module_ is easy. You can optionally provide a name for it
+ (probably based on the name of the translation unit).
+
+* | ``Module::iterator`` - Typedef for function list iterator
+ | ``Module::const_iterator`` - Typedef for const_iterator.
+ | ``begin()``, ``end()``, ``size()``, ``empty()``
+
+ These are forwarding methods that make it easy to access the contents of a
+ ``Module`` object's :ref:`Function <c_Function>` list.
+
+* ``Module::FunctionListType &getFunctionList()``
+
+ Returns the list of :ref:`Function <c_Function>`\ 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.
+
+----------------
+
+* | ``Module::global_iterator`` - Typedef for global variable list iterator
+ | ``Module::const_global_iterator`` - Typedef for const_iterator.
+ | ``global_begin()``, ``global_end()``, ``global_size()``, ``global_empty()``
+
+ These are forwarding methods that make it easy to access the contents of a
+ ``Module`` object's GlobalVariable_ list.
+
+* ``Module::GlobalListType &getGlobalList()``
+
+ Returns the list of GlobalVariable_\ 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.
+
+----------------
+
+* ``SymbolTable *getSymbolTable()``
+
+ Return a reference to the SymbolTable_ for this ``Module``.
+
+----------------
+
+* ``Function *getFunction(StringRef Name) const``
+
+ Look up the specified function in the ``Module`` SymbolTable_. If it does not
+ exist, return ``null``.
+
+* ``Function *getOrInsertFunction(const std::string &Name, const FunctionType
+ *T)``
+
+ Look up the specified function in the ``Module`` SymbolTable_. If it does not
+ exist, add an external declaration for the function and return it.
+
+* ``std::string getTypeName(const Type *Ty)``
+
+ If there is at least one entry in the SymbolTable_ for the specified Type_,
+ return it. Otherwise return the empty string.
+
+* ``bool addTypeName(const std::string &Name, const Type *Ty)``
+
+ Insert an entry in the SymbolTable_ mapping ``Name`` to ``Ty``. If there is
+ already an entry for this name, true is returned and the SymbolTable_ is not
+ modified.
+
+.. _Value:
+
+The ``Value`` class
+-------------------
+
+``#include "llvm/IR/Value.h"``
+
+header source: `Value.h <http://llvm.org/doxygen/Value_8h-source.html>`_
+
+doxygen info: `Value Class <http://llvm.org/doxygen/classllvm_1_1Value.html>`_
+
+The ``Value`` 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 ``Value``\ s, such as
+Constant_\ s, Argument_\ s. Even Instruction_\ s and :ref:`Function
+<c_Function>`\ s are ``Value``\ s.
+
+A particular ``Value`` 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 Argument_ class) is "used" by every instruction in the function
+that references the argument. To keep track of this relationship, the ``Value``
+class keeps a list of all of the ``User``\ s that is using it (the User_ class
+is a base class for all nodes in the LLVM graph that can refer to ``Value``\ s).
+This use list is how LLVM represents def-use information in the program, and is
+accessible through the ``use_*`` methods, shown below.
+
+Because LLVM is a typed representation, every LLVM ``Value`` is typed, and this
+Type_ is available through the ``getType()`` method. In addition, all LLVM
+values can be named. The "name" of the ``Value`` is a symbolic string printed
+in the LLVM code:
+
+.. code-block:: llvm
+
+ %foo = add i32 1, 2
+
+.. _nameWarning:
+
+The name of this instruction is "foo". **NOTE** that the name of any value may
+be missing (an empty string), so names should **ONLY** 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
+``std::map`` of pointers to the ``Value`` itself instead.
+
+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.
+
+.. _m_Value:
+
+Important Public Members of the ``Value`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* | ``Value::use_iterator`` - Typedef for iterator over the use-list
+ | ``Value::const_use_iterator`` - Typedef for const_iterator over the
+ use-list
+ | ``unsigned use_size()`` - Returns the number of users of the value.
+ | ``bool use_empty()`` - Returns true if there are no users.
+ | ``use_iterator use_begin()`` - Get an iterator to the start of the
+ use-list.
+ | ``use_iterator use_end()`` - Get an iterator to the end of the use-list.
+ | ``User *use_back()`` - Returns the last element in the list.
+
+ 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 STL_.
+
+* ``Type *getType() const``
+ This method returns the Type of the Value.
+
+* | ``bool hasName() const``
+ | ``std::string getName() const``
+ | ``void setName(const std::string &Name)``
+
+ This family of methods is used to access and assign a name to a ``Value``, be
+ aware of the :ref:`precaution above <nameWarning>`.
+
+* ``void replaceAllUsesWith(Value *V)``
+
+ This method traverses the use list of a ``Value`` changing all User_\ s of the
+ current value to refer to "``V``" 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:
+
+ .. code-block:: c++
+
+ Inst->replaceAllUsesWith(ConstVal);
+
+.. _User:
+
+The ``User`` class
+------------------
+
+``#include "llvm/IR/User.h"``
+
+header source: `User.h <http://llvm.org/doxygen/User_8h-source.html>`_
+
+doxygen info: `User Class <http://llvm.org/doxygen/classllvm_1_1User.html>`_
+
+Superclass: Value_
+
+The ``User`` class is the common base class of all LLVM nodes that may refer to
+``Value``\ s. It exposes a list of "Operands" that are all of the ``Value``\ s
+that the User is referring to. The ``User`` class itself is a subclass of
+``Value``.
+
+The operands of a ``User`` point directly to the LLVM ``Value`` 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.
+
+.. _m_User:
+
+Important Public Members of the ``User`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``User`` class exposes the operand list in two ways: through an index access
+interface and through an iterator based interface.
+
+* | ``Value *getOperand(unsigned i)``
+ | ``unsigned getNumOperands()``
+
+ These two methods expose the operands of the ``User`` in a convenient form for
+ direct access.
+
+* | ``User::op_iterator`` - Typedef for iterator over the operand list
+ | ``op_iterator op_begin()`` - Get an iterator to the start of the operand
+ list.
+ | ``op_iterator op_end()`` - Get an iterator to the end of the operand list.
+
+ Together, these methods make up the iterator based interface to the operands
+ of a ``User``.
+
+
+.. _Instruction:
+
+The ``Instruction`` class
+-------------------------
+
+``#include "llvm/IR/Instruction.h"``
+
+header source: `Instruction.h
+<http://llvm.org/doxygen/Instruction_8h-source.html>`_
+
+doxygen info: `Instruction Class
+<http://llvm.org/doxygen/classllvm_1_1Instruction.html>`_
+
+Superclasses: User_, Value_
+
+The ``Instruction`` 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 ``Instruction`` class itself is the opcode (instruction
+type) and the parent BasicBlock_ the ``Instruction`` is embedded into. To
+represent a specific type of instruction, one of many subclasses of
+``Instruction`` are used.
+
+Because the ``Instruction`` class subclasses the User_ class, its operands can
+be accessed in the same way as for other ``User``\ s (with the
+``getOperand()``/``getNumOperands()`` and ``op_begin()``/``op_end()`` methods).
+An important file for the ``Instruction`` class is the ``llvm/Instruction.def``
+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 ``Instruction::Add`` and ``Instruction::ICmp``), as well as the
+concrete sub-classes of ``Instruction`` that implement the instruction (for
+example BinaryOperator_ and CmpInst_). Unfortunately, the use of macros in this
+file confuses doxygen, so these enum values don't show up correctly in the
+`doxygen output <http://llvm.org/doxygen/classllvm_1_1Instruction.html>`_.
+
+.. _s_Instruction:
+
+Important Subclasses of the ``Instruction`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _BinaryOperator:
+
+* ``BinaryOperator``
+
+ This subclasses represents all two operand instructions whose operands must be
+ the same type, except for the comparison instructions.
+
+.. _CastInst:
+
+* ``CastInst``
+ This subclass is the parent of the 12 casting instructions. It provides
+ common operations on cast instructions.
+
+.. _CmpInst:
+
+* ``CmpInst``
+
+ This subclass respresents the two comparison instructions,
+ `ICmpInst <LangRef.html#i_icmp>`_ (integer opreands), and
+ `FCmpInst <LangRef.html#i_fcmp>`_ (floating point operands).
+
+.. _TerminatorInst:
+
+* ``TerminatorInst``
+
+ This subclass is the parent of all terminator instructions (those which can
+ terminate a block).
+
+.. _m_Instruction:
+
+Important Public Members of the ``Instruction`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``BasicBlock *getParent()``
+
+ Returns the BasicBlock_ that this
+ ``Instruction`` is embedded into.
+
+* ``bool mayWriteToMemory()``
+
+ Returns true if the instruction writes to memory, i.e. it is a ``call``,
+ ``free``, ``invoke``, or ``store``.
+
+* ``unsigned getOpcode()``
+
+ Returns the opcode for the ``Instruction``.
+
+* ``Instruction *clone() const``
+
+ Returns another instance of the specified instruction, identical in all ways
+ to the original except that the instruction has no parent (i.e. it's not
+ embedded into a BasicBlock_), and it has no name.
+
+.. _Constant:
+
+The ``Constant`` class and subclasses
+-------------------------------------
+
+Constant represents a base class for different types of constants. It is
+subclassed by ConstantInt, ConstantArray, etc. for representing the various
+types of Constants. GlobalValue_ is also a subclass, which represents the
+address of a global variable or function.
+
+.. _s_Constant:
+
+Important Subclasses of Constant
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ConstantInt : This subclass of Constant represents an integer constant of
+ any width.
+
+ * ``const APInt& getValue() const``: Returns the underlying
+ value of this constant, an APInt value.
+
+ * ``int64_t getSExtValue() const``: 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.
+
+ * ``uint64_t getZExtValue() const``: 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.
+
+ * ``static ConstantInt* get(const APInt& Val)``: Returns the ConstantInt
+ object that represents the value provided by ``Val``. The type is implied
+ as the IntegerType that corresponds to the bit width of ``Val``.
+
+ * ``static ConstantInt* get(const Type *Ty, uint64_t Val)``: Returns the
+ ConstantInt object that represents the value provided by ``Val`` for integer
+ type ``Ty``.
+
+* ConstantFP : This class represents a floating point constant.
+
+ * ``double getValue() const``: Returns the underlying value of this constant.
+
+* ConstantArray : This represents a constant array.
+
+ * ``const std::vector<Use> &getValues() const``: Returns a vector of
+ component constants that makeup this array.
+
+* ConstantStruct : This represents a constant struct.
+
+ * ``const std::vector<Use> &getValues() const``: Returns a vector of
+ component constants that makeup this array.
+
+* GlobalValue : This represents either a global variable or a function. In
+ either case, the value is a constant fixed address (after linking).
+
+.. _GlobalValue:
+
+The ``GlobalValue`` class
+-------------------------
+
+``#include "llvm/IR/GlobalValue.h"``
+
+header source: `GlobalValue.h
+<http://llvm.org/doxygen/GlobalValue_8h-source.html>`_
+
+doxygen info: `GlobalValue Class
+<http://llvm.org/doxygen/classllvm_1_1GlobalValue.html>`_
+
+Superclasses: Constant_, User_, Value_
+
+Global values ( GlobalVariable_\ s or :ref:`Function <c_Function>`\ s) are the
+only LLVM values that are visible in the bodies of all :ref:`Function
+<c_Function>`\ 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, ``GlobalValue``\ s know their linkage rules.
+Specifically, ``GlobalValue``\ s know whether they have internal or external
+linkage, as defined by the ``LinkageTypes`` enumeration.
+
+If a ``GlobalValue`` has internal linkage (equivalent to being ``static`` 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,
+``GlobalValue``\ s keep track of which Module_ they are currently part of.
+
+Because ``GlobalValue``\ s are memory objects, they are always referred to by
+their **address**. As such, the Type_ of a global is always a pointer to its
+contents. It is important to remember this when using the ``GetElementPtrInst``
+instruction because this pointer must be dereferenced first. For example, if
+you have a ``GlobalVariable`` (a subclass of ``GlobalValue)`` that is an array
+of 24 ints, type ``[24 x i32]``, then the ``GlobalVariable`` is a pointer to
+that array. Although the address of the first element of this array and the
+value of the ``GlobalVariable`` are the same, they have different types. The
+``GlobalVariable``'s type is ``[24 x i32]``. The first element's type is
+``i32.`` Because of this, accessing a global value requires you to dereference
+the pointer with ``GetElementPtrInst`` first, then its elements can be accessed.
+This is explained in the `LLVM Language Reference Manual
+<LangRef.html#globalvars>`_.
+
+.. _m_GlobalValue:
+
+Important Public Members of the ``GlobalValue`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* | ``bool hasInternalLinkage() const``
+ | ``bool hasExternalLinkage() const``
+ | ``void setInternalLinkage(bool HasInternalLinkage)``
+
+ These methods manipulate the linkage characteristics of the ``GlobalValue``.
+
+* ``Module *getParent()``
+
+ This returns the Module_ that the
+ GlobalValue is currently embedded into.
+
+.. _c_Function:
+
+The ``Function`` class
+----------------------
+
+``#include "llvm/IR/Function.h"``
+
+header source: `Function.h <http://llvm.org/doxygen/Function_8h-source.html>`_
+
+doxygen info: `Function Class
+<http://llvm.org/doxygen/classllvm_1_1Function.html>`_
+
+Superclasses: GlobalValue_, Constant_, User_, Value_
+
+The ``Function`` 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 ``Function`` class keeps track of a list of
+BasicBlock_\ s, a list of formal Argument_\ s, and a SymbolTable_.
+
+The list of BasicBlock_\ s is the most commonly used part of ``Function``
+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 BasicBlock_ is the implicit entry node for the ``Function``. 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
+``Function``. If the BasicBlock_ list is empty, this indicates that the
+``Function`` is actually a function declaration: the actual body of the function
+hasn't been linked in yet.
+
+In addition to a list of BasicBlock_\ s, the ``Function`` class also keeps track
+of the list of formal Argument_\ s that the function receives. This container
+manages the lifetime of the Argument_ nodes, just like the BasicBlock_ list does
+for the BasicBlock_\ s.
+
+The SymbolTable_ 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 SymbolTable_ is used
+internally to make sure that there are not conflicts between the names of
+Instruction_\ s, BasicBlock_\ s, or Argument_\ s in the function body.
+
+Note that ``Function`` is a GlobalValue_ and therefore also a Constant_. The
+value of the function is its address (after linking) which is guaranteed to be
+constant.
+
+.. _m_Function:
+
+Important Public Members of the ``Function``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``Function(const FunctionType *Ty, LinkageTypes Linkage,
+ const std::string &N = "", Module* Parent = 0)``
+
+ Constructor used when you need to create new ``Function``\ 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 FunctionType_ argument
+ specifies the formal arguments and return value for the function. The same
+ FunctionType_ value can be used to create multiple functions. The ``Parent``
+ 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.
+
+* ``bool isDeclaration()``
+
+ Return whether or not the ``Function`` 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.
+
+* | ``Function::iterator`` - Typedef for basic block list iterator
+ | ``Function::const_iterator`` - Typedef for const_iterator.
+ | ``begin()``, ``end()``, ``size()``, ``empty()``
+
+ These are forwarding methods that make it easy to access the contents of a
+ ``Function`` object's BasicBlock_ list.
+
+* ``Function::BasicBlockListType &getBasicBlockList()``
+
+ Returns the list of BasicBlock_\ 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.
+
+* | ``Function::arg_iterator`` - Typedef for the argument list iterator
+ | ``Function::const_arg_iterator`` - Typedef for const_iterator.
+ | ``arg_begin()``, ``arg_end()``, ``arg_size()``, ``arg_empty()``
+
+ These are forwarding methods that make it easy to access the contents of a
+ ``Function`` object's Argument_ list.
+
+* ``Function::ArgumentListType &getArgumentList()``
+
+ Returns the list of Argument_. This is necessary to use when you need to
+ update the list or perform a complex action that doesn't have a forwarding
+ method.
+
+* ``BasicBlock &getEntryBlock()``
+
+ Returns the entry ``BasicBlock`` for the function. Because the entry block
+ for the function is always the first block, this returns the first block of
+ the ``Function``.
+
+* | ``Type *getReturnType()``
+ | ``FunctionType *getFunctionType()``
+
+ This traverses the Type_ of the ``Function`` and returns the return type of
+ the function, or the FunctionType_ of the actual function.
+
+* ``SymbolTable *getSymbolTable()``
+
+ Return a pointer to the SymbolTable_ for this ``Function``.
+
+.. _GlobalVariable:
+
+The ``GlobalVariable`` class
+----------------------------
+
+``#include "llvm/IR/GlobalVariable.h"``
+
+header source: `GlobalVariable.h
+<http://llvm.org/doxygen/GlobalVariable_8h-source.html>`_
+
+doxygen info: `GlobalVariable Class
+<http://llvm.org/doxygen/classllvm_1_1GlobalVariable.html>`_
+
+Superclasses: GlobalValue_, Constant_, User_, Value_
+
+Global variables are represented with the (surprise surprise) ``GlobalVariable``
+class. Like functions, ``GlobalVariable``\ s are also subclasses of
+GlobalValue_, and as such are always referenced by their address (global values
+must live in memory, so their "name" refers to their constant address). See
+GlobalValue_ for more on this. Global variables may have an initial value
+(which must be a Constant_), and if they have an initializer, they may be marked
+as "constant" themselves (indicating that their contents never change at
+runtime).
+
+.. _m_GlobalVariable:
+
+Important Public Members of the ``GlobalVariable`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``GlobalVariable(const Type *Ty, bool isConstant, LinkageTypes &Linkage,
+ Constant *Initializer = 0, const std::string &Name = "", Module* Parent = 0)``
+
+ Create a new global variable of the specified type. If ``isConstant`` 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
+ `LLVM Language Reference <LangRef.html#modulestructure>`_ 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.
+
+* ``bool isConstant() const``
+
+ Returns true if this is a global variable that is known not to be modified at
+ runtime.
+
+* ``bool hasInitializer()``
+
+ Returns true if this ``GlobalVariable`` has an intializer.
+
+* ``Constant *getInitializer()``
+
+ Returns the initial value for a ``GlobalVariable``. It is not legal to call
+ this method if there is no initializer.
+
+.. _BasicBlock:
+
+The ``BasicBlock`` class
+------------------------
+
+``#include "llvm/IR/BasicBlock.h"``
+
+header source: `BasicBlock.h
+<http://llvm.org/doxygen/BasicBlock_8h-source.html>`_
+
+doxygen info: `BasicBlock Class
+<http://llvm.org/doxygen/classllvm_1_1BasicBlock.html>`_
+
+Superclass: Value_
+
+This class represents a single entry single exit section of the code, commonly
+known as a basic block by the compiler community. The ``BasicBlock`` class
+maintains a list of Instruction_\ 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 TerminatorInst_ class).
+
+In addition to tracking the list of instructions that make up the block, the
+``BasicBlock`` class also keeps track of the :ref:`Function <c_Function>` that
+it is embedded into.
+
+Note that ``BasicBlock``\ s themselves are Value_\ s, because they are
+referenced by instructions like branches and can go in the switch tables.
+``BasicBlock``\ s have type ``label``.
+
+.. _m_BasicBlock:
+
+Important Public Members of the ``BasicBlock`` class
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* ``BasicBlock(const std::string &Name = "", Function *Parent = 0)``
+
+ The ``BasicBlock`` 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 :ref:`Function <c_Function>` to insert it into. If the
+ ``Parent`` parameter is specified, the new ``BasicBlock`` is automatically
+ inserted at the end of the specified :ref:`Function <c_Function>`, if not
+ specified, the BasicBlock must be manually inserted into the :ref:`Function
+ <c_Function>`.
+
+* | ``BasicBlock::iterator`` - Typedef for instruction list iterator
+ | ``BasicBlock::const_iterator`` - Typedef for const_iterator.
+ | ``begin()``, ``end()``, ``front()``, ``back()``,
+ ``size()``, ``empty()``
+ STL-style functions for accessing the instruction list.
+
+ 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 ``getInstList()`` method.
+
+* ``BasicBlock::InstListType &getInstList()``
+
+ 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 ``BasicBlock`` 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 ``BasicBlock``.
+
+* ``Function *getParent()``
+
+ Returns a pointer to :ref:`Function <c_Function>` the block is embedded into,
+ or a null pointer if it is homeless.
+
+* ``TerminatorInst *getTerminator()``
+
+ Returns a pointer to the terminator instruction that appears at the end of the
+ ``BasicBlock``. If there is no terminator instruction, or if the last
+ instruction in the block is not a terminator, then a null pointer is returned.
+
+.. _Argument:
+
+The ``Argument`` class
+----------------------
+
+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.
+
+
Added: www-releases/trunk/3.5.1/docs/_sources/Projects.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/Projects.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/Projects.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/Projects.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,257 @@
+========================
+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.
+
+If you want to devise your own build system, studying other projects and LLVM
+``Makefiles`` will probably provide enough information on how to write your own
+``Makefiles``.
+
+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.
+
+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 contains regression tests in ``llvm/test``. These tests are run by the
+ :doc:`Lit <CommandGuide/lit>` testing tool. This test procedure uses ``RUN``
+ lines in the actual test case to determine how to run the test. See the
+ :doc:`TestingGuide` for more details.
+
+* 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.5.1/docs/_sources/ReleaseNotes.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/ReleaseNotes.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/ReleaseNotes.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/ReleaseNotes.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,398 @@
+======================
+LLVM 3.5 Release Notes
+======================
+
+.. contents::
+ :local:
+
+
+Introduction
+============
+
+This document contains the release notes for the LLVM Compiler Infrastructure,
+release 3.5. Here we describe the status of LLVM, including major improvements
+from the previous release, improvements in various subprojects of LLVM, and
+some of the current users of the code. All LLVM releases may be downloaded
+from the `LLVM releases web site <http://llvm.org/releases/>`_.
+
+For more information about LLVM, including information about the latest
+release, please check out the `main LLVM web site <http://llvm.org/>`_. If you
+have questions or comments, the `LLVM Developer's Mailing List
+<http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>`_ is a good place to send
+them.
+
+Non-comprehensive list of changes in this release
+=================================================
+
+Changes to the MIPS Target
+--------------------------
+
+* A large number of bugs have been fixed for big-endian Mips targets using the
+ N32 and N64 ABI's. Please note that some of these bugs will still affect
+ LLVM-IR generated by LLVM 3.5 since correct code generation depends on
+ appropriate usage of the ``inreg``, ``signext``, and ``zeroext`` attributes
+ on all function arguments and returns.
+
+* The registers used to return a structure containing a single 128-bit floating
+ point member on the N32/N64 ABI's have been changed from those specified by
+ the ABI documentation to match those used by GCC. The documentation specifies
+ that ``$f0`` and ``$f2`` should be used but GCC has used ``$f0`` and ``$f1``
+ for many years.
+
+* Returning a zero-byte struct no longer causes incorrect code generation when
+ using the O32 ABI.
+
+* Passing structures of less than 32-bits using the O32 ABI on a big-endian
+ target has been fixed.
+
+* The exception personality has been changed for 64-bit Mips targets to
+ eliminate warnings about relocations in a read-only section.
+
+* Incorrect usage of odd-numbered single-precision floating point registers
+ has been fixed when the fastcc calling convention is used with 64-bit FPU's
+ and -mno-odd-spreg.
+
+* For inline assembly, the 'z' print-modifier print modifier can now be used on
+ non-immediate values.
+
+* Attempting to disassemble l[wd]c[23], s[wd]c[23], cache, and pref no longer
+ triggers an assertion.
+
+Non-comprehensive list of changes in 3.5
+========================================
+
+* All backends have been changed to use the MC asm printer and support for the
+ non MC one has been removed.
+
+* Clang can now successfully self-host itself on Linux/Sparc64 and on
+ FreeBSD/Sparc64.
+
+* LLVM now assumes the assembler supports ``.loc`` for generating debug line
+ numbers. The old support for printing the debug line info directly was only
+ used by ``llc`` and has been removed.
+
+* All inline assembly is parsed by the integrated assembler when it is enabled.
+ Previously this was only the case for object-file output. It is now the case
+ for assembly output as well. The integrated assembler can be disabled with
+ the ``-no-integrated-as`` option.
+
+* llvm-ar now handles IR files like regular object files. In particular, a
+ regular symbol table is created for symbols defined in IR files, including
+ those in file scope inline assembly.
+
+* LLVM now always uses cfi directives for producing most stack
+ unwinding information.
+
+* The prefix for loop vectorizer hint metadata has been changed from
+ ``llvm.vectorizer`` to ``llvm.loop.vectorize``. In addition,
+ ``llvm.vectorizer.unroll`` metadata has been renamed
+ ``llvm.loop.interleave.count``.
+
+* Some backends previously implemented Atomic NAND(x,y) as ``x & ~y``. Now
+ all backends implement it as ``~(x & y)``, matching the semantics of GCC 4.4
+ and later.
+
+.. NOTE
+ For small 1-3 sentence descriptions, just add an entry at the end of
+ this list. If your description won't fit comfortably in one bullet
+ point (e.g. maybe you would like to give an example of the
+ functionality, or simply have a lot to talk about), see the `NOTE` below
+ for adding a new subsection.
+
+* ... next change ...
+
+.. NOTE
+ If you would like to document a larger change, then you can add a
+ subsection about it right here. You can copy the following boilerplate
+ and un-indent it (the indentation causes it to be inside this comment).
+
+ Special New Feature
+ -------------------
+
+ Makes programs 10x faster by doing Special New Thing.
+
+Changes to the ARM Backend
+--------------------------
+
+Since release 3.3, a lot of new features have been included in the ARM
+back-end but weren't production ready (ie. well tested) on release 3.4.
+Just after the 3.4 release, we started heavily testing two major parts
+of the back-end: the integrated assembler (IAS) and the ARM exception
+handling (EHABI), and now they are enabled by default on LLVM/Clang.
+
+The IAS received a lot of GNU extensions and directives, as well as some
+specific pre-UAL instructions. Not all remaining directives will be
+implemented, as we made judgement calls on the need versus the complexity,
+and have chosen simplicity and future compatibility where hard decisions
+had to be made. The major difference is, as stated above, the IAS validates
+all inline ASM, not just for object emission, and that cause trouble with
+some uses of inline ASM as pre-processor magic.
+
+So, while the IAS is good enough to compile large projects (including most
+of the Linux kernel), there are a few things that we can't (and probably
+won't) do. For those cases, please use ``-fno-integrated-as`` in Clang.
+
+Exception handling is another big change. After extensive testing and
+changes to cooperate with Dwarf unwinding, EHABI is enabled by default.
+The options ``-arm-enable-ehabi`` and ``-arm-enable-ehabi-descriptors``,
+which were used to enable EHABI in the previous releases, are removed now.
+
+This means all ARM code will emit EH unwind tables, or CFI unwinding (for
+debug/profiling), or both. To avoid run-time inconsistencies, C code will
+also emit EH tables (in case they interoperate with C++ code), as is the
+case for other architectures (ex. x86_64).
+
+Changes to the MIPS Target
+--------------------------
+
+There has been a large amount of improvements to the MIPS target which can be
+broken down into subtarget, ABI, and Integrated Assembler changes.
+
+Subtargets
+^^^^^^^^^^
+
+Added support for Release 6 of the MIPS32 and MIPS64 architecture (MIPS32r6
+and MIPS64r6). Release 6 makes a number of significant changes to the MIPS32
+and MIPS64 architectures. For example, FPU registers are always 64-bits wide,
+FPU NaN values conform to IEEE 754 (2008), and the unaligned memory instructions
+(such as lwl and lwr) have been replaced with a requirement for ordinary memory
+operations to support unaligned operations. Full details of MIPS32 and MIPS64
+Release 6 can be found on the `MIPS64 Architecture page at Imagination
+Technologies <http://www.imgtec.com/mips/architectures/mips64.asp>`_.
+
+This release also adds experimental support for MIPS-IV, cnMIPS, and Cavium
+Octeon CPU's.
+
+Support for the MIPS SIMD Architecture (MSA) has been improved to support MSA
+on MIPS64.
+
+Support for IEEE 754 (2008) NaN values has been added.
+
+ABI and ABI extensions
+^^^^^^^^^^^^^^^^^^^^^^
+
+There has also been considerable ABI work since the 3.4 release. This release
+adds support for the N32 ABI, the O32-FPXX ABI Extension, the O32-FP64 ABI
+Extension, and the O32-FP64A ABI Extension.
+
+The N32 ABI is an existing ABI that has now been implemented in LLVM. It is a
+64-bit ABI that is similar to N64 but retains 32-bit pointers. N64 remains the
+default 64-bit ABI in LLVM. This differs from GCC where N32 is the default
+64-bit ABI.
+
+The O32-FPXX ABI Extension is 100% compatible with the O32-ABI and the O32-FP64
+ABI Extension and may be linked with either but may not be linked with both of
+these simultaneously. It extends the O32 ABI to allow the same code to execute
+without modification on processors with 32-bit FPU registers as well as 64-bit
+FPU registers. The O32-FPXX ABI Extension is enabled by default for the O32 ABI
+on mips*-img-linux-gnu and mips*-mti-linux-gnu triples and is selected with
+-mfpxx. It is expected that future releases of LLVM will enable the FPXX
+Extension for O32 on all triples.
+
+The O32-FP64 ABI Extension is an extension to the O32 ABI to fully exploit FPU's
+with 64-bit registers and is enabled with -mfp64. This replaces an undocumented
+and unsupported O32 extension which was previously enabled with -mfp64. It is
+100% compatible with the O32-FPXX ABI Extension.
+
+The O32-FP64A ABI Extension is a restricted form of the O32-FP64 ABI Extension
+which allows interlinking with unmodified binaries that use the base O32 ABI.
+
+Integrated Assembler
+^^^^^^^^^^^^^^^^^^^^
+
+The MIPS Integrated Assembler has undergone a substantial overhaul including a
+rewrite of the assembly parser. It's not ready for general use in this release
+but adventurous users may wish to enable it using ``-fintegrated-as``.
+
+In this release, the integrated assembler supports the majority of MIPS-I,
+MIPS-II, MIPS-III, MIPS-IV, MIPS-V, MIPS32, MIPS32r2, MIPS32r6, MIPS64,
+MIPS64r2, and MIPS64r6 as well as some of the Application Specific Extensions
+such as MSA. It also supports several of the MIPS specific assembler directives
+such as ``.set``, ``.module``, ``.cpload``, etc.
+
+Changes to the AArch64 Target
+-----------------------------
+
+The AArch64 target in LLVM 3.5 is based on substantially different code to the
+one in LLVM 3.4, having been created as the result of merging code released by
+Apple for targetting iOS with the previously existing backend.
+
+We hope the result is a general improvement in the project. Particularly notable
+changes are:
+
+* We should produce faster code, having combined optimisations and ideas from
+ both sources in the final backend.
+* We have a FastISel for AArch64, which should compile time for debug builds (at
+ -O0).
+* We can now target iOS platforms (using the triple ``arm64-apple-ios7.0``).
+
+Background
+^^^^^^^^^^
+
+During the 3.5 release cycle, Apple released the source used to generate 64-bit
+ARM programs on iOS platforms. This took the form of a separate backend that had
+been developed in parallel to, and largely isolation from, the existing
+code.
+
+We decided that maintaining the two backends indefinitely was not an option,
+since their features almost entirely overlapped. However, the implementation
+details in both were different enough that any merge had to firmly start with
+one backend as the core and cherry-pick the best features and optimisations from
+the other.
+
+After discussion, we decided to start with the Apple backend (called ARM64 at
+the time) since it was older, more thoroughly tested in production use, and had
+fewer idiosyncracies in the implementation details.
+
+Many people from across the community worked throughout April and May to ensure
+that this merge destination had all the features we wanted, from both
+sources. In many cases we could simply copy code across; others needed heavy
+modification for the new host; in the most worthwhile, we looked at both
+implementations and combined the best features of each in an entirely new way.
+
+We had also decided that the name of the combined backend should be AArch64,
+following ARM's official documentation. So, at the end of May the old
+AArch64 directory was removed, and ARM64 renamed into its place.
+
+Changes to the PowerPC Target
+-----------------------------
+
+The PowerPC 64-bit Little Endian subtarget (powerpc64le-unknown-linux-gnu) is
+now fully supported. This includes support for the Altivec instruction set.
+
+The Power Architecture 64-Bit ELFv2 ABI Specification is now supported, and
+is the default ABI for Little Endian. The ELFv1 ABI remains the default ABI
+for Big Endian. Currently, it is not possible to override these defaults.
+That capability will be available (albeit not recommended) in a future release.
+
+Links to the ELFv2 ABI specification and to the Power ISA Version 2.07
+specification may be found `here <https://www-03.ibm.com/technologyconnect/tgcm/TGCMServlet.wss?alias=OpenPOWER&linkid=1n0000>`_ (free registration required).
+Efforts are underway to move this to a location that doesn't require
+registration, but the planned site isn't ready yet.
+
+Experimental support for the VSX instruction set introduced with ISA 2.06
+is now available using the ``-mvsx`` switch. Work remains on this, so it
+is not recommended for production use. VSX is disabled for Little Endian
+regardless of this switch setting.
+
+Load/store cost estimates have been improved.
+
+Constant hoisting has been enabled.
+
+Global named register support has been enabled.
+
+Initial support for PIC code has been added for the 32-bit ELF subtarget.
+Further support will be available in a future release.
+
+
+Changes to CMake build system
+-----------------------------
+
+* Building and installing LLVM, Clang and lld sphinx documentation can now be
+ done in CMake builds. If ``LLVM_ENABLE_SPHINX`` is enabled the
+ "``docs-<project>-html``" and "``docs-<project>-man``" targets (e.g.
+ ``docs-llvm-html``) become available which can be invoked directly (e.g.
+ ``make docs-llvm-html``) to build only the relevant sphinx documentation. If
+ ``LLVM_BUILD_DOCS`` is enabled then the sphinx documentation will also be
+ built as part of the normal build. Enabling this variable also means that if
+ the ``install`` target is invoked then the built documentation will be
+ installed. See :ref:`LLVM-specific variables`.
+
+* Both the Autoconf/Makefile and CMake build systems now generate
+ ``LLVMConfig.cmake`` (and other files) to export installed libraries. This
+ means that projects using CMake to build against LLVM libraries can now build
+ against an installed LLVM built by the Autoconf/Makefile system. See
+ :ref:`Embedding LLVM in your project` for details.
+
+* Use of ``llvm_map_components_to_libraries()`` by external projects is
+ deprecated and the new ``llvm_map_components_to_libnames()`` should be used
+ instead.
+
+External Open Source Projects Using LLVM 3.5
+============================================
+
+An exciting aspect of LLVM is that it is used as an enabling technology for
+a lot of other language and tools projects. This section lists some of the
+projects that have already been updated to work with LLVM 3.5.
+
+LDC - the LLVM-based D compiler
+-------------------------------
+
+`D <http://dlang.org>`_ is a language with C-like syntax and static typing. It
+pragmatically combines efficiency, control, and modeling power, with safety and
+programmer productivity. D supports powerful concepts like Compile-Time Function
+Execution (CTFE) and Template Meta-Programming, provides an innovative approach
+to concurrency and offers many classical paradigms.
+
+`LDC <http://wiki.dlang.org/LDC>`_ uses the frontend from the reference compiler
+combined with LLVM as backend to produce efficient native code. LDC targets
+x86/x86_64 systems like Linux, OS X, FreeBSD and Windows and also Linux/PPC64.
+Ports to other architectures like ARM, AArch64 and MIPS64 are underway.
+
+Portable Computing Language (pocl)
+----------------------------------
+
+In addition to producing an easily portable open source OpenCL
+implementation, another major goal of `pocl <http://portablecl.org/>`_
+is improving performance portability of OpenCL programs with
+compiler optimizations, reducing the need for target-dependent manual
+optimizations. An important part of pocl is a set of LLVM passes used to
+statically parallelize multiple work-items with the kernel compiler, even in
+the presence of work-group barriers. This enables static parallelization of
+the fine-grained static concurrency in the work groups in multiple ways.
+
+TTA-based Co-design Environment (TCE)
+-------------------------------------
+
+`TCE <http://tce.cs.tut.fi/>`_ is a toolset for designing new
+exposed datapath processors based on the Transport triggered architecture (TTA).
+The toolset provides a complete co-design flow from C/C++
+programs down to synthesizable VHDL/Verilog and parallel program binaries.
+Processor customization points include the register files, function units,
+supported operations, and the interconnection network.
+
+TCE uses Clang and LLVM for C/C++/OpenCL C language support, target independent
+optimizations and also for parts of code generation. It generates
+new LLVM-based code generators "on the fly" for the designed processors and
+loads them in to the compiler backend as runtime libraries to avoid
+per-target recompilation of larger parts of the compiler chain.
+
+ISPC
+----
+
+`ISPC <http://ispc.github.io/>`_ is a C-based language based on the SPMD
+(single program, multiple data) programming model that generates efficient
+SIMD code for modern processors without the need for complex analysis and
+autovectorization. The language exploits the concept of âvaryingâ data types,
+which ensure vector-friendly data layout, explicit vectorization and compact
+representation of the program. The project uses the LLVM infrastructure for
+optimization and code generation.
+
+Likely
+------
+
+`Likely <http://www.liblikely.org>`_ is an embeddable just-in-time Lisp for
+image recognition and heterogenous architectures. Algorithms are just-in-time
+compiled using LLVMâs MCJIT infrastructure to execute on single or
+multi-threaded CPUs and potentially OpenCL SPIR or CUDA enabled GPUs. Likely
+exploits the observation that while image processing and statistical learning
+kernels must be written generically to handle any matrix datatype, at runtime
+they tend to be executed repeatedly on the same type. Likely also seeks to
+explore new optimizations for statistical learning algorithms by moving them
+from an offline model generation step to a compile-time simplification of a
+function (the learning algorithm) with constant arguments (the training set).
+
+
+Additional Information
+======================
+
+A wide variety of additional information is available on the `LLVM web page
+<http://llvm.org/>`_, in particular in the `documentation
+<http://llvm.org/docs/>`_ section. The web page also contains versions of the
+API documentation which is up-to-date with the Subversion version of the source
+code. You can access versions of these documents specific to this release by
+going into the ``llvm/docs/`` directory in the LLVM tree.
+
+If you have any questions or comments about LLVM, please feel free to contact
+us via the `mailing lists <http://llvm.org/docs/#maillist>`_.
+
Added: www-releases/trunk/3.5.1/docs/_sources/ReleaseProcess.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/ReleaseProcess.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/ReleaseProcess.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/ReleaseProcess.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,210 @@
+=============================
+How To Validate a New Release
+=============================
+
+.. contents::
+ :local:
+ :depth: 1
+
+Introduction
+============
+
+This document contains information about testing the release candidates that will
+ultimately be the next LLVM release. For more information on how to manage the
+actual release, please refer to :doc:`HowToReleaseLLVM`.
+
+Overview of the Release Process
+-------------------------------
+
+Once the release process starts, the Release Manager will ask for volunteers,
+and it'll be the role of each volunteer to:
+
+* Test and benchmark the previous release
+
+* Test and benchmark each release candidate, comparing to the previous release and candidates
+
+* Identify, reduce and report every regression found during tests and benchmarks
+
+* Make sure the critical bugs get fixed and merged to the next release candidate
+
+Not all bugs or regressions are show-stoppers and it's a bit of a grey area what
+should be fixed before the next candidate and what can wait until the next release.
+
+It'll depend on:
+
+* The severity of the bug, how many people it affects and if it's a regression or a
+ known bug. Known bugs are "unsupported features" and some bugs can be disabled if
+ they have been implemented recently.
+
+* The stage in the release. Less critical bugs should be considered to be fixed between
+ RC1 and RC2, but not so much at the end of it.
+
+* If it's a correctness or a performance regression. Performance regression tends to be
+ taken more lightly than correctness.
+
+.. _scripts:
+
+Scripts
+=======
+
+The scripts are in the ``utils/release`` directory.
+
+test-release.sh
+---------------
+
+This script will check-out, configure and compile LLVM+Clang (+ most add-ons, like ``compiler-rt``,
+``libcxx`` and ``clang-extra-tools``) in three stages, and will test the final stage.
+It'll have installed the final binaries on the Phase3/Releasei(+Asserts) directory, and
+that's the one you should use for the test-suite and other external tests.
+
+To run the script on a specific release candidate run::
+
+ ./test-release.sh \
+ -release 3.3 \
+ -rc 1 \
+ -no-64bit \
+ -test-asserts \
+ -no-compare-files
+
+Each system will require different options. For instance, x86_64 will obviously not need
+``-no-64bit`` while 32-bit systems will, or the script will fail.
+
+The important flags to get right are:
+
+* On the pre-release, you should change ``-rc 1`` to ``-final``. On RC2, change it to ``-rc 2`` and so on.
+
+* On non-release testing, you can use ``-final`` in conjunction with ``-no-checkout``, but you'll have to
+ create the ``final`` directory by hand and link the correct source dir to ``final/llvm.src``.
+
+* For release candidates, you need ``-test-asserts``, or it won't create a "Release+Asserts" directory,
+ which is needed for release testing and benchmarking. This will take twice as long.
+
+* On the final candidate you just need Release builds, and that's the binary directory you'll have to pack.
+
+This script builds three phases of Clang+LLVM twice each (Release and Release+Asserts), so use
+screen or nohup to avoid headaches, since it'll take a long time.
+
+Use the ``--help`` option to see all the options and chose it according to your needs.
+
+
+findRegressions-nightly.py
+--------------------------
+
+TODO
+
+.. _test-suite:
+
+Test Suite
+==========
+
+.. contents::
+ :local:
+
+Follow the `LNT Quick Start Guide <http://llvm.org/docs/lnt/quickstart.html>`__ link on how to set-up the test-suite
+
+The binary location you'll have to use for testing is inside the ``rcN/Phase3/Release+Asserts/llvmCore-REL-RC.install``.
+Link that directory to an easier location and run the test-suite.
+
+An example on the run command line, assuming you created a link from the correct
+install directory to ``~/devel/llvm/install``::
+
+ ./sandbox/bin/python sandbox/bin/lnt runtest \
+ nt \
+ -j4 \
+ --sandbox sandbox \
+ --test-suite ~/devel/llvm/test/test-suite \
+ --cc ~/devel/llvm/install/bin/clang \
+ --cxx ~/devel/llvm/install/bin/clang++
+
+It should have no new regressions, compared to the previous release or release candidate. You don't need to fix
+all the bugs in the test-suite, since they're not necessarily meant to pass on all architectures all the time. This is
+due to the nature of the result checking, which relies on direct comparison, and most of the time, the failures are
+related to bad output checking, rather than bad code generation.
+
+If the errors are in LLVM itself, please report every single regression found as blocker, and all the other bugs
+as important, but not necessarily blocking the release to proceed. They can be set as "known failures" and to be
+fix on a future date.
+
+.. _pre-release-process:
+
+Pre-Release Process
+===================
+
+.. contents::
+ :local:
+
+When the release process is announced on the mailing list, you should prepare
+for the testing, by applying the same testing you'll do on the release candidates,
+on the previous release.
+
+You should:
+
+* Download the previous release sources from http://llvm.org/releases/download.html.
+
+* Run the test-release.sh script on ``final`` mode (change ``-rc 1`` to ``-final``).
+
+* Once all three stages are done, it'll test the final stage.
+
+* Using the ``Phase3/Release+Asserts/llvmCore-MAJ.MIN-final.install`` base, run the test-suite.
+
+If the final phase's ``make check-all`` failed, it's a good idea to also test the
+intermediate stages by going on the obj directory and running ``make check-all`` to find
+if there's at least one stage that passes (helps when reducing the error for bug report
+purposes).
+
+.. _release-process:
+
+Release Process
+===============
+
+.. contents::
+ :local:
+
+When the Release Manager sends you the release candidate, download all sources,
+unzip on the same directory (there will be sym-links from the appropriate places
+to them), and run the release test as above.
+
+You should:
+
+* Download the current candidate sources from where the release manager points you
+ (ex. http://llvm.org/pre-releases/3.3/rc1/).
+
+* Repeat the steps above with ``-rc 1``, ``-rc 2`` etc modes and run the test-suite
+ the same way.
+
+* Compare the results, report all errors on Bugzilla and publish the binary blob
+ where the release manager can grab it.
+
+Once the release manages announces that the latest candidate is the good one, you
+have to pack the ``Release`` (no Asserts) install directory on ``Phase3`` and that
+will be the official binary.
+
+* Rename (or link) ``clang+llvm-REL-ARCH-ENV`` to the .install directory
+
+* Tar that into the same name with ``.tar.gz`` extensioan from outside the directory
+
+* Make it available for the release manager to download
+
+.. _bug-reporting:
+
+Bug Reporting Process
+=====================
+
+.. contents::
+ :local:
+
+If you found regressions or failures when comparing a release candidate with the
+previous release, follow the rules below:
+
+* Critical bugs on compilation should be fixed as soon as possible, possibly before
+ releasing the binary blobs.
+
+* Check-all tests should be fixed before the next release candidate, but can wait
+ until the test-suite run is finished.
+
+* Bugs in the test suite or unimportant check-all tests can be fixed in between
+ release candidates.
+
+* New features or recent big changes, when close to the release, should have done
+ in a way that it's easy to disable. If they misbehave, prefer disabling them than
+ releasing an unstable (but untested) binary package.
Added: www-releases/trunk/3.5.1/docs/_sources/SegmentedStacks.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/SegmentedStacks.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/SegmentedStacks.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/SegmentedStacks.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,77 @@
+========================
+Segmented Stacks in LLVM
+========================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+Segmented stack allows stack space to be allocated incrementally than as a
+monolithic chunk (of some worst case size) at thread initialization. This is
+done by allocating stack blocks (henceforth called *stacklets*) and linking them
+into a doubly linked list. The function prologue is responsible for checking if
+the current stacklet has enough space for the function to execute; and if not,
+call into the libgcc runtime to allocate more stack space. Segmented stacks are
+enabled with the ``"split-stack"`` attribute on LLVM functions.
+
+The runtime functionality is `already there in libgcc
+<http://gcc.gnu.org/wiki/SplitStacks>`_.
+
+Implementation Details
+======================
+
+.. _allocating stacklets:
+
+Allocating Stacklets
+--------------------
+
+As mentioned above, the function prologue checks if the current stacklet has
+enough space. The current approach is to use a slot in the TCB to store the
+current stack limit (minus the amount of space needed to allocate a new block) -
+this slot's offset is again dictated by ``libgcc``. The generated
+assembly looks like this on x86-64:
+
+.. code-block:: nasm
+
+ leaq -8(%rsp), %r10
+ cmpq %fs:112, %r10
+ jg .LBB0_2
+
+ # More stack space needs to be allocated
+ movabsq $8, %r10 # The amount of space needed
+ movabsq $0, %r11 # The total size of arguments passed on stack
+ callq __morestack
+ ret # The reason for this extra return is explained below
+ .LBB0_2:
+ # Usual prologue continues here
+
+The size of function arguments on the stack needs to be passed to
+``__morestack`` (this function is implemented in ``libgcc``) since that number
+of bytes has to be copied from the previous stacklet to the current one. This is
+so that SP (and FP) relative addressing of function arguments work as expected.
+
+The unusual ``ret`` is needed to have the function which made a call to
+``__morestack`` return correctly. ``__morestack``, instead of returning, calls
+into ``.LBB0_2``. This is possible since both, the size of the ``ret``
+instruction and the PC of call to ``__morestack`` are known. When the function
+body returns, control is transferred back to ``__morestack``. ``__morestack``
+then de-allocates the new stacklet, restores the correct SP value, and does a
+second return, which returns control to the correct caller.
+
+Variable Sized Allocas
+----------------------
+
+The section on `allocating stacklets`_ automatically assumes that every stack
+frame will be of fixed size. However, LLVM allows the use of the ``llvm.alloca``
+intrinsic to allocate dynamically sized blocks of memory on the stack. When
+faced with such a variable-sized alloca, code is generated to:
+
+* Check if the current stacklet has enough space. If yes, just bump the SP, like
+ in the normal case.
+* If not, generate a call to ``libgcc``, which allocates the memory from the
+ heap.
+
+The memory allocated from the heap is linked into a list in the current
+stacklet, and freed along with the same. This prevents a memory leak.
Added: www-releases/trunk/3.5.1/docs/_sources/SourceLevelDebugging.txt
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.5.1/docs/_sources/SourceLevelDebugging.txt?rev=225843&view=auto
==============================================================================
--- www-releases/trunk/3.5.1/docs/_sources/SourceLevelDebugging.txt (added)
+++ www-releases/trunk/3.5.1/docs/_sources/SourceLevelDebugging.txt Tue Jan 13 16:55:20 2015
@@ -0,0 +1,2321 @@
+================================
+Source Level Debugging with LLVM
+================================
+
+.. contents::
+ :local:
+
+Introduction
+============
+
+This document is the central repository for all information pertaining to debug
+information in LLVM. It describes the :ref:`actual format that the LLVM debug
+information takes <format>`, which is useful for those interested in creating
+front-ends or dealing directly with the information. Further, this document
+provides specific examples of what debug information for C/C++ looks like.
+
+Philosophy behind LLVM debugging information
+--------------------------------------------
+
+The idea of the LLVM debugging information is to capture how the important
+pieces of the source-language's Abstract Syntax Tree map onto LLVM code.
+Several design aspects have shaped the solution that appears here. The
+important ones are:
+
+* Debugging information should have very little impact on the rest of the
+ compiler. No transformations, analyses, or code generators should need to
+ be modified because of debugging information.
+
+* LLVM optimizations should interact in :ref:`well-defined and easily described
+ ways <intro_debugopt>` with the debugging information.
+
+* Because LLVM is designed to support arbitrary programming languages,
+ LLVM-to-LLVM tools should not need to know anything about the semantics of
+ the source-level-language.
+
+* Source-level languages are often **widely** different from one another.
+ LLVM should not put any restrictions of the flavor of the source-language,
+ and the debugging information should work with any language.
+
+* With code generator support, it should be possible to use an LLVM compiler
+ to compile a program to native machine code and standard debugging
+ formats. This allows compatibility with traditional machine-code level
+ debuggers, like GDB or DBX.
+
+The approach used by the LLVM implementation is to use a small set of
+:ref:`intrinsic functions <format_common_intrinsics>` to define a mapping
+between LLVM program objects and the source-level objects. The description of
+the source-level program is maintained in LLVM metadata in an
+:ref:`implementation-defined format <ccxx_frontend>` (the C/C++ front-end
+currently uses working draft 7 of the `DWARF 3 standard
+<http://www.eagercon.com/dwarf/dwarf3std.htm>`_).
+
+When a program is being debugged, a debugger interacts with the user and turns
+the stored debug information into source-language specific information. As
+such, a debugger must be aware of the source-language, and is thus tied to a
+specific language or family of languages.
+
+Debug information consumers
+---------------------------
+
+The role of debug information is to provide meta information normally stripped
+away during the compilation process. This meta information provides an LLVM
+user a relationship between generated code and the original program source
+code.
+
+Currently, debug information is consumed by DwarfDebug to produce dwarf
+information used by the gdb debugger. Other targets could use the same
+information to produce stabs or other debug forms.
+
+It would also be reasonable to use debug information to feed profiling tools
+for analysis of generated code, or, tools for reconstructing the original
+source from generated code.
+
+TODO - expound a bit more.
+
+.. _intro_debugopt:
+
+Debugging optimized code
+------------------------
+
+An extremely high priority of LLVM debugging information is to make it interact
+well with optimizations and analysis. In particular, the LLVM debug
+information provides the following guarantees:
+
+* LLVM debug information **always provides information to accurately read
+ the source-level state of the program**, regardless of which LLVM
+ optimizations have been run, and without any modification to the
+ optimizations themselves. However, some optimizations may impact the
+ ability to modify the current state of the program with a debugger, such
+ as setting program variables, or calling functions that have been
+ deleted.
+
+* As desired, LLVM optimizations can be upgraded to be aware of the LLVM
+ debugging information, allowing them to update the debugging information
+ as they perform aggressive optimizations. This means that, with effort,
+ the LLVM optimizers could optimize debug code just as well as non-debug
+ code.
+
+* LLVM debug information does not prevent optimizations from
+ happening (for example inlining, basic block reordering/merging/cleanup,
+ tail duplication, etc).
+
+* LLVM debug information is automatically optimized along with the rest of
+ the program, using existing facilities. For example, duplicate
+ information is automatically merged by the linker, and unused information
+ is automatically removed.
+
+Basically, the debug information allows you to compile a program with
+"``-O0 -g``" and get full debug information, allowing you to arbitrarily modify
+the program as it executes from a debugger. Compiling a program with
+"``-O3 -g``" gives you full debug information that is always available and
+accurate for reading (e.g., you get accurate stack traces despite tail call
+elimination and inlining), but you might lose the ability to modify the program
+and call functions where were optimized out of the program, or inlined away
+completely.
+
+:ref:`LLVM test suite <test-suite-quickstart>` provides a framework to test
+optimizer's handling of debugging information. It can be run like this:
+
+.. code-block:: bash
+
+ % cd llvm/projects/test-suite/MultiSource/Benchmarks # or some other level
+ % make TEST=dbgopt
+
+This will test impact of debugging information on optimization passes. If
+debugging information influences optimization passes then it will be reported
+as a failure. See :doc:`TestingGuide` for more information on LLVM test
+infrastructure and how to run various tests.
+
+.. _format:
+
+Debugging information format
+============================
+
+LLVM debugging information has been carefully designed to make it possible for
+the optimizer to optimize the program and debugging information without
+necessarily having to know anything about debugging information. In
+particular, the use of metadata avoids duplicated debugging information from
+the beginning, and the global dead code elimination pass automatically deletes
+debugging information for a function if it decides to delete the function.
+
+To do this, most of the debugging information (descriptors for types,
+variables, functions, source files, etc) is inserted by the language front-end
+in the form of LLVM metadata.
+
+Debug information is designed to be agnostic about the target debugger and
+debugging information representation (e.g. DWARF/Stabs/etc). It uses a generic
+pass to decode the information that represents variables, types, functions,
+namespaces, etc: this allows for arbitrary source-language semantics and
+type-systems to be used, as long as there is a module written for the target
+debugger to interpret the information.
+
+To provide basic functionality, the LLVM debugger does have to make some
+assumptions about the source-level language being debugged, though it keeps
+these to a minimum. The only common features that the LLVM debugger assumes
+exist are :ref:`source files <format_files>`, and :ref:`program objects
+<format_global_variables>`. These abstract objects are used by a debugger to
+form stack traces, show information about local variables, etc.
+
+This section of the documentation first describes the representation aspects
+common to any source-language. :ref:`ccxx_frontend` describes the data layout
+conventions used by the C and C++ front-ends.
+
+Debug information descriptors
+-----------------------------
+
+In consideration of the complexity and volume of debug information, LLVM
+provides a specification for well formed debug descriptors.
+
+Consumers of LLVM debug information expect the descriptors for program objects
+to start in a canonical format, but the descriptors can include additional
+information appended at the end that is source-language specific. All debugging
+information objects start with a tag to indicate what type of object it is.
+The source-language is allowed to define its own objects, by using unreserved
+tag numbers. We recommend using with tags in the range 0x1000 through 0x2000
+(there is a defined ``enum DW_TAG_user_base = 0x1000``.)
+
+The fields of debug descriptors used internally by LLVM are restricted to only
+the simple data types ``i32``, ``i1``, ``float``, ``double``, ``mdstring`` and
+``mdnode``.
+
+.. code-block:: llvm
+
+ !1 = metadata !{
+ i32, ;; A tag
+ ...
+ }
+
+<a name="LLVMDebugVersion">The first field of a descriptor is always an
+``i32`` containing a tag value identifying the content of the descriptor.
+The remaining fields are specific to the descriptor. The values of tags are
+loosely bound to the tag values of DWARF information entries. However, that
+does not restrict the use of the information supplied to DWARF targets.
+
+The details of the various descriptors follow.
+
+Compile unit descriptors
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !0 = metadata !{
+ i32, ;; Tag = 17 (DW_TAG_compile_unit)
+ metadata, ;; Source directory (including trailing slash) & file pair
+ i32, ;; DWARF language identifier (ex. DW_LANG_C89)
+ metadata ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
+ i1, ;; True if this is optimized.
+ metadata, ;; Flags
+ i32 ;; Runtime version
+ metadata ;; List of enums types
+ metadata ;; List of retained types
+ metadata ;; List of subprograms
+ metadata ;; List of global variables
+ metadata ;; List of imported entities
+ metadata ;; Split debug filename
+ }
+
+These descriptors contain a source language ID for the file (we use the DWARF
+3.0 ID numbers, such as ``DW_LANG_C89``, ``DW_LANG_C_plus_plus``,
+``DW_LANG_Cobol74``, etc), a reference to a metadata node containing a pair of
+strings for the source file name and the working directory, as well as an
+identifier string for the compiler that produced it.
+
+Compile unit descriptors provide the root context for objects declared in a
+specific compilation unit. File descriptors are defined using this context.
+These descriptors are collected by a named metadata ``!llvm.dbg.cu``. They
+keep track of subprograms, global variables, type information, and imported
+entities (declarations and namespaces).
+
+.. _format_files:
+
+File descriptors
+^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !0 = metadata !{
+ i32, ;; Tag = 41 (DW_TAG_file_type)
+ metadata, ;; Source directory (including trailing slash) & file pair
+ }
+
+These descriptors contain information for a file. Global variables and top
+level functions would be defined using this context. File descriptors also
+provide context for source line correspondence.
+
+Each input file is encoded as a separate file descriptor in LLVM debugging
+information output.
+
+.. _format_global_variables:
+
+Global variable descriptors
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !1 = metadata !{
+ i32, ;; Tag = 52 (DW_TAG_variable)
+ i32, ;; Unused field.
+ metadata, ;; Reference to context descriptor
+ metadata, ;; Name
+ metadata, ;; Display name (fully qualified C++ name)
+ metadata, ;; MIPS linkage name (for C++)
+ metadata, ;; Reference to file where defined
+ i32, ;; Line number where defined
+ metadata, ;; Reference to type descriptor
+ i1, ;; True if the global is local to compile unit (static)
+ i1, ;; True if the global is defined in the compile unit (not extern)
+ {}*, ;; Reference to the global variable
+ metadata, ;; The static member declaration, if any
+ }
+
+These descriptors provide debug information about global variables. They
+provide details such as name, type and where the variable is defined. All
+global variables are collected inside the named metadata ``!llvm.dbg.cu``.
+
+.. _format_subprograms:
+
+Subprogram descriptors
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32, ;; Tag = 46 (DW_TAG_subprogram)
+ metadata, ;; Source directory (including trailing slash) & file pair
+ metadata, ;; Reference to context descriptor
+ metadata, ;; Name
+ metadata, ;; Display name (fully qualified C++ name)
+ metadata, ;; MIPS linkage name (for C++)
+ i32, ;; Line number where defined
+ metadata, ;; Reference to type descriptor
+ i1, ;; True if the global is local to compile unit (static)
+ i1, ;; True if the global is defined in the compile unit (not extern)
+ i32, ;; Virtuality, e.g. dwarf::DW_VIRTUALITY__virtual
+ i32, ;; Index into a virtual function
+ metadata, ;; indicates which base type contains the vtable pointer for the
+ ;; derived class
+ i32, ;; Flags - Artificial, Private, Protected, Explicit, Prototyped.
+ i1, ;; isOptimized
+ {}*, ;; Reference to the LLVM function
+ metadata, ;; Lists function template parameters
+ metadata, ;; Function declaration descriptor
+ metadata, ;; List of function variables
+ i32 ;; Line number where the scope of the subprogram begins
+ }
+
+These descriptors provide debug information about functions, methods and
+subprograms. They provide details such as name, return types and the source
+location where the subprogram is defined.
+
+Block descriptors
+^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !3 = metadata !{
+ i32, ;; Tag = 11 (DW_TAG_lexical_block)
+ metadata, ;; Source directory (including trailing slash) & file pair
+ metadata, ;; Reference to context descriptor
+ i32, ;; Line number
+ i32, ;; Column number
+ i32, ;; DWARF path discriminator value
+ i32 ;; Unique ID to identify blocks from a template function
+ }
+
+This descriptor provides debug information about nested blocks within a
+subprogram. The line number and column numbers are used to dinstinguish two
+lexical blocks at same depth.
+
+.. code-block:: llvm
+
+ !3 = metadata !{
+ i32, ;; Tag = 11 (DW_TAG_lexical_block)
+ metadata, ;; Source directory (including trailing slash) & file pair
+ metadata ;; Reference to the scope we're annotating with a file change
+ }
+
+This descriptor provides a wrapper around a lexical scope to handle file
+changes in the middle of a lexical block.
+
+.. _format_basic_type:
+
+Basic type descriptors
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !4 = metadata !{
+ i32, ;; Tag = 36 (DW_TAG_base_type)
+ metadata, ;; Source directory (including trailing slash) & file pair (may be null)
+ metadata, ;; Reference to context
+ metadata, ;; Name (may be "" for anonymous types)
+ i32, ;; Line number where defined (may be 0)
+ i64, ;; Size in bits
+ i64, ;; Alignment in bits
+ i64, ;; Offset in bits
+ i32, ;; Flags
+ i32 ;; DWARF type encoding
+ }
+
+These descriptors define primitive types used in the code. Example ``int``,
+``bool`` and ``float``. The context provides the scope of the type, which is
+usually the top level. Since basic types are not usually user defined the
+context and line number can be left as NULL and 0. The size, alignment and
+offset are expressed in bits and can be 64 bit values. The alignment is used
+to round the offset when embedded in a :ref:`composite type
+<format_composite_type>` (example to keep float doubles on 64 bit boundaries).
+The offset is the bit offset if embedded in a :ref:`composite type
+<format_composite_type>`.
+
+The type encoding provides the details of the type. The values are typically
+one of the following:
+
+.. code-block:: llvm
+
+ DW_ATE_address = 1
+ DW_ATE_boolean = 2
+ DW_ATE_float = 4
+ DW_ATE_signed = 5
+ DW_ATE_signed_char = 6
+ DW_ATE_unsigned = 7
+ DW_ATE_unsigned_char = 8
+
+.. _format_derived_type:
+
+Derived type descriptors
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !5 = metadata !{
+ i32, ;; Tag (see below)
+ metadata, ;; Source directory (including trailing slash) & file pair (may be null)
+ metadata, ;; Reference to context
+ metadata, ;; Name (may be "" for anonymous types)
+ i32, ;; Line number where defined (may be 0)
+ i64, ;; Size in bits
+ i64, ;; Alignment in bits
+ i64, ;; Offset in bits
+ i32, ;; Flags to encode attributes, e.g. private
+ metadata, ;; Reference to type derived from
+ metadata, ;; (optional) Name of the Objective C property associated with
+ ;; Objective-C an ivar, or the type of which this
+ ;; pointer-to-member is pointing to members of.
+ metadata, ;; (optional) Name of the Objective C property getter selector.
+ metadata, ;; (optional) Name of the Objective C property setter selector.
+ i32 ;; (optional) Objective C property attributes.
+ }
+
+These descriptors are used to define types derived from other types. The value
+of the tag varies depending on the meaning. The following are possible tag
+values:
+
+.. code-block:: llvm
+
+ DW_TAG_formal_parameter = 5
+ DW_TAG_member = 13
+ DW_TAG_pointer_type = 15
+ DW_TAG_reference_type = 16
+ DW_TAG_typedef = 22
+ DW_TAG_ptr_to_member_type = 31
+ DW_TAG_const_type = 38
+ DW_TAG_volatile_type = 53
+ DW_TAG_restrict_type = 55
+
+``DW_TAG_member`` is used to define a member of a :ref:`composite type
+<format_composite_type>` or :ref:`subprogram <format_subprograms>`. The type
+of the member is the :ref:`derived type <format_derived_type>`.
+``DW_TAG_formal_parameter`` is used to define a member which is a formal
+argument of a subprogram.
+
+``DW_TAG_typedef`` is used to provide a name for the derived type.
+
+``DW_TAG_pointer_type``, ``DW_TAG_reference_type``, ``DW_TAG_const_type``,
+``DW_TAG_volatile_type`` and ``DW_TAG_restrict_type`` are used to qualify the
+:ref:`derived type <format_derived_type>`.
+
+:ref:`Derived type <format_derived_type>` location can be determined from the
+context and line number. The size, alignment and offset are expressed in bits
+and can be 64 bit values. The alignment is used to round the offset when
+embedded in a :ref:`composite type <format_composite_type>` (example to keep
+float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
+in a :ref:`composite type <format_composite_type>`.
+
+Note that the ``void *`` type is expressed as a type derived from NULL.
+
+.. _format_composite_type:
+
+Composite type descriptors
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !6 = metadata !{
+ i32, ;; Tag (see below)
+ metadata, ;; Source directory (including trailing slash) & file pair (may be null)
+ metadata, ;; Reference to context
+ metadata, ;; Name (may be "" for anonymous types)
+ i32, ;; Line number where defined (may be 0)
+ i64, ;; Size in bits
+ i64, ;; Alignment in bits
+ i64, ;; Offset in bits
+ i32, ;; Flags
+ metadata, ;; Reference to type derived from
+ metadata, ;; Reference to array of member descriptors
+ i32, ;; Runtime languages
+ metadata, ;; Base type containing the vtable pointer for this type
+ metadata, ;; Template parameters
+ metadata ;; A unique identifier for type uniquing purpose (may be null)
+ }
+
+These descriptors are used to define types that are composed of 0 or more
+elements. The value of the tag varies depending on the meaning. The following
+are possible tag values:
+
+.. code-block:: llvm
+
+ DW_TAG_array_type = 1
+ DW_TAG_enumeration_type = 4
+ DW_TAG_structure_type = 19
+ DW_TAG_union_type = 23
+ DW_TAG_subroutine_type = 21
+ DW_TAG_inheritance = 28
+
+The vector flag indicates that an array type is a native packed vector.
+
+The members of array types (tag = ``DW_TAG_array_type``) are
+:ref:`subrange descriptors <format_subrange>`, each
+representing the range of subscripts at that level of indexing.
+
+The members of enumeration types (tag = ``DW_TAG_enumeration_type``) are
+:ref:`enumerator descriptors <format_enumerator>`, each representing the
+definition of enumeration value for the set. All enumeration type descriptors
+are collected inside the named metadata ``!llvm.dbg.cu``.
+
+The members of structure (tag = ``DW_TAG_structure_type``) or union (tag =
+``DW_TAG_union_type``) types are any one of the :ref:`basic
+<format_basic_type>`, :ref:`derived <format_derived_type>` or :ref:`composite
+<format_composite_type>` type descriptors, each representing a field member of
+the structure or union.
+
+For C++ classes (tag = ``DW_TAG_structure_type``), member descriptors provide
+information about base classes, static members and member functions. If a
+member is a :ref:`derived type descriptor <format_derived_type>` and has a tag
+of ``DW_TAG_inheritance``, then the type represents a base class. If the member
+of is a :ref:`global variable descriptor <format_global_variables>` then it
+represents a static member. And, if the member is a :ref:`subprogram
+descriptor <format_subprograms>` then it represents a member function. For
+static members and member functions, ``getName()`` returns the members link or
+the C++ mangled name. ``getDisplayName()`` the simplied version of the name.
+
+The first member of subroutine (tag = ``DW_TAG_subroutine_type``) type elements
+is the return type for the subroutine. The remaining elements are the formal
+arguments to the subroutine.
+
+:ref:`Composite type <format_composite_type>` location can be determined from
+the context and line number. The size, alignment and offset are expressed in
+bits and can be 64 bit values. The alignment is used to round the offset when
+embedded in a :ref:`composite type <format_composite_type>` (as an example, to
+keep float doubles on 64 bit boundaries). The offset is the bit offset if
+embedded in a :ref:`composite type <format_composite_type>`.
+
+.. _format_subrange:
+
+Subrange descriptors
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !42 = metadata !{
+ i32, ;; Tag = 33 (DW_TAG_subrange_type)
+ i64, ;; Low value
+ i64 ;; High value
+ }
+
+These descriptors are used to define ranges of array subscripts for an array
+:ref:`composite type <format_composite_type>`. The low value defines the lower
+bounds typically zero for C/C++. The high value is the upper bounds. Values
+are 64 bit. ``High - Low + 1`` is the size of the array. If ``Low > High``
+the array bounds are not included in generated debugging information.
+
+.. _format_enumerator:
+
+Enumerator descriptors
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !6 = metadata !{
+ i32, ;; Tag = 40 (DW_TAG_enumerator)
+ metadata, ;; Name
+ i64 ;; Value
+ }
+
+These descriptors are used to define members of an enumeration :ref:`composite
+type <format_composite_type>`, it associates the name to the value.
+
+Local variables
+^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !7 = metadata !{
+ i32, ;; Tag (see below)
+ metadata, ;; Context
+ metadata, ;; Name
+ metadata, ;; Reference to file where defined
+ i32, ;; 24 bit - Line number where defined
+ ;; 8 bit - Argument number. 1 indicates 1st argument.
+ metadata, ;; Reference to the type descriptor
+ i32, ;; flags
+ metadata ;; (optional) Reference to inline location
+ metadata ;; (optional) Reference to a complex expression (see below)
+ }
+
+These descriptors are used to define variables local to a sub program. The
+value of the tag depends on the usage of the variable:
+
+.. code-block:: llvm
+
+ DW_TAG_auto_variable = 256
+ DW_TAG_arg_variable = 257
+
+An auto variable is any variable declared in the body of the function. An
+argument variable is any variable that appears as a formal argument to the
+function.
+
+The context is either the subprogram or block where the variable is defined.
+Name the source variable name. Context and line indicate where the variable
+was defined. Type descriptor defines the declared type of the variable.
+
+.. _format_common_intrinsics:
+
+Debugger intrinsic functions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+LLVM uses several intrinsic functions (name prefixed with "``llvm.dbg``") to
+provide debug information at various points in generated code.
+
+``llvm.dbg.declare``
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ void %llvm.dbg.declare(metadata, metadata)
+
+This intrinsic provides information about a local element (e.g., variable).
+The first argument is metadata holding the alloca for the variable. The second
+argument is metadata containing a description of the variable.
+
+``llvm.dbg.value``
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ void %llvm.dbg.value(metadata, i64, metadata)
+
+This intrinsic provides information when a user source variable is set to a new
+value. The first argument is the new value (wrapped as metadata). The second
+argument is the offset in the user source variable where the new value is
+written. The third argument is metadata containing a description of the user
+source variable.
+
+Object lifetimes and scoping
+============================
+
+In many languages, the local variables in functions can have their lifetimes or
+scopes limited to a subset of a function. In the C family of languages, for
+example, variables are only live (readable and writable) within the source
+block that they are defined in. In functional languages, values are only
+readable after they have been defined. Though this is a very obvious concept,
+it is non-trivial to model in LLVM, because it has no notion of scoping in this
+sense, and does not want to be tied to a language's scoping rules.
+
+In order to handle this, the LLVM debug format uses the metadata attached to
+llvm instructions to encode line number and scoping information. Consider the
+following C fragment, for example:
+
+.. code-block:: c
+
+ 1. void foo() {
+ 2. int X = 21;
+ 3. int Y = 22;
+ 4. {
+ 5. int Z = 23;
+ 6. Z = X;
+ 7. }
+ 8. X = Y;
+ 9. }
+
+Compiled to LLVM, this function would be represented like this:
+
+.. code-block:: llvm
+
+ define void @foo() #0 {
+ entry:
+ %X = alloca i32, align 4
+ %Y = alloca i32, align 4
+ %Z = alloca i32, align 4
+ call void @llvm.dbg.declare(metadata !{i32* %X}, metadata !10), !dbg !12
+ ; [debug line = 2:7] [debug variable = X]
+ store i32 21, i32* %X, align 4, !dbg !12
+ call void @llvm.dbg.declare(metadata !{i32* %Y}, metadata !13), !dbg !14
+ ; [debug line = 3:7] [debug variable = Y]
+ store i32 22, i32* %Y, align 4, !dbg !14
+ call void @llvm.dbg.declare(metadata !{i32* %Z}, metadata !15), !dbg !17
+ ; [debug line = 5:9] [debug variable = Z]
+ store i32 23, i32* %Z, align 4, !dbg !17
+ %0 = load i32* %X, align 4, !dbg !18
+ [debug line = 6:5]
+ store i32 %0, i32* %Z, align 4, !dbg !18
+ %1 = load i32* %Y, align 4, !dbg !19
+ [debug line = 8:3]
+ store i32 %1, i32* %X, align 4, !dbg !19
+ ret void, !dbg !20
+ }
+
+ ; Function Attrs: nounwind readnone
+ declare void @llvm.dbg.declare(metadata, metadata) #1
+
+ attributes #0 = { nounwind ssp uwtable "less-precise-fpmad"="false"
+ "no-frame-pointer-elim"="true" "no-frame-pointer-elim-non-leaf"
+ "no-infs-fp-math"="false" "no-nans-fp-math"="false"
+ "stack-protector-buffer-size"="8" "unsafe-fp-math"="false"
+ "use-soft-float"="false" }
+ attributes #1 = { nounwind readnone }
+
+ !llvm.dbg.cu = !{!0}
+ !llvm.module.flags = !{!8}
+ !llvm.ident = !{!9}
+
+ !0 = metadata !{i32 786449, metadata !1, i32 12,
+ metadata !"clang version 3.4 (trunk 193128) (llvm/trunk 193139)",
+ i1 false, metadata !"", i32 0, metadata !2, metadata !2, metadata !3,
+ metadata !2, metadata !2, metadata !""} ; [ DW_TAG_compile_unit ] \
+ [/private/tmp/foo.c] \
+ [DW_LANG_C99]
+ !1 = metadata !{metadata !"t.c", metadata !"/private/tmp"}
+ !2 = metadata !{i32 0}
+ !3 = metadata !{metadata !4}
+ !4 = metadata !{i32 786478, metadata !1, metadata !5, metadata !"foo",
+ metadata !"foo", metadata !"", i32 1, metadata !6,
+ i1 false, i1 true, i32 0, i32 0, null, i32 0, i1 false,
+ void ()* @foo, null, null, metadata !2, i32 1}
+ ; [ DW_TAG_subprogram ] [line 1] [def] [foo]
+ !5 = metadata !{i32 786473, metadata !1} ; [ DW_TAG_file_type ] \
+ [/private/tmp/t.c]
+ !6 = metadata !{i32 786453, i32 0, null, metadata !"", i32 0, i64 0, i64 0,
+ i64 0, i32 0, null, metadata !7, i32 0, null, null, null}
+ ; [ DW_TAG_subroutine_type ] \
+ [line 0, size 0, align 0, offset 0] [from ]
+ !7 = metadata !{null}
+ !8 = metadata !{i32 2, metadata !"Dwarf Version", i32 2}
+ !9 = metadata !{metadata !"clang version 3.4 (trunk 193128) (llvm/trunk 193139)"}
+ !10 = metadata !{i32 786688, metadata !4, metadata !"X", metadata !5, i32 2,
+ metadata !11, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [X] \
+ [line 2]
+ !11 = metadata !{i32 786468, null, null, metadata !"int", i32 0, i64 32,
+ i64 32, i64 0, i32 0, i32 5} ; [ DW_TAG_base_type ] [int] \
+ [line 0, size 32, align 32, offset 0, enc DW_ATE_signed]
+ !12 = metadata !{i32 2, i32 0, metadata !4, null}
+ !13 = metadata !{i32 786688, metadata !4, metadata !"Y", metadata !5, i32 3,
+ metadata !11, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [Y] \
+ [line 3]
+ !14 = metadata !{i32 3, i32 0, metadata !4, null}
+ !15 = metadata !{i32 786688, metadata !16, metadata !"Z", metadata !5, i32 5,
+ metadata !11, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [Z] \
+ [line 5]
+ !16 = metadata !{i32 786443, metadata !1, metadata !4, i32 4, i32 0, i32 0,
+ i32 0} \
+ ; [ DW_TAG_lexical_block ] [/private/tmp/t.c]
+ !17 = metadata !{i32 5, i32 0, metadata !16, null}
+ !18 = metadata !{i32 6, i32 0, metadata !16, null}
+ !19 = metadata !{i32 8, i32 0, metadata !4, null} ; [ DW_TAG_imported_declaration ]
+ !20 = metadata !{i32 9, i32 0, metadata !4, null}
+
+This example illustrates a few important details about LLVM debugging
+information. In particular, it shows how the ``llvm.dbg.declare`` intrinsic and
+location information, which are attached to an instruction, are applied
+together to allow a debugger to analyze the relationship between statements,
+variable definitions, and the code used to implement the function.
+
+.. code-block:: llvm
+
+ call void @llvm.dbg.declare(metadata !{i32* %X}, metadata !10), !dbg !12
+ ; [debug line = 2:7] [debug variable = X]
+
+The first intrinsic ``%llvm.dbg.declare`` encodes debugging information for the
+variable ``X``. The metadata ``!dbg !12`` attached to the intrinsic provides
+scope information for the variable ``X``.
+
+.. code-block:: llvm
+
+ !12 = metadata !{i32 2, i32 0, metadata !4, null}
+ !4 = metadata !{i32 786478, metadata !1, metadata !5, metadata !"foo",
+ metadata !"foo", metadata !"", i32 1, metadata !6,
+ i1 false, i1 true, i32 0, i32 0, null, i32 0, i1 false,
+ void ()* @foo, null, null, metadata !2, i32 1}
+ ; [ DW_TAG_subprogram ] [line 1] [def] [foo]
+
+Here ``!12`` is metadata providing location information. It has four fields:
+line number, column number, scope, and original scope. The original scope
+represents inline location if this instruction is inlined inside a caller, and
+is null otherwise. In this example, scope is encoded by ``!4``, a
+:ref:`subprogram descriptor <format_subprograms>`. This way the location
+information attached to the intrinsics indicates that the variable ``X`` is
+declared at line number 2 at a function level scope in function ``foo``.
+
+Now lets take another example.
+
+.. code-block:: llvm
+
+ call void @llvm.dbg.declare(metadata !{i32* %Z}, metadata !15), !dbg !17
+ ; [debug line = 5:9] [debug variable = Z]
+
+The third intrinsic ``%llvm.dbg.declare`` encodes debugging information for
+variable ``Z``. The metadata ``!dbg !17`` attached to the intrinsic provides
+scope information for the variable ``Z``.
+
+.. code-block:: llvm
+
+ !16 = metadata !{i32 786443, metadata !1, metadata !4, i32 4, i32 0, i32 0,
+ i32 0}
+ ; [ DW_TAG_lexical_block ] [/private/tmp/t.c]
+ !17 = metadata !{i32 5, i32 0, metadata !16, null}
+
+Here ``!15`` indicates that ``Z`` is declared at line number 5 and
+column number 0 inside of lexical scope ``!16``. The lexical scope itself
+resides inside of subprogram ``!4`` described above.
+
+The scope information attached with each instruction provides a straightforward
+way to find instructions covered by a scope.
+
+.. _ccxx_frontend:
+
+C/C++ front-end specific debug information
+==========================================
+
+The C and C++ front-ends represent information about the program in a format
+that is effectively identical to `DWARF 3.0
+<http://www.eagercon.com/dwarf/dwarf3std.htm>`_ in terms of information
+content. This allows code generators to trivially support native debuggers by
+generating standard dwarf information, and contains enough information for
+non-dwarf targets to translate it as needed.
+
+This section describes the forms used to represent C and C++ programs. Other
+languages could pattern themselves after this (which itself is tuned to
+representing programs in the same way that DWARF 3 does), or they could choose
+to provide completely different forms if they don't fit into the DWARF model.
+As support for debugging information gets added to the various LLVM
+source-language front-ends, the information used should be documented here.
+
+The following sections provide examples of various C/C++ constructs and the
+debug information that would best describe those constructs.
+
+C/C++ source file information
+-----------------------------
+
+Given the source files ``MySource.cpp`` and ``MyHeader.h`` located in the
+directory ``/Users/mine/sources``, the following code:
+
+.. code-block:: c
+
+ #include "MyHeader.h"
+
+ int main(int argc, char *argv[]) {
+ return 0;
+ }
+
+a C/C++ front-end would generate the following descriptors:
+
+.. code-block:: llvm
+
+ ...
+ ;;
+ ;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".
+ ;;
+ !0 = metadata !{
+ i32 786449, ;; Tag
+ metadata !1, ;; File/directory name
+ i32 4, ;; Language Id
+ metadata !"clang version 3.4 ",
+ i1 false, ;; Optimized compile unit
+ metadata !"", ;; Compiler flags
+ i32 0, ;; Runtime version
+ metadata !2, ;; Enumeration types
+ metadata !2, ;; Retained types
+ metadata !3, ;; Subprograms
+ metadata !2, ;; Global variables
+ metadata !2, ;; Imported entities (declarations and namespaces)
+ metadata !"" ;; Split debug filename
+ }
+
+ ;;
+ ;; Define the file for the file "/Users/mine/sources/MySource.cpp".
+ ;;
+ !1 = metadata !{
+ metadata !"MySource.cpp",
+ metadata !"/Users/mine/sources"
+ }
+ !5 = metadata !{
+ i32 786473, ;; Tag
+ metadata !1
+ }
+
+ ;;
+ ;; Define the file for the file "/Users/mine/sources/Myheader.h"
+ ;;
+ !14 = metadata !{
+ i32 786473, ;; Tag
+ metadata !15
+ }
+ !15 = metadata !{
+ metadata !"./MyHeader.h",
+ metadata !"/Users/mine/sources",
+ }
+
+ ...
+
+``llvm::Instruction`` provides easy access to metadata attached with an
+instruction. One can extract line number information encoded in LLVM IR using
+``Instruction::getMetadata()`` and ``DILocation::getLineNumber()``.
+
+.. code-block:: c++
+
+ if (MDNode *N = I->getMetadata("dbg")) { // Here I is an LLVM instruction
+ DILocation Loc(N); // DILocation is in DebugInfo.h
+ unsigned Line = Loc.getLineNumber();
+ StringRef File = Loc.getFilename();
+ StringRef Dir = Loc.getDirectory();
+ }
+
+C/C++ global variable information
+---------------------------------
+
+Given an integer global variable declared as follows:
+
+.. code-block:: c
+
+ int MyGlobal = 100;
+
+a C/C++ front-end would generate the following descriptors:
+
+.. code-block:: llvm
+
+ ;;
+ ;; Define the global itself.
+ ;;
+ %MyGlobal = global int 100
+ ...
+ ;;
+ ;; List of debug info of globals
+ ;;
+ !llvm.dbg.cu = !{!0}
+
+ ;; Define the compile unit.
+ !0 = metadata !{
+ i32 786449, ;; Tag
+ i32 0, ;; Context
+ i32 4, ;; Language
+ metadata !"foo.cpp", ;; File
+ metadata !"/Volumes/Data/tmp", ;; Directory
+ metadata !"clang version 3.1 ", ;; Producer
+ i1 true, ;; Deprecated field
+ i1 false, ;; "isOptimized"?
+ metadata !"", ;; Flags
+ i32 0, ;; Runtime Version
+ metadata !1, ;; Enum Types
+ metadata !1, ;; Retained Types
+ metadata !1, ;; Subprograms
+ metadata !3, ;; Global Variables
+ metadata !1, ;; Imported entities
+ "", ;; Split debug filename
+ } ; [ DW_TAG_compile_unit ]
+
+ ;; The Array of Global Variables
+ !3 = metadata !{
+ metadata !4
+ }
+
+ ;;
+ ;; Define the global variable itself.
+ ;;
+ !4 = metadata !{
+ i32 786484, ;; Tag
+ i32 0, ;; Unused
+ null, ;; Unused
+ metadata !"MyGlobal", ;; Name
+ metadata !"MyGlobal", ;; Display Name
+ metadata !"", ;; Linkage Name
+ metadata !6, ;; File
+ i32 1, ;; Line
+ metadata !7, ;; Type
+ i32 0, ;; IsLocalToUnit
+ i32 1, ;; IsDefinition
+ i32* @MyGlobal, ;; LLVM-IR Value
+ null ;; Static member declaration
+ } ; [ DW_TAG_variable ]
+
+ ;;
+ ;; Define the file
+ ;;
+ !5 = metadata !{
+ metadata !"foo.cpp", ;; File
+ metadata !"/Volumes/Data/tmp", ;; Directory
+ }
+ !6 = metadata !{
+ i32 786473, ;; Tag
+ metadata !5 ;; Unused
+ } ; [ DW_TAG_file_type ]
+
+ ;;
+ ;; Define the type
+ ;;
+ !7 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; Unused
+ null, ;; Unused
+ metadata !"int", ;; Name
+ i32 0, ;; Line
+ i64 32, ;; Size in Bits
+ i64 32, ;; Align in Bits
+ i64 0, ;; Offset
+ i32 0, ;; Flags
+ i32 5 ;; Encoding
+ } ; [ DW_TAG_base_type ]
+
+C/C++ function information
+--------------------------
+
+Given a function declared as follows:
+
+.. code-block:: c
+
+ int main(int argc, char *argv[]) {
+ return 0;
+ }
+
+a C/C++ front-end would generate the following descriptors:
+
+.. code-block:: llvm
+
+ ;;
+ ;; Define the anchor for subprograms.
+ ;;
+ !6 = metadata !{
+ i32 786484, ;; Tag
+ metadata !1, ;; File
+ metadata !1, ;; Context
+ metadata !"main", ;; Name
+ metadata !"main", ;; Display name
+ metadata !"main", ;; Linkage name
+ i32 1, ;; Line number
+ metadata !4, ;; Type
+ i1 false, ;; Is local
+ i1 true, ;; Is definition
+ i32 0, ;; Virtuality attribute, e.g. pure virtual function
+ i32 0, ;; Index into virtual table for C++ methods
+ i32 0, ;; Type that holds virtual table.
+ i32 0, ;; Flags
+ i1 false, ;; True if this function is optimized
+ Function *, ;; Pointer to llvm::Function
+ null, ;; Function template parameters
+ null, ;; List of function variables (emitted when optimizing)
+ 1 ;; Line number of the opening '{' of the function
+ }
+ ;;
+ ;; Define the subprogram itself.
+ ;;
+ define i32 @main(i32 %argc, i8** %argv) {
+ ...
+ }
+
+C/C++ basic types
+-----------------
+
+The following are the basic type descriptors for C/C++ core types:
+
+bool
+^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"bool", ;; Name
+ i32 0, ;; Line number
+ i64 8, ;; Size in Bits
+ i64 8, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 2 ;; Encoding
+ }
+
+char
+^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"char", ;; Name
+ i32 0, ;; Line number
+ i64 8, ;; Size in Bits
+ i64 8, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 6 ;; Encoding
+ }
+
+unsigned char
+^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"unsigned char",
+ i32 0, ;; Line number
+ i64 8, ;; Size in Bits
+ i64 8, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 8 ;; Encoding
+ }
+
+short
+^^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"short int",
+ i32 0, ;; Line number
+ i64 16, ;; Size in Bits
+ i64 16, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 5 ;; Encoding
+ }
+
+unsigned short
+^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"short unsigned int",
+ i32 0, ;; Line number
+ i64 16, ;; Size in Bits
+ i64 16, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 7 ;; Encoding
+ }
+
+int
+^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"int", ;; Name
+ i32 0, ;; Line number
+ i64 32, ;; Size in Bits
+ i64 32, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 5 ;; Encoding
+ }
+
+unsigned int
+^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"unsigned int",
+ i32 0, ;; Line number
+ i64 32, ;; Size in Bits
+ i64 32, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 7 ;; Encoding
+ }
+
+long long
+^^^^^^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"long long int",
+ i32 0, ;; Line number
+ i64 64, ;; Size in Bits
+ i64 64, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 5 ;; Encoding
+ }
+
+unsigned long long
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"long long unsigned int",
+ i32 0, ;; Line number
+ i64 64, ;; Size in Bits
+ i64 64, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 7 ;; Encoding
+ }
+
+float
+^^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"float",
+ i32 0, ;; Line number
+ i64 32, ;; Size in Bits
+ i64 32, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 4 ;; Encoding
+ }
+
+double
+^^^^^^
+
+.. code-block:: llvm
+
+ !2 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"double",;; Name
+ i32 0, ;; Line number
+ i64 64, ;; Size in Bits
+ i64 64, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 4 ;; Encoding
+ }
+
+C/C++ derived types
+-------------------
+
+Given the following as an example of C/C++ derived type:
+
+.. code-block:: c
+
+ typedef const int *IntPtr;
+
+a C/C++ front-end would generate the following descriptors:
+
+.. code-block:: llvm
+
+ ;;
+ ;; Define the typedef "IntPtr".
+ ;;
+ !2 = metadata !{
+ i32 786454, ;; Tag
+ metadata !3, ;; File
+ metadata !1, ;; Context
+ metadata !"IntPtr", ;; Name
+ i32 0, ;; Line number
+ i64 0, ;; Size in bits
+ i64 0, ;; Align in bits
+ i64 0, ;; Offset in bits
+ i32 0, ;; Flags
+ metadata !4 ;; Derived From type
+ }
+ ;;
+ ;; Define the pointer type.
+ ;;
+ !4 = metadata !{
+ i32 786447, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"", ;; Name
+ i32 0, ;; Line number
+ i64 64, ;; Size in bits
+ i64 64, ;; Align in bits
+ i64 0, ;; Offset in bits
+ i32 0, ;; Flags
+ metadata !5 ;; Derived From type
+ }
+ ;;
+ ;; Define the const type.
+ ;;
+ !5 = metadata !{
+ i32 786470, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"", ;; Name
+ i32 0, ;; Line number
+ i64 0, ;; Size in bits
+ i64 0, ;; Align in bits
+ i64 0, ;; Offset in bits
+ i32 0, ;; Flags
+ metadata !6 ;; Derived From type
+ }
+ ;;
+ ;; Define the int type.
+ ;;
+ !6 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"int", ;; Name
+ i32 0, ;; Line number
+ i64 32, ;; Size in bits
+ i64 32, ;; Align in bits
+ i64 0, ;; Offset in bits
+ i32 0, ;; Flags
+ i32 5 ;; Encoding
+ }
+
+C/C++ struct/union types
+------------------------
+
+Given the following as an example of C/C++ struct type:
+
+.. code-block:: c
+
+ struct Color {
+ unsigned Red;
+ unsigned Green;
+ unsigned Blue;
+ };
+
+a C/C++ front-end would generate the following descriptors:
+
+.. code-block:: llvm
+
+ ;;
+ ;; Define basic type for unsigned int.
+ ;;
+ !5 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; File
+ null, ;; Context
+ metadata !"unsigned int",
+ i32 0, ;; Line number
+ i64 32, ;; Size in Bits
+ i64 32, ;; Align in Bits
+ i64 0, ;; Offset in Bits
+ i32 0, ;; Flags
+ i32 7 ;; Encoding
+ }
+ ;;
+ ;; Define composite type for struct Color.
+ ;;
+ !2 = metadata !{
+ i32 786451, ;; Tag
+ metadata !1, ;; Compile unit
+ null, ;; Context
+ metadata !"Color", ;; Name
+ i32 1, ;; Line number
+ i64 96, ;; Size in bits
+ i64 32, ;; Align in bits
+ i64 0, ;; Offset in bits
+ i32 0, ;; Flags
+ null, ;; Derived From
+ metadata !3, ;; Elements
+ i32 0, ;; Runtime Language
+ null, ;; Base type containing the vtable pointer for this type
+ null ;; Template parameters
+ }
+
+ ;;
+ ;; Define the Red field.
+ ;;
+ !4 = metadata !{
+ i32 786445, ;; Tag
+ metadata !1, ;; File
+ metadata !1, ;; Context
+ metadata !"Red", ;; Name
+ i32 2, ;; Line number
+ i64 32, ;; Size in bits
+ i64 32, ;; Align in bits
+ i64 0, ;; Offset in bits
+ i32 0, ;; Flags
+ metadata !5 ;; Derived From type
+ }
+
+ ;;
+ ;; Define the Green field.
+ ;;
+ !6 = metadata !{
+ i32 786445, ;; Tag
+ metadata !1, ;; File
+ metadata !1, ;; Context
+ metadata !"Green", ;; Name
+ i32 3, ;; Line number
+ i64 32, ;; Size in bits
+ i64 32, ;; Align in bits
+ i64 32, ;; Offset in bits
+ i32 0, ;; Flags
+ metadata !5 ;; Derived From type
+ }
+
+ ;;
+ ;; Define the Blue field.
+ ;;
+ !7 = metadata !{
+ i32 786445, ;; Tag
+ metadata !1, ;; File
+ metadata !1, ;; Context
+ metadata !"Blue", ;; Name
+ i32 4, ;; Line number
+ i64 32, ;; Size in bits
+ i64 32, ;; Align in bits
+ i64 64, ;; Offset in bits
+ i32 0, ;; Flags
+ metadata !5 ;; Derived From type
+ }
+
+ ;;
+ ;; Define the array of fields used by the composite type Color.
+ ;;
+ !3 = metadata !{metadata !4, metadata !6, metadata !7}
+
+C/C++ enumeration types
+-----------------------
+
+Given the following as an example of C/C++ enumeration type:
+
+.. code-block:: c
+
+ enum Trees {
+ Spruce = 100,
+ Oak = 200,
+ Maple = 300
+ };
+
+a C/C++ front-end would generate the following descriptors:
+
+.. code-block:: llvm
+
+ ;;
+ ;; Define composite type for enum Trees
+ ;;
+ !2 = metadata !{
+ i32 786436, ;; Tag
+ metadata !1, ;; File
+ metadata !1, ;; Context
+ metadata !"Trees", ;; Name
+ i32 1, ;; Line number
+ i64 32, ;; Size in bits
+ i64 32, ;; Align in bits
+ i64 0, ;; Offset in bits
+ i32 0, ;; Flags
+ null, ;; Derived From type
+ metadata !3, ;; Elements
+ i32 0 ;; Runtime language
+ }
+
+ ;;
+ ;; Define the array of enumerators used by composite type Trees.
+ ;;
+ !3 = metadata !{metadata !4, metadata !5, metadata !6}
+
+ ;;
+ ;; Define Spruce enumerator.
+ ;;
+ !4 = metadata !{i32 786472, metadata !"Spruce", i64 100}
+
+ ;;
+ ;; Define Oak enumerator.
+ ;;
+ !5 = metadata !{i32 786472, metadata !"Oak", i64 200}
+
+ ;;
+ ;; Define Maple enumerator.
+ ;;
+ !6 = metadata !{i32 786472, metadata !"Maple", i64 300}
+
+Debugging information format
+============================
+
+Debugging Information Extension for Objective C Properties
+----------------------------------------------------------
+
+Introduction
+^^^^^^^^^^^^
+
+Objective C provides a simpler way to declare and define accessor methods using
+declared properties. The language provides features to declare a property and
+to let compiler synthesize accessor methods.
+
+The debugger lets developer inspect Objective C interfaces and their instance
+variables and class variables. However, the debugger does not know anything
+about the properties defined in Objective C interfaces. The debugger consumes
+information generated by compiler in DWARF format. The format does not support
+encoding of Objective C properties. This proposal describes DWARF extensions to
+encode Objective C properties, which the debugger can use to let developers
+inspect Objective C properties.
+
+Proposal
+^^^^^^^^
+
+Objective C properties exist separately from class members. A property can be
+defined only by "setter" and "getter" selectors, and be calculated anew on each
+access. Or a property can just be a direct access to some declared ivar.
+Finally it can have an ivar "automatically synthesized" for it by the compiler,
+in which case the property can be referred to in user code directly using the
+standard C dereference syntax as well as through the property "dot" syntax, but
+there is no entry in the ``@interface`` declaration corresponding to this ivar.
+
+To facilitate debugging, these properties we will add a new DWARF TAG into the
+``DW_TAG_structure_type`` definition for the class to hold the description of a
+given property, and a set of DWARF attributes that provide said description.
+The property tag will also contain the name and declared type of the property.
+
+If there is a related ivar, there will also be a DWARF property attribute placed
+in the ``DW_TAG_member`` DIE for that ivar referring back to the property TAG
+for that property. And in the case where the compiler synthesizes the ivar
+directly, the compiler is expected to generate a ``DW_TAG_member`` for that
+ivar (with the ``DW_AT_artificial`` set to 1), whose name will be the name used
+to access this ivar directly in code, and with the property attribute pointing
+back to the property it is backing.
+
+The following examples will serve as illustration for our discussion:
+
+.. code-block:: objc
+
+ @interface I1 {
+ int n2;
+ }
+
+ @property int p1;
+ @property int p2;
+ @end
+
+ @implementation I1
+ @synthesize p1;
+ @synthesize p2 = n2;
+ @end
+
+This produces the following DWARF (this is a "pseudo dwarfdump" output):
+
+.. code-block:: none
+
+ 0x00000100: TAG_structure_type [7] *
+ AT_APPLE_runtime_class( 0x10 )
+ AT_name( "I1" )
+ AT_decl_file( "Objc_Property.m" )
+ AT_decl_line( 3 )
+
+ 0x00000110 TAG_APPLE_property
+ AT_name ( "p1" )
+ AT_type ( {0x00000150} ( int ) )
+
+ 0x00000120: TAG_APPLE_property
+ AT_name ( "p2" )
+ AT_type ( {0x00000150} ( int ) )
+
+ 0x00000130: TAG_member [8]
+ AT_name( "_p1" )
+ AT_APPLE_property ( {0x00000110} "p1" )
+ AT_type( {0x00000150} ( int ) )
+ AT_artificial ( 0x1 )
+
+ 0x00000140: TAG_member [8]
+ AT_name( "n2" )
+ AT_APPLE_property ( {0x00000120} "p2" )
+ AT_type( {0x00000150} ( int ) )
+
+ 0x00000150: AT_type( ( int ) )
+
+Note, the current convention is that the name of the ivar for an
+auto-synthesized property is the name of the property from which it derives
+with an underscore prepended, as is shown in the example. But we actually
+don't need to know this convention, since we are given the name of the ivar
+directly.
+
+Also, it is common practice in ObjC to have different property declarations in
+the @interface and @implementation - e.g. to provide a read-only property in
+the interface,and a read-write interface in the implementation. In that case,
+the compiler should emit whichever property declaration will be in force in the
+current translation unit.
+
+Developers can decorate a property with attributes which are encoded using
+``DW_AT_APPLE_property_attribute``.
+
+.. code-block:: objc
+
+ @property (readonly, nonatomic) int pr;
+
+.. code-block:: none
+
+ TAG_APPLE_property [8]
+ AT_name( "pr" )
+ AT_type ( {0x00000147} (int) )
+ AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)
+
+The setter and getter method names are attached to the property using
+``DW_AT_APPLE_property_setter`` and ``DW_AT_APPLE_property_getter`` attributes.
+
+.. code-block:: objc
+
+ @interface I1
+ @property (setter=myOwnP3Setter:) int p3;
+ -(void)myOwnP3Setter:(int)a;
+ @end
+
+ @implementation I1
+ @synthesize p3;
+ -(void)myOwnP3Setter:(int)a{ }
+ @end
+
+The DWARF for this would be:
+
+.. code-block:: none
+
+ 0x000003bd: TAG_structure_type [7] *
+ AT_APPLE_runtime_class( 0x10 )
+ AT_name( "I1" )
+ AT_decl_file( "Objc_Property.m" )
+ AT_decl_line( 3 )
+
+ 0x000003cd TAG_APPLE_property
+ AT_name ( "p3" )
+ AT_APPLE_property_setter ( "myOwnP3Setter:" )
+ AT_type( {0x00000147} ( int ) )
+
+ 0x000003f3: TAG_member [8]
+ AT_name( "_p3" )
+ AT_type ( {0x00000147} ( int ) )
+ AT_APPLE_property ( {0x000003cd} )
+ AT_artificial ( 0x1 )
+
+New DWARF Tags
+^^^^^^^^^^^^^^
+
++-----------------------+--------+
+| TAG | Value |
++=======================+========+
+| DW_TAG_APPLE_property | 0x4200 |
++-----------------------+--------+
+
+New DWARF Attributes
+^^^^^^^^^^^^^^^^^^^^
+
++--------------------------------+--------+-----------+
+| Attribute | Value | Classes |
++================================+========+===========+
+| DW_AT_APPLE_property | 0x3fed | Reference |
++--------------------------------+--------+-----------+
+| DW_AT_APPLE_property_getter | 0x3fe9 | String |
++--------------------------------+--------+-----------+
+| DW_AT_APPLE_property_setter | 0x3fea | String |
++--------------------------------+--------+-----------+
+| DW_AT_APPLE_property_attribute | 0x3feb | Constant |
++--------------------------------+--------+-----------+
+
+New DWARF Constants
+^^^^^^^^^^^^^^^^^^^
+
++--------------------------------+-------+
+| Name | Value |
++================================+=======+
+| DW_AT_APPLE_PROPERTY_readonly | 0x1 |
++--------------------------------+-------+
+| DW_AT_APPLE_PROPERTY_readwrite | 0x2 |
++--------------------------------+-------+
+| DW_AT_APPLE_PROPERTY_assign | 0x4 |
++--------------------------------+-------+
+| DW_AT_APPLE_PROPERTY_retain | 0x8 |
++--------------------------------+-------+
+| DW_AT_APPLE_PROPERTY_copy | 0x10 |
++--------------------------------+-------+
+| DW_AT_APPLE_PROPERTY_nonatomic | 0x20 |
++--------------------------------+-------+
+
+Name Accelerator Tables
+-----------------------
+
+Introduction
+^^^^^^^^^^^^
+
+The "``.debug_pubnames``" and "``.debug_pubtypes``" formats are not what a
+debugger needs. The "``pub``" in the section name indicates that the entries
+in the table are publicly visible names only. This means no static or hidden
+functions show up in the "``.debug_pubnames``". No static variables or private
+class variables are in the "``.debug_pubtypes``". Many compilers add different
+things to these tables, so we can't rely upon the contents between gcc, icc, or
+clang.
+
+The typical query given by users tends not to match up with the contents of
+these tables. For example, the DWARF spec states that "In the case of the name
+of a function member or static data member of a C++ structure, class or union,
+the name presented in the "``.debug_pubnames``" section is not the simple name
+given by the ``DW_AT_name attribute`` of the referenced debugging information
+entry, but rather the fully qualified name of the data or function member."
+So the only names in these tables for complex C++ entries is a fully
+qualified name. Debugger users tend not to enter their search strings as
+"``a::b::c(int,const Foo&) const``", but rather as "``c``", "``b::c``" , or
+"``a::b::c``". So the name entered in the name table must be demangled in
+order to chop it up appropriately and additional names must be manually entered
+into the table to make it effective as a name lookup table for debuggers to
+se.
+
+All debuggers currently ignore the "``.debug_pubnames``" table as a result of
+its inconsistent and useless public-only name content making it a waste of
+space in the object file. These tables, when they are written to disk, are not
+sorted in any way, leaving every debugger to do its own parsing and sorting.
+These tables also include an inlined copy of the string values in the table
+itself making the tables much larger than they need to be on disk, especially
+for large C++ programs.
+
+Can't we just fix the sections by adding all of the names we need to this
+table? No, because that is not what the tables are defined to contain and we
+won't know the difference between the old bad tables and the new good tables.
+At best we could make our own renamed sections that contain all of the data we
+need.
+
+These tables are also insufficient for what a debugger like LLDB needs. LLDB
+uses clang for its expression parsing where LLDB acts as a PCH. LLDB is then
+often asked to look for type "``foo``" or namespace "``bar``", or list items in
+namespace "``baz``". Namespaces are not included in the pubnames or pubtypes
+tables. Since clang asks a lot of questions when it is parsing an expression,
+we need to be very fast when looking up names, as it happens a lot. Having new
+accelerator tables that are optimized for very quick lookups will benefit this
+type of debugging experience greatly.
+
+We would like to generate name lookup tables that can be mapped into memory
+from disk, and used as is, with little or no up-front parsing. We would also
+be able to control the exact content of these different tables so they contain
+exactly what we need. The Name Accelerator Tables were designed to fix these
+issues. In order to solve these issues we need to:
+
+* Have a format that can be mapped into memory from disk and used as is
+* Lookups should be very fast
+* Extensible table format so these tables can be made by many producers
+* Contain all of the names needed for typical lookups out of the box
+* Strict rules for the contents of tables
+
+Table size is important and the accelerator table format should allow the reuse
+of strings from common string tables so the strings for the names are not
+duplicated. We also want to make sure the table is ready to be used as-is by
+simply mapping the table into memory with minimal header parsing.
+
+The name lookups need to be fast and optimized for the kinds of lookups that
+debuggers tend to do. Optimally we would like to touch as few parts of the
+mapped table as possible when doing a name lookup and be able to quickly find
+the name entry we are looking for, or discover there are no matches. In the
+case of debuggers we optimized for lookups that fail most of the time.
+
+Each table that is defined should have strict rules on exactly what is in the
+accelerator tables and documented so clients can rely on the content.
+
+Hash Tables
+^^^^^^^^^^^
+
+Standard Hash Tables
+""""""""""""""""""""
+
+Typical hash tables have a header, buckets, and each bucket points to the
+bucket contents:
+
+.. code-block:: none
+
+ .------------.
+ | HEADER |
+ |------------|
+ | BUCKETS |
+ |------------|
+ | DATA |
+ `------------'
+
+The BUCKETS are an array of offsets to DATA for each hash:
+
+.. code-block:: none
+
+ .------------.
+ | 0x00001000 | BUCKETS[0]
+ | 0x00002000 | BUCKETS[1]
+ | 0x00002200 | BUCKETS[2]
+ | 0x000034f0 | BUCKETS[3]
+ | | ...
+ | 0xXXXXXXXX | BUCKETS[n_buckets]
+ '------------'
+
+So for ``bucket[3]`` in the example above, we have an offset into the table
+0x000034f0 which points to a chain of entries for the bucket. Each bucket must
+contain a next pointer, full 32 bit hash value, the string itself, and the data
+for the current string value.
+
+.. code-block:: none
+
+ .------------.
+ 0x000034f0: | 0x00003500 | next pointer
+ | 0x12345678 | 32 bit hash
+ | "erase" | string value
+ | data[n] | HashData for this bucket
+ |------------|
+ 0x00003500: | 0x00003550 | next pointer
+ | 0x29273623 | 32 bit hash
+ | "dump" | string value
+ | data[n] | HashData for this bucket
+ |------------|
+ 0x00003550: | 0x00000000 | next pointer
+ | 0x82638293 | 32 bit hash
+ | "main" | string value
+ | data[n] | HashData for this bucket
+ `------------'
+
+The problem with this layout for debuggers is that we need to optimize for the
+negative lookup case where the symbol we're searching for is not present. So
+if we were to lookup "``printf``" in the table above, we would make a 32 hash
+for "``printf``", it might match ``bucket[3]``. We would need to go to the
+offset 0x000034f0 and start looking to see if our 32 bit hash matches. To do
+so, we need to read the next pointer, then read the hash, compare it, and skip
+to the next bucket. Each time we are skipping many bytes in memory and
+touching new cache pages just to do the compare on the full 32 bit hash. All
+of these accesses then tell us that we didn't have a match.
+
+Name Hash Tables
+""""""""""""""""
+
+To solve the issues mentioned above we have structured the hash tables a bit
+differently: a header, buckets, an array of all unique 32 bit hash values,
+followed by an array of hash value data offsets, one for each hash value, then
+the data for all hash values:
+
+.. code-block:: none
+
+ .-------------.
+ | HEADER |
+ |-------------|
+ | BUCKETS |
+ |-------------|
+ | HASHES |
+ |-------------|
+ | OFFSETS |
+ |-------------|
+ | DATA |
+ `-------------'
+
+The ``BUCKETS`` in the name tables are an index into the ``HASHES`` array. By
+making all of the full 32 bit hash values contiguous in memory, we allow
+ourselves to efficiently check for a match while touching as little memory as
+possible. Most often checking the 32 bit hash values is as far as the lookup
+goes. If it does match, it usually is a match with no collisions. So for a
+table with "``n_buckets``" buckets, and "``n_hashes``" unique 32 bit hash
+values, we can clarify the contents of the ``BUCKETS``, ``HASHES`` and
+``OFFSETS`` as:
+
+.. code-block:: none
+
+ .-------------------------.
+ | HEADER.magic | uint32_t
+ | HEADER.version | uint16_t
+ | HEADER.hash_function | uint16_t
+ | HEADER.bucket_count | uint32_t
+ | HEADER.hashes_count | uint32_t
+ | HEADER.header_data_len | uint32_t
+ | HEADER_DATA | HeaderData
+ |-------------------------|
+ | BUCKETS | uint32_t[n_buckets] // 32 bit hash indexes
+ |-------------------------|
+ | HASHES | uint32_t[n_hashes] // 32 bit hash values
+ |-------------------------|
+ | OFFSETS | uint32_t[n_hashes] // 32 bit offsets to hash value data
+ |-------------------------|
+ | ALL HASH DATA |
+ `-------------------------'
+
+So taking the exact same data from the standard hash example above we end up
+with:
+
+.. code-block:: none
+
+ .------------.
+ | HEADER |
+ |------------|
+ | 0 | BUCKETS[0]
+ | 2 | BUCKETS[1]
+ | 5 | BUCKETS[2]
+ | 6 | BUCKETS[3]
+ | | ...
+ | ... | BUCKETS[n_buckets]
+ |------------|
+ | 0x........ | HASHES[0]
+ | 0x........ | HASHES[1]
+ | 0x........ | HASHES[2]
+ | 0x........ | HASHES[3]
+ | 0x........ | HASHES[4]
+ | 0x........ | HASHES[5]
+ | 0x12345678 | HASHES[6] hash for BUCKETS[3]
+ | 0x29273623 | HASHES[7] hash for BUCKETS[3]
+ | 0x82638293 | HASHES[8] hash for BUCKETS[3]
+ | 0x........ | HASHES[9]
+ | 0x........ | HASHES[10]
+ | 0x........ | HASHES[11]
+ | 0x........ | HASHES[12]
+ | 0x........ | HASHES[13]
+ | 0x........ | HASHES[n_hashes]
+ |------------|
+ | 0x........ | OFFSETS[0]
+ | 0x........ | OFFSETS[1]
+ | 0x........ | OFFSETS[2]
+ | 0x........ | OFFSETS[3]
+ | 0x........ | OFFSETS[4]
+ | 0x........ | OFFSETS[5]
+ | 0x000034f0 | OFFSETS[6] offset for BUCKETS[3]
+ | 0x00003500 | OFFSETS[7] offset for BUCKETS[3]
+ | 0x00003550 | OFFSETS[8] offset for BUCKETS[3]
+ | 0x........ | OFFSETS[9]
+ | 0x........ | OFFSETS[10]
+ | 0x........ | OFFSETS[11]
+ | 0x........ | OFFSETS[12]
+ | 0x........ | OFFSETS[13]
+ | 0x........ | OFFSETS[n_hashes]
+ |------------|
+ | |
+ | |
+ | |
+ | |
+ | |
+ |------------|
+ 0x000034f0: | 0x00001203 | .debug_str ("erase")
+ | 0x00000004 | A 32 bit array count - number of HashData with name "erase"
+ | 0x........ | HashData[0]
+ | 0x........ | HashData[1]
+ | 0x........ | HashData[2]
+ | 0x........ | HashData[3]
+ | 0x00000000 | String offset into .debug_str (terminate data for hash)
+ |------------|
+ 0x00003500: | 0x00001203 | String offset into .debug_str ("collision")
+ | 0x00000002 | A 32 bit array count - number of HashData with name "collision"
+ | 0x........ | HashData[0]
+ | 0x........ | HashData[1]
+ | 0x00001203 | String offset into .debug_str ("dump")
+ | 0x00000003 | A 32 bit array count - number of HashData with name "dump"
+ | 0x........ | HashData[0]
+ | 0x........ | HashData[1]
+ | 0x........ | HashData[2]
+ | 0x00000000 | String offset into .debug_str (terminate data for hash)
+ |------------|
+ 0x00003550: | 0x00001203 | String offset into .debug_str ("main")
+ | 0x00000009 | A 32 bit array count - number of HashData with name "main"
+ | 0x........ | HashData[0]
+ | 0x........ | HashData[1]
+ | 0x........ | HashData[2]
+ | 0x........ | HashData[3]
+ | 0x........ | HashData[4]
+ | 0x........ | HashData[5]
+ | 0x........ | HashData[6]
+ | 0x........ | HashData[7]
+ | 0x........ | HashData[8]
+ | 0x00000000 | String offset into .debug_str (terminate data for hash)
+ `------------'
+
+So we still have all of the same data, we just organize it more efficiently for
+debugger lookup. If we repeat the same "``printf``" lookup from above, we
+would hash "``printf``" and find it matches ``BUCKETS[3]`` by taking the 32 bit
+hash value and modulo it by ``n_buckets``. ``BUCKETS[3]`` contains "6" which
+is the index into the ``HASHES`` table. We would then compare any consecutive
+32 bit hashes values in the ``HASHES`` array as long as the hashes would be in
+``BUCKETS[3]``. We do this by verifying that each subsequent hash value modulo
+``n_buckets`` is still 3. In the case of a failed lookup we would access the
+memory for ``BUCKETS[3]``, and then compare a few consecutive 32 bit hashes
+before we know that we have no match. We don't end up marching through
+multiple words of memory and we really keep the number of processor data cache
+lines being accessed as small as possible.
+
+The string hash that is used for these lookup tables is the Daniel J.
+Bernstein hash which is also used in the ELF ``GNU_HASH`` sections. It is a
+very good hash for all kinds of names in programs with very few hash
+collisions.
+
+Empty buckets are designated by using an invalid hash index of ``UINT32_MAX``.
+
+Details
+^^^^^^^
+
+These name hash tables are designed to be generic where specializations of the
+table get to define additional data that goes into the header ("``HeaderData``"),
+how the string value is stored ("``KeyType``") and the content of the data for each
+hash value.
+
+Header Layout
+"""""""""""""
+
+The header has a fixed part, and the specialized part. The exact format of the
+header is:
+
+.. code-block:: c
+
+ struct Header
+ {
+ uint32_t magic; // 'HASH' magic value to allow endian detection
+ uint16_t version; // Version number
+ uint16_t hash_function; // The hash function enumeration that was used
+ uint32_t bucket_count; // The number of buckets in this hash table
+ uint32_t hashes_count; // The total number of unique hash values and hash data offsets in this table
+ uint32_t header_data_len; // The bytes to skip to get to the hash indexes (buckets) for correct alignment
+ // Specifically the length of the following HeaderData field - this does not
+ // include the size of the preceding fields
+ HeaderData header_data; // Implementation specific header data
+ };
+
+The header starts with a 32 bit "``magic``" value which must be ``'HASH'``
+encoded as an ASCII integer. This allows the detection of the start of the
+hash table and also allows the table's byte order to be determined so the table
+can be correctly extracted. The "``magic``" value is followed by a 16 bit
+``version`` number which allows the table to be revised and modified in the
+future. The current version number is 1. ``hash_function`` is a ``uint16_t``
+enumeration that specifies which hash function was used to produce this table.
+The current values for the hash function enumerations include:
+
+.. code-block:: c
+
+ enum HashFunctionType
+ {
+ eHashFunctionDJB = 0u, // Daniel J Bernstein hash function
+ };
+
+``bucket_count`` is a 32 bit unsigned integer that represents how many buckets
+are in the ``BUCKETS`` array. ``hashes_count`` is the number of unique 32 bit
+hash values that are in the ``HASHES`` array, and is the same number of offsets
+are contained in the ``OFFSETS`` array. ``header_data_len`` specifies the size
+in bytes of the ``HeaderData`` that is filled in by specialized versions of
+this table.
+
+Fixed Lookup
+""""""""""""
+
+The header is followed by the buckets, hashes, offsets, and hash value data.
+
+.. code-block:: c
+
+ struct FixedTable
+ {
+ uint32_t buckets[Header.bucket_count]; // An array of hash indexes into the "hashes[]" array below
+ uint32_t hashes [Header.hashes_count]; // Every unique 32 bit hash for the entire table is in this table
+ uint32_t offsets[Header.hashes_count]; // An offset that corresponds to each item in the "hashes[]" array above
+ };
+
+``buckets`` is an array of 32 bit indexes into the ``hashes`` array. The
+``hashes`` array contains all of the 32 bit hash values for all names in the
+hash table. Each hash in the ``hashes`` table has an offset in the ``offsets``
+array that points to the data for the hash value.
+
+This table setup makes it very easy to repurpose these tables to contain
+different data, while keeping the lookup mechanism the same for all tables.
+This layout also makes it possible to save the table to disk and map it in
+later and do very efficient name lookups with little or no parsing.
+
+DWARF lookup tables can be implemented in a variety of ways and can store a lot
+of information for each name. We want to make the DWARF tables extensible and
+able to store the data efficiently so we have used some of the DWARF features
+that enable efficient data storage to define exactly what kind of data we store
+for each name.
+
+The ``HeaderData`` contains a definition of the contents of each HashData chunk.
+We might want to store an offset to all of the debug information entries (DIEs)
+for each name. To keep things extensible, we create a list of items, or
+Atoms, that are contained in the data for each name. First comes the type of
+the data in each atom:
+
+.. code-block:: c
+
+ enum AtomType
+ {
+ eAtomTypeNULL = 0u,
+ eAtomTypeDIEOffset = 1u, // DIE offset, check form for encoding
+ eAtomTypeCUOffset = 2u, // DIE offset of the compiler unit header that contains the item in question
+ eAtomTypeTag = 3u, // DW_TAG_xxx value, should be encoded as DW_FORM_data1 (if no tags exceed 255) or DW_FORM_data2
+ eAtomTypeNameFlags = 4u, // Flags from enum NameFlags
+ eAtomTypeTypeFlags = 5u, // Flags from enum TypeFlags
+ };
+
+The enumeration values and their meanings are:
+
+.. code-block:: none
+
+ eAtomTypeNULL - a termination atom that specifies the end of the atom list
+ eAtomTypeDIEOffset - an offset into the .debug_info section for the DWARF DIE for this name
+ eAtomTypeCUOffset - an offset into the .debug_info section for the CU that contains the DIE
+ eAtomTypeDIETag - The DW_TAG_XXX enumeration value so you don't have to parse the DWARF to see what it is
+ eAtomTypeNameFlags - Flags for functions and global variables (isFunction, isInlined, isExternal...)
+ eAtomTypeTypeFlags - Flags for types (isCXXClass, isObjCClass, ...)
+
+Then we allow each atom type to define the atom type and how the data for each
+atom type data is encoded:
+
+.. code-block:: c
+
+ struct Atom
+ {
+ uint16_t type; // AtomType enum value
+ uint16_t form; // DWARF DW_FORM_XXX defines
+ };
+
+The ``form`` type above is from the DWARF specification and defines the exact
+encoding of the data for the Atom type. See the DWARF specification for the
+``DW_FORM_`` definitions.
+
+.. code-block:: c
+
+ struct HeaderData
+ {
+ uint32_t die_offset_base;
+ uint32_t atom_count;
+ Atoms atoms[atom_count0];
+ };
+
+``HeaderData`` defines the base DIE offset that should be added to any atoms
+that are encoded using the ``DW_FORM_ref1``, ``DW_FORM_ref2``,
+``DW_FORM_ref4``, ``DW_FORM_ref8`` or ``DW_FORM_ref_udata``. It also defines
+what is contained in each ``HashData`` object -- ``Atom.form`` tells us how large
+each field will be in the ``HashData`` and the ``Atom.type`` tells us how this data
+should be interpreted.
+
+For the current implementations of the "``.apple_names``" (all functions +
+globals), the "``.apple_types``" (names of all types that are defined), and
+the "``.apple_namespaces``" (all namespaces), we currently set the ``Atom``
+array to be:
+
+.. code-block:: c
+
+ HeaderData.atom_count = 1;
+ HeaderData.atoms[0].type = eAtomTypeDIEOffset;
+ HeaderData.atoms[0].form = DW_FORM_data4;
+
+This defines the contents to be the DIE offset (eAtomTypeDIEOffset) that is
+encoded as a 32 bit value (DW_FORM_data4). This allows a single name to have
+multiple matching DIEs in a single file, which could come up with an inlined
+function for instance. Future tables could include more information about the
+DIE such as flags indicating if the DIE is a function, method, block,
+or inlined.
+
+The KeyType for the DWARF table is a 32 bit string table offset into the
+".debug_str" table. The ".debug_str" is the string table for the DWARF which
+may already contain copies of all of the strings. This helps make sure, with
+help from the compiler, that we reuse the strings between all of the DWARF
+sections and keeps the hash table size down. Another benefit to having the
+compiler generate all strings as DW_FORM_strp in the debug info, is that
+DWARF parsing can be made much faster.
+
+After a lookup is made, we get an offset into the hash data. The hash data
+needs to be able to deal with 32 bit hash collisions, so the chunk of data
+at the offset in the hash data consists of a triple:
+
+.. code-block:: c
+
+ uint32_t str_offset
+ uint32_t hash_data_count
+ HashData[hash_data_count]
+
+If "str_offset" is zero, then the bucket contents are done. 99.9% of the
+hash data chunks contain a single item (no 32 bit hash collision):
+
+.. code-block:: none
+
+ .------------.
+ | 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")
+ | 0x00000004 | uint32_t HashData count
+ | 0x........ | uint32_t HashData[0] DIE offset
+ | 0x........ | uint32_t HashData[1] DIE offset
+ | 0x........ | uint32_t HashData[2] DIE offset
+ | 0x........ | uint32_t HashData[3] DIE offset
+ | 0x00000000 | uint32_t KeyType (end of hash chain)
+ `------------'
+
+If there are collisions, you will have multiple valid string offsets:
+
+.. code-block:: none
+
+ .------------.
+ | 0x00001023 | uint32_t KeyType (.debug_str[0x0001023] => "main")
+ | 0x00000004 | uint32_t HashData count
+ | 0x........ | uint32_t HashData[0] DIE offset
+ | 0x........ | uint32_t HashData[1] DIE offset
+ | 0x........ | uint32_t HashData[2] DIE offset
+ | 0x........ | uint32_t HashData[3] DIE offset
+ | 0x00002023 | uint32_t KeyType (.debug_str[0x0002023] => "print")
+ | 0x00000002 | uint32_t HashData count
+ | 0x........ | uint32_t HashData[0] DIE offset
+ | 0x........ | uint32_t HashData[1] DIE offset
+ | 0x00000000 | uint32_t KeyType (end of hash chain)
+ `------------'
+
+Current testing with real world C++ binaries has shown that there is around 1
+32 bit hash collision per 100,000 name entries.
+
+Contents
+^^^^^^^^
+
+As we said, we want to strictly define exactly what is included in the
+different tables. For DWARF, we have 3 tables: "``.apple_names``",
+"``.apple_types``", and "``.apple_namespaces``".
+
+"``.apple_names``" sections should contain an entry for each DWARF DIE whose
+``DW_TAG`` is a ``DW_TAG_label``, ``DW_TAG_inlined_subroutine``, or
+``DW_TAG_subprogram`` that has address attributes: ``DW_AT_low_pc``,
+``DW_AT_high_pc``, ``DW_AT_ranges`` or ``DW_AT_entry_pc``. It also contains
+``DW_TAG_variable`` DIEs that have a ``DW_OP_addr`` in the location (global and
+static variables). All global and static variables should be included,
+including those scoped within functions and classes. For example using the
+following code:
+
+.. code-block:: c
+
+ static int var = 0;
+
+ void f ()
+ {
+ static int var = 0;
+ }
+
+Both of the static ``var`` variables would be included in the table. All
+functions should emit both their full names and their basenames. For C or C++,
+the full name is the mangled name (if available) which is usually in the
+``DW_AT_MIPS_linkage_name`` attribute, and the ``DW_AT_name`` contains the
+function basename. If global or static variables have a mangled name in a
+``DW_AT_MIPS_linkage_name`` attribute, this should be emitted along with the
+simple name found in the ``DW_AT_name`` attribute.
+
+"``.apple_types``" sections should contain an entry for each DWARF DIE whose
+tag is one of:
+
+* DW_TAG_array_type
+* DW_TAG_class_type
+* DW_TAG_enumeration_type
+* DW_TAG_pointer_type
+* DW_TAG_reference_type
+* DW_TAG_string_type
+* DW_TAG_structure_type
+* DW_TAG_subroutine_type
+* DW_TAG_typedef
+* DW_TAG_union_type
+* DW_TAG_ptr_to_member_type
+* DW_TAG_set_type
+* DW_TAG_subrange_type
+* DW_TAG_base_type
+* DW_TAG_const_type
+* DW_TAG_constant
+* DW_TAG_file_type
+* DW_TAG_namelist
+* DW_TAG_packed_type
+* DW_TAG_volatile_type
+* DW_TAG_restrict_type
+* DW_TAG_interface_type
+* DW_TAG_unspecified_type
+* DW_TAG_shared_type
+
+Only entries with a ``DW_AT_name`` attribute are included, and the entry must
+not be a forward declaration (``DW_AT_declaration`` attribute with a non-zero
+value). For example, using the following code:
+
+.. code-block:: c
+
+ int main ()
+ {
+ int *b = 0;
+ return *b;
+ }
+
+We get a few type DIEs:
+
+.. code-block:: none
+
+ 0x00000067: TAG_base_type [5]
+ AT_encoding( DW_ATE_signed )
+ AT_name( "int" )
+ AT_byte_size( 0x04 )
+
+ 0x0000006e: TAG_pointer_type [6]
+ AT_type( {0x00000067} ( int ) )
+ AT_byte_size( 0x08 )
+
+The DW_TAG_pointer_type is not included because it does not have a ``DW_AT_name``.
+
+"``.apple_namespaces``" section should contain all ``DW_TAG_namespace`` DIEs.
+If we run into a namespace that has no name this is an anonymous namespace, and
+the name should be output as "``(anonymous namespace)``" (without the quotes).
+Why? This matches the output of the ``abi::cxa_demangle()`` that is in the
+standard C++ library that demangles mangled names.
+
+
+Language Extensions and File Format Changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Objective-C Extensions
+""""""""""""""""""""""
+
+"``.apple_objc``" section should contain all ``DW_TAG_subprogram`` DIEs for an
+Objective-C class. The name used in the hash table is the name of the
+Objective-C class itself. If the Objective-C class has a category, then an
+entry is made for both the class name without the category, and for the class
+name with the category. So if we have a DIE at offset 0x1234 with a name of
+method "``-[NSString(my_additions) stringWithSpecialString:]``", we would add
+an entry for "``NSString``" that points to DIE 0x1234, and an entry for
+"``NSString(my_additions)``" that points to 0x1234. This allows us to quickly
+track down all Objective-C methods for an Objective-C class when doing
+expressions. It is needed because of the dynamic nature of Objective-C where
+anyone can add methods to a class. The DWARF for Objective-C methods is also
+emitted differently from C++ classes where the methods are not usually
+contained in the class definition, they are scattered about across one or more
+compile units. Categories can also be defined in different shared libraries.
+So we need to be able to quickly find all of the methods and class functions
+given the Objective-C class name, or quickly find all methods and class
+functions for a class + category name. This table does not contain any
+selector names, it just maps Objective-C class names (or class names +
+category) to all of the methods and class functions. The selectors are added
+as function basenames in the "``.debug_names``" section.
+
+In the "``.apple_names``" section for Objective-C functions, the full name is
+the entire function name with the brackets ("``-[NSString
+stringWithCString:]``") and the basename is the selector only
+("``stringWithCString:``").
+
+Mach-O Changes
+""""""""""""""
+
+The sections names for the apple hash tables are for non-mach-o files. For
+mach-o files, the sections should be contained in the ``__DWARF`` segment with
+names as follows:
+
+* "``.apple_names``" -> "``__apple_names``"
+* "``.apple_types``" -> "``__apple_types``"
+* "``.apple_namespaces``" -> "``__apple_namespac``" (16 character limit)
+* "``.apple_objc``" -> "``__apple_objc``"
+
More information about the llvm-commits
mailing list