[www-releases] r184142 - Add docs and links for the 3.3 release.
Bill Wendling
isanbard at gmail.com
Mon Jun 17 16:07:13 PDT 2013
Added: www-releases/trunk/3.3/docs/ProgrammersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/ProgrammersManual.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/ProgrammersManual.html (added)
+++ www-releases/trunk/3.3/docs/ProgrammersManual.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,2809 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Programmerâs Manual — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="LLVM Extensions" href="Extensions.html" />
+ <link rel="prev" title="How to set up LLVM-style RTTI for your class hierarchy" href="HowToSetUpLLVMStyleRTTI.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Extensions.html" title="LLVM Extensions"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-programmer-s-manual">
+<h1>LLVM Programmer’s Manual<a class="headerlink" href="#llvm-programmer-s-manual" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id6">Introduction</a></li>
+<li><a class="reference internal" href="#general-information" id="id7">General Information</a><ul>
+<li><a class="reference internal" href="#the-c-standard-template-library" id="id8">The C++ Standard Template Library</a></li>
+<li><a class="reference internal" href="#other-useful-references" id="id9">Other useful references</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#important-and-useful-llvm-apis" id="id10">Important and useful LLVM APIs</a><ul>
+<li><a class="reference internal" href="#the-isa-cast-and-dyn-cast-templates" id="id11">The <tt class="docutils literal"><span class="pre">isa<></span></tt>, <tt class="docutils literal"><span class="pre">cast<></span></tt> and <tt class="docutils literal"><span class="pre">dyn_cast<></span></tt> templates</a></li>
+<li><a class="reference internal" href="#passing-strings-the-stringref-and-twine-classes" id="id12">Passing strings (the <tt class="docutils literal"><span class="pre">StringRef</span></tt> and <tt class="docutils literal"><span class="pre">Twine</span></tt> classes)</a><ul>
+<li><a class="reference internal" href="#the-stringref-class" id="id13">The <tt class="docutils literal"><span class="pre">StringRef</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-twine-class" id="id14">The <tt class="docutils literal"><span class="pre">Twine</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-debug-macro-and-debug-option" id="id15">The <tt class="docutils literal"><span class="pre">DEBUG()</span></tt> macro and <tt class="docutils literal"><span class="pre">-debug</span></tt> option</a><ul>
+<li><a class="reference internal" href="#fine-grained-debug-info-with-debug-type-and-the-debug-only-option" id="id16">Fine grained debug info with <tt class="docutils literal"><span class="pre">DEBUG_TYPE</span></tt> and the <tt class="docutils literal"><span class="pre">-debug-only</span></tt> option</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-statistic-class-stats-option" id="id17">The <tt class="docutils literal"><span class="pre">Statistic</span></tt> class & <tt class="docutils literal"><span class="pre">-stats</span></tt> option</a></li>
+<li><a class="reference internal" href="#viewing-graphs-while-debugging-code" id="id18">Viewing graphs while debugging code</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#picking-the-right-data-structure-for-a-task" id="id19">Picking the Right Data Structure for a Task</a><ul>
+<li><a class="reference internal" href="#sequential-containers-std-vector-std-list-etc" id="id20">Sequential Containers (std::vector, std::list, etc)</a><ul>
+<li><a class="reference internal" href="#llvm-adt-arrayref-h" id="id21">llvm/ADT/ArrayRef.h</a></li>
+<li><a class="reference internal" href="#fixed-size-arrays" id="id22">Fixed Size Arrays</a></li>
+<li><a class="reference internal" href="#heap-allocated-arrays" id="id23">Heap Allocated Arrays</a></li>
+<li><a class="reference internal" href="#llvm-adt-tinyptrvector-h" id="id24">llvm/ADT/TinyPtrVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallvector-h" id="id25">llvm/ADT/SmallVector.h</a></li>
+<li><a class="reference internal" href="#vector" id="id26"><vector></a></li>
+<li><a class="reference internal" href="#deque" id="id27"><deque></a></li>
+<li><a class="reference internal" href="#list" id="id28"><list></a></li>
+<li><a class="reference internal" href="#llvm-adt-ilist-h" id="id29">llvm/ADT/ilist.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-packedvector-h" id="id30">llvm/ADT/PackedVector.h</a></li>
+<li><a class="reference internal" href="#ilist-traits" id="id31">ilist_traits</a></li>
+<li><a class="reference internal" href="#iplist" id="id32">iplist</a></li>
+<li><a class="reference internal" href="#llvm-adt-ilist-node-h" id="id33">llvm/ADT/ilist_node.h</a></li>
+<li><a class="reference internal" href="#sentinels" id="id34">Sentinels</a></li>
+<li><a class="reference internal" href="#other-sequential-container-options" id="id35">Other Sequential Container options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#string-like-containers" id="id36">String-like containers</a><ul>
+<li><a class="reference internal" href="#llvm-adt-stringref-h" id="id37">llvm/ADT/StringRef.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-twine-h" id="id38">llvm/ADT/Twine.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallstring-h" id="id39">llvm/ADT/SmallString.h</a></li>
+<li><a class="reference internal" href="#std-string" id="id40">std::string</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#set-like-containers-std-set-smallset-setvector-etc" id="id41">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a><ul>
+<li><a class="reference internal" href="#a-sorted-vector" id="id42">A sorted ‘vector’</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallset-h" id="id43">llvm/ADT/SmallSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallptrset-h" id="id44">llvm/ADT/SmallPtrSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-denseset-h" id="id45">llvm/ADT/DenseSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-sparseset-h" id="id46">llvm/ADT/SparseSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-sparsemultiset-h" id="id47">llvm/ADT/SparseMultiSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-foldingset-h" id="id48">llvm/ADT/FoldingSet.h</a></li>
+<li><a class="reference internal" href="#set" id="id49"><set></a></li>
+<li><a class="reference internal" href="#llvm-adt-setvector-h" id="id50">llvm/ADT/SetVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-uniquevector-h" id="id51">llvm/ADT/UniqueVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-immutableset-h" id="id52">llvm/ADT/ImmutableSet.h</a></li>
+<li><a class="reference internal" href="#other-set-like-container-options" id="id53">Other Set-Like Container Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#map-like-containers-std-map-densemap-etc" id="id54">Map-Like Containers (std::map, DenseMap, etc)</a><ul>
+<li><a class="reference internal" href="#dss-sortedvectormap" id="id55">A sorted ‘vector’</a></li>
+<li><a class="reference internal" href="#llvm-adt-stringmap-h" id="id56">llvm/ADT/StringMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-indexedmap-h" id="id57">llvm/ADT/IndexedMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-densemap-h" id="id58">llvm/ADT/DenseMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-valuemap-h" id="id59">llvm/ADT/ValueMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-intervalmap-h" id="id60">llvm/ADT/IntervalMap.h</a></li>
+<li><a class="reference internal" href="#map" id="id61"><map></a></li>
+<li><a class="reference internal" href="#llvm-adt-mapvector-h" id="id62">llvm/ADT/MapVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-inteqclasses-h" id="id63">llvm/ADT/IntEqClasses.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-immutablemap-h" id="id64">llvm/ADT/ImmutableMap.h</a></li>
+<li><a class="reference internal" href="#other-map-like-container-options" id="id65">Other Map-Like Container Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#bit-storage-containers-bitvector-sparsebitvector" id="id66">Bit storage containers (BitVector, SparseBitVector)</a><ul>
+<li><a class="reference internal" href="#bitvector" id="id67">BitVector</a></li>
+<li><a class="reference internal" href="#smallbitvector" id="id68">SmallBitVector</a></li>
+<li><a class="reference internal" href="#sparsebitvector" id="id69">SparseBitVector</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#helpful-hints-for-common-operations" id="id70">Helpful Hints for Common Operations</a><ul>
+<li><a class="reference internal" href="#basic-inspection-and-traversal-routines" id="id71">Basic Inspection and Traversal Routines</a><ul>
+<li><a class="reference internal" href="#iterating-over-the-basicblock-in-a-function" id="id72">Iterating over the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> in a <tt class="docutils literal"><span class="pre">Function</span></tt></a></li>
+<li><a class="reference internal" href="#iterating-over-the-instruction-in-a-basicblock" id="id73">Iterating over the <tt class="docutils literal"><span class="pre">Instruction</span></tt> in a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt></a></li>
+<li><a class="reference internal" href="#iterating-over-the-instruction-in-a-function" id="id74">Iterating over the <tt class="docutils literal"><span class="pre">Instruction</span></tt> in a <tt class="docutils literal"><span class="pre">Function</span></tt></a></li>
+<li><a class="reference internal" href="#turning-an-iterator-into-a-class-pointer-and-vice-versa" id="id75">Turning an iterator into a class pointer (and vice-versa)</a></li>
+<li><a class="reference internal" href="#finding-call-sites-a-slightly-more-complex-example" id="id76">Finding call sites: a slightly more complex example</a></li>
+<li><a class="reference internal" href="#treating-calls-and-invokes-the-same-way" id="id77">Treating calls and invokes the same way</a></li>
+<li><a class="reference internal" href="#iterating-over-def-use-use-def-chains" id="id78">Iterating over def-use & use-def chains</a></li>
+<li><a class="reference internal" href="#iterating-over-predecessors-successors-of-blocks" id="id79">Iterating over predecessors & successors of blocks</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#making-simple-changes" id="id80">Making simple changes</a><ul>
+<li><a class="reference internal" href="#creating-and-inserting-new-instructions" id="id81">Creating and inserting new <tt class="docutils literal"><span class="pre">Instruction</span></tt>s</a></li>
+<li><a class="reference internal" href="#deleting-instructions" id="id82">Deleting Instructions</a></li>
+<li><a class="reference internal" href="#replacing-an-instruction-with-another-value" id="id83">Replacing an Instruction with another Value</a><ul>
+<li><a class="reference internal" href="#replacing-individual-instructions" id="id84">Replacing individual instructions</a></li>
+<li><a class="reference internal" href="#schanges-deleting-sub" id="id85">Deleting Instructions</a></li>
+<li><a class="reference internal" href="#replacing-multiple-uses-of-users-and-values" id="id86">Replacing multiple uses of Users and Values</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#deleting-globalvariables" id="id87">Deleting GlobalVariables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#how-to-create-types" id="id88">How to Create Types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#threads-and-llvm" id="id89">Threads and LLVM</a><ul>
+<li><a class="reference internal" href="#entering-and-exiting-multithreaded-mode" id="id90">Entering and Exiting Multithreaded Mode</a></li>
+<li><a class="reference internal" href="#ending-execution-with-llvm-shutdown" id="id91">Ending Execution with <tt class="docutils literal"><span class="pre">llvm_shutdown()</span></tt></a></li>
+<li><a class="reference internal" href="#lazy-initialization-with-managedstatic" id="id92">Lazy Initialization with <tt class="docutils literal"><span class="pre">ManagedStatic</span></tt></a></li>
+<li><a class="reference internal" href="#achieving-isolation-with-llvmcontext" id="id93">Achieving Isolation with <tt class="docutils literal"><span class="pre">LLVMContext</span></tt></a></li>
+<li><a class="reference internal" href="#threads-and-the-jit" id="id94">Threads and the JIT</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#advanced-topics" id="id95">Advanced Topics</a><ul>
+<li><a class="reference internal" href="#the-valuesymboltable-class" id="id96">The <tt class="docutils literal"><span class="pre">ValueSymbolTable</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-user-and-owned-use-classes-memory-layout" id="id97">The <tt class="docutils literal"><span class="pre">User</span></tt> and owned <tt class="docutils literal"><span class="pre">Use</span></tt> classes’ memory layout</a><ul>
+<li><a class="reference internal" href="#interaction-and-relationship-between-user-and-use-objects" id="id98">Interaction and relationship between <tt class="docutils literal"><span class="pre">User</span></tt> and <tt class="docutils literal"><span class="pre">Use</span></tt> objects</a></li>
+<li><a class="reference internal" href="#the-waymarking-algorithm" id="id99">The waymarking algorithm</a></li>
+<li><a class="reference internal" href="#reference-implementation" id="id100">Reference implementation</a></li>
+<li><a class="reference internal" href="#tagging-considerations" id="id101">Tagging considerations</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-core-llvm-class-hierarchy-reference" id="id102">The Core LLVM Class Hierarchy Reference</a><ul>
+<li><a class="reference internal" href="#the-type-class-and-derived-types" id="id103">The Type class and Derived Types</a><ul>
+<li><a class="reference internal" href="#important-public-methods" id="id104">Important Public Methods</a></li>
+<li><a class="reference internal" href="#important-derived-types" id="id105">Important Derived Types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-module-class" id="id106">The <tt class="docutils literal"><span class="pre">Module</span></tt> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-module-class" id="id107">Important Public Members of the <tt class="docutils literal"><span class="pre">Module</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-value-class" id="id108">The <tt class="docutils literal"><span class="pre">Value</span></tt> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-value-class" id="id109">Important Public Members of the <tt class="docutils literal"><span class="pre">Value</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-user-class" id="id110">The <tt class="docutils literal"><span class="pre">User</span></tt> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-user-class" id="id111">Important Public Members of the <tt class="docutils literal"><span class="pre">User</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-instruction-class" id="id112">The <tt class="docutils literal"><span class="pre">Instruction</span></tt> class</a><ul>
+<li><a class="reference internal" href="#important-subclasses-of-the-instruction-class" id="id113">Important Subclasses of the <tt class="docutils literal"><span class="pre">Instruction</span></tt> class</a></li>
+<li><a class="reference internal" href="#important-public-members-of-the-instruction-class" id="id114">Important Public Members of the <tt class="docutils literal"><span class="pre">Instruction</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-constant-class-and-subclasses" id="id115">The <tt class="docutils literal"><span class="pre">Constant</span></tt> class and subclasses</a><ul>
+<li><a class="reference internal" href="#important-subclasses-of-constant" id="id116">Important Subclasses of Constant</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-globalvalue-class" id="id117">The <tt class="docutils literal"><span class="pre">GlobalValue</span></tt> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-globalvalue-class" id="id118">Important Public Members of the <tt class="docutils literal"><span class="pre">GlobalValue</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-function-class" id="id119">The <tt class="docutils literal"><span class="pre">Function</span></tt> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-function" id="id120">Important Public Members of the <tt class="docutils literal"><span class="pre">Function</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-globalvariable-class" id="id121">The <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-globalvariable-class" id="id122">Important Public Members of the <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-basicblock-class" id="id123">The <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-basicblock-class" id="id124">Important Public Members of the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-argument-class" id="id125">The <tt class="docutils literal"><span class="pre">Argument</span></tt> class</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This is always a work in progress.</p>
+</div>
+<div class="section" id="introduction">
+<span id="id1"></span><h2><a class="toc-backref" href="#id6">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is meant to highlight some of the important classes and interfaces
+available in the LLVM source-base. This manual is not intended to explain what
+LLVM is, how it works, and what LLVM code looks like. It assumes that you know
+the basics of LLVM and are interested in writing transformations or otherwise
+analyzing or manipulating the code.</p>
+<p>This document should get you oriented so that you can find your way in the
+continuously growing source code that makes up the LLVM infrastructure. Note
+that this manual is not intended to serve as a replacement for reading the
+source code, so if you think there should be a method in one of these classes to
+do something, but it’s not listed, check the source. Links to the <a class="reference external" href="http://llvm.org/doxygen/">doxygen</a> sources are provided to make this as easy as
+possible.</p>
+<p>The first section of this document describes general information that is useful
+to know when working in the LLVM infrastructure, and the second describes the
+Core LLVM classes. In the future this manual will be extended with information
+describing how to use extension libraries, such as dominator information, CFG
+traversal routines, and useful utilities like the <tt class="docutils literal"><span class="pre">InstVisitor</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/InstVisitor_8h-source.html">doxygen</a>) template.</p>
+</div>
+<div class="section" id="general-information">
+<span id="general"></span><h2><a class="toc-backref" href="#id7">General Information</a><a class="headerlink" href="#general-information" title="Permalink to this headline">¶</a></h2>
+<p>This section contains general information that is useful if you are working in
+the LLVM source-base, but that isn’t specific to any particular API.</p>
+<div class="section" id="the-c-standard-template-library">
+<span id="stl"></span><h3><a class="toc-backref" href="#id8">The C++ Standard Template Library</a><a class="headerlink" href="#the-c-standard-template-library" title="Permalink to this headline">¶</a></h3>
+<p>LLVM makes heavy use of the C++ Standard Template Library (STL), perhaps much
+more than you are used to, or have seen before. Because of this, you might want
+to do a little background reading in the techniques used and capabilities of the
+library. There are many good pages that discuss the STL, and several books on
+the subject that you can get, so it will not be discussed in this document.</p>
+<p>Here are some useful links:</p>
+<ol class="arabic simple">
+<li><a class="reference external" href="http://en.cppreference.com/w/">cppreference.com</a> - an excellent
+reference for the STL and other parts of the standard C++ library.</li>
+<li><a class="reference external" href="http://www.tempest-sw.com/cpp/">C++ In a Nutshell</a> - This is an O’Reilly
+book in the making. It has a decent Standard Library Reference that rivals
+Dinkumware’s, and is unfortunately no longer free since the book has been
+published.</li>
+<li><a class="reference external" href="http://www.parashift.com/c++-faq-lite/">C++ Frequently Asked Questions</a>.</li>
+<li><a class="reference external" href="http://www.sgi.com/tech/stl/">SGI’s STL Programmer’s Guide</a> - Contains a
+useful <a class="reference external" href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction to the STL</a>.</li>
+<li><a class="reference external" href="http://www.research.att.com/%7Ebs/C++.html">Bjarne Stroustrup’s C++ Page</a>.</li>
+<li><a class="reference external" href="http://www.mindview.net/Books/TICPP/ThinkingInCPP2e.html">Bruce Eckel’s Thinking in C++, 2nd ed. Volume 2 Revision 4.0
+(even better, get the book)</a>.</li>
+</ol>
+<p>You are also encouraged to take a look at the <a class="reference internal" href="CodingStandards.html"><em>LLVM Coding Standards</em></a> guide which focuses on how to write maintainable code more
+than where to put your curly braces.</p>
+</div>
+<div class="section" id="other-useful-references">
+<span id="resources"></span><h3><a class="toc-backref" href="#id9">Other useful references</a><a class="headerlink" href="#other-useful-references" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li><a class="reference external" href="http://www.fortran-2000.com/ArnaudRecipes/sharedlib.html">Using static and shared libraries across platforms</a></li>
+</ol>
+</div>
+</div>
+<div class="section" id="important-and-useful-llvm-apis">
+<span id="apis"></span><h2><a class="toc-backref" href="#id10">Important and useful LLVM APIs</a><a class="headerlink" href="#important-and-useful-llvm-apis" title="Permalink to this headline">¶</a></h2>
+<p>Here we highlight some LLVM APIs that are generally useful and good to know
+about when writing transformations.</p>
+<div class="section" id="the-isa-cast-and-dyn-cast-templates">
+<span id="isa"></span><h3><a class="toc-backref" href="#id11">The <tt class="docutils literal"><span class="pre">isa<></span></tt>, <tt class="docutils literal"><span class="pre">cast<></span></tt> and <tt class="docutils literal"><span class="pre">dyn_cast<></span></tt> templates</a><a class="headerlink" href="#the-isa-cast-and-dyn-cast-templates" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM source-base makes extensive use of a custom form of RTTI. These
+templates have many similarities to the C++ <tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt> operator, but
+they don’t have some drawbacks (primarily stemming from the fact that
+<tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt> only works on classes that have a v-table). Because they are
+used so often, you must know what they do and how they work. All of these
+templates are defined in the <tt class="docutils literal"><span class="pre">llvm/Support/Casting.h</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/Casting_8h-source.html">doxygen</a>) file (note that you very
+rarely have to include this file directly).</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">isa<></span></tt>:</dt>
+<dd>The <tt class="docutils literal"><span class="pre">isa<></span></tt> operator works exactly like the Java “<tt class="docutils literal"><span class="pre">instanceof</span></tt>” operator.
+It returns true or false depending on whether a reference or pointer points to
+an instance of the specified class. This can be very useful for constraint
+checking of various sorts (example below).</dd>
+<dt><tt class="docutils literal"><span class="pre">cast<></span></tt>:</dt>
+<dd><p class="first">The <tt class="docutils literal"><span class="pre">cast<></span></tt> operator is a “checked cast” operation. It converts a pointer
+or reference from a base class to a derived class, causing an assertion
+failure if it is not really an instance of the right type. This should be
+used in cases where you have some information that makes you believe that
+something is of the right type. An example of the <tt class="docutils literal"><span class="pre">isa<></span></tt> and <tt class="docutils literal"><span class="pre">cast<></span></tt>
+template is:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="kt">bool</span> <span class="nf">isLoopInvariant</span><span class="p">(</span><span class="k">const</span> <span class="n">Value</span> <span class="o">*</span><span class="n">V</span><span class="p">,</span> <span class="k">const</span> <span class="n">Loop</span> <span class="o">*</span><span class="n">L</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">isa</span><span class="o"><</span><span class="n">Constant</span><span class="o">></span><span class="p">(</span><span class="n">V</span><span class="p">)</span> <span class="o">||</span> <span class="n">isa</span><span class="o"><</span><span class="n">Argument</span><span class="o">></span><span class="p">(</span><span class="n">V</span><span class="p">)</span> <span class="o">||</span> <span class="n">isa</span><span class="o"><</span><span class="n">GlobalValue</span><span class="o">></span><span class="p">(</span><span class="n">V</span><span class="p">))</span>
+ <span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
+
+ <span class="c1">// Otherwise, it must be an instruction...</span>
+ <span class="k">return</span> <span class="o">!</span><span class="n">L</span><span class="o">-></span><span class="n">contains</span><span class="p">(</span><span class="n">cast</span><span class="o"><</span><span class="n">Instruction</span><span class="o">></span><span class="p">(</span><span class="n">V</span><span class="p">)</span><span class="o">-></span><span class="n">getParent</span><span class="p">());</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p class="last">Note that you should <strong>not</strong> use an <tt class="docutils literal"><span class="pre">isa<></span></tt> test followed by a <tt class="docutils literal"><span class="pre">cast<></span></tt>,
+for that use the <tt class="docutils literal"><span class="pre">dyn_cast<></span></tt> operator.</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">dyn_cast<></span></tt>:</dt>
+<dd><p class="first">The <tt class="docutils literal"><span class="pre">dyn_cast<></span></tt> operator is a “checking cast” operation. It checks to see
+if the operand is of the specified type, and if so, returns a pointer to it
+(this operator does not work with references). If the operand is not of the
+correct type, a null pointer is returned. Thus, this works very much like
+the <tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt> operator in C++, and should be used in the same
+circumstances. Typically, the <tt class="docutils literal"><span class="pre">dyn_cast<></span></tt> operator is used in an <tt class="docutils literal"><span class="pre">if</span></tt>
+statement or some other flow control statement like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">AllocationInst</span> <span class="o">*</span><span class="n">AI</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">AllocationInst</span><span class="o">></span><span class="p">(</span><span class="n">Val</span><span class="p">))</span> <span class="p">{</span>
+ <span class="c1">// ...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This form of the <tt class="docutils literal"><span class="pre">if</span></tt> statement effectively combines together a call to
+<tt class="docutils literal"><span class="pre">isa<></span></tt> and a call to <tt class="docutils literal"><span class="pre">cast<></span></tt> into one statement, which is very
+convenient.</p>
+<p class="last">Note that the <tt class="docutils literal"><span class="pre">dyn_cast<></span></tt> operator, like C++’s <tt class="docutils literal"><span class="pre">dynamic_cast<></span></tt> or Java’s
+<tt class="docutils literal"><span class="pre">instanceof</span></tt> operator, can be abused. In particular, you should not use big
+chained <tt class="docutils literal"><span class="pre">if/then/else</span></tt> blocks to check for lots of different variants of
+classes. If you find yourself wanting to do this, it is much cleaner and more
+efficient to use the <tt class="docutils literal"><span class="pre">InstVisitor</span></tt> class to dispatch over the instruction
+type directly.</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">cast_or_null<></span></tt>:</dt>
+<dd>The <tt class="docutils literal"><span class="pre">cast_or_null<></span></tt> operator works just like the <tt class="docutils literal"><span class="pre">cast<></span></tt> operator,
+except that it allows for a null pointer as an argument (which it then
+propagates). This can sometimes be useful, allowing you to combine several
+null checks into one.</dd>
+<dt><tt class="docutils literal"><span class="pre">dyn_cast_or_null<></span></tt>:</dt>
+<dd>The <tt class="docutils literal"><span class="pre">dyn_cast_or_null<></span></tt> operator works just like the <tt class="docutils literal"><span class="pre">dyn_cast<></span></tt>
+operator, except that it allows for a null pointer as an argument (which it
+then propagates). This can sometimes be useful, allowing you to combine
+several null checks into one.</dd>
+</dl>
+<p>These five templates can be used with any classes, whether they have a v-table
+or not. If you want to add support for these templates, see the document
+<a class="reference internal" href="HowToSetUpLLVMStyleRTTI.html"><em>How to set up LLVM-style RTTI for your class hierarchy</em></a></p>
+</div>
+<div class="section" id="passing-strings-the-stringref-and-twine-classes">
+<span id="string-apis"></span><h3><a class="toc-backref" href="#id12">Passing strings (the <tt class="docutils literal"><span class="pre">StringRef</span></tt> and <tt class="docutils literal"><span class="pre">Twine</span></tt> classes)</a><a class="headerlink" href="#passing-strings-the-stringref-and-twine-classes" title="Permalink to this headline">¶</a></h3>
+<p>Although LLVM generally does not do much string manipulation, we do have several
+important APIs which take strings. Two important examples are the Value class
+– which has names for instructions, functions, etc. – and the <tt class="docutils literal"><span class="pre">StringMap</span></tt>
+class which is used extensively in LLVM and Clang.</p>
+<p>These are generic classes, and they need to be able to accept strings which may
+have embedded null characters. Therefore, they cannot simply take a <tt class="docutils literal"><span class="pre">const</span>
+<span class="pre">char</span> <span class="pre">*</span></tt>, and taking a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">std::string&</span></tt> requires clients to perform a heap
+allocation which is usually unnecessary. Instead, many LLVM APIs use a
+<tt class="docutils literal"><span class="pre">StringRef</span></tt> or a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">Twine&</span></tt> for passing strings efficiently.</p>
+<div class="section" id="the-stringref-class">
+<span id="stringref"></span><h4><a class="toc-backref" href="#id13">The <tt class="docutils literal"><span class="pre">StringRef</span></tt> class</a><a class="headerlink" href="#the-stringref-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">StringRef</span></tt> data type represents a reference to a constant string (a
+character array and a length) and supports the common operations available on
+<tt class="docutils literal"><span class="pre">std::string</span></tt>, but does not require heap allocation.</p>
+<p>It can be implicitly constructed using a C style null-terminated string, an
+<tt class="docutils literal"><span class="pre">std::string</span></tt>, or explicitly with a character pointer and length. For
+example, the <tt class="docutils literal"><span class="pre">StringRef</span></tt> find function is declared as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">iterator</span> <span class="nf">find</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">Key</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>and clients can call it using any one of:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Map</span><span class="p">.</span><span class="n">find</span><span class="p">(</span><span class="s">"foo"</span><span class="p">);</span> <span class="c1">// Lookup "foo"</span>
+<span class="n">Map</span><span class="p">.</span><span class="n">find</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="p">(</span><span class="s">"bar"</span><span class="p">));</span> <span class="c1">// Lookup "bar"</span>
+<span class="n">Map</span><span class="p">.</span><span class="n">find</span><span class="p">(</span><span class="n">StringRef</span><span class="p">(</span><span class="s">"</span><span class="se">\0</span><span class="s">baz"</span><span class="p">,</span> <span class="mi">4</span><span class="p">));</span> <span class="c1">// Lookup "\0baz"</span>
+</pre></div>
+</div>
+<p>Similarly, APIs which need to return a string may return a <tt class="docutils literal"><span class="pre">StringRef</span></tt>
+instance, which can be used directly or converted to an <tt class="docutils literal"><span class="pre">std::string</span></tt> using
+the <tt class="docutils literal"><span class="pre">str</span></tt> member function. See <tt class="docutils literal"><span class="pre">llvm/ADT/StringRef.h</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1StringRef_8h-source.html">doxygen</a>) for more
+information.</p>
+<p>You should rarely use the <tt class="docutils literal"><span class="pre">StringRef</span></tt> class directly, because it contains
+pointers to external memory it is not generally safe to store an instance of the
+class (unless you know that the external storage will not be freed).
+<tt class="docutils literal"><span class="pre">StringRef</span></tt> is small and pervasive enough in LLVM that it should always be
+passed by value.</p>
+</div>
+<div class="section" id="the-twine-class">
+<h4><a class="toc-backref" href="#id14">The <tt class="docutils literal"><span class="pre">Twine</span></tt> class</a><a class="headerlink" href="#the-twine-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">Twine</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Twine.html">doxygen</a>)
+class is an efficient way for APIs to accept concatenated strings. For example,
+a common LLVM paradigm is to name one instruction based on the name of another
+instruction with a suffix, for example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">New</span> <span class="o">=</span> <span class="n">CmpInst</span><span class="o">::</span><span class="n">Create</span><span class="p">(...,</span> <span class="n">SO</span><span class="o">-></span><span class="n">getName</span><span class="p">()</span> <span class="o">+</span> <span class="s">".cmp"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">Twine</span></tt> class is effectively a lightweight <a class="reference external" href="http://en.wikipedia.org/wiki/Rope_(computer_science)">rope</a> which points to
+temporary (stack allocated) objects. Twines can be implicitly constructed as
+the result of the plus operator applied to strings (i.e., a C strings, an
+<tt class="docutils literal"><span class="pre">std::string</span></tt>, or a <tt class="docutils literal"><span class="pre">StringRef</span></tt>). The twine delays the actual concatenation
+of strings until it is actually required, at which point it can be efficiently
+rendered directly into a character array. This avoids unnecessary heap
+allocation involved in constructing the temporary results of string
+concatenation. See <tt class="docutils literal"><span class="pre">llvm/ADT/Twine.h</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/Twine_8h_source.html">doxygen</a>) and <a class="reference internal" href="#dss-twine"><em>here</em></a>
+for more information.</p>
+<p>As with a <tt class="docutils literal"><span class="pre">StringRef</span></tt>, <tt class="docutils literal"><span class="pre">Twine</span></tt> objects point to external memory and should
+almost never be stored or mentioned directly. They are intended solely for use
+when defining a function which should be able to efficiently accept concatenated
+strings.</p>
+</div>
+</div>
+<div class="section" id="the-debug-macro-and-debug-option">
+<span id="debug"></span><h3><a class="toc-backref" href="#id15">The <tt class="docutils literal"><span class="pre">DEBUG()</span></tt> macro and <tt class="docutils literal"><span class="pre">-debug</span></tt> option</a><a class="headerlink" href="#the-debug-macro-and-debug-option" title="Permalink to this headline">¶</a></h3>
+<p>Often when working on your pass you will put a bunch of debugging printouts and
+other code into your pass. After you get it working, you want to remove it, but
+you may need it again in the future (to work out new bugs that you run across).</p>
+<p>Naturally, because of this, you don’t want to delete the debug printouts, but
+you don’t want them to always be noisy. A standard compromise is to comment
+them out, allowing you to enable them if you need them in the future.</p>
+<p>The <tt class="docutils literal"><span class="pre">llvm/Support/Debug.h</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/Debug_8h-source.html">doxygen</a>) file provides a macro named
+<tt class="docutils literal"><span class="pre">DEBUG()</span></tt> that is a much nicer solution to this problem. Basically, you can
+put arbitrary code into the argument of the <tt class="docutils literal"><span class="pre">DEBUG</span></tt> macro, and it is only
+executed if ‘<tt class="docutils literal"><span class="pre">opt</span></tt>‘ (or any other tool) is run with the ‘<tt class="docutils literal"><span class="pre">-debug</span></tt>‘ command
+line argument:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">DEBUG</span><span class="p">(</span><span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"I am here!</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Then you can run your pass like this:</p>
+<div class="highlight-none"><div class="highlight"><pre>$ opt < a.bc > /dev/null -mypass
+<no output>
+$ opt < a.bc > /dev/null -mypass -debug
+I am here!
+</pre></div>
+</div>
+<p>Using the <tt class="docutils literal"><span class="pre">DEBUG()</span></tt> macro instead of a home-brewed solution allows you to not
+have to create “yet another” command line option for the debug output for your
+pass. Note that <tt class="docutils literal"><span class="pre">DEBUG()</span></tt> macros are disabled for optimized builds, so they
+do not cause a performance impact at all (for the same reason, they should also
+not contain side-effects!).</p>
+<p>One additional nice thing about the <tt class="docutils literal"><span class="pre">DEBUG()</span></tt> macro is that you can enable or
+disable it directly in gdb. Just use “<tt class="docutils literal"><span class="pre">set</span> <span class="pre">DebugFlag=0</span></tt>” or “<tt class="docutils literal"><span class="pre">set</span>
+<span class="pre">DebugFlag=1</span></tt>” from the gdb if the program is running. If the program hasn’t
+been started yet, you can always just run it with <tt class="docutils literal"><span class="pre">-debug</span></tt>.</p>
+<div class="section" id="fine-grained-debug-info-with-debug-type-and-the-debug-only-option">
+<span id="debug-type"></span><h4><a class="toc-backref" href="#id16">Fine grained debug info with <tt class="docutils literal"><span class="pre">DEBUG_TYPE</span></tt> and the <tt class="docutils literal"><span class="pre">-debug-only</span></tt> option</a><a class="headerlink" href="#fine-grained-debug-info-with-debug-type-and-the-debug-only-option" title="Permalink to this headline">¶</a></h4>
+<p>Sometimes you may find yourself in a situation where enabling <tt class="docutils literal"><span class="pre">-debug</span></tt> just
+turns on <strong>too much</strong> information (such as when working on the code generator).
+If you want to enable debug information with more fine-grained control, you
+define the <tt class="docutils literal"><span class="pre">DEBUG_TYPE</span></tt> macro and the <tt class="docutils literal"><span class="pre">-debug</span></tt> only option as follows:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#undef DEBUG_TYPE</span>
+<span class="n">DEBUG</span><span class="p">(</span><span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"No debug type</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="cp">#define DEBUG_TYPE "foo"</span>
+<span class="n">DEBUG</span><span class="p">(</span><span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"'foo' debug type</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="cp">#undef DEBUG_TYPE</span>
+<span class="cp">#define DEBUG_TYPE "bar"</span>
+<span class="n">DEBUG</span><span class="p">(</span><span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"'bar' debug type</span><span class="se">\n</span><span class="s">"</span><span class="p">));</span>
+<span class="cp">#undef DEBUG_TYPE</span>
+<span class="cp">#define DEBUG_TYPE ""</span>
+<span class="n">DEBUG</span><span class="p">(</span><span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"No debug type (2)</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Then you can run your pass like this:</p>
+<div class="highlight-none"><div class="highlight"><pre>$ 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
+</pre></div>
+</div>
+<p>Of course, in practice, you should only set <tt class="docutils literal"><span class="pre">DEBUG_TYPE</span></tt> at the top of a file,
+to specify the debug type for the entire module (if you do this before you
+<tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/Support/Debug.h"</span></tt>, you don’t have to insert the ugly
+<tt class="docutils literal"><span class="pre">#undef</span></tt>‘s). Also, you should use names more meaningful than “foo” and “bar”,
+because there is no system in place to ensure that names do not conflict. If
+two different modules use the same string, they will all be turned on when the
+name is specified. This allows, for example, all debug information for
+instruction scheduling to be enabled with <tt class="docutils literal"><span class="pre">-debug-type=InstrSched</span></tt>, even if
+the source lives in multiple files.</p>
+<p>The <tt class="docutils literal"><span class="pre">DEBUG_WITH_TYPE</span></tt> macro is also available for situations where you would
+like to set <tt class="docutils literal"><span class="pre">DEBUG_TYPE</span></tt>, but only for one specific <tt class="docutils literal"><span class="pre">DEBUG</span></tt> statement. It
+takes an additional first parameter, which is the type to use. For example, the
+preceding example could be written as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">DEBUG_WITH_TYPE</span><span class="p">(</span><span class="s">""</span><span class="p">,</span> <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"No debug type</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="n">DEBUG_WITH_TYPE</span><span class="p">(</span><span class="s">"foo"</span><span class="p">,</span> <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"'foo' debug type</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="n">DEBUG_WITH_TYPE</span><span class="p">(</span><span class="s">"bar"</span><span class="p">,</span> <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"'bar' debug type</span><span class="se">\n</span><span class="s">"</span><span class="p">));</span>
+<span class="n">DEBUG_WITH_TYPE</span><span class="p">(</span><span class="s">""</span><span class="p">,</span> <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"No debug type (2)</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="the-statistic-class-stats-option">
+<span id="statistic"></span><h3><a class="toc-backref" href="#id17">The <tt class="docutils literal"><span class="pre">Statistic</span></tt> class & <tt class="docutils literal"><span class="pre">-stats</span></tt> option</a><a class="headerlink" href="#the-statistic-class-stats-option" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">llvm/ADT/Statistic.h</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/Statistic_8h-source.html">doxygen</a>) file provides a class
+named <tt class="docutils literal"><span class="pre">Statistic</span></tt> that is used as a unified way to keep track of what the LLVM
+compiler is doing and how effective various optimizations are. It is useful to
+see what optimizations are contributing to making a particular program run
+faster.</p>
+<p>Often you may run your pass on some big program, and you’re interested to see
+how many times it makes a certain transformation. Although you can do this with
+hand inspection, or some ad-hoc method, this is a real pain and not very useful
+for big programs. Using the <tt class="docutils literal"><span class="pre">Statistic</span></tt> class makes it very easy to keep
+track of this information, and the calculated information is presented in a
+uniform manner with the rest of the passes being executed.</p>
+<p>There are many examples of <tt class="docutils literal"><span class="pre">Statistic</span></tt> uses, but the basics of using it are as
+follows:</p>
+<ol class="arabic simple">
+<li>Define your statistic like this:</li>
+</ol>
+<blockquote>
+<div><div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define DEBUG_TYPE "mypassname" </span><span class="c1">// This goes before any #includes.</span>
+<span class="n">STATISTIC</span><span class="p">(</span><span class="n">NumXForms</span><span class="p">,</span> <span class="s">"The # of times I did stuff"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">STATISTIC</span></tt> macro defines a static variable, whose name is specified by
+the first argument. The pass name is taken from the <tt class="docutils literal"><span class="pre">DEBUG_TYPE</span></tt> macro, and
+the description is taken from the second argument. The variable defined
+(“NumXForms” in this case) acts like an unsigned integer.</p>
+</div></blockquote>
+<ol class="arabic simple">
+<li>Whenever you make a transformation, bump the counter:</li>
+</ol>
+<blockquote>
+<div><div class="highlight-c++"><div class="highlight"><pre><span class="o">++</span><span class="n">NumXForms</span><span class="p">;</span> <span class="c1">// I did stuff!</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p>That’s all you have to do. To get ‘<tt class="docutils literal"><span class="pre">opt</span></tt>‘ to print out the statistics
+gathered, use the ‘<tt class="docutils literal"><span class="pre">-stats</span></tt>‘ option:</p>
+<div class="highlight-none"><div class="highlight"><pre>$ opt -stats -mypassname < program.bc > /dev/null
+... statistics output ...
+</pre></div>
+</div>
+<p>When running <tt class="docutils literal"><span class="pre">opt</span></tt> on a C file from the SPEC benchmark suite, it gives a
+report that looks like this:</p>
+<div class="highlight-none"><div class="highlight"><pre> 7646 bitcodewriter - Number of normal instructions
+ 725 bitcodewriter - Number of oversized instructions
+129996 bitcodewriter - Number of bitcode bytes written
+ 2817 raise - Number of insts DCEd or constprop'd
+ 3213 raise - Number of cast-of-self removed
+ 5046 raise - Number of expression trees converted
+ 75 raise - Number of other getelementptr's formed
+ 138 raise - Number of load/store peepholes
+ 42 deadtypeelim - Number of unused typenames removed from symtab
+ 392 funcresolve - Number of varargs functions resolved
+ 27 globaldce - Number of global variables removed
+ 2 adce - Number of basic blocks removed
+ 134 cee - Number of branches revectored
+ 49 cee - Number of setcc instruction eliminated
+ 532 gcse - Number of loads removed
+ 2919 gcse - Number of instructions removed
+ 86 indvars - Number of canonical indvars added
+ 87 indvars - Number of aux indvars removed
+ 25 instcombine - Number of dead inst eliminate
+ 434 instcombine - Number of insts combined
+ 248 licm - Number of load insts hoisted
+ 1298 licm - Number of insts hoisted to a loop pre-header
+ 3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)
+ 75 mem2reg - Number of alloca's promoted
+ 1444 cfgsimplify - Number of blocks simplified
+</pre></div>
+</div>
+<p>Obviously, with so many optimizations, having a unified framework for this stuff
+is very nice. Making your pass fit well into the framework makes it more
+maintainable and useful.</p>
+</div>
+<div class="section" id="viewing-graphs-while-debugging-code">
+<span id="viewgraph"></span><h3><a class="toc-backref" href="#id18">Viewing graphs while debugging code</a><a class="headerlink" href="#viewing-graphs-while-debugging-code" title="Permalink to this headline">¶</a></h3>
+<p>Several of the important data structures in LLVM are graphs: for example CFGs
+made out of LLVM <a class="reference internal" href="#basicblock"><em>BasicBlocks</em></a>, CFGs made out of LLVM
+<a class="reference internal" href="CodeGenerator.html#machinebasicblock"><em>MachineBasicBlocks</em></a>, and <a class="reference internal" href="CodeGenerator.html#selectiondag"><em>Instruction Selection
+DAGs</em></a>. In many cases, while debugging various parts of the
+compiler, it is nice to instantly visualize these graphs.</p>
+<p>LLVM provides several callbacks that are available in a debug build to do
+exactly that. If you call the <tt class="docutils literal"><span class="pre">Function::viewCFG()</span></tt> method, for example, the
+current LLVM tool will pop up a window containing the CFG for the function where
+each basic block is a node in the graph, and each node contains the instructions
+in the block. Similarly, there also exists <tt class="docutils literal"><span class="pre">Function::viewCFGOnly()</span></tt> (does
+not include the instructions), the <tt class="docutils literal"><span class="pre">MachineFunction::viewCFG()</span></tt> and
+<tt class="docutils literal"><span class="pre">MachineFunction::viewCFGOnly()</span></tt>, and the <tt class="docutils literal"><span class="pre">SelectionDAG::viewGraph()</span></tt>
+methods. Within GDB, for example, you can usually use something like <tt class="docutils literal"><span class="pre">call</span>
+<span class="pre">DAG.viewGraph()</span></tt> to pop up a window. Alternatively, you can sprinkle calls to
+these functions in your code in places you want to debug.</p>
+<p>Getting this to work requires a small amount of configuration. On Unix systems
+with X11, install the <a class="reference external" href="http://www.graphviz.org">graphviz</a> toolkit, and make
+sure ‘dot’ and ‘gv’ are in your path. If you are running on Mac OS/X, download
+and install the Mac OS/X <a class="reference external" href="http://www.pixelglow.com/graphviz/">Graphviz program</a> and add
+<tt class="docutils literal"><span class="pre">/Applications/Graphviz.app/Contents/MacOS/</span></tt> (or wherever you install it) to
+your path. Once in your system and path are set up, rerun the LLVM configure
+script and rebuild LLVM to enable this functionality.</p>
+<p><tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> has been extended to make it easier to locate <em>interesting</em>
+nodes in large complex graphs. From gdb, if you <tt class="docutils literal"><span class="pre">call</span> <span class="pre">DAG.setGraphColor(node,</span>
+<span class="pre">"color")</span></tt>, then the next <tt class="docutils literal"><span class="pre">call</span> <span class="pre">DAG.viewGraph()</span></tt> would highlight the node in
+the specified color (choices of colors can be found at <a class="reference external" href="http://www.graphviz.org/doc/info/colors.html">colors</a>.) More complex node attributes
+can be provided with <tt class="docutils literal"><span class="pre">call</span> <span class="pre">DAG.setGraphAttrs(node,</span> <span class="pre">"attributes")</span></tt> (choices can
+be found at <a class="reference external" href="http://www.graphviz.org/doc/info/attrs.html">Graph attributes</a>.)
+If you want to restart and clear all the current graph attributes, then you can
+<tt class="docutils literal"><span class="pre">call</span> <span class="pre">DAG.clearGraphAttrs()</span></tt>.</p>
+<p>Note that graph visualization features are compiled out of Release builds to
+reduce file size. This means that you need a Debug+Asserts or Release+Asserts
+build to use these features.</p>
+</div>
+</div>
+<div class="section" id="picking-the-right-data-structure-for-a-task">
+<span id="datastructure"></span><h2><a class="toc-backref" href="#id19">Picking the Right Data Structure for a Task</a><a class="headerlink" href="#picking-the-right-data-structure-for-a-task" title="Permalink to this headline">¶</a></h2>
+<p>LLVM has a plethora of data structures in the <tt class="docutils literal"><span class="pre">llvm/ADT/</span></tt> directory, and we
+commonly use STL data structures. This section describes the trade-offs you
+should consider when you pick one.</p>
+<p>The first step is a choose your own adventure: do you want a sequential
+container, a set-like container, or a map-like container? The most important
+thing when choosing a container is the algorithmic properties of how you plan to
+access the container. Based on that, you should use:</p>
+<ul class="simple">
+<li>a <a class="reference internal" href="#ds-map"><em>map-like</em></a> 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.</li>
+<li>a <a class="reference internal" href="#ds-set"><em>set-like</em></a> container if you need to put a bunch of stuff into
+a container that automatically eliminates duplicates. Some set-like
+containers support efficient iteration through the elements in sorted order.
+Set-like containers are more expensive than sequential containers.</li>
+<li>a <a class="reference internal" href="#ds-sequential"><em>sequential</em></a> container provides the most efficient way
+to add elements and keeps track of the order they are added to the collection.
+They permit duplicates and support efficient iteration, but do not support
+efficient look-up based on a key.</li>
+<li>a <a class="reference internal" href="#ds-string"><em>string</em></a> container is a specialized sequential container or
+reference structure that is used for character or byte arrays.</li>
+<li>a <a class="reference internal" href="#ds-bit"><em>bit</em></a> container provides an efficient way to store and
+perform set operations on sets of numeric id’s, while automatically
+eliminating duplicates. Bit containers require a maximum of 1 bit for each
+identifier you want to store.</li>
+</ul>
+<p>Once the proper category of container is determined, you can fine tune the
+memory use, constant factors, and cache behaviors of access by intelligently
+picking a member of the category. Note that constant factors and cache behavior
+can be a big deal. If you have a vector that usually only contains a few
+elements (but could contain many), for example, it’s much better to use
+<a class="reference internal" href="#dss-smallvector"><em>SmallVector</em></a> than <a class="reference internal" href="#dss-vector"><em>vector</em></a>. Doing so
+avoids (relatively) expensive malloc/free calls, which dwarf the cost of adding
+the elements to the container.</p>
+<div class="section" id="sequential-containers-std-vector-std-list-etc">
+<span id="ds-sequential"></span><h3><a class="toc-backref" href="#id20">Sequential Containers (std::vector, std::list, etc)</a><a class="headerlink" href="#sequential-containers-std-vector-std-list-etc" title="Permalink to this headline">¶</a></h3>
+<p>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.</p>
+<div class="section" id="llvm-adt-arrayref-h">
+<span id="dss-arrayref"></span><h4><a class="toc-backref" href="#id21">llvm/ADT/ArrayRef.h</a><a class="headerlink" href="#llvm-adt-arrayref-h" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">llvm::ArrayRef</span></tt> 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 <tt class="docutils literal"><span class="pre">ArrayRef</span></tt>, the API can be passed a fixed size array, an
+<tt class="docutils literal"><span class="pre">std::vector</span></tt>, an <tt class="docutils literal"><span class="pre">llvm::SmallVector</span></tt> and anything else that is contiguous
+in memory.</p>
+</div>
+<div class="section" id="fixed-size-arrays">
+<span id="dss-fixedarrays"></span><h4><a class="toc-backref" href="#id22">Fixed Size Arrays</a><a class="headerlink" href="#fixed-size-arrays" title="Permalink to this headline">¶</a></h4>
+<p>Fixed size arrays are very simple and very fast. They are good if you know
+exactly how many elements you have, or you have a (low) upper bound on how many
+you have.</p>
+</div>
+<div class="section" id="heap-allocated-arrays">
+<span id="dss-heaparrays"></span><h4><a class="toc-backref" href="#id23">Heap Allocated Arrays</a><a class="headerlink" href="#heap-allocated-arrays" title="Permalink to this headline">¶</a></h4>
+<p>Heap allocated arrays (<tt class="docutils literal"><span class="pre">new[]</span></tt> + <tt class="docutils literal"><span class="pre">delete[]</span></tt>) are also simple. They are good
+if the number of elements is variable, if you know how many elements you will
+need before the array is allocated, and if the array is usually large (if not,
+consider a <a class="reference internal" href="#dss-smallvector"><em>SmallVector</em></a>). The cost of a heap allocated
+array is the cost of the new/delete (aka malloc/free). Also note that if you
+are allocating an array of a type with a constructor, the constructor and
+destructors will be run for every element in the array (re-sizable vectors only
+construct those elements actually used).</p>
+</div>
+<div class="section" id="llvm-adt-tinyptrvector-h">
+<span id="dss-tinyptrvector"></span><h4><a class="toc-backref" href="#id24">llvm/ADT/TinyPtrVector.h</a><a class="headerlink" href="#llvm-adt-tinyptrvector-h" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">TinyPtrVector<Type></span></tt> is a highly specialized collection class that is
+optimized to avoid allocation in the case when a vector has zero or one
+elements. It has two major restrictions: 1) it can only hold values of pointer
+type, and 2) it cannot hold a null pointer.</p>
+<p>Since this container is highly specialized, it is rarely used.</p>
+</div>
+<div class="section" id="llvm-adt-smallvector-h">
+<span id="dss-smallvector"></span><h4><a class="toc-backref" href="#id25">llvm/ADT/SmallVector.h</a><a class="headerlink" href="#llvm-adt-smallvector-h" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">SmallVector<Type,</span> <span class="pre">N></span></tt> is a simple class that looks and smells just like
+<tt class="docutils literal"><span class="pre">vector<Type></span></tt>: it supports efficient iteration, lays out elements in memory
+order (so you can do pointer arithmetic between elements), supports efficient
+push_back/pop_back operations, supports efficient random access to its elements,
+etc.</p>
+<p>The advantage of SmallVector is that it allocates space for some number of
+elements (N) <strong>in the object itself</strong>. Because of this, if the SmallVector is
+dynamically smaller than N, no malloc is performed. This can be a big win in
+cases where the malloc/free call is far more expensive than the code that
+fiddles around with the elements.</p>
+<p>This is good for vectors that are “usually small” (e.g. the number of
+predecessors/successors of a block is usually less than 8). On the other hand,
+this makes the size of the SmallVector itself large, so you don’t want to
+allocate lots of them (doing so will waste a lot of space). As such,
+SmallVectors are most useful when on the stack.</p>
+<p>SmallVector also provides a nice portable and efficient replacement for
+<tt class="docutils literal"><span class="pre">alloca</span></tt>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>Prefer to use <tt class="docutils literal"><span class="pre">SmallVectorImpl<T></span></tt> as a parameter type.</p>
+<p>In APIs that don’t care about the “small size” (most?), prefer to use
+the <tt class="docutils literal"><span class="pre">SmallVectorImpl<T></span></tt> class, which is basically just the “vector
+header” (and methods) without the elements allocated after it. Note that
+<tt class="docutils literal"><span class="pre">SmallVector<T,</span> <span class="pre">N></span></tt> inherits from <tt class="docutils literal"><span class="pre">SmallVectorImpl<T></span></tt> so the
+conversion is implicit and costs nothing. E.g.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// BAD: Clients cannot pass e.g. SmallVector<Foo, 4>.</span>
+<span class="n">hardcodedSmallSize</span><span class="p">(</span><span class="n">SmallVector</span><span class="o"><</span><span class="n">Foo</span><span class="p">,</span> <span class="mi">2</span><span class="o">></span> <span class="o">&</span><span class="n">Out</span><span class="p">);</span>
+<span class="c1">// GOOD: Clients can pass any SmallVector<Foo, N>.</span>
+<span class="n">allowsAnySmallSize</span><span class="p">(</span><span class="n">SmallVectorImpl</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span> <span class="o">&</span><span class="n">Out</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">someFunc</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">SmallVector</span><span class="o"><</span><span class="n">Foo</span><span class="p">,</span> <span class="mi">8</span><span class="o">></span> <span class="n">Vec</span><span class="p">;</span>
+ <span class="n">hardcodedSmallSize</span><span class="p">(</span><span class="n">Vec</span><span class="p">);</span> <span class="c1">// Error.</span>
+ <span class="n">allowsAnySmallSize</span><span class="p">(</span><span class="n">Vec</span><span class="p">);</span> <span class="c1">// Works.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p class="last">Even though it has “<tt class="docutils literal"><span class="pre">Impl</span></tt>” in the name, this is so widely used that
+it really isn’t “private to the implementation” anymore. A name like
+<tt class="docutils literal"><span class="pre">SmallVectorHeader</span></tt> would be more appropriate.</p>
+</div>
+</div>
+<div class="section" id="vector">
+<span id="dss-vector"></span><h4><a class="toc-backref" href="#id26"><vector></a><a class="headerlink" href="#vector" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">std::vector</span></tt> is well loved and respected. It is useful when SmallVector
+isn’t: when the size of the vector is often large (thus the small optimization
+will rarely be a benefit) or if you will be allocating many instances of the
+vector itself (which would waste space for elements that aren’t in the
+container). vector is also useful when interfacing with code that expects
+vectors :).</p>
+<p>One worthwhile note about std::vector: avoid code like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span> <span class="p">...</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">foo</span><span class="o">></span> <span class="n">V</span><span class="p">;</span>
+ <span class="c1">// make use of V.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Instead, write this as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">foo</span><span class="o">></span> <span class="n">V</span><span class="p">;</span>
+<span class="k">for</span> <span class="p">(</span> <span class="p">...</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// make use of V.</span>
+ <span class="n">V</span><span class="p">.</span><span class="n">clear</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Doing so will save (at least) one heap allocation and free per iteration of the
+loop.</p>
+</div>
+<div class="section" id="deque">
+<span id="dss-deque"></span><h4><a class="toc-backref" href="#id27"><deque></a><a class="headerlink" href="#deque" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">std::deque</span></tt> is, in some senses, a generalized version of <tt class="docutils literal"><span class="pre">std::vector</span></tt>.
+Like <tt class="docutils literal"><span class="pre">std::vector</span></tt>, it provides constant time random access and other similar
+properties, but it also provides efficient access to the front of the list. It
+does not guarantee continuity of elements within memory.</p>
+<p>In exchange for this extra flexibility, <tt class="docutils literal"><span class="pre">std::deque</span></tt> has significantly higher
+constant factor costs than <tt class="docutils literal"><span class="pre">std::vector</span></tt>. If possible, use <tt class="docutils literal"><span class="pre">std::vector</span></tt> or
+something cheaper.</p>
+</div>
+<div class="section" id="list">
+<span id="dss-list"></span><h4><a class="toc-backref" href="#id28"><list></a><a class="headerlink" href="#list" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">std::list</span></tt> 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.
+<tt class="docutils literal"><span class="pre">std::list</span></tt> also only supports bidirectional iteration, not random access
+iteration.</p>
+<p>In exchange for this high cost, std::list supports efficient access to both ends
+of the list (like <tt class="docutils literal"><span class="pre">std::deque</span></tt>, but unlike <tt class="docutils literal"><span class="pre">std::vector</span></tt> or
+<tt class="docutils literal"><span class="pre">SmallVector</span></tt>). In addition, the iterator invalidation characteristics of
+std::list are stronger than that of a vector class: inserting or removing an
+element into the list does not invalidate iterator or pointers to other elements
+in the list.</p>
+</div>
+<div class="section" id="llvm-adt-ilist-h">
+<span id="dss-ilist"></span><h4><a class="toc-backref" href="#id29">llvm/ADT/ilist.h</a><a class="headerlink" href="#llvm-adt-ilist-h" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">ilist<T></span></tt> implements an ‘intrusive’ doubly-linked list. It is intrusive,
+because it requires the element to store and provide access to the prev/next
+pointers for the list.</p>
+<p><tt class="docutils literal"><span class="pre">ilist</span></tt> has the same drawbacks as <tt class="docutils literal"><span class="pre">std::list</span></tt>, and additionally requires an
+<tt class="docutils literal"><span class="pre">ilist_traits</span></tt> implementation for the element type, but it provides some novel
+characteristics. In particular, it can efficiently store polymorphic objects,
+the traits class is informed when an element is inserted or removed from the
+list, and <tt class="docutils literal"><span class="pre">ilist</span></tt>s are guaranteed to support a constant-time splice
+operation.</p>
+<p>These properties are exactly what we want for things like <tt class="docutils literal"><span class="pre">Instruction</span></tt>s and
+basic blocks, which is why these are implemented with <tt class="docutils literal"><span class="pre">ilist</span></tt>s.</p>
+<p>Related classes of interest are explained in the following subsections:</p>
+<ul class="simple">
+<li><a class="reference internal" href="#dss-ilist-traits"><em>ilist_traits</em></a></li>
+<li><a class="reference internal" href="#dss-iplist"><em>iplist</em></a></li>
+<li><a class="reference internal" href="#dss-ilist-node"><em>llvm/ADT/ilist_node.h</em></a></li>
+<li><a class="reference internal" href="#dss-ilist-sentinel"><em>Sentinels</em></a></li>
+</ul>
+</div>
+<div class="section" id="llvm-adt-packedvector-h">
+<span id="dss-packedvector"></span><h4><a class="toc-backref" href="#id30">llvm/ADT/PackedVector.h</a><a class="headerlink" href="#llvm-adt-packedvector-h" title="Permalink to this headline">¶</a></h4>
+<p>Useful for storing a vector of values using only a few number of bits for each
+value. Apart from the standard operations of a vector-like container, it can
+also perform an ‘or’ set operation.</p>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">State</span> <span class="p">{</span>
+ <span class="n">None</span> <span class="o">=</span> <span class="mh">0x0</span><span class="p">,</span>
+ <span class="n">FirstCondition</span> <span class="o">=</span> <span class="mh">0x1</span><span class="p">,</span>
+ <span class="n">SecondCondition</span> <span class="o">=</span> <span class="mh">0x2</span><span class="p">,</span>
+ <span class="n">Both</span> <span class="o">=</span> <span class="mh">0x3</span>
+<span class="p">};</span>
+
+<span class="n">State</span> <span class="nf">get</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">PackedVector</span><span class="o"><</span><span class="n">State</span><span class="p">,</span> <span class="mi">2</span><span class="o">></span> <span class="n">Vec1</span><span class="p">;</span>
+ <span class="n">Vec1</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">FirstCondition</span><span class="p">);</span>
+
+ <span class="n">PackedVector</span><span class="o"><</span><span class="n">State</span><span class="p">,</span> <span class="mi">2</span><span class="o">></span> <span class="n">Vec2</span><span class="p">;</span>
+ <span class="n">Vec2</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">SecondCondition</span><span class="p">);</span>
+
+ <span class="n">Vec1</span> <span class="o">|=</span> <span class="n">Vec2</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">Vec1</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> <span class="c1">// returns 'Both'.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="ilist-traits">
+<span id="dss-ilist-traits"></span><h4><a class="toc-backref" href="#id31">ilist_traits</a><a class="headerlink" href="#ilist-traits" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">ilist_traits<T></span></tt> is <tt class="docutils literal"><span class="pre">ilist<T></span></tt>‘s customization mechanism. <tt class="docutils literal"><span class="pre">iplist<T></span></tt>
+(and consequently <tt class="docutils literal"><span class="pre">ilist<T></span></tt>) publicly derive from this traits class.</p>
+</div>
+<div class="section" id="iplist">
+<span id="dss-iplist"></span><h4><a class="toc-backref" href="#id32">iplist</a><a class="headerlink" href="#iplist" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">iplist<T></span></tt> is <tt class="docutils literal"><span class="pre">ilist<T></span></tt>‘s base and as such supports a slightly narrower
+interface. Notably, inserters from <tt class="docutils literal"><span class="pre">T&</span></tt> are absent.</p>
+<p><tt class="docutils literal"><span class="pre">ilist_traits<T></span></tt> is a public base of this class and can be used for a wide
+variety of customizations.</p>
+</div>
+<div class="section" id="llvm-adt-ilist-node-h">
+<span id="dss-ilist-node"></span><h4><a class="toc-backref" href="#id33">llvm/ADT/ilist_node.h</a><a class="headerlink" href="#llvm-adt-ilist-node-h" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">ilist_node<T></span></tt> implements a the forward and backward links that are expected
+by the <tt class="docutils literal"><span class="pre">ilist<T></span></tt> (and analogous containers) in the default manner.</p>
+<p><tt class="docutils literal"><span class="pre">ilist_node<T></span></tt>s are meant to be embedded in the node type <tt class="docutils literal"><span class="pre">T</span></tt>, usually
+<tt class="docutils literal"><span class="pre">T</span></tt> publicly derives from <tt class="docutils literal"><span class="pre">ilist_node<T></span></tt>.</p>
+</div>
+<div class="section" id="sentinels">
+<span id="dss-ilist-sentinel"></span><h4><a class="toc-backref" href="#id34">Sentinels</a><a class="headerlink" href="#sentinels" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">ilist</span></tt>s have another specialty that must be considered. To be a good
+citizen in the C++ ecosystem, it needs to support the standard container
+operations, such as <tt class="docutils literal"><span class="pre">begin</span></tt> and <tt class="docutils literal"><span class="pre">end</span></tt> iterators, etc. Also, the
+<tt class="docutils literal"><span class="pre">operator--</span></tt> must work correctly on the <tt class="docutils literal"><span class="pre">end</span></tt> iterator in the case of
+non-empty <tt class="docutils literal"><span class="pre">ilist</span></tt>s.</p>
+<p>The only sensible solution to this problem is to allocate a so-called <em>sentinel</em>
+along with the intrusive list, which serves as the <tt class="docutils literal"><span class="pre">end</span></tt> iterator, providing
+the back-link to the last element. However conforming to the C++ convention it
+is illegal to <tt class="docutils literal"><span class="pre">operator++</span></tt> beyond the sentinel and it also must not be
+dereferenced.</p>
+<p>These constraints allow for some implementation freedom to the <tt class="docutils literal"><span class="pre">ilist</span></tt> how to
+allocate and store the sentinel. The corresponding policy is dictated by
+<tt class="docutils literal"><span class="pre">ilist_traits<T></span></tt>. By default a <tt class="docutils literal"><span class="pre">T</span></tt> gets heap-allocated whenever the need
+for a sentinel arises.</p>
+<p>While the default policy is sufficient in most cases, it may break down when
+<tt class="docutils literal"><span class="pre">T</span></tt> does not provide a default constructor. Also, in the case of many
+instances of <tt class="docutils literal"><span class="pre">ilist</span></tt>s, the memory overhead of the associated sentinels is
+wasted. To alleviate the situation with numerous and voluminous
+<tt class="docutils literal"><span class="pre">T</span></tt>-sentinels, sometimes a trick is employed, leading to <em>ghostly sentinels</em>.</p>
+<p>Ghostly sentinels are obtained by specially-crafted <tt class="docutils literal"><span class="pre">ilist_traits<T></span></tt> which
+superpose the sentinel with the <tt class="docutils literal"><span class="pre">ilist</span></tt> instance in memory. Pointer
+arithmetic is used to obtain the sentinel, which is relative to the <tt class="docutils literal"><span class="pre">ilist</span></tt>‘s
+<tt class="docutils literal"><span class="pre">this</span></tt> pointer. The <tt class="docutils literal"><span class="pre">ilist</span></tt> is augmented by an extra pointer, which serves
+as the back-link of the sentinel. This is the only field in the ghostly
+sentinel which can be legally accessed.</p>
+</div>
+<div class="section" id="other-sequential-container-options">
+<span id="dss-other"></span><h4><a class="toc-backref" href="#id35">Other Sequential Container options</a><a class="headerlink" href="#other-sequential-container-options" title="Permalink to this headline">¶</a></h4>
+<p>Other STL containers are available, such as <tt class="docutils literal"><span class="pre">std::string</span></tt>.</p>
+<p>There are also various STL adapter classes such as <tt class="docutils literal"><span class="pre">std::queue</span></tt>,
+<tt class="docutils literal"><span class="pre">std::priority_queue</span></tt>, <tt class="docutils literal"><span class="pre">std::stack</span></tt>, etc. These provide simplified access
+to an underlying container but don’t affect the cost of the container itself.</p>
+</div>
+</div>
+<div class="section" id="string-like-containers">
+<span id="ds-string"></span><h3><a class="toc-backref" href="#id36">String-like containers</a><a class="headerlink" href="#string-like-containers" title="Permalink to this headline">¶</a></h3>
+<p>There are a variety of ways to pass around and use strings in C and C++, and
+LLVM adds a few new options to choose from. Pick the first option on this list
+that will do what you need, they are ordered according to their relative cost.</p>
+<p>Note that is is generally preferred to <em>not</em> pass strings around as <tt class="docutils literal"><span class="pre">const</span>
+<span class="pre">char*</span></tt>‘s. These have a number of problems, including the fact that they
+cannot represent embedded nul (“0”) characters, and do not have a length
+available efficiently. The general replacement for ‘<tt class="docutils literal"><span class="pre">const</span> <span class="pre">char*</span></tt>‘ is
+StringRef.</p>
+<p>For more information on choosing string containers for APIs, please see
+<a class="reference internal" href="#string-apis"><em>Passing Strings</em></a>.</p>
+<div class="section" id="llvm-adt-stringref-h">
+<span id="dss-stringref"></span><h4><a class="toc-backref" href="#id37">llvm/ADT/StringRef.h</a><a class="headerlink" href="#llvm-adt-stringref-h" title="Permalink to this headline">¶</a></h4>
+<p>The StringRef class is a simple value class that contains a pointer to a
+character and a length, and is quite related to the <a class="reference internal" href="#dss-arrayref"><em>ArrayRef</em></a> class (but specialized for arrays of characters). Because
+StringRef carries a length with it, it safely handles strings with embedded nul
+characters in it, getting the length does not require a strlen call, and it even
+has very convenient APIs for slicing and dicing the character range that it
+represents.</p>
+<p>StringRef is ideal for passing simple strings around that are known to be live,
+either because they are C string literals, std::string, a C array, or a
+SmallVector. Each of these cases has an efficient implicit conversion to
+StringRef, which doesn’t result in a dynamic strlen being executed.</p>
+<p>StringRef has a few major limitations which make more powerful string containers
+useful:</p>
+<ol class="arabic simple">
+<li>You cannot directly convert a StringRef to a ‘const char*’ because there is
+no way to add a trailing nul (unlike the .c_str() method on various stronger
+classes).</li>
+<li>StringRef doesn’t own or keep alive the underlying string bytes.
+As such it can easily lead to dangling pointers, and is not suitable for
+embedding in datastructures in most cases (instead, use an std::string or
+something like that).</li>
+<li>For the same reason, StringRef cannot be used as the return value of a
+method if the method “computes” the result string. Instead, use std::string.</li>
+<li>StringRef’s do not allow you to mutate the pointed-to string bytes and it
+doesn’t allow you to insert or remove bytes from the range. For editing
+operations like this, it interoperates with the <a class="reference internal" href="#dss-twine"><em>Twine</em></a>
+class.</li>
+</ol>
+<p>Because of its strengths and limitations, it is very common for a function to
+take a StringRef and for a method on an object to return a StringRef that points
+into some string that it owns.</p>
+</div>
+<div class="section" id="llvm-adt-twine-h">
+<span id="dss-twine"></span><h4><a class="toc-backref" href="#id38">llvm/ADT/Twine.h</a><a class="headerlink" href="#llvm-adt-twine-h" title="Permalink to this headline">¶</a></h4>
+<p>The Twine class is used as an intermediary datatype for APIs that want to take a
+string that can be constructed inline with a series of concatenations. Twine
+works by forming recursive instances of the Twine datatype (a simple value
+object) on the stack as temporary objects, linking them together into a tree
+which is then linearized when the Twine is consumed. Twine is only safe to use
+as the argument to a function, and should always be a const reference, e.g.:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="k">const</span> <span class="n">Twine</span> <span class="o">&</span><span class="n">T</span><span class="p">);</span>
+<span class="p">...</span>
+<span class="n">StringRef</span> <span class="n">X</span> <span class="o">=</span> <span class="p">...</span>
+<span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="p">...</span>
+<span class="n">foo</span><span class="p">(</span><span class="n">X</span> <span class="o">+</span> <span class="s">"."</span> <span class="o">+</span> <span class="n">Twine</span><span class="p">(</span><span class="n">i</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This example forms a string like “blarg.42” by concatenating the values
+together, and does not form intermediate strings containing “blarg” or “blarg.”.</p>
+<p>Because Twine is constructed with temporary objects on the stack, and because
+these instances are destroyed at the end of the current statement, it is an
+inherently dangerous API. For example, this simple variant contains undefined
+behavior and will probably crash:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="k">const</span> <span class="n">Twine</span> <span class="o">&</span><span class="n">T</span><span class="p">);</span>
+<span class="p">...</span>
+<span class="n">StringRef</span> <span class="n">X</span> <span class="o">=</span> <span class="p">...</span>
+<span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="p">...</span>
+<span class="k">const</span> <span class="n">Twine</span> <span class="o">&</span><span class="n">Tmp</span> <span class="o">=</span> <span class="n">X</span> <span class="o">+</span> <span class="s">"."</span> <span class="o">+</span> <span class="n">Twine</span><span class="p">(</span><span class="n">i</span><span class="p">);</span>
+<span class="n">foo</span><span class="p">(</span><span class="n">Tmp</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>... because the temporaries are destroyed before the call. That said, Twine’s
+are much more efficient than intermediate std::string temporaries, and they work
+really well with StringRef. Just be aware of their limitations.</p>
+</div>
+<div class="section" id="llvm-adt-smallstring-h">
+<span id="dss-smallstring"></span><h4><a class="toc-backref" href="#id39">llvm/ADT/SmallString.h</a><a class="headerlink" href="#llvm-adt-smallstring-h" title="Permalink to this headline">¶</a></h4>
+<p>SmallString is a subclass of <a class="reference internal" href="#dss-smallvector"><em>SmallVector</em></a> that adds some
+convenience APIs like += that takes StringRef’s. SmallString avoids allocating
+memory in the case when the preallocated space is enough to hold its data, and
+it calls back to general heap allocation when required. Since it owns its data,
+it is very safe to use and supports full mutation of the string.</p>
+<p>Like SmallVector’s, the big downside to SmallString is their sizeof. While they
+are optimized for small strings, they themselves are not particularly small.
+This means that they work great for temporary scratch buffers on the stack, but
+should not generally be put into the heap: it is very rare to see a SmallString
+as the member of a frequently-allocated heap data structure or returned
+by-value.</p>
+</div>
+<div class="section" id="std-string">
+<span id="dss-stdstring"></span><h4><a class="toc-backref" href="#id40">std::string</a><a class="headerlink" href="#std-string" title="Permalink to this headline">¶</a></h4>
+<p>The standard C++ std::string class is a very general class that (like
+SmallString) owns its underlying data. sizeof(std::string) is very reasonable
+so it can be embedded into heap data structures and returned by-value. On the
+other hand, std::string is highly inefficient for inline editing (e.g.
+concatenating a bunch of stuff together) and because it is provided by the
+standard library, its performance characteristics depend a lot of the host
+standard library (e.g. libc++ and MSVC provide a highly optimized string class,
+GCC contains a really slow implementation).</p>
+<p>The major disadvantage of std::string is that almost every operation that makes
+them larger can allocate memory, which is slow. As such, it is better to use
+SmallVector or Twine as a scratch buffer, but then use std::string to persist
+the result.</p>
+</div>
+</div>
+<div class="section" id="set-like-containers-std-set-smallset-setvector-etc">
+<span id="ds-set"></span><h3><a class="toc-backref" href="#id41">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a><a class="headerlink" href="#set-like-containers-std-set-smallset-setvector-etc" title="Permalink to this headline">¶</a></h3>
+<p>Set-like containers are useful when you need to canonicalize multiple values
+into a single representation. There are several different choices for how to do
+this, providing various trade-offs.</p>
+<div class="section" id="a-sorted-vector">
+<span id="dss-sortedvectorset"></span><h4><a class="toc-backref" href="#id42">A sorted ‘vector’</a><a class="headerlink" href="#a-sorted-vector" title="Permalink to this headline">¶</a></h4>
+<p>If you intend to insert a lot of elements, then do a lot of queries, a great
+approach is to use a vector (or other sequential container) with
+std::sort+std::unique to remove duplicates. This approach works really well if
+your usage pattern has these two distinct phases (insert then query), and can be
+coupled with a good choice of <a class="reference internal" href="#ds-sequential"><em>sequential container</em></a>.</p>
+<p>This combination provides the several nice properties: the result data is
+contiguous in memory (good for cache locality), has few allocations, is easy to
+address (iterators in the final vector are just indices or pointers), and can be
+efficiently queried with a standard binary search (e.g.
+<tt class="docutils literal"><span class="pre">std::lower_bound</span></tt>; if you want the whole range of elements comparing
+equal, use <tt class="docutils literal"><span class="pre">std::equal_range</span></tt>).</p>
+</div>
+<div class="section" id="llvm-adt-smallset-h">
+<span id="dss-smallset"></span><h4><a class="toc-backref" href="#id43">llvm/ADT/SmallSet.h</a><a class="headerlink" href="#llvm-adt-smallset-h" title="Permalink to this headline">¶</a></h4>
+<p>If you have a set-like data structure that is usually small and whose elements
+are reasonably small, a <tt class="docutils literal"><span class="pre">SmallSet<Type,</span> <span class="pre">N></span></tt> is a good choice. This set has
+space for N elements in place (thus, if the set is dynamically smaller than N,
+no malloc traffic is required) and accesses them with a simple linear search.
+When the set grows beyond ‘N’ elements, it allocates a more expensive
+representation that guarantees efficient access (for most types, it falls back
+to std::set, but for pointers it uses something far better, <a class="reference internal" href="#dss-smallptrset"><em>SmallPtrSet</em></a>.</p>
+<p>The magic of this class is that it handles small sets extremely efficiently, but
+gracefully handles extremely large sets without loss of efficiency. The
+drawback is that the interface is quite small: it supports insertion, queries
+and erasing, but does not support iteration.</p>
+</div>
+<div class="section" id="llvm-adt-smallptrset-h">
+<span id="dss-smallptrset"></span><h4><a class="toc-backref" href="#id44">llvm/ADT/SmallPtrSet.h</a><a class="headerlink" href="#llvm-adt-smallptrset-h" title="Permalink to this headline">¶</a></h4>
+<p>SmallPtrSet has all the advantages of <tt class="docutils literal"><span class="pre">SmallSet</span></tt> (and a <tt class="docutils literal"><span class="pre">SmallSet</span></tt> of
+pointers is transparently implemented with a <tt class="docutils literal"><span class="pre">SmallPtrSet</span></tt>), but also supports
+iterators. If more than ‘N’ insertions are performed, a single quadratically
+probed hash table is allocated and grows as needed, providing extremely
+efficient access (constant time insertion/deleting/queries with low constant
+factors) and is very stingy with malloc traffic.</p>
+<p>Note that, unlike <tt class="docutils literal"><span class="pre">std::set</span></tt>, the iterators of <tt class="docutils literal"><span class="pre">SmallPtrSet</span></tt> are invalidated
+whenever an insertion occurs. Also, the values visited by the iterators are not
+visited in sorted order.</p>
+</div>
+<div class="section" id="llvm-adt-denseset-h">
+<span id="dss-denseset"></span><h4><a class="toc-backref" href="#id45">llvm/ADT/DenseSet.h</a><a class="headerlink" href="#llvm-adt-denseset-h" title="Permalink to this headline">¶</a></h4>
+<p>DenseSet is a simple quadratically probed hash table. It excels at supporting
+small values: it uses a single allocation to hold all of the pairs that are
+currently inserted in the set. DenseSet is a great way to unique small values
+that are not simple pointers (use <a class="reference internal" href="#dss-smallptrset"><em>SmallPtrSet</em></a> for
+pointers). Note that DenseSet has the same requirements for the value type that
+<a class="reference internal" href="#dss-densemap"><em>DenseMap</em></a> has.</p>
+</div>
+<div class="section" id="llvm-adt-sparseset-h">
+<span id="dss-sparseset"></span><h4><a class="toc-backref" href="#id46">llvm/ADT/SparseSet.h</a><a class="headerlink" href="#llvm-adt-sparseset-h" title="Permalink to this headline">¶</a></h4>
+<p>SparseSet holds a small number of objects identified by unsigned keys of
+moderate size. It uses a lot of memory, but provides operations that are almost
+as fast as a vector. Typical keys are physical registers, virtual registers, or
+numbered basic blocks.</p>
+<p>SparseSet is useful for algorithms that need very fast clear/find/insert/erase
+and fast iteration over small sets. It is not intended for building composite
+data structures.</p>
+</div>
+<div class="section" id="llvm-adt-sparsemultiset-h">
+<span id="dss-sparsemultiset"></span><h4><a class="toc-backref" href="#id47">llvm/ADT/SparseMultiSet.h</a><a class="headerlink" href="#llvm-adt-sparsemultiset-h" title="Permalink to this headline">¶</a></h4>
+<p>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.</p>
+<p>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.</p>
+</div>
+<div class="section" id="llvm-adt-foldingset-h">
+<span id="dss-foldingset"></span><h4><a class="toc-backref" href="#id48">llvm/ADT/FoldingSet.h</a><a class="headerlink" href="#llvm-adt-foldingset-h" title="Permalink to this headline">¶</a></h4>
+<p>FoldingSet is an aggregate class that is really good at uniquing
+expensive-to-create or polymorphic objects. It is a combination of a chained
+hash table with intrusive links (uniqued objects are required to inherit from
+FoldingSetNode) that uses <a class="reference internal" href="#dss-smallvector"><em>SmallVector</em></a> as part of its ID
+process.</p>
+<p>Consider a case where you want to implement a “getOrCreateFoo” method for a
+complex object (for example, a node in the code generator). The client has a
+description of <strong>what</strong> it wants to generate (it knows the opcode and all the
+operands), but we don’t want to ‘new’ a node, then try inserting it into a set
+only to find out it already exists, at which point we would have to delete it
+and return the node that already exists.</p>
+<p>To support this style of client, FoldingSet perform a query with a
+FoldingSetNodeID (which wraps SmallVector) that can be used to describe the
+element that we want to query for. The query either returns the element
+matching the ID or it returns an opaque ID that indicates where insertion should
+take place. Construction of the ID usually does not require heap traffic.</p>
+<p>Because FoldingSet uses intrusive links, it can support polymorphic objects in
+the set (for example, you can have SDNode instances mixed with LoadSDNodes).
+Because the elements are individually allocated, pointers to the elements are
+stable: inserting or removing elements does not invalidate any pointers to other
+elements.</p>
+</div>
+<div class="section" id="set">
+<span id="dss-set"></span><h4><a class="toc-backref" href="#id49"><set></a><a class="headerlink" href="#set" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">std::set</span></tt> is a reasonable all-around set class, which is decent at many
+things but great at nothing. std::set allocates memory for each element
+inserted (thus it is very malloc intensive) and typically stores three pointers
+per element in the set (thus adding a large amount of per-element space
+overhead). It offers guaranteed log(n) performance, which is not particularly
+fast from a complexity standpoint (particularly if the elements of the set are
+expensive to compare, like strings), and has extremely high constant factors for
+lookup, insertion and removal.</p>
+<p>The advantages of std::set are that its iterators are stable (deleting or
+inserting an element from the set does not affect iterators or pointers to other
+elements) and that iteration over the set is guaranteed to be in sorted order.
+If the elements in the set are large, then the relative overhead of the pointers
+and malloc traffic is not a big deal, but if the elements of the set are small,
+std::set is almost never a good choice.</p>
+</div>
+<div class="section" id="llvm-adt-setvector-h">
+<span id="dss-setvector"></span><h4><a class="toc-backref" href="#id50">llvm/ADT/SetVector.h</a><a class="headerlink" href="#llvm-adt-setvector-h" title="Permalink to this headline">¶</a></h4>
+<p>LLVM’s <tt class="docutils literal"><span class="pre">SetVector<Type></span></tt> is an adapter class that combines your choice of a
+set-like container along with a <a class="reference internal" href="#ds-sequential"><em>Sequential Container</em></a> The
+important property that this provides is efficient insertion with uniquing
+(duplicate elements are ignored) with iteration support. It implements this by
+inserting elements into both a set-like container and the sequential container,
+using the set-like container for uniquing and the sequential container for
+iteration.</p>
+<p>The difference between SetVector and other sets is that the order of iteration
+is guaranteed to match the order of insertion into the SetVector. This property
+is really important for things like sets of pointers. Because pointer values
+are non-deterministic (e.g. vary across runs of the program on different
+machines), iterating over the pointers in the set will not be in a well-defined
+order.</p>
+<p>The drawback of SetVector is that it requires twice as much space as a normal
+set and has the sum of constant factors from the set-like container and the
+sequential container that it uses. Use it <strong>only</strong> if you need to iterate over
+the elements in a deterministic order. SetVector is also expensive to delete
+elements out of (linear time), unless you use it’s “pop_back” method, which is
+faster.</p>
+<p><tt class="docutils literal"><span class="pre">SetVector</span></tt> is an adapter class that defaults to using <tt class="docutils literal"><span class="pre">std::vector</span></tt> and a
+size 16 <tt class="docutils literal"><span class="pre">SmallSet</span></tt> for the underlying containers, so it is quite expensive.
+However, <tt class="docutils literal"><span class="pre">"llvm/ADT/SetVector.h"</span></tt> also provides a <tt class="docutils literal"><span class="pre">SmallSetVector</span></tt> class,
+which defaults to using a <tt class="docutils literal"><span class="pre">SmallVector</span></tt> and <tt class="docutils literal"><span class="pre">SmallSet</span></tt> of a specified size.
+If you use this, and if your sets are dynamically smaller than <tt class="docutils literal"><span class="pre">N</span></tt>, you will
+save a lot of heap traffic.</p>
+</div>
+<div class="section" id="llvm-adt-uniquevector-h">
+<span id="dss-uniquevector"></span><h4><a class="toc-backref" href="#id51">llvm/ADT/UniqueVector.h</a><a class="headerlink" href="#llvm-adt-uniquevector-h" title="Permalink to this headline">¶</a></h4>
+<p>UniqueVector is similar to <a class="reference internal" href="#dss-setvector"><em>SetVector</em></a> but it retains a
+unique ID for each element inserted into the set. It internally contains a map
+and a vector, and it assigns a unique ID for each value inserted into the set.</p>
+<p>UniqueVector is very expensive: its cost is the sum of the cost of maintaining
+both the map and vector, it has high complexity, high constant factors, and
+produces a lot of malloc traffic. It should be avoided.</p>
+</div>
+<div class="section" id="llvm-adt-immutableset-h">
+<span id="dss-immutableset"></span><h4><a class="toc-backref" href="#id52">llvm/ADT/ImmutableSet.h</a><a class="headerlink" href="#llvm-adt-immutableset-h" title="Permalink to this headline">¶</a></h4>
+<p>ImmutableSet is an immutable (functional) set implementation based on an AVL
+tree. Adding or removing elements is done through a Factory object and results
+in the creation of a new ImmutableSet object. If an ImmutableSet already exists
+with the given contents, then the existing one is returned; equality is compared
+with a FoldingSetNodeID. The time and space complexity of add or remove
+operations is logarithmic in the size of the original set.</p>
+<p>There is no method for returning an element of the set, you can only check for
+membership.</p>
+</div>
+<div class="section" id="other-set-like-container-options">
+<span id="dss-otherset"></span><h4><a class="toc-backref" href="#id53">Other Set-Like Container Options</a><a class="headerlink" href="#other-set-like-container-options" title="Permalink to this headline">¶</a></h4>
+<p>The STL provides several other options, such as std::multiset and the various
+“hash_set” like containers (whether from C++ TR1 or from the SGI library). We
+never use hash_set and unordered_set because they are generally very expensive
+(each insertion requires a malloc) and very non-portable.</p>
+<p>std::multiset is useful if you’re not interested in elimination of duplicates,
+but has all the drawbacks of std::set. A sorted vector (where you don’t delete
+duplicate entries) or some other approach is almost always better.</p>
+</div>
+</div>
+<div class="section" id="map-like-containers-std-map-densemap-etc">
+<span id="ds-map"></span><h3><a class="toc-backref" href="#id54">Map-Like Containers (std::map, DenseMap, etc)</a><a class="headerlink" href="#map-like-containers-std-map-densemap-etc" title="Permalink to this headline">¶</a></h3>
+<p>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. :)</p>
+<div class="section" id="dss-sortedvectormap">
+<span id="id2"></span><h4><a class="toc-backref" href="#id55">A sorted ‘vector’</a><a class="headerlink" href="#dss-sortedvectormap" title="Permalink to this headline">¶</a></h4>
+<p>If your usage pattern follows a strict insert-then-query approach, you can
+trivially use the same approach as <a class="reference internal" href="#dss-sortedvectorset"><em>sorted vectors for set-like containers</em></a>. The only difference is that your query function (which
+uses std::lower_bound to get efficient log(n) lookup) should only compare the
+key, not both the key and value. This yields the same advantages as sorted
+vectors for sets.</p>
+</div>
+<div class="section" id="llvm-adt-stringmap-h">
+<span id="dss-stringmap"></span><h4><a class="toc-backref" href="#id56">llvm/ADT/StringMap.h</a><a class="headerlink" href="#llvm-adt-stringmap-h" title="Permalink to this headline">¶</a></h4>
+<p>Strings are commonly used as keys in maps, and they are difficult to support
+efficiently: they are variable length, inefficient to hash and compare when
+long, expensive to copy, etc. StringMap is a specialized container designed to
+cope with these issues. It supports mapping an arbitrary range of bytes to an
+arbitrary other object.</p>
+<p>The StringMap implementation uses a quadratically-probed hash table, where the
+buckets store a pointer to the heap allocated entries (and some other stuff).
+The entries in the map must be heap allocated because the strings are variable
+length. The string data (key) and the element object (value) are stored in the
+same allocation with the string data immediately after the element object.
+This container guarantees the “<tt class="docutils literal"><span class="pre">(char*)(&Value+1)</span></tt>” points to the key string
+for a value.</p>
+<p>The StringMap is very fast for several reasons: quadratic probing is very cache
+efficient for lookups, the hash value of strings in buckets is not recomputed
+when looking up an element, StringMap rarely has to touch the memory for
+unrelated objects when looking up a value (even when hash collisions happen),
+hash table growth does not recompute the hash values for strings already in the
+table, and each pair in the map is store in a single allocation (the string data
+is stored in the same allocation as the Value of a pair).</p>
+<p>StringMap also provides query methods that take byte ranges, so it only ever
+copies a string if a value is inserted into the table.</p>
+<p>StringMap iteratation order, however, is not guaranteed to be deterministic, so
+any uses which require that should instead use a std::map.</p>
+</div>
+<div class="section" id="llvm-adt-indexedmap-h">
+<span id="dss-indexmap"></span><h4><a class="toc-backref" href="#id57">llvm/ADT/IndexedMap.h</a><a class="headerlink" href="#llvm-adt-indexedmap-h" title="Permalink to this headline">¶</a></h4>
+<p>IndexedMap is a specialized container for mapping small dense integers (or
+values that can be mapped to small dense integers) to some other type. It is
+internally implemented as a vector with a mapping function that maps the keys
+to the dense integer range.</p>
+<p>This is useful for cases like virtual registers in the LLVM code generator: they
+have a dense mapping that is offset by a compile-time constant (the first
+virtual register ID).</p>
+</div>
+<div class="section" id="llvm-adt-densemap-h">
+<span id="dss-densemap"></span><h4><a class="toc-backref" href="#id58">llvm/ADT/DenseMap.h</a><a class="headerlink" href="#llvm-adt-densemap-h" title="Permalink to this headline">¶</a></h4>
+<p>DenseMap is a simple quadratically probed hash table. It excels at supporting
+small keys and values: it uses a single allocation to hold all of the pairs
+that are currently inserted in the map. DenseMap is a great way to map
+pointers to pointers, or map other small types to each other.</p>
+<p>There are several aspects of DenseMap that you should be aware of, however.
+The iterators in a DenseMap are invalidated whenever an insertion occurs,
+unlike map. Also, because DenseMap allocates space for a large number of
+key/value pairs (it starts with 64 by default), it will waste a lot of space if
+your keys or values are large. Finally, you must implement a partial
+specialization of DenseMapInfo for the key that you want, if it isn’t already
+supported. This is required to tell DenseMap about two special marker values
+(which can never be inserted into the map) that it needs internally.</p>
+<p>DenseMap’s find_as() method supports lookup operations using an alternate key
+type. This is useful in cases where the normal key type is expensive to
+construct, but cheap to compare against. The DenseMapInfo is responsible for
+defining the appropriate comparison and hashing methods for each alternate key
+type used.</p>
+</div>
+<div class="section" id="llvm-adt-valuemap-h">
+<span id="dss-valuemap"></span><h4><a class="toc-backref" href="#id59">llvm/ADT/ValueMap.h</a><a class="headerlink" href="#llvm-adt-valuemap-h" title="Permalink to this headline">¶</a></h4>
+<p>ValueMap is a wrapper around a <a class="reference internal" href="#dss-densemap"><em>DenseMap</em></a> mapping
+<tt class="docutils literal"><span class="pre">Value*</span></tt>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 <tt class="docutils literal"><span class="pre">Config</span></tt>
+parameter to the ValueMap template.</p>
+</div>
+<div class="section" id="llvm-adt-intervalmap-h">
+<span id="dss-intervalmap"></span><h4><a class="toc-backref" href="#id60">llvm/ADT/IntervalMap.h</a><a class="headerlink" href="#llvm-adt-intervalmap-h" title="Permalink to this headline">¶</a></h4>
+<p>IntervalMap is a compact map for small keys and values. It maps key intervals
+instead of single keys, and it will automatically coalesce adjacent intervals.
+When then map only contains a few intervals, they are stored in the map object
+itself to avoid allocations.</p>
+<p>The IntervalMap iterators are quite big, so they should not be passed around as
+STL iterators. The heavyweight iterators allow a smaller data structure.</p>
+</div>
+<div class="section" id="map">
+<span id="dss-map"></span><h4><a class="toc-backref" href="#id61"><map></a><a class="headerlink" href="#map" title="Permalink to this headline">¶</a></h4>
+<p>std::map has similar characteristics to <a class="reference internal" href="#dss-set"><em>std::set</em></a>: it uses a
+single allocation per pair inserted into the map, it offers log(n) lookup with
+an extremely large constant factor, imposes a space penalty of 3 pointers per
+pair in the map, etc.</p>
+<p>std::map is most useful when your keys or values are very large, if you need to
+iterate over the collection in sorted order, or if you need stable iterators
+into the map (i.e. they don’t get invalidated if an insertion or deletion of
+another element takes place).</p>
+</div>
+<div class="section" id="llvm-adt-mapvector-h">
+<span id="dss-mapvector"></span><h4><a class="toc-backref" href="#id62">llvm/ADT/MapVector.h</a><a class="headerlink" href="#llvm-adt-mapvector-h" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">MapVector<KeyT,ValueT></span></tt> provides a subset of the DenseMap interface. The
+main difference is that the iteration order is guaranteed to be the insertion
+order, making it an easy (but somewhat expensive) solution for non-deterministic
+iteration over maps of pointers.</p>
+<p>It is implemented by mapping from key to an index in a vector of key,value
+pairs. This provides fast lookup and iteration, but has two main drawbacks: The
+key is stored twice and it doesn’t support removing elements.</p>
+</div>
+<div class="section" id="llvm-adt-inteqclasses-h">
+<span id="dss-inteqclasses"></span><h4><a class="toc-backref" href="#id63">llvm/ADT/IntEqClasses.h</a><a class="headerlink" href="#llvm-adt-inteqclasses-h" title="Permalink to this headline">¶</a></h4>
+<p>IntEqClasses provides a compact representation of equivalence classes of small
+integers. Initially, each integer in the range 0..n-1 has its own equivalence
+class. Classes can be joined by passing two class representatives to the
+join(a, b) method. Two integers are in the same class when findLeader() returns
+the same representative.</p>
+<p>Once all equivalence classes are formed, the map can be compressed so each
+integer 0..n-1 maps to an equivalence class number in the range 0..m-1, where m
+is the total number of equivalence classes. The map must be uncompressed before
+it can be edited again.</p>
+</div>
+<div class="section" id="llvm-adt-immutablemap-h">
+<span id="dss-immutablemap"></span><h4><a class="toc-backref" href="#id64">llvm/ADT/ImmutableMap.h</a><a class="headerlink" href="#llvm-adt-immutablemap-h" title="Permalink to this headline">¶</a></h4>
+<p>ImmutableMap is an immutable (functional) map implementation based on an AVL
+tree. Adding or removing elements is done through a Factory object and results
+in the creation of a new ImmutableMap object. If an ImmutableMap already exists
+with the given key set, then the existing one is returned; equality is compared
+with a FoldingSetNodeID. The time and space complexity of add or remove
+operations is logarithmic in the size of the original map.</p>
+</div>
+<div class="section" id="other-map-like-container-options">
+<span id="dss-othermap"></span><h4><a class="toc-backref" href="#id65">Other Map-Like Container Options</a><a class="headerlink" href="#other-map-like-container-options" title="Permalink to this headline">¶</a></h4>
+<p>The STL provides several other options, such as std::multimap and the various
+“hash_map” like containers (whether from C++ TR1 or from the SGI library). We
+never use hash_set and unordered_set because they are generally very expensive
+(each insertion requires a malloc) and very non-portable.</p>
+<p>std::multimap is useful if you want to map a key to multiple values, but has all
+the drawbacks of std::map. A sorted vector or some other approach is almost
+always better.</p>
+</div>
+</div>
+<div class="section" id="bit-storage-containers-bitvector-sparsebitvector">
+<span id="ds-bit"></span><h3><a class="toc-backref" href="#id66">Bit storage containers (BitVector, SparseBitVector)</a><a class="headerlink" href="#bit-storage-containers-bitvector-sparsebitvector" title="Permalink to this headline">¶</a></h3>
+<p>Unlike the other containers, there are only two bit storage containers, and
+choosing when to use each is relatively straightforward.</p>
+<p>One additional option is <tt class="docutils literal"><span class="pre">std::vector<bool></span></tt>: we discourage its use for two
+reasons 1) the implementation in many common compilers (e.g. commonly
+available versions of GCC) is extremely inefficient and 2) the C++ standards
+committee is likely to deprecate this container and/or change it significantly
+somehow. In any case, please don’t use it.</p>
+<div class="section" id="bitvector">
+<span id="dss-bitvector"></span><h4><a class="toc-backref" href="#id67">BitVector</a><a class="headerlink" href="#bitvector" title="Permalink to this headline">¶</a></h4>
+<p>The BitVector container provides a dynamic size set of bits for manipulation.
+It supports individual bit setting/testing, as well as set operations. The set
+operations take time O(size of bitvector), but operations are performed one word
+at a time, instead of one bit at a time. This makes the BitVector very fast for
+set operations compared to other containers. Use the BitVector when you expect
+the number of set bits to be high (i.e. a dense set).</p>
+</div>
+<div class="section" id="smallbitvector">
+<span id="dss-smallbitvector"></span><h4><a class="toc-backref" href="#id68">SmallBitVector</a><a class="headerlink" href="#smallbitvector" title="Permalink to this headline">¶</a></h4>
+<p>The SmallBitVector container provides the same interface as BitVector, but it is
+optimized for the case where only a small number of bits, less than 25 or so,
+are needed. It also transparently supports larger bit counts, but slightly less
+efficiently than a plain BitVector, so SmallBitVector should only be used when
+larger counts are rare.</p>
+<p>At this time, SmallBitVector does not support set operations (and, or, xor), and
+its operator[] does not provide an assignable lvalue.</p>
+</div>
+<div class="section" id="sparsebitvector">
+<span id="dss-sparsebitvector"></span><h4><a class="toc-backref" href="#id69">SparseBitVector</a><a class="headerlink" href="#sparsebitvector" title="Permalink to this headline">¶</a></h4>
+<p>The SparseBitVector container is much like BitVector, with one major difference:
+Only the bits that are set, are stored. This makes the SparseBitVector much
+more space efficient than BitVector when the set is sparse, as well as making
+set operations O(number of set bits) instead of O(size of universe). The
+downside to the SparseBitVector is that setting and testing of random bits is
+O(N), and on large SparseBitVectors, this can be slower than BitVector. In our
+implementation, setting or testing bits in sorted order (either forwards or
+reverse) is O(1) worst case. Testing and setting bits within 128 bits (depends
+on size) of the current bit is also O(1). As a general statement,
+testing/setting bits in a SparseBitVector is O(distance away from last set bit).</p>
+</div>
+</div>
+</div>
+<div class="section" id="helpful-hints-for-common-operations">
+<span id="common"></span><h2><a class="toc-backref" href="#id70">Helpful Hints for Common Operations</a><a class="headerlink" href="#helpful-hints-for-common-operations" title="Permalink to this headline">¶</a></h2>
+<p>This section describes how to perform some very simple transformations of LLVM
+code. This is meant to give examples of common idioms used, showing the
+practical side of LLVM transformations.</p>
+<p>Because this is a “how-to” section, you should also read about the main classes
+that you will be working with. The <a class="reference internal" href="#coreclasses"><em>Core LLVM Class Hierarchy Reference</em></a> contains details and descriptions of the main classes that you
+should know about.</p>
+<div class="section" id="basic-inspection-and-traversal-routines">
+<span id="inspection"></span><h3><a class="toc-backref" href="#id71">Basic Inspection and Traversal Routines</a><a class="headerlink" href="#basic-inspection-and-traversal-routines" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM compiler infrastructure have many different data structures that may be
+traversed. Following the example of the C++ standard template library, the
+techniques used to traverse these various data structures are all basically the
+same. For a enumerable sequence of values, the <tt class="docutils literal"><span class="pre">XXXbegin()</span></tt> function (or
+method) returns an iterator to the start of the sequence, the <tt class="docutils literal"><span class="pre">XXXend()</span></tt>
+function returns an iterator pointing to one past the last valid element of the
+sequence, and there is some <tt class="docutils literal"><span class="pre">XXXiterator</span></tt> data type that is common between the
+two operations.</p>
+<p>Because the pattern for iteration is common across many different aspects of the
+program representation, the standard template library algorithms may be used on
+them, and it is easier to remember how to iterate. First we show a few common
+examples of the data structures that need to be traversed. Other data
+structures are traversed in very similar ways.</p>
+<div class="section" id="iterating-over-the-basicblock-in-a-function">
+<span id="iterate-function"></span><h4><a class="toc-backref" href="#id72">Iterating over the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> in a <tt class="docutils literal"><span class="pre">Function</span></tt></a><a class="headerlink" href="#iterating-over-the-basicblock-in-a-function" title="Permalink to this headline">¶</a></h4>
+<p>It’s quite common to have a <tt class="docutils literal"><span class="pre">Function</span></tt> instance that you’d like to transform
+in some way; in particular, you’d like to manipulate its <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s. To
+facilitate this, you’ll need to iterate over all of the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s that
+constitute the <tt class="docutils literal"><span class="pre">Function</span></tt>. The following is an example that prints the name
+of a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> and the number of <tt class="docutils literal"><span class="pre">Instruction</span></tt>s it contains:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// func is a pointer to a Function instance</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">Function</span><span class="o">::</span><span class="n">iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">func</span><span class="o">-></span><span class="n">begin</span><span class="p">(),</span> <span class="n">e</span> <span class="o">=</span> <span class="n">func</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="c1">// Print out the name of the basic block if it has one, and then the</span>
+ <span class="c1">// number of instructions that it contains</span>
+ <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"Basic block (name="</span> <span class="o"><<</span> <span class="n">i</span><span class="o">-></span><span class="n">getName</span><span class="p">()</span> <span class="o"><<</span> <span class="s">") has "</span>
+ <span class="o"><<</span> <span class="n">i</span><span class="o">-></span><span class="n">size</span><span class="p">()</span> <span class="o"><<</span> <span class="s">" instructions.</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Note that i can be used as if it were a pointer for the purposes of invoking
+member functions of the <tt class="docutils literal"><span class="pre">Instruction</span></tt> class. This is because the indirection
+operator is overloaded for the iterator classes. In the above code, the
+expression <tt class="docutils literal"><span class="pre">i->size()</span></tt> is exactly equivalent to <tt class="docutils literal"><span class="pre">(*i).size()</span></tt> just like
+you’d expect.</p>
+</div>
+<div class="section" id="iterating-over-the-instruction-in-a-basicblock">
+<span id="iterate-basicblock"></span><h4><a class="toc-backref" href="#id73">Iterating over the <tt class="docutils literal"><span class="pre">Instruction</span></tt> in a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt></a><a class="headerlink" href="#iterating-over-the-instruction-in-a-basicblock" title="Permalink to this headline">¶</a></h4>
+<p>Just like when dealing with <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s in <tt class="docutils literal"><span class="pre">Function</span></tt>s, it’s easy to
+iterate over the individual instructions that make up <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s. Here’s
+a code snippet that prints out each instruction in a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// blk is a pointer to a BasicBlock instance</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">BasicBlock</span><span class="o">::</span><span class="n">iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">blk</span><span class="o">-></span><span class="n">begin</span><span class="p">(),</span> <span class="n">e</span> <span class="o">=</span> <span class="n">blk</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="c1">// The next statement works since operator<<(ostream&,...)</span>
+ <span class="c1">// is overloaded for Instruction&</span>
+ <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="o">*</span><span class="n">i</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>However, this isn’t really the best way to print out the contents of a
+<tt class="docutils literal"><span class="pre">BasicBlock</span></tt>! Since the ostream operators are overloaded for virtually
+anything you’ll care about, you could have just invoked the print routine on the
+basic block itself: <tt class="docutils literal"><span class="pre">errs()</span> <span class="pre"><<</span> <span class="pre">*blk</span> <span class="pre"><<</span> <span class="pre">"\n";</span></tt>.</p>
+</div>
+<div class="section" id="iterating-over-the-instruction-in-a-function">
+<span id="iterate-insiter"></span><h4><a class="toc-backref" href="#id74">Iterating over the <tt class="docutils literal"><span class="pre">Instruction</span></tt> in a <tt class="docutils literal"><span class="pre">Function</span></tt></a><a class="headerlink" href="#iterating-over-the-instruction-in-a-function" title="Permalink to this headline">¶</a></h4>
+<p>If you’re finding that you commonly iterate over a <tt class="docutils literal"><span class="pre">Function</span></tt>‘s
+<tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s and then that <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>‘s <tt class="docutils literal"><span class="pre">Instruction</span></tt>s,
+<tt class="docutils literal"><span class="pre">InstIterator</span></tt> should be used instead. You’ll need to include
+<tt class="docutils literal"><span class="pre">llvm/Support/InstIterator.h</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/InstIterator_8h-source.html">doxygen</a>) and then instantiate
+<tt class="docutils literal"><span class="pre">InstIterator</span></tt>s explicitly in your code. Here’s a small example that shows
+how to dump all instructions in a function to the standard error stream:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Support/InstIterator.h"</span>
+
+<span class="c1">// F is a pointer to a Function instance</span>
+<span class="k">for</span> <span class="p">(</span><span class="n">inst_iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">inst_begin</span><span class="p">(</span><span class="n">F</span><span class="p">),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">inst_end</span><span class="p">(</span><span class="n">F</span><span class="p">);</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
+ <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="o">*</span><span class="n">I</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Easy, isn’t it? You can also use <tt class="docutils literal"><span class="pre">InstIterator</span></tt>s to fill a work list with
+its initial contents. For example, if you wanted to initialize a work list to
+contain all instructions in a <tt class="docutils literal"><span class="pre">Function</span></tt> F, all you would need to do is
+something like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">set</span><span class="o"><</span><span class="n">Instruction</span><span class="o">*></span> <span class="n">worklist</span><span class="p">;</span>
+<span class="c1">// or better yet, SmallPtrSet<Instruction*, 64> worklist;</span>
+
+<span class="k">for</span> <span class="p">(</span><span class="n">inst_iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">inst_begin</span><span class="p">(</span><span class="n">F</span><span class="p">),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">inst_end</span><span class="p">(</span><span class="n">F</span><span class="p">);</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span>
+ <span class="n">worklist</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="o">&*</span><span class="n">I</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The STL set <tt class="docutils literal"><span class="pre">worklist</span></tt> would now contain all instructions in the <tt class="docutils literal"><span class="pre">Function</span></tt>
+pointed to by F.</p>
+</div>
+<div class="section" id="turning-an-iterator-into-a-class-pointer-and-vice-versa">
+<span id="iterate-convert"></span><h4><a class="toc-backref" href="#id75">Turning an iterator into a class pointer (and vice-versa)</a><a class="headerlink" href="#turning-an-iterator-into-a-class-pointer-and-vice-versa" title="Permalink to this headline">¶</a></h4>
+<p>Sometimes, it’ll be useful to grab a reference (or pointer) to a class instance
+when all you’ve got at hand is an iterator. Well, extracting a reference or a
+pointer from an iterator is very straight-forward. Assuming that <tt class="docutils literal"><span class="pre">i</span></tt> is a
+<tt class="docutils literal"><span class="pre">BasicBlock::iterator</span></tt> and <tt class="docutils literal"><span class="pre">j</span></tt> is a <tt class="docutils literal"><span class="pre">BasicBlock::const_iterator</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Instruction</span><span class="o">&</span> <span class="n">inst</span> <span class="o">=</span> <span class="o">*</span><span class="n">i</span><span class="p">;</span> <span class="c1">// Grab reference to instruction reference</span>
+<span class="n">Instruction</span><span class="o">*</span> <span class="n">pinst</span> <span class="o">=</span> <span class="o">&*</span><span class="n">i</span><span class="p">;</span> <span class="c1">// Grab pointer to instruction reference</span>
+<span class="k">const</span> <span class="n">Instruction</span><span class="o">&</span> <span class="n">inst</span> <span class="o">=</span> <span class="o">*</span><span class="n">j</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>However, the iterators you’ll be working with in the LLVM framework are special:
+they will automatically convert to a ptr-to-instance type whenever they need to.
+Instead of 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,</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Instruction</span> <span class="o">*</span><span class="n">pinst</span> <span class="o">=</span> <span class="o">&*</span><span class="n">i</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>is semantically equivalent to</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Instruction</span> <span class="o">*</span><span class="n">pinst</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>It’s also possible to turn a class pointer into the corresponding iterator, and
+this is a constant time operation (very efficient). The following code snippet
+illustrates use of the conversion constructors provided by LLVM iterators. By
+using these, you can explicitly grab the iterator of something without actually
+obtaining it via iteration over some structure:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">printNextInstruction</span><span class="p">(</span><span class="n">Instruction</span><span class="o">*</span> <span class="n">inst</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">BasicBlock</span><span class="o">::</span><span class="n">iterator</span> <span class="n">it</span><span class="p">(</span><span class="n">inst</span><span class="p">);</span>
+ <span class="o">++</span><span class="n">it</span><span class="p">;</span> <span class="c1">// After this line, it refers to the instruction after *inst</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">it</span> <span class="o">!=</span> <span class="n">inst</span><span class="o">-></span><span class="n">getParent</span><span class="p">()</span><span class="o">-></span><span class="n">end</span><span class="p">())</span> <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="o">*</span><span class="n">it</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Unfortunately, these implicit conversions come at a cost; they prevent these
+iterators from conforming to standard iterator conventions, and thus from being
+usable with standard algorithms and containers. For example, they prevent the
+following code, where <tt class="docutils literal"><span class="pre">B</span></tt> is a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>, from compiling:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">llvm</span><span class="o">::</span><span class="n">SmallVector</span><span class="o"><</span><span class="n">llvm</span><span class="o">::</span><span class="n">Instruction</span> <span class="o">*</span><span class="p">,</span> <span class="mi">16</span><span class="o">></span><span class="p">(</span><span class="n">B</span><span class="o">-></span><span class="n">begin</span><span class="p">(),</span> <span class="n">B</span><span class="o">-></span><span class="n">end</span><span class="p">());</span>
+</pre></div>
+</div>
+<p>Because of this, these implicit conversions may be removed some day, and
+<tt class="docutils literal"><span class="pre">operator*</span></tt> changed to return a pointer instead of a reference.</p>
+</div>
+<div class="section" id="finding-call-sites-a-slightly-more-complex-example">
+<span id="iterate-complex"></span><h4><a class="toc-backref" href="#id76">Finding call sites: a slightly more complex example</a><a class="headerlink" href="#finding-call-sites-a-slightly-more-complex-example" title="Permalink to this headline">¶</a></h4>
+<p>Say that you’re writing a FunctionPass and would like to count all the locations
+in the entire module (that is, across every <tt class="docutils literal"><span class="pre">Function</span></tt>) where a certain
+function (i.e., some <tt class="docutils literal"><span class="pre">Function</span> <span class="pre">*</span></tt>) is already in scope. As you’ll learn
+later, you may want to use an <tt class="docutils literal"><span class="pre">InstVisitor</span></tt> to accomplish this in a much more
+straight-forward manner, but this example will allow us to explore how you’d do
+it if you didn’t have <tt class="docutils literal"><span class="pre">InstVisitor</span></tt> around. In pseudo-code, this is what we
+want to do:</p>
+<div class="highlight-none"><div class="highlight"><pre>initialize callCounter to zero
+for each Function f in the Module
+ for each BasicBlock b in f
+ for each Instruction i in b
+ if (i is a CallInst and calls the given function)
+ increment callCounter
+</pre></div>
+</div>
+<p>And the actual code is (remember, because we’re writing a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>, our
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt>-derived class simply has to override the <tt class="docutils literal"><span class="pre">runOnFunction</span></tt>
+method):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Function</span><span class="o">*</span> <span class="n">targetFunc</span> <span class="o">=</span> <span class="p">...;</span>
+
+<span class="k">class</span> <span class="nc">OurFunctionPass</span> <span class="o">:</span> <span class="k">public</span> <span class="n">FunctionPass</span> <span class="p">{</span>
+ <span class="nl">public:</span>
+ <span class="n">OurFunctionPass</span><span class="p">()</span><span class="o">:</span> <span class="n">callCounter</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="p">{</span> <span class="p">}</span>
+
+ <span class="k">virtual</span> <span class="n">runOnFunction</span><span class="p">(</span><span class="n">Function</span><span class="o">&</span> <span class="n">F</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">Function</span><span class="o">::</span><span class="n">iterator</span> <span class="n">b</span> <span class="o">=</span> <span class="n">F</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">be</span> <span class="o">=</span> <span class="n">F</span><span class="p">.</span><span class="n">end</span><span class="p">();</span> <span class="n">b</span> <span class="o">!=</span> <span class="n">be</span><span class="p">;</span> <span class="o">++</span><span class="n">b</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">BasicBlock</span><span class="o">::</span><span class="n">iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">b</span><span class="o">-></span><span class="n">begin</span><span class="p">(),</span> <span class="n">ie</span> <span class="o">=</span> <span class="n">b</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">ie</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">CallInst</span><span class="o">*</span> <span class="n">callInst</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">CallInst</span><span class="o">></span><span class="p">(</span><span class="o">&*</span><span class="n">i</span><span class="p">))</span> <span class="p">{</span>
+ <span class="c1">// We know we've encountered a call instruction, so we</span>
+ <span class="c1">// need to determine if it's a call to the</span>
+ <span class="c1">// function pointed to by m_func or not.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">callInst</span><span class="o">-></span><span class="n">getCalledFunction</span><span class="p">()</span> <span class="o">==</span> <span class="n">targetFunc</span><span class="p">)</span>
+ <span class="o">++</span><span class="n">callCounter</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+
+ <span class="nl">private:</span>
+ <span class="kt">unsigned</span> <span class="n">callCounter</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="treating-calls-and-invokes-the-same-way">
+<span id="calls-and-invokes"></span><h4><a class="toc-backref" href="#id77">Treating calls and invokes the same way</a><a class="headerlink" href="#treating-calls-and-invokes-the-same-way" title="Permalink to this headline">¶</a></h4>
+<p>You may have noticed that the previous example was a bit oversimplified in that
+it did not deal with call sites generated by ‘invoke’ instructions. In this,
+and in other situations, you may find that you want to treat <tt class="docutils literal"><span class="pre">CallInst</span></tt>s and
+<tt class="docutils literal"><span class="pre">InvokeInst</span></tt>s the same way, even though their most-specific common base
+class is <tt class="docutils literal"><span class="pre">Instruction</span></tt>, which includes lots of less closely-related things.
+For these cases, LLVM provides a handy wrapper class called <tt class="docutils literal"><span class="pre">CallSite</span></tt>
+(<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1CallSite.html">doxygen</a>) It is
+essentially a wrapper around an <tt class="docutils literal"><span class="pre">Instruction</span></tt> pointer, with some methods that
+provide functionality common to <tt class="docutils literal"><span class="pre">CallInst</span></tt>s and <tt class="docutils literal"><span class="pre">InvokeInst</span></tt>s.</p>
+<p>This class has “value semantics”: it should be passed by value, not by reference
+and it should not be dynamically allocated or deallocated using <tt class="docutils literal"><span class="pre">operator</span> <span class="pre">new</span></tt>
+or <tt class="docutils literal"><span class="pre">operator</span> <span class="pre">delete</span></tt>. It is efficiently copyable, assignable and
+constructable, with costs equivalents to that of a bare pointer. If you look at
+its definition, it has only a single pointer member.</p>
+</div>
+<div class="section" id="iterating-over-def-use-use-def-chains">
+<span id="iterate-chains"></span><h4><a class="toc-backref" href="#id78">Iterating over def-use & use-def chains</a><a class="headerlink" href="#iterating-over-def-use-use-def-chains" title="Permalink to this headline">¶</a></h4>
+<p>Frequently, we might have an instance of the <tt class="docutils literal"><span class="pre">Value</span></tt> class (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Value.html">doxygen</a>) and we want to determine
+which <tt class="docutils literal"><span class="pre">User</span></tt> s use the <tt class="docutils literal"><span class="pre">Value</span></tt>. The list of all <tt class="docutils literal"><span class="pre">User</span></tt>s of a particular
+<tt class="docutils literal"><span class="pre">Value</span></tt> is called a <em>def-use</em> chain. For example, let’s say we have a
+<tt class="docutils literal"><span class="pre">Function*</span></tt> named <tt class="docutils literal"><span class="pre">F</span></tt> to a particular function <tt class="docutils literal"><span class="pre">foo</span></tt>. Finding all of the
+instructions that <em>use</em> <tt class="docutils literal"><span class="pre">foo</span></tt> is as simple as iterating over the <em>def-use</em>
+chain of <tt class="docutils literal"><span class="pre">F</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Function</span> <span class="o">*</span><span class="n">F</span> <span class="o">=</span> <span class="p">...;</span>
+
+<span class="k">for</span> <span class="p">(</span><span class="n">Value</span><span class="o">::</span><span class="n">use_iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">F</span><span class="o">-></span><span class="n">use_begin</span><span class="p">(),</span> <span class="n">e</span> <span class="o">=</span> <span class="n">F</span><span class="o">-></span><span class="n">use_end</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Instruction</span> <span class="o">*</span><span class="n">Inst</span> <span class="o">=</span> <span class="n">dyn_cast</span><span class="o"><</span><span class="n">Instruction</span><span class="o">></span><span class="p">(</span><span class="o">*</span><span class="n">i</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="s">"F is used in instruction:</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">errs</span><span class="p">()</span> <span class="o"><<</span> <span class="o">*</span><span class="n">Inst</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+ <span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that dereferencing a <tt class="docutils literal"><span class="pre">Value::use_iterator</span></tt> is not a very cheap operation.
+Instead of performing <tt class="docutils literal"><span class="pre">*i</span></tt> above several times, consider doing it only once in
+the loop body and reusing its result.</p>
+<p>Alternatively, it’s common to have an instance of the <tt class="docutils literal"><span class="pre">User</span></tt> Class (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1User.html">doxygen</a>) and need to know what
+<tt class="docutils literal"><span class="pre">Value</span></tt>s are used by it. The list of all <tt class="docutils literal"><span class="pre">Value</span></tt>s used by a <tt class="docutils literal"><span class="pre">User</span></tt> is
+known as a <em>use-def</em> chain. Instances of class <tt class="docutils literal"><span class="pre">Instruction</span></tt> are common
+<tt class="docutils literal"><span class="pre">User</span></tt> s, so we might want to iterate over all of the values that a particular
+instruction uses (that is, the operands of the particular <tt class="docutils literal"><span class="pre">Instruction</span></tt>):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Instruction</span> <span class="o">*</span><span class="n">pi</span> <span class="o">=</span> <span class="p">...;</span>
+
+<span class="k">for</span> <span class="p">(</span><span class="n">User</span><span class="o">::</span><span class="n">op_iterator</span> <span class="n">i</span> <span class="o">=</span> <span class="n">pi</span><span class="o">-></span><span class="n">op_begin</span><span class="p">(),</span> <span class="n">e</span> <span class="o">=</span> <span class="n">pi</span><span class="o">-></span><span class="n">op_end</span><span class="p">();</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Value</span> <span class="o">*</span><span class="n">v</span> <span class="o">=</span> <span class="o">*</span><span class="n">i</span><span class="p">;</span>
+ <span class="c1">// ...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Declaring objects as <tt class="docutils literal"><span class="pre">const</span></tt> is an important tool of enforcing mutation free
+algorithms (such as analyses, etc.). For this purpose above iterators come in
+constant flavors as <tt class="docutils literal"><span class="pre">Value::const_use_iterator</span></tt> and
+<tt class="docutils literal"><span class="pre">Value::const_op_iterator</span></tt>. They automatically arise when calling
+<tt class="docutils literal"><span class="pre">use/op_begin()</span></tt> on <tt class="docutils literal"><span class="pre">const</span> <span class="pre">Value*</span></tt>s or <tt class="docutils literal"><span class="pre">const</span> <span class="pre">User*</span></tt>s respectively.
+Upon dereferencing, they return <tt class="docutils literal"><span class="pre">const</span> <span class="pre">Use*</span></tt>s. Otherwise the above patterns
+remain unchanged.</p>
+</div>
+<div class="section" id="iterating-over-predecessors-successors-of-blocks">
+<span id="iterate-preds"></span><h4><a class="toc-backref" href="#id79">Iterating over predecessors & successors of blocks</a><a class="headerlink" href="#iterating-over-predecessors-successors-of-blocks" title="Permalink to this headline">¶</a></h4>
+<p>Iterating over the predecessors and successors of a block is quite easy with the
+routines defined in <tt class="docutils literal"><span class="pre">"llvm/Support/CFG.h"</span></tt>. Just use code like this to
+iterate over all predecessors of BB:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Support/CFG.h"</span>
+<span class="n">BasicBlock</span> <span class="o">*</span><span class="n">BB</span> <span class="o">=</span> <span class="p">...;</span>
+
+<span class="k">for</span> <span class="p">(</span><span class="n">pred_iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">pred_begin</span><span class="p">(</span><span class="n">BB</span><span class="p">),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">pred_end</span><span class="p">(</span><span class="n">BB</span><span class="p">);</span> <span class="n">PI</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">PI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">BasicBlock</span> <span class="o">*</span><span class="n">Pred</span> <span class="o">=</span> <span class="o">*</span><span class="n">PI</span><span class="p">;</span>
+ <span class="c1">// ...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Similarly, to iterate over successors use <tt class="docutils literal"><span class="pre">succ_iterator/succ_begin/succ_end</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="making-simple-changes">
+<span id="simplechanges"></span><h3><a class="toc-backref" href="#id80">Making simple changes</a><a class="headerlink" href="#making-simple-changes" title="Permalink to this headline">¶</a></h3>
+<p>There are some primitive transformation operations present in the LLVM
+infrastructure that are worth knowing about. When performing transformations,
+it’s fairly common to manipulate the contents of basic blocks. This section
+describes some of the common methods for doing so and gives example code.</p>
+<div class="section" id="creating-and-inserting-new-instructions">
+<span id="schanges-creating"></span><h4><a class="toc-backref" href="#id81">Creating and inserting new <tt class="docutils literal"><span class="pre">Instruction</span></tt>s</a><a class="headerlink" href="#creating-and-inserting-new-instructions" title="Permalink to this headline">¶</a></h4>
+<p><em>Instantiating Instructions</em></p>
+<p>Creation of <tt class="docutils literal"><span class="pre">Instruction</span></tt>s is straight-forward: simply call the constructor
+for the kind of instruction to instantiate and provide the necessary parameters.
+For example, an <tt class="docutils literal"><span class="pre">AllocaInst</span></tt> only <em>requires</em> a (const-ptr-to) <tt class="docutils literal"><span class="pre">Type</span></tt>. Thus:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">AllocaInst</span><span class="o">*</span> <span class="n">ai</span> <span class="o">=</span> <span class="k">new</span> <span class="n">AllocaInst</span><span class="p">(</span><span class="n">Type</span><span class="o">::</span><span class="n">Int32Ty</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>will create an <tt class="docutils literal"><span class="pre">AllocaInst</span></tt> instance that represents the allocation of one
+integer in the current stack frame, at run time. Each <tt class="docutils literal"><span class="pre">Instruction</span></tt> subclass
+is likely to have varying default parameters which change the semantics of the
+instruction, so refer to the <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Instruction.html">doxygen documentation for the subclass of
+Instruction</a> that
+you’re interested in instantiating.</p>
+<p><em>Naming values</em></p>
+<p>It is very useful to name the values of instructions when you’re able to, as
+this facilitates the debugging of your transformations. If you end up looking
+at generated LLVM machine code, you definitely want to have logical names
+associated with the results of instructions! By supplying a value for the
+<tt class="docutils literal"><span class="pre">Name</span></tt> (default) parameter of the <tt class="docutils literal"><span class="pre">Instruction</span></tt> constructor, you associate a
+logical name with the result of the instruction’s execution at run time. For
+example, say that I’m writing a transformation that dynamically allocates space
+for an integer on the stack, and that integer is going to be used as some kind
+of index by some other code. To accomplish this, I place an <tt class="docutils literal"><span class="pre">AllocaInst</span></tt> at
+the first point in the first <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> of some <tt class="docutils literal"><span class="pre">Function</span></tt>, and I’m
+intending to use it within the same <tt class="docutils literal"><span class="pre">Function</span></tt>. I might do:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">AllocaInst</span><span class="o">*</span> <span class="n">pa</span> <span class="o">=</span> <span class="k">new</span> <span class="n">AllocaInst</span><span class="p">(</span><span class="n">Type</span><span class="o">::</span><span class="n">Int32Ty</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="s">"indexLoc"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>where <tt class="docutils literal"><span class="pre">indexLoc</span></tt> is now the logical name of the instruction’s execution value,
+which is a pointer to an integer on the run time stack.</p>
+<p><em>Inserting instructions</em></p>
+<p>There are essentially two ways to insert an <tt class="docutils literal"><span class="pre">Instruction</span></tt> into an existing
+sequence of instructions that form a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>:</p>
+<ul>
+<li><p class="first">Insertion into an explicit instruction list</p>
+<p>Given a <tt class="docutils literal"><span class="pre">BasicBlock*</span> <span class="pre">pb</span></tt>, an <tt class="docutils literal"><span class="pre">Instruction*</span> <span class="pre">pi</span></tt> within that <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>,
+and a newly-created instruction we wish to insert before <tt class="docutils literal"><span class="pre">*pi</span></tt>, we do the
+following:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">pb</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">Instruction</span> <span class="o">*</span><span class="n">pi</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">Instruction</span> <span class="o">*</span><span class="n">newInst</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Instruction</span><span class="p">(...);</span>
+
+<span class="n">pb</span><span class="o">-></span><span class="n">getInstList</span><span class="p">().</span><span class="n">insert</span><span class="p">(</span><span class="n">pi</span><span class="p">,</span> <span class="n">newInst</span><span class="p">);</span> <span class="c1">// Inserts newInst before pi in pb</span>
+</pre></div>
+</div>
+<p>Appending to the end of a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> is so common that the <tt class="docutils literal"><span class="pre">Instruction</span></tt>
+class and <tt class="docutils literal"><span class="pre">Instruction</span></tt>-derived classes provide constructors which take a
+pointer to a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> to be appended to. For example code that looked
+like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">pb</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">Instruction</span> <span class="o">*</span><span class="n">newInst</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Instruction</span><span class="p">(...);</span>
+
+<span class="n">pb</span><span class="o">-></span><span class="n">getInstList</span><span class="p">().</span><span class="n">push_back</span><span class="p">(</span><span class="n">newInst</span><span class="p">);</span> <span class="c1">// Appends newInst to pb</span>
+</pre></div>
+</div>
+<p>becomes:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">pb</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">Instruction</span> <span class="o">*</span><span class="n">newInst</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Instruction</span><span class="p">(...,</span> <span class="n">pb</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>which is much cleaner, especially if you are creating long instruction
+streams.</p>
+</li>
+<li><p class="first">Insertion into an implicit instruction list</p>
+<p><tt class="docutils literal"><span class="pre">Instruction</span></tt> instances that are already in <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s are implicitly
+associated with an existing instruction list: the instruction list of the
+enclosing basic block. Thus, we could have accomplished the same thing as the
+above code without being given a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> by doing:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Instruction</span> <span class="o">*</span><span class="n">pi</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">Instruction</span> <span class="o">*</span><span class="n">newInst</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Instruction</span><span class="p">(...);</span>
+
+<span class="n">pi</span><span class="o">-></span><span class="n">getParent</span><span class="p">()</span><span class="o">-></span><span class="n">getInstList</span><span class="p">().</span><span class="n">insert</span><span class="p">(</span><span class="n">pi</span><span class="p">,</span> <span class="n">newInst</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In fact, this sequence of steps occurs so frequently that the <tt class="docutils literal"><span class="pre">Instruction</span></tt>
+class and <tt class="docutils literal"><span class="pre">Instruction</span></tt>-derived classes provide constructors which take (as
+a default parameter) a pointer to an <tt class="docutils literal"><span class="pre">Instruction</span></tt> which the newly-created
+<tt class="docutils literal"><span class="pre">Instruction</span></tt> should precede. That is, <tt class="docutils literal"><span class="pre">Instruction</span></tt> constructors are
+capable of inserting the newly-created instance into the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> of a
+provided instruction, immediately before that instruction. Using an
+<tt class="docutils literal"><span class="pre">Instruction</span></tt> constructor with a <tt class="docutils literal"><span class="pre">insertBefore</span></tt> (default) parameter, the
+above code becomes:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Instruction</span><span class="o">*</span> <span class="n">pi</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">Instruction</span><span class="o">*</span> <span class="n">newInst</span> <span class="o">=</span> <span class="k">new</span> <span class="n">Instruction</span><span class="p">(...,</span> <span class="n">pi</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>which is much cleaner, especially if you’re creating a lot of instructions and
+adding them to <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="deleting-instructions">
+<span id="schanges-deleting"></span><h4><a class="toc-backref" href="#id82">Deleting Instructions</a><a class="headerlink" href="#deleting-instructions" title="Permalink to this headline">¶</a></h4>
+<p>Deleting an instruction from an existing sequence of instructions that form a
+<a class="reference internal" href="#basicblock">BasicBlock</a> is very straight-forward: just call the instruction’s
+<tt class="docutils literal"><span class="pre">eraseFromParent()</span></tt> method. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Instruction</span> <span class="o">*</span><span class="n">I</span> <span class="o">=</span> <span class="p">..</span> <span class="p">;</span>
+<span class="n">I</span><span class="o">-></span><span class="n">eraseFromParent</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>This unlinks the instruction from its containing basic block and deletes it. If
+you’d just like to unlink the instruction from its containing basic block but
+not delete it, you can use the <tt class="docutils literal"><span class="pre">removeFromParent()</span></tt> method.</p>
+</div>
+<div class="section" id="replacing-an-instruction-with-another-value">
+<span id="schanges-replacing"></span><h4><a class="toc-backref" href="#id83">Replacing an Instruction with another Value</a><a class="headerlink" href="#replacing-an-instruction-with-another-value" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="replacing-individual-instructions">
+<h5><a class="toc-backref" href="#id84">Replacing individual instructions</a><a class="headerlink" href="#replacing-individual-instructions" title="Permalink to this headline">¶</a></h5>
+<p>Including “<a class="reference external" href="http://llvm.org/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>” permits use of two
+very useful replace functions: <tt class="docutils literal"><span class="pre">ReplaceInstWithValue</span></tt> and
+<tt class="docutils literal"><span class="pre">ReplaceInstWithInst</span></tt>.</p>
+</div>
+<div class="section" id="schanges-deleting-sub">
+<span id="id3"></span><h5><a class="toc-backref" href="#id85">Deleting Instructions</a><a class="headerlink" href="#schanges-deleting-sub" title="Permalink to this headline">¶</a></h5>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">ReplaceInstWithValue</span></tt></p>
+<p>This function replaces all uses of a given instruction with a value, and then
+removes the original instruction. The following example illustrates the
+replacement of the result of a particular <tt class="docutils literal"><span class="pre">AllocaInst</span></tt> that allocates memory
+for a single integer with a null pointer to an integer.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">AllocaInst</span><span class="o">*</span> <span class="n">instToReplace</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">BasicBlock</span><span class="o">::</span><span class="n">iterator</span> <span class="n">ii</span><span class="p">(</span><span class="n">instToReplace</span><span class="p">);</span>
+
+<span class="n">ReplaceInstWithValue</span><span class="p">(</span><span class="n">instToReplace</span><span class="o">-></span><span class="n">getParent</span><span class="p">()</span><span class="o">-></span><span class="n">getInstList</span><span class="p">(),</span> <span class="n">ii</span><span class="p">,</span>
+ <span class="n">Constant</span><span class="o">::</span><span class="n">getNullValue</span><span class="p">(</span><span class="n">PointerType</span><span class="o">::</span><span class="n">getUnqual</span><span class="p">(</span><span class="n">Type</span><span class="o">::</span><span class="n">Int32Ty</span><span class="p">)));</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">ReplaceInstWithInst</span></tt></p>
+<p>This function replaces a particular instruction with another instruction,
+inserting the new instruction into the basic block at the location where the
+old instruction was, and replacing any uses of the old instruction with the
+new instruction. The following example illustrates the replacement of one
+<tt class="docutils literal"><span class="pre">AllocaInst</span></tt> with another.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">AllocaInst</span><span class="o">*</span> <span class="n">instToReplace</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">BasicBlock</span><span class="o">::</span><span class="n">iterator</span> <span class="n">ii</span><span class="p">(</span><span class="n">instToReplace</span><span class="p">);</span>
+
+<span class="n">ReplaceInstWithInst</span><span class="p">(</span><span class="n">instToReplace</span><span class="o">-></span><span class="n">getParent</span><span class="p">()</span><span class="o">-></span><span class="n">getInstList</span><span class="p">(),</span> <span class="n">ii</span><span class="p">,</span>
+ <span class="k">new</span> <span class="n">AllocaInst</span><span class="p">(</span><span class="n">Type</span><span class="o">::</span><span class="n">Int32Ty</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="s">"ptrToReplacedInt"</span><span class="p">));</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="replacing-multiple-uses-of-users-and-values">
+<h5><a class="toc-backref" href="#id86">Replacing multiple uses of Users and Values</a><a class="headerlink" href="#replacing-multiple-uses-of-users-and-values" title="Permalink to this headline">¶</a></h5>
+<p>You can use <tt class="docutils literal"><span class="pre">Value::replaceAllUsesWith</span></tt> and <tt class="docutils literal"><span class="pre">User::replaceUsesOfWith</span></tt> to
+change more than one use at a time. See the doxygen documentation for the
+<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Value.html">Value Class</a> and <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1User.html">User Class</a>, respectively, for more
+information.</p>
+</div>
+</div>
+<div class="section" id="deleting-globalvariables">
+<span id="schanges-deletinggv"></span><h4><a class="toc-backref" href="#id87">Deleting GlobalVariables</a><a class="headerlink" href="#deleting-globalvariables" title="Permalink to this headline">¶</a></h4>
+<p>Deleting a global variable from a module is just as easy as deleting an
+Instruction. First, you must have a pointer to the global variable that you
+wish to delete. You use this pointer to erase it from its parent, the module.
+For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">GlobalVariable</span> <span class="o">*</span><span class="n">GV</span> <span class="o">=</span> <span class="p">..</span> <span class="p">;</span>
+
+<span class="n">GV</span><span class="o">-></span><span class="n">eraseFromParent</span><span class="p">();</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="how-to-create-types">
+<span id="create-types"></span><h3><a class="toc-backref" href="#id88">How to Create Types</a><a class="headerlink" href="#how-to-create-types" title="Permalink to this headline">¶</a></h3>
+<p>In generating IR, you may need some complex types. If you know these types
+statically, you can use <tt class="docutils literal"><span class="pre">TypeBuilder<...>::get()</span></tt>, defined in
+<tt class="docutils literal"><span class="pre">llvm/Support/TypeBuilder.h</span></tt>, to retrieve them. <tt class="docutils literal"><span class="pre">TypeBuilder</span></tt> has two forms
+depending on whether you’re building types for cross-compilation or native
+library use. <tt class="docutils literal"><span class="pre">TypeBuilder<T,</span> <span class="pre">true></span></tt> requires that <tt class="docutils literal"><span class="pre">T</span></tt> be independent of the
+host environment, meaning that it’s built out of types from the <tt class="docutils literal"><span class="pre">llvm::types</span></tt>
+(<a class="reference external" href="http://llvm.org/doxygen/namespacellvm_1_1types.html">doxygen</a>) namespace
+and pointers, functions, arrays, etc. built of those. <tt class="docutils literal"><span class="pre">TypeBuilder<T,</span> <span class="pre">false></span></tt>
+additionally allows native C types whose size may depend on the host compiler.
+For example,</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">FunctionType</span> <span class="o">*</span><span class="n">ft</span> <span class="o">=</span> <span class="n">TypeBuilder</span><span class="o"><</span><span class="n">types</span><span class="o">::</span><span class="n">i</span><span class="o"><</span><span class="mi">8</span><span class="o">></span><span class="p">(</span><span class="n">types</span><span class="o">::</span><span class="n">i</span><span class="o"><</span><span class="mi">32</span><span class="o">>*</span><span class="p">),</span> <span class="nb">true</span><span class="o">>::</span><span class="n">get</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>is easier to read and write than the equivalent</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="k">const</span> <span class="n">Type</span><span class="o">*></span> <span class="n">params</span><span class="p">;</span>
+<span class="n">params</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">PointerType</span><span class="o">::</span><span class="n">getUnqual</span><span class="p">(</span><span class="n">Type</span><span class="o">::</span><span class="n">Int32Ty</span><span class="p">));</span>
+<span class="n">FunctionType</span> <span class="o">*</span><span class="n">ft</span> <span class="o">=</span> <span class="n">FunctionType</span><span class="o">::</span><span class="n">get</span><span class="p">(</span><span class="n">Type</span><span class="o">::</span><span class="n">Int8Ty</span><span class="p">,</span> <span class="n">params</span><span class="p">,</span> <span class="nb">false</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>See the <a class="reference external" href="http://llvm.org/doxygen/TypeBuilder_8h-source.html#l00001">class comment</a> for more details.</p>
+</div>
+</div>
+<div class="section" id="threads-and-llvm">
+<span id="threading"></span><h2><a class="toc-backref" href="#id89">Threads and LLVM</a><a class="headerlink" href="#threads-and-llvm" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the interaction of the LLVM APIs with multithreading,
+both on the part of client applications, and in the JIT, in the hosted
+application.</p>
+<p>Note that LLVM’s support for multithreading is still relatively young. Up
+through version 2.5, the execution of threaded hosted applications was
+supported, but not threaded client access to the APIs. While this use case is
+now supported, clients <em>must</em> adhere to the guidelines specified below to ensure
+proper operation in multithreaded mode.</p>
+<p>Note that, on Unix-like platforms, LLVM requires the presence of GCC’s atomic
+intrinsics in order to support threaded operation. If you need a
+multhreading-capable LLVM on a platform without a suitably modern system
+compiler, consider compiling LLVM and LLVM-GCC in single-threaded mode, and
+using the resultant compiler to build a copy of LLVM with multithreading
+support.</p>
+<div class="section" id="entering-and-exiting-multithreaded-mode">
+<span id="startmultithreaded"></span><h3><a class="toc-backref" href="#id90">Entering and Exiting Multithreaded Mode</a><a class="headerlink" href="#entering-and-exiting-multithreaded-mode" title="Permalink to this headline">¶</a></h3>
+<p>In order to properly protect its internal data structures while avoiding
+excessive locking overhead in the single-threaded case, the LLVM must intialize
+certain data structures necessary to provide guards around its internals. To do
+so, the client program must invoke <tt class="docutils literal"><span class="pre">llvm_start_multithreaded()</span></tt> before making
+any concurrent LLVM API calls. To subsequently tear down these structures, use
+the <tt class="docutils literal"><span class="pre">llvm_stop_multithreaded()</span></tt> call. You can also use the
+<tt class="docutils literal"><span class="pre">llvm_is_multithreaded()</span></tt> call to check the status of multithreaded mode.</p>
+<p>Note that both of these calls must be made <em>in isolation</em>. That is to say that
+no other LLVM API calls may be executing at any time during the execution of
+<tt class="docutils literal"><span class="pre">llvm_start_multithreaded()</span></tt> or <tt class="docutils literal"><span class="pre">llvm_stop_multithreaded</span></tt>. It’s is the
+client’s responsibility to enforce this isolation.</p>
+<p>The return value of <tt class="docutils literal"><span class="pre">llvm_start_multithreaded()</span></tt> indicates the success or
+failure of the initialization. Failure typically indicates that your copy of
+LLVM was built without multithreading support, typically because GCC atomic
+intrinsics were not found in your system compiler. In this case, the LLVM API
+will not be safe for concurrent calls. However, it <em>will</em> be safe for hosting
+threaded applications in the JIT, though <a class="reference internal" href="#jitthreading"><em>care must be taken</em></a> to ensure that side exits and the like do not accidentally
+result in concurrent LLVM API calls.</p>
+</div>
+<div class="section" id="ending-execution-with-llvm-shutdown">
+<span id="shutdown"></span><h3><a class="toc-backref" href="#id91">Ending Execution with <tt class="docutils literal"><span class="pre">llvm_shutdown()</span></tt></a><a class="headerlink" href="#ending-execution-with-llvm-shutdown" title="Permalink to this headline">¶</a></h3>
+<p>When you are done using the LLVM APIs, you should call <tt class="docutils literal"><span class="pre">llvm_shutdown()</span></tt> to
+deallocate memory used for internal structures. This will also invoke
+<tt class="docutils literal"><span class="pre">llvm_stop_multithreaded()</span></tt> if LLVM is operating in multithreaded mode. As
+such, <tt class="docutils literal"><span class="pre">llvm_shutdown()</span></tt> requires the same isolation guarantees as
+<tt class="docutils literal"><span class="pre">llvm_stop_multithreaded()</span></tt>.</p>
+<p>Note that, if you use scope-based shutdown, you can use the
+<tt class="docutils literal"><span class="pre">llvm_shutdown_obj</span></tt> class, which calls <tt class="docutils literal"><span class="pre">llvm_shutdown()</span></tt> in its destructor.</p>
+</div>
+<div class="section" id="lazy-initialization-with-managedstatic">
+<span id="managedstatic"></span><h3><a class="toc-backref" href="#id92">Lazy Initialization with <tt class="docutils literal"><span class="pre">ManagedStatic</span></tt></a><a class="headerlink" href="#lazy-initialization-with-managedstatic" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">ManagedStatic</span></tt> is a utility class in LLVM used to implement static
+initialization of static resources, such as the global type tables. Before the
+invocation of <tt class="docutils literal"><span class="pre">llvm_shutdown()</span></tt>, it implements a simple lazy initialization
+scheme. Once <tt class="docutils literal"><span class="pre">llvm_start_multithreaded()</span></tt> returns, however, it uses
+double-checked locking to implement thread-safe lazy initialization.</p>
+<p>Note that, because no other threads are allowed to issue LLVM API calls before
+<tt class="docutils literal"><span class="pre">llvm_start_multithreaded()</span></tt> returns, it is possible to have
+<tt class="docutils literal"><span class="pre">ManagedStatic</span></tt>s of <tt class="docutils literal"><span class="pre">llvm::sys::Mutex</span></tt>s.</p>
+<p>The <tt class="docutils literal"><span class="pre">llvm_acquire_global_lock()</span></tt> and <tt class="docutils literal"><span class="pre">llvm_release_global_lock</span></tt> APIs provide
+access to the global lock used to implement the double-checked locking for lazy
+initialization. These should only be used internally to LLVM, and only if you
+know what you’re doing!</p>
+</div>
+<div class="section" id="achieving-isolation-with-llvmcontext">
+<span id="llvmcontext"></span><h3><a class="toc-backref" href="#id93">Achieving Isolation with <tt class="docutils literal"><span class="pre">LLVMContext</span></tt></a><a class="headerlink" href="#achieving-isolation-with-llvmcontext" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">LLVMContext</span></tt> is an opaque class in the LLVM API which clients can use to
+operate multiple, isolated instances of LLVM concurrently within the same
+address space. For instance, in a hypothetical compile-server, the compilation
+of an individual translation unit is conceptually independent from all the
+others, and it would be desirable to be able to compile incoming translation
+units concurrently on independent server threads. Fortunately, <tt class="docutils literal"><span class="pre">LLVMContext</span></tt>
+exists to enable just this kind of scenario!</p>
+<p>Conceptually, <tt class="docutils literal"><span class="pre">LLVMContext</span></tt> provides isolation. Every LLVM entity
+(<tt class="docutils literal"><span class="pre">Module</span></tt>s, <tt class="docutils literal"><span class="pre">Value</span></tt>s, <tt class="docutils literal"><span class="pre">Type</span></tt>s, <tt class="docutils literal"><span class="pre">Constant</span></tt>s, etc.) in LLVM’s
+in-memory IR belongs to an <tt class="docutils literal"><span class="pre">LLVMContext</span></tt>. Entities in different contexts
+<em>cannot</em> interact with each other: <tt class="docutils literal"><span class="pre">Module</span></tt>s in different contexts cannot be
+linked together, <tt class="docutils literal"><span class="pre">Function</span></tt>s cannot be added to <tt class="docutils literal"><span class="pre">Module</span></tt>s in different
+contexts, etc. What this means is that is is safe to compile on multiple
+threads simultaneously, as long as no two threads operate on entities within the
+same context.</p>
+<p>In practice, very few places in the API require the explicit specification of a
+<tt class="docutils literal"><span class="pre">LLVMContext</span></tt>, other than the <tt class="docutils literal"><span class="pre">Type</span></tt> creation/lookup APIs. Because every
+<tt class="docutils literal"><span class="pre">Type</span></tt> carries a reference to its owning context, most other entities can
+determine what context they belong to by looking at their own <tt class="docutils literal"><span class="pre">Type</span></tt>. If you
+are adding new entities to LLVM IR, please try to maintain this interface
+design.</p>
+<p>For clients that do <em>not</em> require the benefits of isolation, LLVM provides a
+convenience API <tt class="docutils literal"><span class="pre">getGlobalContext()</span></tt>. This returns a global, lazily
+initialized <tt class="docutils literal"><span class="pre">LLVMContext</span></tt> that may be used in situations where isolation is
+not a concern.</p>
+</div>
+<div class="section" id="threads-and-the-jit">
+<span id="jitthreading"></span><h3><a class="toc-backref" href="#id94">Threads and the JIT</a><a class="headerlink" href="#threads-and-the-jit" title="Permalink to this headline">¶</a></h3>
+<p>LLVM’s “eager” JIT compiler is safe to use in threaded programs. Multiple
+threads can call <tt class="docutils literal"><span class="pre">ExecutionEngine::getPointerToFunction()</span></tt> or
+<tt class="docutils literal"><span class="pre">ExecutionEngine::runFunction()</span></tt> concurrently, and multiple threads can run
+code output by the JIT concurrently. The user must still ensure that only one
+thread accesses IR in a given <tt class="docutils literal"><span class="pre">LLVMContext</span></tt> while another thread might be
+modifying it. One way to do that is to always hold the JIT lock while accessing
+IR outside the JIT (the JIT <em>modifies</em> the IR by adding <tt class="docutils literal"><span class="pre">CallbackVH</span></tt>s).
+Another way is to only call <tt class="docutils literal"><span class="pre">getPointerToFunction()</span></tt> from the
+<tt class="docutils literal"><span class="pre">LLVMContext</span></tt>‘s thread.</p>
+<p>When the JIT is configured to compile lazily (using
+<tt class="docutils literal"><span class="pre">ExecutionEngine::DisableLazyCompilation(false)</span></tt>), there is currently a <a class="reference external" href="http://llvm.org/bugs/show_bug.cgi?id=5184">race
+condition</a> in updating call sites
+after a function is lazily-jitted. It’s still possible to use the lazy JIT in a
+threaded program if you ensure that only one thread at a time can call any
+particular lazy stub and that the JIT lock guards any IR access, but we suggest
+using only the eager JIT in threaded programs.</p>
+</div>
+</div>
+<div class="section" id="advanced-topics">
+<span id="advanced"></span><h2><a class="toc-backref" href="#id95">Advanced Topics</a><a class="headerlink" href="#advanced-topics" title="Permalink to this headline">¶</a></h2>
+<p>This section describes some of the advanced or obscure API’s that most clients
+do not need to be aware of. These API’s tend manage the inner workings of the
+LLVM system, and only need to be accessed in unusual circumstances.</p>
+<div class="section" id="the-valuesymboltable-class">
+<span id="symboltable"></span><h3><a class="toc-backref" href="#id96">The <tt class="docutils literal"><span class="pre">ValueSymbolTable</span></tt> class</a><a class="headerlink" href="#the-valuesymboltable-class" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">ValueSymbolTable</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1ValueSymbolTable.html">doxygen</a>) class provides
+a symbol table that the <a class="reference internal" href="#c-function"><em>Function</em></a> and <a class="reference internal" href="#module">Module</a> classes use for
+naming value definitions. The symbol table can provide a name for any <a class="reference internal" href="#value">Value</a>.</p>
+<p>Note that the <tt class="docutils literal"><span class="pre">SymbolTable</span></tt> class should not be directly accessed by most
+clients. It should only be used when iteration over the symbol table names
+themselves are required, which is very special purpose. Note that not all LLVM
+<a class="reference internal" href="#value">Value</a>s have names, and those without names (i.e. they have an empty name) do
+not exist in the symbol table.</p>
+<p>Symbol tables support iteration over the values in the symbol table with
+<tt class="docutils literal"><span class="pre">begin/end/iterator</span></tt> and supports querying to see if a specific name is in the
+symbol table (with <tt class="docutils literal"><span class="pre">lookup</span></tt>). The <tt class="docutils literal"><span class="pre">ValueSymbolTable</span></tt> class exposes no
+public mutator methods, instead, simply call <tt class="docutils literal"><span class="pre">setName</span></tt> on a value, which will
+autoinsert it into the appropriate symbol table.</p>
+</div>
+<div class="section" id="the-user-and-owned-use-classes-memory-layout">
+<span id="userlayout"></span><h3><a class="toc-backref" href="#id97">The <tt class="docutils literal"><span class="pre">User</span></tt> and owned <tt class="docutils literal"><span class="pre">Use</span></tt> classes’ memory layout</a><a class="headerlink" href="#the-user-and-owned-use-classes-memory-layout" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">User</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1User.html">doxygen</a>)
+class provides a basis for expressing the ownership of <tt class="docutils literal"><span class="pre">User</span></tt> towards other
+<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Value.html">Value instance</a>s. The
+<tt class="docutils literal"><span class="pre">Use</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Use.html">doxygen</a>) helper
+class is employed to do the bookkeeping and to facilitate <em>O(1)</em> addition and
+removal.</p>
+<div class="section" id="interaction-and-relationship-between-user-and-use-objects">
+<span id="use2user"></span><h4><a class="toc-backref" href="#id98">Interaction and relationship between <tt class="docutils literal"><span class="pre">User</span></tt> and <tt class="docutils literal"><span class="pre">Use</span></tt> objects</a><a class="headerlink" href="#interaction-and-relationship-between-user-and-use-objects" title="Permalink to this headline">¶</a></h4>
+<p>A subclass of <tt class="docutils literal"><span class="pre">User</span></tt> can choose between incorporating its <tt class="docutils literal"><span class="pre">Use</span></tt> objects or
+refer to them out-of-line by means of a pointer. A mixed variant (some <tt class="docutils literal"><span class="pre">Use</span></tt>
+s inline others hung off) is impractical and breaks the invariant that the
+<tt class="docutils literal"><span class="pre">Use</span></tt> objects belonging to the same <tt class="docutils literal"><span class="pre">User</span></tt> form a contiguous array.</p>
+<p>We have 2 different layouts in the <tt class="docutils literal"><span class="pre">User</span></tt> (sub)classes:</p>
+<ul>
+<li><p class="first">Layout a)</p>
+<p>The <tt class="docutils literal"><span class="pre">Use</span></tt> object(s) are inside (resp. at fixed offset) of the <tt class="docutils literal"><span class="pre">User</span></tt>
+object and there are a fixed number of them.</p>
+</li>
+<li><p class="first">Layout b)</p>
+<p>The <tt class="docutils literal"><span class="pre">Use</span></tt> object(s) are referenced by a pointer to an array from the
+<tt class="docutils literal"><span class="pre">User</span></tt> object and there may be a variable number of them.</p>
+</li>
+</ul>
+<p>As of v2.4 each layout still possesses a direct pointer to the start of the
+array of <tt class="docutils literal"><span class="pre">Use</span></tt>s. Though not mandatory for layout a), we stick to this
+redundancy for the sake of simplicity. The <tt class="docutils literal"><span class="pre">User</span></tt> object also stores the
+number of <tt class="docutils literal"><span class="pre">Use</span></tt> objects it has. (Theoretically this information can also be
+calculated given the scheme presented below.)</p>
+<p>Special forms of allocation operators (<tt class="docutils literal"><span class="pre">operator</span> <span class="pre">new</span></tt>) enforce the following
+memory layouts:</p>
+<ul>
+<li><p class="first">Layout a) is modelled by prepending the <tt class="docutils literal"><span class="pre">User</span></tt> object by the <tt class="docutils literal"><span class="pre">Use[]</span></tt>
+array.</p>
+<div class="highlight-none"><div class="highlight"><pre>...---.---.---.---.-------...
+ | P | P | P | P | User
+'''---'---'---'---'-------'''
+</pre></div>
+</div>
+</li>
+<li><p class="first">Layout b) is modelled by pointing at the <tt class="docutils literal"><span class="pre">Use[]</span></tt> array.</p>
+<div class="highlight-none"><div class="highlight"><pre>.-------...
+| User
+'-------'''
+ |
+ v
+ .---.---.---.---...
+ | P | P | P | P |
+ '---'---'---'---'''
+</pre></div>
+</div>
+</li>
+</ul>
+<p><em>(In the above figures</em> ‘<tt class="docutils literal"><span class="pre">P</span></tt>‘ <em>stands for the</em> <tt class="docutils literal"><span class="pre">Use**</span></tt> <em>that is stored in
+each</em> <tt class="docutils literal"><span class="pre">Use</span></tt> <em>object in the member</em> <tt class="docutils literal"><span class="pre">Use::Prev</span></tt> <em>)</em></p>
+</div>
+<div class="section" id="the-waymarking-algorithm">
+<span id="waymarking"></span><h4><a class="toc-backref" href="#id99">The waymarking algorithm</a><a class="headerlink" href="#the-waymarking-algorithm" title="Permalink to this headline">¶</a></h4>
+<p>Since the <tt class="docutils literal"><span class="pre">Use</span></tt> objects are deprived of the direct (back)pointer to their
+<tt class="docutils literal"><span class="pre">User</span></tt> objects, there must be a fast and exact method to recover it. This is
+accomplished by the following scheme:</p>
+<p>A bit-encoding in the 2 LSBits (least significant bits) of the <tt class="docutils literal"><span class="pre">Use::Prev</span></tt>
+allows to find the start of the <tt class="docutils literal"><span class="pre">User</span></tt> object:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">00</span></tt> — binary digit 0</li>
+<li><tt class="docutils literal"><span class="pre">01</span></tt> — binary digit 1</li>
+<li><tt class="docutils literal"><span class="pre">10</span></tt> — stop and calculate (<tt class="docutils literal"><span class="pre">s</span></tt>)</li>
+<li><tt class="docutils literal"><span class="pre">11</span></tt> — full stop (<tt class="docutils literal"><span class="pre">S</span></tt>)</li>
+</ul>
+<p>Given a <tt class="docutils literal"><span class="pre">Use*</span></tt>, all we have to do is to walk till we get a stop and we either
+have a <tt class="docutils literal"><span class="pre">User</span></tt> immediately behind or we have to walk to the next stop picking
+up digits and calculating the offset:</p>
+<div class="highlight-none"><div class="highlight"><pre>.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
+| 1 | s | 1 | 0 | 1 | 0 | s | 1 | 1 | 0 | s | 1 | 1 | s | 1 | S | User (or User*)
+'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'---'----------------
+ |+15 |+10 |+6 |+3 |+1
+ | | | | | __>
+ | | | | __________>
+ | | | ______________________>
+ | | ______________________________________>
+ | __________________________________________________________>
+</pre></div>
+</div>
+<p>Only the significant number of bits need to be stored between the stops, so that
+the <em>worst case is 20 memory accesses</em> when there are 1000 <tt class="docutils literal"><span class="pre">Use</span></tt> objects
+associated with a <tt class="docutils literal"><span class="pre">User</span></tt>.</p>
+</div>
+<div class="section" id="reference-implementation">
+<span id="referenceimpl"></span><h4><a class="toc-backref" href="#id100">Reference implementation</a><a class="headerlink" href="#reference-implementation" title="Permalink to this headline">¶</a></h4>
+<p>The following literate Haskell fragment demonstrates the concept:</p>
+<div class="highlight-haskell"><div class="highlight"><pre><span class="o">></span> <span class="kr">import</span> <span class="nn">Test.QuickCheck</span>
+<span class="o">></span>
+<span class="o">></span> <span class="n">digits</span> <span class="ow">::</span> <span class="kt">Int</span> <span class="ow">-></span> <span class="p">[</span><span class="kt">Char</span><span class="p">]</span> <span class="ow">-></span> <span class="p">[</span><span class="kt">Char</span><span class="p">]</span>
+<span class="o">></span> <span class="n">digits</span> <span class="mi">0</span> <span class="n">acc</span> <span class="ow">=</span> <span class="sc">'0'</span> <span class="kt">:</span> <span class="n">acc</span>
+<span class="o">></span> <span class="n">digits</span> <span class="mi">1</span> <span class="n">acc</span> <span class="ow">=</span> <span class="sc">'1'</span> <span class="kt">:</span> <span class="n">acc</span>
+<span class="o">></span> <span class="n">digits</span> <span class="n">n</span> <span class="n">acc</span> <span class="ow">=</span> <span class="n">digits</span> <span class="p">(</span><span class="n">n</span> <span class="p">`</span><span class="n">div</span><span class="p">`</span> <span class="mi">2</span><span class="p">)</span> <span class="o">$</span> <span class="n">digits</span> <span class="p">(</span><span class="n">n</span> <span class="p">`</span><span class="n">mod</span><span class="p">`</span> <span class="mi">2</span><span class="p">)</span> <span class="n">acc</span>
+<span class="o">></span>
+<span class="o">></span> <span class="n">dist</span> <span class="ow">::</span> <span class="kt">Int</span> <span class="ow">-></span> <span class="p">[</span><span class="kt">Char</span><span class="p">]</span> <span class="ow">-></span> <span class="p">[</span><span class="kt">Char</span><span class="p">]</span>
+<span class="o">></span> <span class="n">dist</span> <span class="mi">0</span> <span class="kt">[]</span> <span class="ow">=</span> <span class="p">[</span><span class="sc">'S'</span><span class="p">]</span>
+<span class="o">></span> <span class="n">dist</span> <span class="mi">0</span> <span class="n">acc</span> <span class="ow">=</span> <span class="n">acc</span>
+<span class="o">></span> <span class="n">dist</span> <span class="mi">1</span> <span class="n">acc</span> <span class="ow">=</span> <span class="kr">let</span> <span class="n">r</span> <span class="ow">=</span> <span class="n">dist</span> <span class="mi">0</span> <span class="n">acc</span> <span class="kr">in</span> <span class="n">'s'</span> <span class="kt">:</span> <span class="n">digits</span> <span class="p">(</span><span class="n">length</span> <span class="n">r</span><span class="p">)</span> <span class="n">r</span>
+<span class="o">></span> <span class="n">dist</span> <span class="n">n</span> <span class="n">acc</span> <span class="ow">=</span> <span class="n">dist</span> <span class="p">(</span><span class="n">n</span> <span class="o">-</span> <span class="mi">1</span><span class="p">)</span> <span class="o">$</span> <span class="n">dist</span> <span class="mi">1</span> <span class="n">acc</span>
+<span class="o">></span>
+<span class="o">></span> <span class="n">takeLast</span> <span class="n">n</span> <span class="n">ss</span> <span class="ow">=</span> <span class="n">reverse</span> <span class="o">$</span> <span class="n">take</span> <span class="n">n</span> <span class="o">$</span> <span class="n">reverse</span> <span class="n">ss</span>
+<span class="o">></span>
+<span class="o">></span> <span class="n">test</span> <span class="ow">=</span> <span class="n">takeLast</span> <span class="mi">40</span> <span class="o">$</span> <span class="n">dist</span> <span class="mi">20</span> <span class="kt">[]</span>
+<span class="o">></span>
+</pre></div>
+</div>
+<p>Printing <test> gives: <tt class="docutils literal"><span class="pre">"1s100000s11010s10100s1111s1010s110s11s1S"</span></tt></p>
+<p>The reverse algorithm computes the length of the string just by examining a
+certain prefix:</p>
+<div class="highlight-haskell"><div class="highlight"><pre><span class="o">></span> <span class="n">pref</span> <span class="ow">::</span> <span class="p">[</span><span class="kt">Char</span><span class="p">]</span> <span class="ow">-></span> <span class="kt">Int</span>
+<span class="o">></span> <span class="n">pref</span> <span class="s">"S"</span> <span class="ow">=</span> <span class="mi">1</span>
+<span class="o">></span> <span class="n">pref</span> <span class="p">(</span><span class="n">'s'</span><span class="kt">:</span><span class="sc">'1'</span><span class="kt">:</span><span class="n">rest</span><span class="p">)</span> <span class="ow">=</span> <span class="n">decode</span> <span class="mi">2</span> <span class="mi">1</span> <span class="n">rest</span>
+<span class="o">></span> <span class="n">pref</span> <span class="p">(</span><span class="kr">_</span><span class="kt">:</span><span class="n">rest</span><span class="p">)</span> <span class="ow">=</span> <span class="mi">1</span> <span class="o">+</span> <span class="n">pref</span> <span class="n">rest</span>
+<span class="o">></span>
+<span class="o">></span> <span class="n">decode</span> <span class="n">walk</span> <span class="n">acc</span> <span class="p">(</span><span class="sc">'0'</span><span class="kt">:</span><span class="n">rest</span><span class="p">)</span> <span class="ow">=</span> <span class="n">decode</span> <span class="p">(</span><span class="n">walk</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="n">acc</span> <span class="o">*</span> <span class="mi">2</span><span class="p">)</span> <span class="n">rest</span>
+<span class="o">></span> <span class="n">decode</span> <span class="n">walk</span> <span class="n">acc</span> <span class="p">(</span><span class="sc">'1'</span><span class="kt">:</span><span class="n">rest</span><span class="p">)</span> <span class="ow">=</span> <span class="n">decode</span> <span class="p">(</span><span class="n">walk</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span> <span class="p">(</span><span class="n">acc</span> <span class="o">*</span> <span class="mi">2</span> <span class="o">+</span> <span class="mi">1</span><span class="p">)</span> <span class="n">rest</span>
+<span class="o">></span> <span class="n">decode</span> <span class="n">walk</span> <span class="n">acc</span> <span class="kr">_</span> <span class="ow">=</span> <span class="n">walk</span> <span class="o">+</span> <span class="n">acc</span>
+<span class="o">></span>
+</pre></div>
+</div>
+<p>Now, as expected, printing <pref test> gives <tt class="docutils literal"><span class="pre">40</span></tt>.</p>
+<p>We can <em>quickCheck</em> this with following property:</p>
+<div class="highlight-haskell"><div class="highlight"><pre><span class="o">></span> <span class="n">testcase</span> <span class="ow">=</span> <span class="n">dist</span> <span class="mi">2000</span> <span class="kt">[]</span>
+<span class="o">></span> <span class="n">testcaseLength</span> <span class="ow">=</span> <span class="n">length</span> <span class="n">testcase</span>
+<span class="o">></span>
+<span class="o">></span> <span class="n">identityProp</span> <span class="n">n</span> <span class="ow">=</span> <span class="n">n</span> <span class="o">></span> <span class="mi">0</span> <span class="o">&&</span> <span class="n">n</span> <span class="o"><=</span> <span class="n">testcaseLength</span> <span class="o">==></span> <span class="n">length</span> <span class="n">arr</span> <span class="o">==</span> <span class="n">pref</span> <span class="n">arr</span>
+<span class="o">></span> <span class="kr">where</span> <span class="n">arr</span> <span class="ow">=</span> <span class="n">takeLast</span> <span class="n">n</span> <span class="n">testcase</span>
+<span class="o">></span>
+</pre></div>
+</div>
+<p>As expected <quickCheck identityProp> gives:</p>
+<div class="highlight-python"><pre>*Main> quickCheck identityProp
+OK, passed 100 tests.</pre>
+</div>
+<p>Let’s be a bit more exhaustive:</p>
+<div class="highlight-haskell"><div class="highlight"><pre><span class="o">></span>
+<span class="o">></span> <span class="n">deepCheck</span> <span class="n">p</span> <span class="ow">=</span> <span class="n">check</span> <span class="p">(</span><span class="n">defaultConfig</span> <span class="p">{</span> <span class="n">configMaxTest</span> <span class="ow">=</span> <span class="mi">500</span> <span class="p">})</span> <span class="n">p</span>
+<span class="o">></span>
+</pre></div>
+</div>
+<p>And here is the result of <deepCheck identityProp>:</p>
+<div class="highlight-python"><pre>*Main> deepCheck identityProp
+OK, passed 500 tests.</pre>
+</div>
+</div>
+<div class="section" id="tagging-considerations">
+<span id="tagging"></span><h4><a class="toc-backref" href="#id101">Tagging considerations</a><a class="headerlink" href="#tagging-considerations" title="Permalink to this headline">¶</a></h4>
+<p>To maintain the invariant that the 2 LSBits of each <tt class="docutils literal"><span class="pre">Use**</span></tt> in <tt class="docutils literal"><span class="pre">Use</span></tt> never
+change after being set up, setters of <tt class="docutils literal"><span class="pre">Use::Prev</span></tt> must re-tag the new
+<tt class="docutils literal"><span class="pre">Use**</span></tt> on every modification. Accordingly getters must strip the tag bits.</p>
+<p>For layout b) instead of the <tt class="docutils literal"><span class="pre">User</span></tt> we find a pointer (<tt class="docutils literal"><span class="pre">User*</span></tt> with LSBit
+set). Following this pointer brings us to the <tt class="docutils literal"><span class="pre">User</span></tt>. A portable trick
+ensures that the first bytes of <tt class="docutils literal"><span class="pre">User</span></tt> (if interpreted as a pointer) never has
+the LSBit set. (Portability is relying on the fact that all known compilers
+place the <tt class="docutils literal"><span class="pre">vptr</span></tt> in the first word of the instances.)</p>
+</div>
+</div>
+</div>
+<div class="section" id="the-core-llvm-class-hierarchy-reference">
+<span id="coreclasses"></span><h2><a class="toc-backref" href="#id102">The Core LLVM Class Hierarchy Reference</a><a class="headerlink" href="#the-core-llvm-class-hierarchy-reference" title="Permalink to this headline">¶</a></h2>
+<p><tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/Type.h"</span></tt></p>
+<p>header source: <a class="reference external" href="http://llvm.org/doxygen/Type_8h-source.html">Type.h</a></p>
+<p>doxygen info: <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Type.html">Type Clases</a></p>
+<p>The Core LLVM classes are the primary means of representing the program being
+inspected or transformed. The core LLVM classes are defined in header files in
+the <tt class="docutils literal"><span class="pre">include/llvm/</span></tt> directory, and implemented in the <tt class="docutils literal"><span class="pre">lib/VMCore</span></tt>
+directory.</p>
+<div class="section" id="the-type-class-and-derived-types">
+<span id="type"></span><h3><a class="toc-backref" href="#id103">The Type class and Derived Types</a><a class="headerlink" href="#the-type-class-and-derived-types" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">Type</span></tt> is a superclass of all type classes. Every <tt class="docutils literal"><span class="pre">Value</span></tt> has a <tt class="docutils literal"><span class="pre">Type</span></tt>.
+<tt class="docutils literal"><span class="pre">Type</span></tt> cannot be instantiated directly but only through its subclasses.
+Certain primitive types (<tt class="docutils literal"><span class="pre">VoidType</span></tt>, <tt class="docutils literal"><span class="pre">LabelType</span></tt>, <tt class="docutils literal"><span class="pre">FloatType</span></tt> and
+<tt class="docutils literal"><span class="pre">DoubleType</span></tt>) have hidden subclasses. They are hidden because they offer no
+useful functionality beyond what the <tt class="docutils literal"><span class="pre">Type</span></tt> class offers except to distinguish
+themselves from other subclasses of <tt class="docutils literal"><span class="pre">Type</span></tt>.</p>
+<p>All other types are subclasses of <tt class="docutils literal"><span class="pre">DerivedType</span></tt>. Types can be named, but this
+is not a requirement. There exists exactly one instance of a given shape at any
+one time. This allows type equality to be performed with address equality of
+the Type Instance. That is, given two <tt class="docutils literal"><span class="pre">Type*</span></tt> values, the types are identical
+if the pointers are identical.</p>
+<div class="section" id="important-public-methods">
+<span id="m-type"></span><h4><a class="toc-backref" href="#id104">Important Public Methods</a><a class="headerlink" href="#important-public-methods" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">isIntegerTy()</span> <span class="pre">const</span></tt>: Returns true for any integer type.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">isFloatingPointTy()</span></tt>: Return true if this is one of the five
+floating point types.</li>
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">isSized()</span></tt>: Return true if the type has known size. Things
+that don’t have a size are abstract types, labels and void.</li>
+</ul>
+</div>
+<div class="section" id="important-derived-types">
+<span id="derivedtypes"></span><h4><a class="toc-backref" href="#id105">Important Derived Types</a><a class="headerlink" href="#important-derived-types" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">IntegerType</span></tt></dt>
+<dd><p class="first">Subclass of DerivedType that represents integer types of any bit width. Any
+bit width between <tt class="docutils literal"><span class="pre">IntegerType::MIN_INT_BITS</span></tt> (1) and
+<tt class="docutils literal"><span class="pre">IntegerType::MAX_INT_BITS</span></tt> (~8 million) can be represented.</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">static</span> <span class="pre">const</span> <span class="pre">IntegerType*</span> <span class="pre">get(unsigned</span> <span class="pre">NumBits)</span></tt>: get an integer
+type of a specific bit width.</li>
+<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">getBitWidth()</span> <span class="pre">const</span></tt>: Get the bit width of an integer type.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">SequentialType</span></tt></dt>
+<dd><p class="first">This is subclassed by ArrayType, PointerType and VectorType.</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">const</span> <span class="pre">Type</span> <span class="pre">*</span> <span class="pre">getElementType()</span> <span class="pre">const</span></tt>: Returns the type of each
+of the elements in the sequential type.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">ArrayType</span></tt></dt>
+<dd><p class="first">This is a subclass of SequentialType and defines the interface for array
+types.</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">getNumElements()</span> <span class="pre">const</span></tt>: Returns the number of elements
+in the array.</li>
+</ul>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">PointerType</span></tt></dt>
+<dd>Subclass of SequentialType for pointer types.</dd>
+<dt><tt class="docutils literal"><span class="pre">VectorType</span></tt></dt>
+<dd>Subclass of SequentialType for vector types. A vector type is similar to an
+ArrayType but is distinguished because it is a first class type whereas
+ArrayType is not. Vector types are used for vector operations and are usually
+small vectors of of an integer or floating point type.</dd>
+<dt><tt class="docutils literal"><span class="pre">StructType</span></tt></dt>
+<dd>Subclass of DerivedTypes for struct types.</dd>
+</dl>
+<dl class="docutils" id="functiontype">
+<dt><tt class="docutils literal"><span class="pre">FunctionType</span></tt></dt>
+<dd><p class="first">Subclass of DerivedTypes for function types.</p>
+<ul class="last simple">
+<li><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">isVarArg()</span> <span class="pre">const</span></tt>: Returns true if it’s a vararg function.</li>
+<li><tt class="docutils literal"><span class="pre">const</span> <span class="pre">Type</span> <span class="pre">*</span> <span class="pre">getReturnType()</span> <span class="pre">const</span></tt>: Returns the return type of the
+function.</li>
+<li><tt class="docutils literal"><span class="pre">const</span> <span class="pre">Type</span> <span class="pre">*</span> <span class="pre">getParamType</span> <span class="pre">(unsigned</span> <span class="pre">i)</span></tt>: Returns the type of the ith
+parameter.</li>
+<li><tt class="docutils literal"><span class="pre">const</span> <span class="pre">unsigned</span> <span class="pre">getNumParams()</span> <span class="pre">const</span></tt>: Returns the number of formal
+parameters.</li>
+</ul>
+</dd>
+</dl>
+</div>
+</div>
+<div class="section" id="the-module-class">
+<span id="module"></span><h3><a class="toc-backref" href="#id106">The <tt class="docutils literal"><span class="pre">Module</span></tt> class</a><a class="headerlink" href="#the-module-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/Module.h"</span></tt></p>
+<p>header source: <a class="reference external" href="http://llvm.org/doxygen/Module_8h-source.html">Module.h</a></p>
+<p>doxygen info: <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Module.html">Module Class</a></p>
+<p>The <tt class="docutils literal"><span class="pre">Module</span></tt> class represents the top level structure present in LLVM
+programs. An LLVM module is effectively either a translation unit of the
+original program or a combination of several translation units merged by the
+linker. The <tt class="docutils literal"><span class="pre">Module</span></tt> class keeps track of a list of <a class="reference internal" href="#c-function"><em>Function</em></a>s, a list of <a class="reference internal" href="#globalvariable">GlobalVariable</a>s, and a <a class="reference internal" href="#symboltable">SymbolTable</a>.
+Additionally, it contains a few helpful member functions that try to make common
+operations easy.</p>
+<div class="section" id="important-public-members-of-the-module-class">
+<span id="m-module"></span><h4><a class="toc-backref" href="#id107">Important Public Members of the <tt class="docutils literal"><span class="pre">Module</span></tt> class</a><a class="headerlink" href="#important-public-members-of-the-module-class" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Module::Module(std::string</span> <span class="pre">name</span> <span class="pre">=</span> <span class="pre">"")</span></tt></p>
+<p>Constructing a <a class="reference internal" href="#module">Module</a> is easy. You can optionally provide a name for it
+(probably based on the name of the translation unit).</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">Module::iterator</span></tt> - Typedef for function list iterator</div>
+<div class="line"><tt class="docutils literal"><span class="pre">Module::const_iterator</span></tt> - Typedef for const_iterator.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">begin()</span></tt>, <tt class="docutils literal"><span class="pre">end()</span></tt>, <tt class="docutils literal"><span class="pre">size()</span></tt>, <tt class="docutils literal"><span class="pre">empty()</span></tt></div>
+</div>
+<p>These are forwarding methods that make it easy to access the contents of a
+<tt class="docutils literal"><span class="pre">Module</span></tt> object’s <a class="reference internal" href="#c-function"><em>Function</em></a> list.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Module::FunctionListType</span> <span class="pre">&getFunctionList()</span></tt></p>
+<p>Returns the list of <a class="reference internal" href="#c-function"><em>Function</em></a>s. This is necessary to use
+when you need to update the list or perform a complex action that doesn’t have
+a forwarding method.</p>
+</li>
+</ul>
+<hr class="docutils" />
+<ul>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">Module::global_iterator</span></tt> - Typedef for global variable list iterator</div>
+<div class="line"><tt class="docutils literal"><span class="pre">Module::const_global_iterator</span></tt> - Typedef for const_iterator.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">global_begin()</span></tt>, <tt class="docutils literal"><span class="pre">global_end()</span></tt>, <tt class="docutils literal"><span class="pre">global_size()</span></tt>, <tt class="docutils literal"><span class="pre">global_empty()</span></tt></div>
+</div>
+<p>These are forwarding methods that make it easy to access the contents of a
+<tt class="docutils literal"><span class="pre">Module</span></tt> object’s <a class="reference internal" href="#globalvariable">GlobalVariable</a> list.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Module::GlobalListType</span> <span class="pre">&getGlobalList()</span></tt></p>
+<p>Returns the list of <a class="reference internal" href="#globalvariable">GlobalVariable</a>s. This is necessary to use when you
+need to update the list or perform a complex action that doesn’t have a
+forwarding method.</p>
+</li>
+</ul>
+<hr class="docutils" />
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">SymbolTable</span> <span class="pre">*getSymbolTable()</span></tt></p>
+<p>Return a reference to the <a class="reference internal" href="#symboltable">SymbolTable</a> for this <tt class="docutils literal"><span class="pre">Module</span></tt>.</p>
+</li>
+</ul>
+<hr class="docutils" />
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Function</span> <span class="pre">*getFunction(StringRef</span> <span class="pre">Name)</span> <span class="pre">const</span></tt></p>
+<p>Look up the specified function in the <tt class="docutils literal"><span class="pre">Module</span></tt> <a class="reference internal" href="#symboltable">SymbolTable</a>. If it does not
+exist, return <tt class="docutils literal"><span class="pre">null</span></tt>.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Function</span> <span class="pre">*getOrInsertFunction(const</span> <span class="pre">std::string</span> <span class="pre">&Name,</span> <span class="pre">const</span> <span class="pre">FunctionType</span>
+<span class="pre">*T)</span></tt></p>
+<p>Look up the specified function in the <tt class="docutils literal"><span class="pre">Module</span></tt> <a class="reference internal" href="#symboltable">SymbolTable</a>. If it does not
+exist, add an external declaration for the function and return it.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">getTypeName(const</span> <span class="pre">Type</span> <span class="pre">*Ty)</span></tt></p>
+<p>If there is at least one entry in the <a class="reference internal" href="#symboltable">SymbolTable</a> for the specified <a class="reference internal" href="#type">Type</a>,
+return it. Otherwise return the empty string.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">addTypeName(const</span> <span class="pre">std::string</span> <span class="pre">&Name,</span> <span class="pre">const</span> <span class="pre">Type</span> <span class="pre">*Ty)</span></tt></p>
+<p>Insert an entry in the <a class="reference internal" href="#symboltable">SymbolTable</a> mapping <tt class="docutils literal"><span class="pre">Name</span></tt> to <tt class="docutils literal"><span class="pre">Ty</span></tt>. If there is
+already an entry for this name, true is returned and the <a class="reference internal" href="#symboltable">SymbolTable</a> is not
+modified.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-value-class">
+<span id="value"></span><h3><a class="toc-backref" href="#id108">The <tt class="docutils literal"><span class="pre">Value</span></tt> class</a><a class="headerlink" href="#the-value-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/Value.h"</span></tt></p>
+<p>header source: <a class="reference external" href="http://llvm.org/doxygen/Value_8h-source.html">Value.h</a></p>
+<p>doxygen info: <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Value.html">Value Class</a></p>
+<p>The <tt class="docutils literal"><span class="pre">Value</span></tt> class is the most important class in the LLVM Source base. It
+represents a typed value that may be used (among other things) as an operand to
+an instruction. There are many different types of <tt class="docutils literal"><span class="pre">Value</span></tt>s, such as
+<a class="reference internal" href="#constant">Constant</a>s, <a class="reference internal" href="#argument">Argument</a>s. Even <a class="reference internal" href="#instruction">Instruction</a>s and <a class="reference internal" href="#c-function"><em>Function</em></a>s are <tt class="docutils literal"><span class="pre">Value</span></tt>s.</p>
+<p>A particular <tt class="docutils literal"><span class="pre">Value</span></tt> may be used many times in the LLVM representation for a
+program. For example, an incoming argument to a function (represented with an
+instance of the <a class="reference internal" href="#argument">Argument</a> class) is “used” by every instruction in the function
+that references the argument. To keep track of this relationship, the <tt class="docutils literal"><span class="pre">Value</span></tt>
+class keeps a list of all of the <tt class="docutils literal"><span class="pre">User</span></tt>s that is using it (the <a class="reference internal" href="#user">User</a> class
+is a base class for all nodes in the LLVM graph that can refer to <tt class="docutils literal"><span class="pre">Value</span></tt>s).
+This use list is how LLVM represents def-use information in the program, and is
+accessible through the <tt class="docutils literal"><span class="pre">use_*</span></tt> methods, shown below.</p>
+<p>Because LLVM is a typed representation, every LLVM <tt class="docutils literal"><span class="pre">Value</span></tt> is typed, and this
+<a class="reference internal" href="#type">Type</a> is available through the <tt class="docutils literal"><span class="pre">getType()</span></tt> method. In addition, all LLVM
+values can be named. The “name” of the <tt class="docutils literal"><span class="pre">Value</span></tt> is a symbolic string printed
+in the LLVM code:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%foo</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="m">2</span>
+</pre></div>
+</div>
+<p id="namewarning">The name of this instruction is “foo”. <strong>NOTE</strong> that the name of any value may
+be missing (an empty string), so names should <strong>ONLY</strong> be used for debugging
+(making the source code easier to read, debugging printouts), they should not be
+used to keep track of values or map between them. For this purpose, use a
+<tt class="docutils literal"><span class="pre">std::map</span></tt> of pointers to the <tt class="docutils literal"><span class="pre">Value</span></tt> itself instead.</p>
+<p>One important aspect of LLVM is that there is no distinction between an SSA
+variable and the operation that produces it. Because of this, any reference to
+the value produced by an instruction (or the value available as an incoming
+argument, for example) is represented as a direct pointer to the instance of the
+class that represents this value. Although this may take some getting used to,
+it simplifies the representation and makes it easier to manipulate.</p>
+<div class="section" id="important-public-members-of-the-value-class">
+<span id="m-value"></span><h4><a class="toc-backref" href="#id109">Important Public Members of the <tt class="docutils literal"><span class="pre">Value</span></tt> class</a><a class="headerlink" href="#important-public-members-of-the-value-class" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">Value::use_iterator</span></tt> - Typedef for iterator over the use-list</div>
+<div class="line"><tt class="docutils literal"><span class="pre">Value::const_use_iterator</span></tt> - Typedef for const_iterator over the
+use-list</div>
+<div class="line"><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">use_size()</span></tt> - Returns the number of users of the value.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">use_empty()</span></tt> - Returns true if there are no users.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">use_iterator</span> <span class="pre">use_begin()</span></tt> - Get an iterator to the start of the
+use-list.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">use_iterator</span> <span class="pre">use_end()</span></tt> - Get an iterator to the end of the use-list.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">User</span> <span class="pre">*use_back()</span></tt> - Returns the last element in the list.</div>
+</div>
+<p>These methods are the interface to access the def-use information in LLVM.
+As with all other iterators in LLVM, the naming conventions follow the
+conventions defined by the <a class="reference internal" href="#stl">STL</a>.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Type</span> <span class="pre">*getType()</span> <span class="pre">const</span></tt>
+This method returns the Type of the Value.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">hasName()</span> <span class="pre">const</span></tt></div>
+<div class="line"><tt class="docutils literal"><span class="pre">std::string</span> <span class="pre">getName()</span> <span class="pre">const</span></tt></div>
+<div class="line"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">setName(const</span> <span class="pre">std::string</span> <span class="pre">&Name)</span></tt></div>
+</div>
+<p>This family of methods is used to access and assign a name to a <tt class="docutils literal"><span class="pre">Value</span></tt>, be
+aware of the <a class="reference internal" href="#namewarning"><em>precaution above</em></a>.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">replaceAllUsesWith(Value</span> <span class="pre">*V)</span></tt></p>
+<p>This method traverses the use list of a <tt class="docutils literal"><span class="pre">Value</span></tt> changing all <a class="reference internal" href="#user">User</a>s of the
+current value to refer to “<tt class="docutils literal"><span class="pre">V</span></tt>” instead. For example, if you detect that an
+instruction always produces a constant value (for example through constant
+folding), you can replace all uses of the instruction with the constant like
+this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Inst</span><span class="o">-></span><span class="n">replaceAllUsesWith</span><span class="p">(</span><span class="n">ConstVal</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-user-class">
+<span id="user"></span><h3><a class="toc-backref" href="#id110">The <tt class="docutils literal"><span class="pre">User</span></tt> class</a><a class="headerlink" href="#the-user-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/User.h"</span></tt></p>
+<p>header source: <a class="reference external" href="http://llvm.org/doxygen/User_8h-source.html">User.h</a></p>
+<p>doxygen info: <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1User.html">User Class</a></p>
+<p>Superclass: <a class="reference internal" href="#value">Value</a></p>
+<p>The <tt class="docutils literal"><span class="pre">User</span></tt> class is the common base class of all LLVM nodes that may refer to
+<tt class="docutils literal"><span class="pre">Value</span></tt>s. It exposes a list of “Operands” that are all of the <tt class="docutils literal"><span class="pre">Value</span></tt>s
+that the User is referring to. The <tt class="docutils literal"><span class="pre">User</span></tt> class itself is a subclass of
+<tt class="docutils literal"><span class="pre">Value</span></tt>.</p>
+<p>The operands of a <tt class="docutils literal"><span class="pre">User</span></tt> point directly to the LLVM <tt class="docutils literal"><span class="pre">Value</span></tt> that it refers
+to. Because LLVM uses Static Single Assignment (SSA) form, there can only be
+one definition referred to, allowing this direct connection. This connection
+provides the use-def information in LLVM.</p>
+<div class="section" id="important-public-members-of-the-user-class">
+<span id="m-user"></span><h4><a class="toc-backref" href="#id111">Important Public Members of the <tt class="docutils literal"><span class="pre">User</span></tt> class</a><a class="headerlink" href="#important-public-members-of-the-user-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">User</span></tt> class exposes the operand list in two ways: through an index access
+interface and through an iterator based interface.</p>
+<ul>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">Value</span> <span class="pre">*getOperand(unsigned</span> <span class="pre">i)</span></tt></div>
+<div class="line"><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">getNumOperands()</span></tt></div>
+</div>
+<p>These two methods expose the operands of the <tt class="docutils literal"><span class="pre">User</span></tt> in a convenient form for
+direct access.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">User::op_iterator</span></tt> - Typedef for iterator over the operand list</div>
+<div class="line"><tt class="docutils literal"><span class="pre">op_iterator</span> <span class="pre">op_begin()</span></tt> - Get an iterator to the start of the operand
+list.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">op_iterator</span> <span class="pre">op_end()</span></tt> - Get an iterator to the end of the operand list.</div>
+</div>
+<p>Together, these methods make up the iterator based interface to the operands
+of a <tt class="docutils literal"><span class="pre">User</span></tt>.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-instruction-class">
+<span id="instruction"></span><h3><a class="toc-backref" href="#id112">The <tt class="docutils literal"><span class="pre">Instruction</span></tt> class</a><a class="headerlink" href="#the-instruction-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/Instruction.h"</span></tt></p>
+<p>header source: <a class="reference external" href="http://llvm.org/doxygen/Instruction_8h-source.html">Instruction.h</a></p>
+<p>doxygen info: <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Instruction.html">Instruction Class</a></p>
+<p>Superclasses: <a class="reference internal" href="#user">User</a>, <a class="reference internal" href="#value">Value</a></p>
+<p>The <tt class="docutils literal"><span class="pre">Instruction</span></tt> class is the common base class for all LLVM instructions.
+It provides only a few methods, but is a very commonly used class. The primary
+data tracked by the <tt class="docutils literal"><span class="pre">Instruction</span></tt> class itself is the opcode (instruction
+type) and the parent <a class="reference internal" href="#basicblock">BasicBlock</a> the <tt class="docutils literal"><span class="pre">Instruction</span></tt> is embedded into. To
+represent a specific type of instruction, one of many subclasses of
+<tt class="docutils literal"><span class="pre">Instruction</span></tt> are used.</p>
+<p>Because the <tt class="docutils literal"><span class="pre">Instruction</span></tt> class subclasses the <a class="reference internal" href="#user">User</a> class, its operands can
+be accessed in the same way as for other <tt class="docutils literal"><span class="pre">User</span></tt>s (with the
+<tt class="docutils literal"><span class="pre">getOperand()</span></tt>/<tt class="docutils literal"><span class="pre">getNumOperands()</span></tt> and <tt class="docutils literal"><span class="pre">op_begin()</span></tt>/<tt class="docutils literal"><span class="pre">op_end()</span></tt> methods).
+An important file for the <tt class="docutils literal"><span class="pre">Instruction</span></tt> class is the <tt class="docutils literal"><span class="pre">llvm/Instruction.def</span></tt>
+file. This file contains some meta-data about the various different types of
+instructions in LLVM. It describes the enum values that are used as opcodes
+(for example <tt class="docutils literal"><span class="pre">Instruction::Add</span></tt> and <tt class="docutils literal"><span class="pre">Instruction::ICmp</span></tt>), as well as the
+concrete sub-classes of <tt class="docutils literal"><span class="pre">Instruction</span></tt> that implement the instruction (for
+example <a class="reference internal" href="#binaryoperator">BinaryOperator</a> and <a class="reference internal" href="#cmpinst">CmpInst</a>). Unfortunately, the use of macros in this
+file confuses doxygen, so these enum values don’t show up correctly in the
+<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Instruction.html">doxygen output</a>.</p>
+<div class="section" id="important-subclasses-of-the-instruction-class">
+<span id="s-instruction"></span><h4><a class="toc-backref" href="#id113">Important Subclasses of the <tt class="docutils literal"><span class="pre">Instruction</span></tt> class</a><a class="headerlink" href="#important-subclasses-of-the-instruction-class" title="Permalink to this headline">¶</a></h4>
+<ul id="binaryoperator">
+<li><p class="first"><tt class="docutils literal"><span class="pre">BinaryOperator</span></tt></p>
+<p>This subclasses represents all two operand instructions whose operands must be
+the same type, except for the comparison instructions.</p>
+</li>
+</ul>
+<ul class="simple" id="castinst">
+<li><tt class="docutils literal"><span class="pre">CastInst</span></tt>
+This subclass is the parent of the 12 casting instructions. It provides
+common operations on cast instructions.</li>
+</ul>
+<ul id="cmpinst">
+<li><p class="first"><tt class="docutils literal"><span class="pre">CmpInst</span></tt></p>
+<p>This subclass respresents the two comparison instructions,
+<a class="reference external" href="LangRef.html#i_icmp">ICmpInst</a> (integer opreands), and
+<a class="reference external" href="LangRef.html#i_fcmp">FCmpInst</a> (floating point operands).</p>
+</li>
+</ul>
+<ul id="terminatorinst">
+<li><p class="first"><tt class="docutils literal"><span class="pre">TerminatorInst</span></tt></p>
+<p>This subclass is the parent of all terminator instructions (those which can
+terminate a block).</p>
+</li>
+</ul>
+</div>
+<div class="section" id="important-public-members-of-the-instruction-class">
+<span id="m-instruction"></span><h4><a class="toc-backref" href="#id114">Important Public Members of the <tt class="docutils literal"><span class="pre">Instruction</span></tt> class</a><a class="headerlink" href="#important-public-members-of-the-instruction-class" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">BasicBlock</span> <span class="pre">*getParent()</span></tt></p>
+<p>Returns the <a class="reference internal" href="#basicblock">BasicBlock</a> that this
+<tt class="docutils literal"><span class="pre">Instruction</span></tt> is embedded into.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">mayWriteToMemory()</span></tt></p>
+<p>Returns true if the instruction writes to memory, i.e. it is a <tt class="docutils literal"><span class="pre">call</span></tt>,
+<tt class="docutils literal"><span class="pre">free</span></tt>, <tt class="docutils literal"><span class="pre">invoke</span></tt>, or <tt class="docutils literal"><span class="pre">store</span></tt>.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">getOpcode()</span></tt></p>
+<p>Returns the opcode for the <tt class="docutils literal"><span class="pre">Instruction</span></tt>.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Instruction</span> <span class="pre">*clone()</span> <span class="pre">const</span></tt></p>
+<p>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 <a class="reference internal" href="#basicblock">BasicBlock</a>), and it has no name.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-constant-class-and-subclasses">
+<span id="constant"></span><h3><a class="toc-backref" href="#id115">The <tt class="docutils literal"><span class="pre">Constant</span></tt> class and subclasses</a><a class="headerlink" href="#the-constant-class-and-subclasses" title="Permalink to this headline">¶</a></h3>
+<p>Constant represents a base class for different types of constants. It is
+subclassed by ConstantInt, ConstantArray, etc. for representing the various
+types of Constants. <a class="reference internal" href="#globalvalue">GlobalValue</a> is also a subclass, which represents the
+address of a global variable or function.</p>
+<div class="section" id="important-subclasses-of-constant">
+<span id="s-constant"></span><h4><a class="toc-backref" href="#id116">Important Subclasses of Constant</a><a class="headerlink" href="#important-subclasses-of-constant" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li>ConstantInt : This subclass of Constant represents an integer constant of
+any width.<ul>
+<li><tt class="docutils literal"><span class="pre">const</span> <span class="pre">APInt&</span> <span class="pre">getValue()</span> <span class="pre">const</span></tt>: Returns the underlying
+value of this constant, an APInt value.</li>
+<li><tt class="docutils literal"><span class="pre">int64_t</span> <span class="pre">getSExtValue()</span> <span class="pre">const</span></tt>: Converts the underlying APInt value to an
+int64_t via sign extension. If the value (not the bit width) of the APInt
+is too large to fit in an int64_t, an assertion will result. For this
+reason, use of this method is discouraged.</li>
+<li><tt class="docutils literal"><span class="pre">uint64_t</span> <span class="pre">getZExtValue()</span> <span class="pre">const</span></tt>: Converts the underlying APInt value
+to a uint64_t via zero extension. IF the value (not the bit width) of the
+APInt is too large to fit in a uint64_t, an assertion will result. For this
+reason, use of this method is discouraged.</li>
+<li><tt class="docutils literal"><span class="pre">static</span> <span class="pre">ConstantInt*</span> <span class="pre">get(const</span> <span class="pre">APInt&</span> <span class="pre">Val)</span></tt>: Returns the ConstantInt
+object that represents the value provided by <tt class="docutils literal"><span class="pre">Val</span></tt>. The type is implied
+as the IntegerType that corresponds to the bit width of <tt class="docutils literal"><span class="pre">Val</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">static</span> <span class="pre">ConstantInt*</span> <span class="pre">get(const</span> <span class="pre">Type</span> <span class="pre">*Ty,</span> <span class="pre">uint64_t</span> <span class="pre">Val)</span></tt>: Returns the
+ConstantInt object that represents the value provided by <tt class="docutils literal"><span class="pre">Val</span></tt> for integer
+type <tt class="docutils literal"><span class="pre">Ty</span></tt>.</li>
+</ul>
+</li>
+<li>ConstantFP : This class represents a floating point constant.<ul>
+<li><tt class="docutils literal"><span class="pre">double</span> <span class="pre">getValue()</span> <span class="pre">const</span></tt>: Returns the underlying value of this constant.</li>
+</ul>
+</li>
+<li>ConstantArray : This represents a constant array.<ul>
+<li><tt class="docutils literal"><span class="pre">const</span> <span class="pre">std::vector<Use></span> <span class="pre">&getValues()</span> <span class="pre">const</span></tt>: Returns a vector of
+component constants that makeup this array.</li>
+</ul>
+</li>
+<li>ConstantStruct : This represents a constant struct.<ul>
+<li><tt class="docutils literal"><span class="pre">const</span> <span class="pre">std::vector<Use></span> <span class="pre">&getValues()</span> <span class="pre">const</span></tt>: Returns a vector of
+component constants that makeup this array.</li>
+</ul>
+</li>
+<li>GlobalValue : This represents either a global variable or a function. In
+either case, the value is a constant fixed address (after linking).</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-globalvalue-class">
+<span id="globalvalue"></span><h3><a class="toc-backref" href="#id117">The <tt class="docutils literal"><span class="pre">GlobalValue</span></tt> class</a><a class="headerlink" href="#the-globalvalue-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/GlobalValue.h"</span></tt></p>
+<p>header source: <a class="reference external" href="http://llvm.org/doxygen/GlobalValue_8h-source.html">GlobalValue.h</a></p>
+<p>doxygen info: <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1GlobalValue.html">GlobalValue Class</a></p>
+<p>Superclasses: <a class="reference internal" href="#constant">Constant</a>, <a class="reference internal" href="#user">User</a>, <a class="reference internal" href="#value">Value</a></p>
+<p>Global values ( <a class="reference internal" href="#globalvariable">GlobalVariable</a>s or <a class="reference internal" href="#c-function"><em>Function</em></a>s) are the
+only LLVM values that are visible in the bodies of all <a class="reference internal" href="#c-function"><em>Function</em></a>s. Because they are visible at global scope, they are also
+subject to linking with other globals defined in different translation units.
+To control the linking process, <tt class="docutils literal"><span class="pre">GlobalValue</span></tt>s know their linkage rules.
+Specifically, <tt class="docutils literal"><span class="pre">GlobalValue</span></tt>s know whether they have internal or external
+linkage, as defined by the <tt class="docutils literal"><span class="pre">LinkageTypes</span></tt> enumeration.</p>
+<p>If a <tt class="docutils literal"><span class="pre">GlobalValue</span></tt> has internal linkage (equivalent to being <tt class="docutils literal"><span class="pre">static</span></tt> in C),
+it is not visible to code outside the current translation unit, and does not
+participate in linking. If it has external linkage, it is visible to external
+code, and does participate in linking. In addition to linkage information,
+<tt class="docutils literal"><span class="pre">GlobalValue</span></tt>s keep track of which <a class="reference internal" href="#module">Module</a> they are currently part of.</p>
+<p>Because <tt class="docutils literal"><span class="pre">GlobalValue</span></tt>s are memory objects, they are always referred to by
+their <strong>address</strong>. As such, the <a class="reference internal" href="#type">Type</a> of a global is always a pointer to its
+contents. It is important to remember this when using the <tt class="docutils literal"><span class="pre">GetElementPtrInst</span></tt>
+instruction because this pointer must be dereferenced first. For example, if
+you have a <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> (a subclass of <tt class="docutils literal"><span class="pre">GlobalValue)</span></tt> that is an array
+of 24 ints, type <tt class="docutils literal"><span class="pre">[24</span> <span class="pre">x</span> <span class="pre">i32]</span></tt>, then the <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> is a pointer to
+that array. Although the address of the first element of this array and the
+value of the <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> are the same, they have different types. The
+<tt class="docutils literal"><span class="pre">GlobalVariable</span></tt>‘s type is <tt class="docutils literal"><span class="pre">[24</span> <span class="pre">x</span> <span class="pre">i32]</span></tt>. The first element’s type is
+<tt class="docutils literal"><span class="pre">i32.</span></tt> Because of this, accessing a global value requires you to dereference
+the pointer with <tt class="docutils literal"><span class="pre">GetElementPtrInst</span></tt> first, then its elements can be accessed.
+This is explained in the <a class="reference external" href="LangRef.html#globalvars">LLVM Language Reference Manual</a>.</p>
+<div class="section" id="important-public-members-of-the-globalvalue-class">
+<span id="m-globalvalue"></span><h4><a class="toc-backref" href="#id118">Important Public Members of the <tt class="docutils literal"><span class="pre">GlobalValue</span></tt> class</a><a class="headerlink" href="#important-public-members-of-the-globalvalue-class" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">hasInternalLinkage()</span> <span class="pre">const</span></tt></div>
+<div class="line"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">hasExternalLinkage()</span> <span class="pre">const</span></tt></div>
+<div class="line"><tt class="docutils literal"><span class="pre">void</span> <span class="pre">setInternalLinkage(bool</span> <span class="pre">HasInternalLinkage)</span></tt></div>
+</div>
+<p>These methods manipulate the linkage characteristics of the <tt class="docutils literal"><span class="pre">GlobalValue</span></tt>.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Module</span> <span class="pre">*getParent()</span></tt></p>
+<p>This returns the <a class="reference internal" href="#module">Module</a> that the
+GlobalValue is currently embedded into.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-function-class">
+<span id="c-function"></span><h3><a class="toc-backref" href="#id119">The <tt class="docutils literal"><span class="pre">Function</span></tt> class</a><a class="headerlink" href="#the-function-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/Function.h"</span></tt></p>
+<p>header source: <a class="reference external" href="http://llvm.org/doxygen/Function_8h-source.html">Function.h</a></p>
+<p>doxygen info: <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Function.html">Function Class</a></p>
+<p>Superclasses: <a class="reference internal" href="#globalvalue">GlobalValue</a>, <a class="reference internal" href="#constant">Constant</a>, <a class="reference internal" href="#user">User</a>, <a class="reference internal" href="#value">Value</a></p>
+<p>The <tt class="docutils literal"><span class="pre">Function</span></tt> class represents a single procedure in LLVM. It is actually
+one of the more complex classes in the LLVM hierarchy because it must keep track
+of a large amount of data. The <tt class="docutils literal"><span class="pre">Function</span></tt> class keeps track of a list of
+<a class="reference internal" href="#basicblock">BasicBlock</a>s, a list of formal <a class="reference internal" href="#argument">Argument</a>s, and a <a class="reference internal" href="#symboltable">SymbolTable</a>.</p>
+<p>The list of <a class="reference internal" href="#basicblock">BasicBlock</a>s is the most commonly used part of <tt class="docutils literal"><span class="pre">Function</span></tt>
+objects. The list imposes an implicit ordering of the blocks in the function,
+which indicate how the code will be laid out by the backend. Additionally, the
+first <a class="reference internal" href="#basicblock">BasicBlock</a> is the implicit entry node for the <tt class="docutils literal"><span class="pre">Function</span></tt>. It is not
+legal in LLVM to explicitly branch to this initial block. There are no implicit
+exit nodes, and in fact there may be multiple exit nodes from a single
+<tt class="docutils literal"><span class="pre">Function</span></tt>. If the <a class="reference internal" href="#basicblock">BasicBlock</a> list is empty, this indicates that the
+<tt class="docutils literal"><span class="pre">Function</span></tt> is actually a function declaration: the actual body of the function
+hasn’t been linked in yet.</p>
+<p>In addition to a list of <a class="reference internal" href="#basicblock">BasicBlock</a>s, the <tt class="docutils literal"><span class="pre">Function</span></tt> class also keeps track
+of the list of formal <a class="reference internal" href="#argument">Argument</a>s that the function receives. This container
+manages the lifetime of the <a class="reference internal" href="#argument">Argument</a> nodes, just like the <a class="reference internal" href="#basicblock">BasicBlock</a> list does
+for the <a class="reference internal" href="#basicblock">BasicBlock</a>s.</p>
+<p>The <a class="reference internal" href="#symboltable">SymbolTable</a> is a very rarely used LLVM feature that is only used when you
+have to look up a value by name. Aside from that, the <a class="reference internal" href="#symboltable">SymbolTable</a> is used
+internally to make sure that there are not conflicts between the names of
+<a class="reference internal" href="#instruction">Instruction</a>s, <a class="reference internal" href="#basicblock">BasicBlock</a>s, or <a class="reference internal" href="#argument">Argument</a>s in the function body.</p>
+<p>Note that <tt class="docutils literal"><span class="pre">Function</span></tt> is a <a class="reference internal" href="#globalvalue">GlobalValue</a> and therefore also a <a class="reference internal" href="#constant">Constant</a>. The
+value of the function is its address (after linking) which is guaranteed to be
+constant.</p>
+<div class="section" id="important-public-members-of-the-function">
+<span id="m-function"></span><h4><a class="toc-backref" href="#id120">Important Public Members of the <tt class="docutils literal"><span class="pre">Function</span></tt></a><a class="headerlink" href="#important-public-members-of-the-function" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Function(const</span> <span class="pre">FunctionType</span> <span class="pre">*Ty,</span> <span class="pre">LinkageTypes</span> <span class="pre">Linkage,</span>
+<span class="pre">const</span> <span class="pre">std::string</span> <span class="pre">&N</span> <span class="pre">=</span> <span class="pre">"",</span> <span class="pre">Module*</span> <span class="pre">Parent</span> <span class="pre">=</span> <span class="pre">0)</span></tt></p>
+<p>Constructor used when you need to create new <tt class="docutils literal"><span class="pre">Function</span></tt>s to add the
+program. The constructor must specify the type of the function to create and
+what type of linkage the function should have. The <a class="reference internal" href="#functiontype">FunctionType</a> argument
+specifies the formal arguments and return value for the function. The same
+<a class="reference internal" href="#functiontype">FunctionType</a> value can be used to create multiple functions. The <tt class="docutils literal"><span class="pre">Parent</span></tt>
+argument specifies the Module in which the function is defined. If this
+argument is provided, the function will automatically be inserted into that
+module’s list of functions.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">isDeclaration()</span></tt></p>
+<p>Return whether or not the <tt class="docutils literal"><span class="pre">Function</span></tt> has a body defined. If the function is
+“external”, it does not have a body, and thus must be resolved by linking with
+a function defined in a different translation unit.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">Function::iterator</span></tt> - Typedef for basic block list iterator</div>
+<div class="line"><tt class="docutils literal"><span class="pre">Function::const_iterator</span></tt> - Typedef for const_iterator.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">begin()</span></tt>, <tt class="docutils literal"><span class="pre">end()</span></tt>, <tt class="docutils literal"><span class="pre">size()</span></tt>, <tt class="docutils literal"><span class="pre">empty()</span></tt></div>
+</div>
+<p>These are forwarding methods that make it easy to access the contents of a
+<tt class="docutils literal"><span class="pre">Function</span></tt> object’s <a class="reference internal" href="#basicblock">BasicBlock</a> list.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Function::BasicBlockListType</span> <span class="pre">&getBasicBlockList()</span></tt></p>
+<p>Returns the list of <a class="reference internal" href="#basicblock">BasicBlock</a>s. This is necessary to use when you need to
+update the list or perform a complex action that doesn’t have a forwarding
+method.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">Function::arg_iterator</span></tt> - Typedef for the argument list iterator</div>
+<div class="line"><tt class="docutils literal"><span class="pre">Function::const_arg_iterator</span></tt> - Typedef for const_iterator.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">arg_begin()</span></tt>, <tt class="docutils literal"><span class="pre">arg_end()</span></tt>, <tt class="docutils literal"><span class="pre">arg_size()</span></tt>, <tt class="docutils literal"><span class="pre">arg_empty()</span></tt></div>
+</div>
+<p>These are forwarding methods that make it easy to access the contents of a
+<tt class="docutils literal"><span class="pre">Function</span></tt> object’s <a class="reference internal" href="#argument">Argument</a> list.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Function::ArgumentListType</span> <span class="pre">&getArgumentList()</span></tt></p>
+<p>Returns the list of <a class="reference internal" href="#argument">Argument</a>. This is necessary to use when you need to
+update the list or perform a complex action that doesn’t have a forwarding
+method.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">BasicBlock</span> <span class="pre">&getEntryBlock()</span></tt></p>
+<p>Returns the entry <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> for the function. Because the entry block
+for the function is always the first block, this returns the first block of
+the <tt class="docutils literal"><span class="pre">Function</span></tt>.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">Type</span> <span class="pre">*getReturnType()</span></tt></div>
+<div class="line"><tt class="docutils literal"><span class="pre">FunctionType</span> <span class="pre">*getFunctionType()</span></tt></div>
+</div>
+<p>This traverses the <a class="reference internal" href="#type">Type</a> of the <tt class="docutils literal"><span class="pre">Function</span></tt> and returns the return type of
+the function, or the <a class="reference internal" href="#functiontype">FunctionType</a> of the actual function.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">SymbolTable</span> <span class="pre">*getSymbolTable()</span></tt></p>
+<p>Return a pointer to the <a class="reference internal" href="#symboltable">SymbolTable</a> for this <tt class="docutils literal"><span class="pre">Function</span></tt>.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-globalvariable-class">
+<span id="globalvariable"></span><h3><a class="toc-backref" href="#id121">The <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> class</a><a class="headerlink" href="#the-globalvariable-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/GlobalVariable.h"</span></tt></p>
+<p>header source: <a class="reference external" href="http://llvm.org/doxygen/GlobalVariable_8h-source.html">GlobalVariable.h</a></p>
+<p>doxygen info: <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1GlobalVariable.html">GlobalVariable Class</a></p>
+<p>Superclasses: <a class="reference internal" href="#globalvalue">GlobalValue</a>, <a class="reference internal" href="#constant">Constant</a>, <a class="reference internal" href="#user">User</a>, <a class="reference internal" href="#value">Value</a></p>
+<p>Global variables are represented with the (surprise surprise) <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt>
+class. Like functions, <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt>s are also subclasses of
+<a class="reference internal" href="#globalvalue">GlobalValue</a>, and as such are always referenced by their address (global values
+must live in memory, so their “name” refers to their constant address). See
+<a class="reference internal" href="#globalvalue">GlobalValue</a> for more on this. Global variables may have an initial value
+(which must be a <a class="reference internal" href="#constant">Constant</a>), and if they have an initializer, they may be marked
+as “constant” themselves (indicating that their contents never change at
+runtime).</p>
+<div class="section" id="important-public-members-of-the-globalvariable-class">
+<span id="m-globalvariable"></span><h4><a class="toc-backref" href="#id122">Important Public Members of the <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> class</a><a class="headerlink" href="#important-public-members-of-the-globalvariable-class" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">GlobalVariable(const</span> <span class="pre">Type</span> <span class="pre">*Ty,</span> <span class="pre">bool</span> <span class="pre">isConstant,</span> <span class="pre">LinkageTypes</span> <span class="pre">&Linkage,</span>
+<span class="pre">Constant</span> <span class="pre">*Initializer</span> <span class="pre">=</span> <span class="pre">0,</span> <span class="pre">const</span> <span class="pre">std::string</span> <span class="pre">&Name</span> <span class="pre">=</span> <span class="pre">"",</span> <span class="pre">Module*</span> <span class="pre">Parent</span> <span class="pre">=</span> <span class="pre">0)</span></tt></p>
+<p>Create a new global variable of the specified type. If <tt class="docutils literal"><span class="pre">isConstant</span></tt> is true
+then the global variable will be marked as unchanging for the program. The
+Linkage parameter specifies the type of linkage (internal, external, weak,
+linkonce, appending) for the variable. If the linkage is InternalLinkage,
+WeakAnyLinkage, WeakODRLinkage, LinkOnceAnyLinkage or LinkOnceODRLinkage, then
+the resultant global variable will have internal linkage. AppendingLinkage
+concatenates together all instances (in different translation units) of the
+variable into a single variable but is only applicable to arrays. See the
+<a class="reference external" href="LangRef.html#modulestructure">LLVM Language Reference</a> for further details
+on linkage types. Optionally an initializer, a name, and the module to put
+the variable into may be specified for the global variable as well.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">isConstant()</span> <span class="pre">const</span></tt></p>
+<p>Returns true if this is a global variable that is known not to be modified at
+runtime.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">bool</span> <span class="pre">hasInitializer()</span></tt></p>
+<p>Returns true if this <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt> has an intializer.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Constant</span> <span class="pre">*getInitializer()</span></tt></p>
+<p>Returns the initial value for a <tt class="docutils literal"><span class="pre">GlobalVariable</span></tt>. It is not legal to call
+this method if there is no initializer.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-basicblock-class">
+<span id="basicblock"></span><h3><a class="toc-backref" href="#id123">The <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> class</a><a class="headerlink" href="#the-basicblock-class" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/BasicBlock.h"</span></tt></p>
+<p>header source: <a class="reference external" href="http://llvm.org/doxygen/BasicBlock_8h-source.html">BasicBlock.h</a></p>
+<p>doxygen info: <a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1BasicBlock.html">BasicBlock Class</a></p>
+<p>Superclass: <a class="reference internal" href="#value">Value</a></p>
+<p>This class represents a single entry single exit section of the code, commonly
+known as a basic block by the compiler community. The <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> class
+maintains a list of <a class="reference internal" href="#instruction">Instruction</a>s, which form the body of the block. Matching
+the language definition, the last element of this list of instructions is always
+a terminator instruction (a subclass of the <a class="reference internal" href="#terminatorinst">TerminatorInst</a> class).</p>
+<p>In addition to tracking the list of instructions that make up the block, the
+<tt class="docutils literal"><span class="pre">BasicBlock</span></tt> class also keeps track of the <a class="reference internal" href="#c-function"><em>Function</em></a> that
+it is embedded into.</p>
+<p>Note that <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s themselves are <a class="reference internal" href="#value">Value</a>s, because they are
+referenced by instructions like branches and can go in the switch tables.
+<tt class="docutils literal"><span class="pre">BasicBlock</span></tt>s have type <tt class="docutils literal"><span class="pre">label</span></tt>.</p>
+<div class="section" id="important-public-members-of-the-basicblock-class">
+<span id="m-basicblock"></span><h4><a class="toc-backref" href="#id124">Important Public Members of the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> class</a><a class="headerlink" href="#important-public-members-of-the-basicblock-class" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">BasicBlock(const</span> <span class="pre">std::string</span> <span class="pre">&Name</span> <span class="pre">=</span> <span class="pre">"",</span> <span class="pre">Function</span> <span class="pre">*Parent</span> <span class="pre">=</span> <span class="pre">0)</span></tt></p>
+<p>The <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> constructor is used to create new basic blocks for
+insertion into a function. The constructor optionally takes a name for the
+new block, and a <a class="reference internal" href="#c-function"><em>Function</em></a> to insert it into. If the
+<tt class="docutils literal"><span class="pre">Parent</span></tt> parameter is specified, the new <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> is automatically
+inserted at the end of the specified <a class="reference internal" href="#c-function"><em>Function</em></a>, if not
+specified, the BasicBlock must be manually inserted into the <a class="reference internal" href="#c-function"><em>Function</em></a>.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><tt class="docutils literal"><span class="pre">BasicBlock::iterator</span></tt> - Typedef for instruction list iterator</div>
+<div class="line"><tt class="docutils literal"><span class="pre">BasicBlock::const_iterator</span></tt> - Typedef for const_iterator.</div>
+<div class="line"><tt class="docutils literal"><span class="pre">begin()</span></tt>, <tt class="docutils literal"><span class="pre">end()</span></tt>, <tt class="docutils literal"><span class="pre">front()</span></tt>, <tt class="docutils literal"><span class="pre">back()</span></tt>,
+<tt class="docutils literal"><span class="pre">size()</span></tt>, <tt class="docutils literal"><span class="pre">empty()</span></tt>
+STL-style functions for accessing the instruction list.</div>
+</div>
+<p>These methods and typedefs are forwarding functions that have the same
+semantics as the standard library methods of the same names. These methods
+expose the underlying instruction list of a basic block in a way that is easy
+to manipulate. To get the full complement of container operations (including
+operations to update the list), you must use the <tt class="docutils literal"><span class="pre">getInstList()</span></tt> method.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">BasicBlock::InstListType</span> <span class="pre">&getInstList()</span></tt></p>
+<p>This method is used to get access to the underlying container that actually
+holds the Instructions. This method must be used when there isn’t a
+forwarding function in the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> class for the operation that you
+would like to perform. Because there are no forwarding functions for
+“updating” operations, you need to use this if you want to update the contents
+of a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt>.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">Function</span> <span class="pre">*getParent()</span></tt></p>
+<p>Returns a pointer to <a class="reference internal" href="#c-function"><em>Function</em></a> the block is embedded into,
+or a null pointer if it is homeless.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">TerminatorInst</span> <span class="pre">*getTerminator()</span></tt></p>
+<p>Returns a pointer to the terminator instruction that appears at the end of the
+<tt class="docutils literal"><span class="pre">BasicBlock</span></tt>. If there is no terminator instruction, or if the last
+instruction in the block is not a terminator, then a null pointer is returned.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-argument-class">
+<span id="argument"></span><h3><a class="toc-backref" href="#id125">The <tt class="docutils literal"><span class="pre">Argument</span></tt> class</a><a class="headerlink" href="#the-argument-class" title="Permalink to this headline">¶</a></h3>
+<p>This subclass of Value defines the interface for incoming formal arguments to a
+function. A Function maintains a list of its formal arguments. An argument has
+a pointer to the parent Function.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Extensions.html" title="LLVM Extensions"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/Projects.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/Projects.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/Projects.html (added)
+++ www-releases/trunk/3.3/docs/Projects.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,403 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Creating an LLVM Project — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="LLVMBuild Guide" href="LLVMBuild.html" />
+ <link rel="prev" title="LLVM Makefile Guide" href="MakefileGuide.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LLVMBuild.html" title="LLVMBuild Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="MakefileGuide.html" title="LLVM Makefile Guide"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="creating-an-llvm-project">
+<h1>Creating an LLVM Project<a class="headerlink" href="#creating-an-llvm-project" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
+<li><a class="reference internal" href="#create-a-project-from-the-sample-project" id="id2">Create a Project from the Sample Project</a></li>
+<li><a class="reference internal" href="#source-tree-layout" id="id3">Source Tree Layout</a></li>
+<li><a class="reference internal" href="#writing-llvm-style-makefiles" id="id4">Writing LLVM Style Makefiles</a><ul>
+<li><a class="reference internal" href="#required-variables" id="id5">Required Variables</a></li>
+<li><a class="reference internal" href="#variables-for-building-subdirectories" id="id6">Variables for Building Subdirectories</a></li>
+<li><a class="reference internal" href="#variables-for-building-libraries" id="id7">Variables for Building Libraries</a></li>
+<li><a class="reference internal" href="#variables-for-building-programs" id="id8">Variables for Building Programs</a></li>
+<li><a class="reference internal" href="#miscellaneous-variables" id="id9">Miscellaneous Variables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#placement-of-object-code" id="id10">Placement of Object Code</a></li>
+<li><a class="reference internal" href="#further-help" id="id11">Further Help</a></li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id1">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>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 <tt class="docutils literal"><span class="pre">Makefile</span></tt> from a project must do the following things:</p>
+<ul class="simple">
+<li>Set <tt class="docutils literal"><span class="pre">make</span></tt> variables. There are several variables that a <tt class="docutils literal"><span class="pre">Makefile</span></tt> needs
+to set to use the LLVM build system:<ul>
+<li><tt class="docutils literal"><span class="pre">PROJECT_NAME</span></tt> - The name by which your project is known.</li>
+<li><tt class="docutils literal"><span class="pre">LLVM_SRC_ROOT</span></tt> - The root of the LLVM source tree.</li>
+<li><tt class="docutils literal"><span class="pre">LLVM_OBJ_ROOT</span></tt> - The root of the LLVM object tree.</li>
+<li><tt class="docutils literal"><span class="pre">PROJ_SRC_ROOT</span></tt> - The root of the project’s source tree.</li>
+<li><tt class="docutils literal"><span class="pre">PROJ_OBJ_ROOT</span></tt> - The root of the project’s object tree.</li>
+<li><tt class="docutils literal"><span class="pre">PROJ_INSTALL_ROOT</span></tt> - The root installation directory.</li>
+<li><tt class="docutils literal"><span class="pre">LEVEL</span></tt> - The relative path from the current directory to the
+project’s root <tt class="docutils literal"><span class="pre">($PROJ_OBJ_ROOT)</span></tt>.</li>
+</ul>
+</li>
+<li>Include <tt class="docutils literal"><span class="pre">Makefile.config</span></tt> from <tt class="docutils literal"><span class="pre">$(LLVM_OBJ_ROOT)</span></tt>.</li>
+<li>Include <tt class="docutils literal"><span class="pre">Makefile.rules</span></tt> from <tt class="docutils literal"><span class="pre">$(LLVM_SRC_ROOT)</span></tt>.</li>
+</ul>
+<p>There are two ways that you can set all of these variables:</p>
+<ul class="simple">
+<li>You can write your own <tt class="docutils literal"><span class="pre">Makefiles</span></tt> which hard-code these values.</li>
+<li>You can use the pre-made LLVM sample project. This sample project includes
+<tt class="docutils literal"><span class="pre">Makefiles</span></tt>, 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.</li>
+</ul>
+<p>This document assumes that you will base your project on the LLVM sample project
+found in <tt class="docutils literal"><span class="pre">llvm/projects/sample</span></tt>. If you want to devise your own build system,
+studying the sample project and LLVM <tt class="docutils literal"><span class="pre">Makefiles</span></tt> will probably provide enough
+information on how to write your own <tt class="docutils literal"><span class="pre">Makefiles</span></tt>.</p>
+</div>
+<div class="section" id="create-a-project-from-the-sample-project">
+<h2><a class="toc-backref" href="#id2">Create a Project from the Sample Project</a><a class="headerlink" href="#create-a-project-from-the-sample-project" title="Permalink to this headline">¶</a></h2>
+<p>Follow these simple steps to start your project:</p>
+<ol class="arabic">
+<li><p class="first">Copy the <tt class="docutils literal"><span class="pre">llvm/projects/sample</span></tt> directory to any place of your choosing.
+You can place it anywhere you like. Rename the directory to match the name
+of your project.</p>
+</li>
+<li><p class="first">If you downloaded LLVM using Subversion, remove all the directories named
+<tt class="docutils literal"><span class="pre">.svn</span></tt> (and all the files therein) from your project’s new source tree.
+This will keep Subversion from thinking that your project is inside
+<tt class="docutils literal"><span class="pre">llvm/trunk/projects/sample</span></tt>.</p>
+</li>
+<li><p class="first">Add your source code and Makefiles to your source tree.</p>
+</li>
+<li><p class="first">If you want your project to be configured with the <tt class="docutils literal"><span class="pre">configure</span></tt> script then
+you need to edit <tt class="docutils literal"><span class="pre">autoconf/configure.ac</span></tt> as follows:</p>
+<ul class="simple">
+<li><strong>AC_INIT</strong> - Place the name of your project, its version number and a
+contact email address for your project as the arguments to this macro</li>
+<li><strong>AC_CONFIG_AUX_DIR</strong> - If your project isn’t in the <tt class="docutils literal"><span class="pre">llvm/projects</span></tt>
+directory then you might need to adjust this so that it specifies a
+relative path to the <tt class="docutils literal"><span class="pre">llvm/autoconf</span></tt> directory.</li>
+<li><strong>LLVM_CONFIG_PROJECT</strong> - Just leave this alone.</li>
+<li><strong>AC_CONFIG_SRCDIR</strong> - Specify a path to a file name that identifies your
+project; or just leave it at <tt class="docutils literal"><span class="pre">Makefile.common.in</span></tt>.</li>
+<li><strong>AC_CONFIG_FILES</strong> - Do not change.</li>
+<li><strong>AC_CONFIG_MAKEFILE</strong> - Use one of these macros for each Makefile that
+your project uses. This macro arranges for your makefiles to be copied from
+the source directory, unmodified, to the build directory.</li>
+</ul>
+</li>
+<li><p class="first">After updating <tt class="docutils literal"><span class="pre">autoconf/configure.ac</span></tt>, regenerate the configure script
+with these commands. (You must be using <tt class="docutils literal"><span class="pre">Autoconf</span></tt> version 2.59 or later
+and your <tt class="docutils literal"><span class="pre">aclocal</span></tt> version should be 1.9 or later.)</p>
+<blockquote>
+<div><div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd </span>autoconf
+% ./AutoRegen.sh
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+<li><p class="first">Run <tt class="docutils literal"><span class="pre">configure</span></tt> in the directory in which you want to place object code.
+Use the following options to tell your project where it can find LLVM:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">--with-llvmsrc=<directory></span></tt></dt>
+<dd><p class="first last">Tell your project where the LLVM source tree is located.</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">--with-llvmobj=<directory></span></tt></dt>
+<dd><p class="first last">Tell your project where the LLVM object tree is located.</p>
+</dd>
+<dt><tt class="docutils literal"><span class="pre">--prefix=<directory></span></tt></dt>
+<dd><p class="first last">Tell your project where it should get installed.</p>
+</dd>
+</dl>
+</li>
+</ol>
+<p>That’s it! Now all you have to do is type <tt class="docutils literal"><span class="pre">gmake</span></tt> (or <tt class="docutils literal"><span class="pre">make</span></tt> if you’re on a
+GNU/Linux system) in the root of your object directory, and your project should
+build.</p>
+</div>
+<div class="section" id="source-tree-layout">
+<h2><a class="toc-backref" href="#id3">Source Tree Layout</a><a class="headerlink" href="#source-tree-layout" title="Permalink to this headline">¶</a></h2>
+<p>In order to use the LLVM build system, you will want to organize your source
+code so that it can benefit from the build system’s features. Mainly, you want
+your source tree layout to look similar to the LLVM source tree layout. The
+best way to do this is to just copy the project tree from
+<tt class="docutils literal"><span class="pre">llvm/projects/sample</span></tt> and modify it to meet your needs, but you can certainly
+add to it if you want.</p>
+<p>Underneath your top level directory, you should have the following directories:</p>
+<p><strong>lib</strong></p>
+<blockquote>
+<div><p>This subdirectory should contain all of your library source code. For each
+library that you build, you will have one directory in <strong>lib</strong> that will
+contain that library’s source code.</p>
+<p>Libraries can be object files, archives, or dynamic libraries. The <strong>lib</strong>
+directory is just a convenient place for libraries as it places them all in
+a directory from which they can be linked later.</p>
+</div></blockquote>
+<p><strong>include</strong></p>
+<blockquote>
+<div><p>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.</p>
+<p>By placing your header files in <strong>include</strong>, they will be found
+automatically by the LLVM build system. For example, if you have a file
+<strong>include/jazz/note.h</strong>, then your source files can include it simply with
+<strong>#include “jazz/note.h”</strong>.</p>
+</div></blockquote>
+<p><strong>tools</strong></p>
+<blockquote>
+<div>This subdirectory should contain all of your source code for executables.
+For each program that you build, you will have one directory in <strong>tools</strong>
+that will contain that program’s source code.</div></blockquote>
+<p><strong>test</strong></p>
+<blockquote>
+<div><p>This subdirectory should contain tests that verify that your code works
+correctly. Automated tests are especially useful.</p>
+<p>Currently, the LLVM build system provides basic support for tests. The LLVM
+system provides the following:</p>
+</div></blockquote>
+<ul>
+<li><p class="first">LLVM contains regression tests in <tt class="docutils literal"><span class="pre">llvm/test</span></tt>. These tests are run by the
+<a class="reference internal" href="CommandGuide/lit.html"><em>Lit</em></a> testing tool. This test procedure uses <tt class="docutils literal"><span class="pre">RUN</span></tt>
+lines in the actual test case to determine how to run the test. See the
+<a class="reference internal" href="TestingGuide.html"><em>LLVM Testing Infrastructure Guide</em></a> for more details.</p>
+</li>
+<li><p class="first">LLVM contains an optional package called <tt class="docutils literal"><span class="pre">llvm-test</span></tt>, 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.</p>
+<p>Currently, there is no way to hook your tests directly into the <tt class="docutils literal"><span class="pre">llvm/test</span></tt>
+testing harness. You will simply need to find a way to use the source
+provided within that directory on your own.</p>
+</li>
+</ul>
+<p>Typically, you will want to build your <strong>lib</strong> directory first followed by your
+<strong>tools</strong> directory.</p>
+</div>
+<div class="section" id="writing-llvm-style-makefiles">
+<h2><a class="toc-backref" href="#id4">Writing LLVM Style Makefiles</a><a class="headerlink" href="#writing-llvm-style-makefiles" title="Permalink to this headline">¶</a></h2>
+<p>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:</p>
+<div class="section" id="required-variables">
+<h3><a class="toc-backref" href="#id5">Required Variables</a><a class="headerlink" href="#required-variables" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">LEVEL</span></tt></p>
+<blockquote>
+<div>This variable is the relative path from this <tt class="docutils literal"><span class="pre">Makefile</span></tt> to the top
+directory of your project’s source code. For example, if your source code
+is in <tt class="docutils literal"><span class="pre">/tmp/src</span></tt>, then the <tt class="docutils literal"><span class="pre">Makefile</span></tt> in <tt class="docutils literal"><span class="pre">/tmp/src/jump/high</span></tt>
+would set <tt class="docutils literal"><span class="pre">LEVEL</span></tt> to <tt class="docutils literal"><span class="pre">"../.."</span></tt>.</div></blockquote>
+</div>
+<div class="section" id="variables-for-building-subdirectories">
+<h3><a class="toc-backref" href="#id6">Variables for Building Subdirectories</a><a class="headerlink" href="#variables-for-building-subdirectories" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">DIRS</span></tt></p>
+<blockquote>
+<div>This is a space separated list of subdirectories that should be built. They
+will be built, one at a time, in the order specified.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">PARALLEL_DIRS</span></tt></p>
+<blockquote>
+<div>This is a list of directories that can be built in parallel. These will be
+built after the directories in DIRS have been built.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">OPTIONAL_DIRS</span></tt></p>
+<blockquote>
+<div>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.</div></blockquote>
+</div>
+<div class="section" id="variables-for-building-libraries">
+<h3><a class="toc-backref" href="#id7">Variables for Building Libraries</a><a class="headerlink" href="#variables-for-building-libraries" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">LIBRARYNAME</span></tt></p>
+<blockquote>
+<div>This variable contains the base name of the library that will be built. For
+example, to build a library named <tt class="docutils literal"><span class="pre">libsample.a</span></tt>, <tt class="docutils literal"><span class="pre">LIBRARYNAME</span></tt> should
+be set to <tt class="docutils literal"><span class="pre">sample</span></tt>.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">BUILD_ARCHIVE</span></tt></p>
+<blockquote>
+<div>By default, a library is a <tt class="docutils literal"><span class="pre">.o</span></tt> file that is linked directly into a
+program. To build an archive (also known as a static library), set the
+<tt class="docutils literal"><span class="pre">BUILD_ARCHIVE</span></tt> variable.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">SHARED_LIBRARY</span></tt></p>
+<blockquote>
+<div>If <tt class="docutils literal"><span class="pre">SHARED_LIBRARY</span></tt> is defined in your Makefile, a shared (or dynamic)
+library will be built.</div></blockquote>
+</div>
+<div class="section" id="variables-for-building-programs">
+<h3><a class="toc-backref" href="#id8">Variables for Building Programs</a><a class="headerlink" href="#variables-for-building-programs" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">TOOLNAME</span></tt></p>
+<blockquote>
+<div>This variable contains the name of the program that will be built. For
+example, to build an executable named <tt class="docutils literal"><span class="pre">sample</span></tt>, <tt class="docutils literal"><span class="pre">TOOLNAME</span></tt> should be set
+to <tt class="docutils literal"><span class="pre">sample</span></tt>.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">USEDLIBS</span></tt></p>
+<blockquote>
+<div><p>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 <strong>lib</strong> directory. The libraries must be specified without their
+<tt class="docutils literal"><span class="pre">lib</span></tt> prefix. For example, to link <tt class="docutils literal"><span class="pre">libsample.a</span></tt>, you would set
+<tt class="docutils literal"><span class="pre">USEDLIBS</span></tt> to <tt class="docutils literal"><span class="pre">sample.a</span></tt>.</p>
+<p>Note that this works only for statically linked libraries.</p>
+</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">LLVMLIBS</span></tt></p>
+<blockquote>
+<div><p>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 <tt class="docutils literal"><span class="pre">lib</span></tt> prefix. For example, to
+link with a driver that performs an IR transformation you might set
+<tt class="docutils literal"><span class="pre">LLVMLIBS</span></tt> to this minimal set of libraries <tt class="docutils literal"><span class="pre">LLVMSupport.a</span> <span class="pre">LLVMCore.a</span>
+<span class="pre">LLVMBitReader.a</span> <span class="pre">LLVMAsmParser.a</span> <span class="pre">LLVMAnalysis.a</span> <span class="pre">LLVMTransformUtils.a</span>
+<span class="pre">LLVMScalarOpts.a</span> <span class="pre">LLVMTarget.a</span></tt>.</p>
+<p>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: <tt class="docutils literal"><span class="pre">llvm-config</span> <span class="pre">--libs</span> <span class="pre">all</span></tt>. Using <tt class="docutils literal"><span class="pre">LINK_COMPONENTS</span></tt> as
+described below, obviates the need to set <tt class="docutils literal"><span class="pre">LLVMLIBS</span></tt>.</p>
+</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">LINK_COMPONENTS</span></tt></p>
+<blockquote>
+<div>This variable holds a space separated list of components that the LLVM
+<tt class="docutils literal"><span class="pre">Makefiles</span></tt> pass to the <tt class="docutils literal"><span class="pre">llvm-config</span></tt> tool to generate a link line for
+the program. For example, to link with all LLVM libraries use
+<tt class="docutils literal"><span class="pre">LINK_COMPONENTS</span> <span class="pre">=</span> <span class="pre">all</span></tt>.</div></blockquote>
+<p><tt class="docutils literal"><span class="pre">LIBS</span></tt></p>
+<blockquote>
+<div><p>To link dynamic libraries, add <tt class="docutils literal"><span class="pre">-l<library</span> <span class="pre">base</span> <span class="pre">name></span></tt> to the <tt class="docutils literal"><span class="pre">LIBS</span></tt>
+variable. The LLVM build system will look in the same places for dynamic
+libraries as it does for static libraries.</p>
+<p>For example, to link <tt class="docutils literal"><span class="pre">libsample.so</span></tt>, you would have the following line in
+your <tt class="docutils literal"><span class="pre">Makefile</span></tt>:</p>
+<blockquote>
+<div><div class="highlight-makefile"><div class="highlight"><pre><span class="nv">LIBS</span> <span class="o">+=</span> -lsample
+</pre></div>
+</div>
+</div></blockquote>
+</div></blockquote>
+<p>Note that <tt class="docutils literal"><span class="pre">LIBS</span></tt> must occur in the Makefile after the inclusion of
+<tt class="docutils literal"><span class="pre">Makefile.common</span></tt>.</p>
+</div>
+<div class="section" id="miscellaneous-variables">
+<h3><a class="toc-backref" href="#id9">Miscellaneous Variables</a><a class="headerlink" href="#miscellaneous-variables" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">CFLAGS</span></tt> & <tt class="docutils literal"><span class="pre">CPPFLAGS</span></tt></p>
+<blockquote>
+<div><p>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.</p>
+<p>It is highly suggested that you append to <tt class="docutils literal"><span class="pre">CFLAGS</span></tt> and <tt class="docutils literal"><span class="pre">CPPFLAGS</span></tt> as
+opposed to overwriting them. The master <tt class="docutils literal"><span class="pre">Makefiles</span></tt> may already have
+useful options in them that you may not want to overwrite.</p>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="placement-of-object-code">
+<h2><a class="toc-backref" href="#id10">Placement of Object Code</a><a class="headerlink" href="#placement-of-object-code" title="Permalink to this headline">¶</a></h2>
+<p>The final location of built libraries and executables will depend upon whether
+you do a <tt class="docutils literal"><span class="pre">Debug</span></tt>, <tt class="docutils literal"><span class="pre">Release</span></tt>, or <tt class="docutils literal"><span class="pre">Profile</span></tt> build.</p>
+<p>Libraries</p>
+<blockquote>
+<div>All libraries (static and dynamic) will be stored in
+<tt class="docutils literal"><span class="pre">PROJ_OBJ_ROOT/<type>/lib</span></tt>, where <em>type</em> is <tt class="docutils literal"><span class="pre">Debug</span></tt>, <tt class="docutils literal"><span class="pre">Release</span></tt>, or
+<tt class="docutils literal"><span class="pre">Profile</span></tt> for a debug, optimized, or profiled build, respectively.</div></blockquote>
+<p>Executables</p>
+<blockquote>
+<div>All executables will be stored in <tt class="docutils literal"><span class="pre">PROJ_OBJ_ROOT/<type>/bin</span></tt>, where <em>type</em>
+is <tt class="docutils literal"><span class="pre">Debug</span></tt>, <tt class="docutils literal"><span class="pre">Release</span></tt>, or <tt class="docutils literal"><span class="pre">Profile</span></tt> for a debug, optimized, or
+profiled build, respectively.</div></blockquote>
+</div>
+<div class="section" id="further-help">
+<h2><a class="toc-backref" href="#id11">Further Help</a><a class="headerlink" href="#further-help" title="Permalink to this headline">¶</a></h2>
+<p>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 <a class="reference external" href="http://lists.cs.uiuc.edu/pipermail/llvmdev/">LLVM Developers Mailing List</a>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LLVMBuild.html" title="LLVMBuild Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="MakefileGuide.html" title="LLVM Makefile Guide"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/ReleaseNotes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/ReleaseNotes.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/ReleaseNotes.html (added)
+++ www-releases/trunk/3.3/docs/ReleaseNotes.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,413 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM 3.3 Release Notes — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="LLVMâs Analysis and Transform Passes" href="Passes.html" />
+ <link rel="prev" title="8. Kaleidoscope: Conclusion and other useful LLVM tidbits" href="tutorial/OCamlLangImpl8.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Passes.html" title="LLVMâs Analysis and Transform Passes"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="tutorial/OCamlLangImpl8.html" title="8. Kaleidoscope: Conclusion and other useful LLVM tidbits"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-3-3-release-notes">
+<h1>LLVM 3.3 Release Notes<a class="headerlink" href="#llvm-3-3-release-notes" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
+<li><a class="reference internal" href="#non-comprehensive-list-of-changes-in-this-release" id="id3">Non-comprehensive list of changes in this release</a><ul>
+<li><a class="reference internal" href="#aarch64-target" id="id4">AArch64 target</a></li>
+<li><a class="reference internal" href="#hexagon-target" id="id5">Hexagon Target</a></li>
+<li><a class="reference internal" href="#mips-target" id="id6">Mips target</a></li>
+<li><a class="reference internal" href="#powerpc-target" id="id7">PowerPC Target</a></li>
+<li><a class="reference internal" href="#loop-vectorizer" id="id8">Loop Vectorizer</a></li>
+<li><a class="reference internal" href="#slp-vectorizer" id="id9">SLP Vectorizer</a></li>
+<li><a class="reference internal" href="#r600-backend" id="id10">R600 Backend</a></li>
+<li><a class="reference internal" href="#systemz-s390x-backend" id="id11">SystemZ/s390x Backend</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#sub-project-status-update" id="id12">Sub-project Status Update</a><ul>
+<li><a class="reference internal" href="#dragonegg-gcc-front-ends-llvm-back-end" id="id13">DragonEgg: GCC front-ends, LLVM back-end</a></li>
+<li><a class="reference internal" href="#lldb-low-level-debugger" id="id14">LLDB: Low Level Debugger</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#external-open-source-projects-using-llvm-3-3" id="id15">External Open Source Projects Using LLVM 3.3</a><ul>
+<li><a class="reference internal" href="#portable-computing-language-pocl" id="id16">Portable Computing Language (pocl)</a></li>
+<li><a class="reference internal" href="#tta-based-co-design-environment-tce" id="id17">TTA-based Co-design Environment (TCE)</a></li>
+<li><a class="reference internal" href="#just-in-time-adaptive-decoder-engine-jade" id="id18">Just-in-time Adaptive Decoder Engine (Jade)</a></li>
+<li><a class="reference internal" href="#ldc-the-llvm-based-d-compiler" id="id19">LDC - the LLVM-based D compiler</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#additional-information" id="id20">Additional Information</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains the release notes for the LLVM Compiler Infrastructure,
+release 3.3. 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 <a class="reference external" href="http://llvm.org/releases/">LLVM releases web site</a>.</p>
+<p>For more information about LLVM, including information about the latest
+release, please check out the <a class="reference external" href="http://llvm.org/">main LLVM web site</a>. If you
+have questions or comments, the <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">LLVM Developer’s Mailing List</a> is a good place to send
+them.</p>
+<p>Note that if you are reading this file from a Subversion checkout or the main
+LLVM web page, this document applies to the <em>next</em> release, not the current
+one. To see the release notes for a specific release, please see the <a class="reference external" href="http://llvm.org/releases/">releases
+page</a>.</p>
+</div>
+<div class="section" id="non-comprehensive-list-of-changes-in-this-release">
+<h2><a class="toc-backref" href="#id3">Non-comprehensive list of changes in this release</a><a class="headerlink" href="#non-comprehensive-list-of-changes-in-this-release" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>The CellSPU port has been removed. It can still be found in older versions.</li>
+<li>The IR-level extended linker APIs (for example, to link bitcode files out of
+archives) have been removed. Any existing clients of these features should
+move to using a linker with integrated LTO support.</li>
+<li>LLVM and Clang’s documentation has been migrated to the <a class="reference external" href="http://sphinx-doc.org/">Sphinx</a> documentation generation system which uses
+easy-to-write reStructuredText. See <cite>llvm/docs/README.txt</cite> for more
+information.</li>
+<li>TargetTransformInfo (TTI) is a new interface that can be used by IR-level
+passes to obtain target-specific information, such as the costs of
+instructions. Only “Lowering” passes such as LSR and the vectorizer are
+allowed to use the TTI infrastructure.</li>
+<li>We’ve improved the X86 and ARM cost model.</li>
+<li>The Attributes classes have been completely rewritten and expanded. They now
+support not only enumerated attributes and alignments, but “string”
+attributes, which are useful for passing information to code generation. See
+<a class="reference internal" href="HowToUseAttributes.html"><em>How To Use Attributes</em></a> for more details.</li>
+<li>TableGen’s syntax for instruction selection patterns has been simplified.
+Instead of specifying types indirectly with register classes, you should now
+specify types directly in the input patterns. See <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> for
+examples of the new syntax. The old syntax using register classes still
+works, but it will be removed in a future LLVM release.</li>
+<li>MCJIT now supports exception handling. Support for it in the old jit will be
+removed in the 3.4 release.</li>
+<li>Command line options can now be grouped into categories which are shown in
+the output of <tt class="docutils literal"><span class="pre">-help</span></tt>. See <a class="reference internal" href="CommandLine.html#grouping-options-into-categories"><em>Grouping options into categories</em></a>.</li>
+<li>The appearance of command line options in <tt class="docutils literal"><span class="pre">-help</span></tt> that are inherited by
+linking with libraries that use the LLVM Command line support library can now
+be modified at runtime. See <a class="reference internal" href="CommandLine.html#cl-getregisteredoptions"><em>The cl::getRegisteredOptions function</em></a>.</li>
+</ul>
+<div class="section" id="aarch64-target">
+<h3><a class="toc-backref" href="#id4">AArch64 target</a><a class="headerlink" href="#aarch64-target" title="Permalink to this headline">¶</a></h3>
+<p>We’ve added support for AArch64, ARM’s 64-bit architecture. Development is still
+in fairly early stages, but we expect successful compilation when:</p>
+<ul class="simple">
+<li>compiling standard compliant C99 and C++03 with Clang;</li>
+<li>using Linux as a target platform;</li>
+<li>where code + static data doesn’t exceed 4GB in size (heap allocated data has
+no limitation).</li>
+</ul>
+<p>Some additional functionality is also implemented, notably DWARF debugging,
+GNU-style thread local storage and inline assembly.</p>
+</div>
+<div class="section" id="hexagon-target">
+<h3><a class="toc-backref" href="#id5">Hexagon Target</a><a class="headerlink" href="#hexagon-target" title="Permalink to this headline">¶</a></h3>
+<p>Removed support for legacy hexagonv2 and hexagonv3 processor architectures which
+are no longer in use. Currently supported architectures are hexagonv4 and
+hexagonv5.</p>
+</div>
+<div class="section" id="mips-target">
+<h3><a class="toc-backref" href="#id6">Mips target</a><a class="headerlink" href="#mips-target" title="Permalink to this headline">¶</a></h3>
+<p>New features and improvements:</p>
+<ul class="simple">
+<li>Clang driver</li>
+</ul>
+<blockquote>
+<div><ul class="simple">
+<li>Support for Sourcery CodeBench Mips toolchain directories tree.</li>
+<li>Support for new command line options including:</li>
+</ul>
+<blockquote>
+<div><ul class="simple">
+<li>-mxgot/-mno-xgot</li>
+<li>-EL / -EB</li>
+<li>-mmicromips / -mno-micromips</li>
+<li>-msingle-float / -mdouble-float</li>
+<li>-mabi=32 (o32 abi) and -mabi=64 (n64 abi)</li>
+</ul>
+</div></blockquote>
+<ul class="simple">
+<li>Previously, options such as -mips16, -mmicromips, -mdsp and -mdspr2 were
+not passed to the assembler. This issue has been fixed.</li>
+</ul>
+</div></blockquote>
+<ul class="simple">
+<li>A number of changes have been made to improve the quality of DSP-ASE code
+generation.</li>
+</ul>
+<blockquote>
+<div><ul class="simple">
+<li>Multiply and multiply-accumulate instructions can now use all four
+accumulators.</li>
+<li>Instruction selection patterns have been added so that DSP instructions
+are emitted without having to use builtins.</li>
+</ul>
+</div></blockquote>
+<ul class="simple">
+<li>Delay slot filler pass can now search successor blocks for instructions to
+fill delay slots (use option -disable-mips-df-succbb-search=false).</li>
+</ul>
+</div>
+<div class="section" id="powerpc-target">
+<h3><a class="toc-backref" href="#id7">PowerPC Target</a><a class="headerlink" href="#powerpc-target" title="Permalink to this headline">¶</a></h3>
+<p>New features and improvements:</p>
+<ul class="simple">
+<li>PowerPC now supports an assembly parser.</li>
+<li>Support added for thread-local storage. 64-bit ELF subtarget only.</li>
+<li>Support added for medium and large code model (-mcmodel=medium,large).
+Medium code model is now the default. 64-bit ELF subtarget only.</li>
+<li>Improved register allocation (fewer reserved registers).</li>
+<li>64-bit atomic load and store are now supported.</li>
+<li>Improved code generation for unaligned memory accesses of scalar types.</li>
+<li>Improved performance of floating-point divide and square root
+with -ffast-math.</li>
+<li>Support for predicated returns.</li>
+<li>Improved code generation for comparisons.</li>
+<li>Support added for inline setjmp and longjmp.</li>
+<li>Support added for many instructions introduced in PowerISA 2.04, 2.05,
+and 2.06.</li>
+<li>Improved spill code for vector registers.</li>
+<li>Support added for -mno-altivec.</li>
+<li>ABI compatibility fixes for complex parameters, 128-bit integer parameters,
+and varargs functions. 64-bit ELF subtarget only.</li>
+</ul>
+</div>
+<div class="section" id="loop-vectorizer">
+<h3><a class="toc-backref" href="#id8">Loop Vectorizer</a><a class="headerlink" href="#loop-vectorizer" title="Permalink to this headline">¶</a></h3>
+<p>We’ve continued the work on the loop vectorizer. The loop vectorizer now
+has the following features:</p>
+<ul class="simple">
+<li>Loops with unknown trip counts.</li>
+<li>Runtime checks of pointers.</li>
+<li>Reductions, Inductions.</li>
+<li>Min/Max reductions of integers.</li>
+<li>If Conversion.</li>
+<li>Pointer induction variables.</li>
+<li>Reverse iterators.</li>
+<li>Vectorization of mixed types.</li>
+<li>Vectorization of function calls.</li>
+<li>Partial unrolling during vectorization.</li>
+</ul>
+<p>The loop vectorizer is now enabled by default for -O3.</p>
+</div>
+<div class="section" id="slp-vectorizer">
+<h3><a class="toc-backref" href="#id9">SLP Vectorizer</a><a class="headerlink" href="#slp-vectorizer" title="Permalink to this headline">¶</a></h3>
+<p>LLVM now has a new SLP vectorizer. The new SLP vectorizer is not enabled by
+default but can be enabled using the clang flag <tt class="docutils literal"><span class="pre">-fslp-vectorize</span></tt>. The
+BB-vectorizer can also be enabled using the command line flag
+<tt class="docutils literal"><span class="pre">-fslp-vectorize-aggressive</span></tt>.</p>
+</div>
+<div class="section" id="r600-backend">
+<h3><a class="toc-backref" href="#id10">R600 Backend</a><a class="headerlink" href="#r600-backend" title="Permalink to this headline">¶</a></h3>
+<p>The R600 backend was added in this release, it supports AMD GPUs (HD2XXX -
+HD7XXX). This backend is used in AMD’s Open Source graphics / compute drivers
+which are developed as part of the <a class="reference external" href="http://www.mesa3d.org">Mesa3D</a> project.</p>
+</div>
+<div class="section" id="systemz-s390x-backend">
+<h3><a class="toc-backref" href="#id11">SystemZ/s390x Backend</a><a class="headerlink" href="#systemz-s390x-backend" title="Permalink to this headline">¶</a></h3>
+<p>LLVM and clang now support IBM’s z/Architecture. At present this support
+is restricted to GNU/Linux (GNU triplet s390x-linux-gnu) and requires
+z10 or greater.</p>
+</div>
+</div>
+<div class="section" id="sub-project-status-update">
+<h2><a class="toc-backref" href="#id12">Sub-project Status Update</a><a class="headerlink" href="#sub-project-status-update" title="Permalink to this headline">¶</a></h2>
+<p>In addition to the core LLVM 3.3 distribution of production-quality compiler
+infrastructure, the LLVM project includes sub-projects that use the LLVM core
+and share the same distribution license. This section provides updates on these
+sub-projects.</p>
+<div class="section" id="dragonegg-gcc-front-ends-llvm-back-end">
+<h3><a class="toc-backref" href="#id13">DragonEgg: GCC front-ends, LLVM back-end</a><a class="headerlink" href="#dragonegg-gcc-front-ends-llvm-back-end" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://dragonegg.llvm.org/">DragonEgg</a> is a
+<a class="reference external" href="http://gcc.gnu.org/wiki/plugins">GCC plugin</a> that replaces GCC’s optimizers
+and code generators with LLVM’s. It works with gcc-4.5, 4.6, 4.7 and 4.8, can
+target the x86-32/x86-64 and ARM processor families, and has been successfully
+used on the Darwin, FreeBSD, KFreeBSD, Linux and OpenBSD platforms. It fully
+supports Ada, C, C++ and Fortran. It has partial support for Go, Java, Obj-C
+and Obj-C++. Note that gcc-4.6 is the best supported version, and that Ada in
+particular doesn’t work well with gcc-4.7 and newer.</p>
+<p>The <a class="reference external" href="http://llvm.org/apt/">3.3 release</a> has the following notable changes.</p>
+<ul class="simple">
+<li>supports gcc-4.8 (requires gcc-4.8.1 or newer)</li>
+<li>object files can be written directly using LLVM’s integrated assembler</li>
+<li>produces saner debug info</li>
+<li>bitfields can now contain arbitrary scalar types (useful for Ada)</li>
+</ul>
+</div>
+<div class="section" id="lldb-low-level-debugger">
+<h3><a class="toc-backref" href="#id14">LLDB: Low Level Debugger</a><a class="headerlink" href="#lldb-low-level-debugger" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://lldb.llvm.org/">LLDB</a> is a ground-up implementation of a command-line
+debugger, as well as a debugger API that can be used from scripts and other
+applications. LLDB uses the following components of the LLVM core distribution
+to support the latest language features and target support:</p>
+<ul class="simple">
+<li>the Clang parser for high-quality parsing of C, C++ and Objective C</li>
+<li>the LLVM disassembler</li>
+<li>the LLVM JIT compiler (MCJIT) for expression evaluation</li>
+</ul>
+<p>The <a class="reference external" href="http://llvm.org/apt/">3.3 release</a> has the following notable changes.</p>
+<p>Linux Features:</p>
+<ul class="simple">
+<li>Support for watchpoints</li>
+<li>vim integration for lldb commands and program status using a <a class="reference external" href="http://llvm.org/svn/llvm-project/lldb/trunk/utils/vim-lldb/README">vim plug-in</a></li>
+<li>Improved register support including vector registers</li>
+<li>Builds with cmake/ninja/auto-tools/clang 3.3/gcc 4.6</li>
+</ul>
+<p>Linux Improvements:</p>
+<ul class="simple">
+<li>Debugging multi-threaded programs</li>
+<li>Debugging i386 programs</li>
+<li>Process list, attach and fork</li>
+<li>Expression evaluation</li>
+</ul>
+</div>
+</div>
+<div class="section" id="external-open-source-projects-using-llvm-3-3">
+<h2><a class="toc-backref" href="#id15">External Open Source Projects Using LLVM 3.3</a><a class="headerlink" href="#external-open-source-projects-using-llvm-3-3" title="Permalink to this headline">¶</a></h2>
+<p>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.3.</p>
+<div class="section" id="portable-computing-language-pocl">
+<h3><a class="toc-backref" href="#id16">Portable Computing Language (pocl)</a><a class="headerlink" href="#portable-computing-language-pocl" title="Permalink to this headline">¶</a></h3>
+<p>In addition to producing an easily portable open source OpenCL implementation,
+another major goal of <a class="reference external" href="http://pocl.sourceforge.net/">pocl</a> 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.</p>
+</div>
+<div class="section" id="tta-based-co-design-environment-tce">
+<h3><a class="toc-backref" href="#id17">TTA-based Co-design Environment (TCE)</a><a class="headerlink" href="#tta-based-co-design-environment-tce" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://tce.cs.tut.fi/">TCE</a> is a toolset for designing new 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.</p>
+<p>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 TTA processors and loads them in
+to the compiler backend as runtime libraries to avoid per-target recompilation
+of larger parts of the compiler chain.</p>
+</div>
+<div class="section" id="just-in-time-adaptive-decoder-engine-jade">
+<h3><a class="toc-backref" href="#id18">Just-in-time Adaptive Decoder Engine (Jade)</a><a class="headerlink" href="#just-in-time-adaptive-decoder-engine-jade" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/orcc/jade">Jade</a> (Just-in-time Adaptive Decoder Engine) is
+a generic video decoder engine using LLVM for just-in-time compilation of video
+decoder configurations. Those configurations are designed by MPEG Reconfigurable
+Video Coding (RVC) committee. MPEG RVC standard is built on a stream-based
+dataflow representation of decoders. It is composed of a standard library of
+coding tools written in RVC-CAL language and a dataflow configuration — block
+diagram — of a decoder.</p>
+<p>Jade project is hosted as part of the Open RVC-CAL Compiler (<a class="reference external" href="http://orcc.sf.net">Orcc</a>) and requires it to translate the RVC-CAL standard
+library of video coding tools into an LLVM assembly code.</p>
+</div>
+<div class="section" id="ldc-the-llvm-based-d-compiler">
+<h3><a class="toc-backref" href="#id19">LDC - the LLVM-based D compiler</a><a class="headerlink" href="#ldc-the-llvm-based-d-compiler" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://dlang.org">D</a> 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.</p>
+<p><a class="reference external" href="http://wiki.dlang.org/LDC">LDC</a> 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 and Windows and also Linux/PPC64. Ports to
+other architectures like ARM are underway.</p>
+</div>
+</div>
+<div class="section" id="additional-information">
+<h2><a class="toc-backref" href="#id20">Additional Information</a><a class="headerlink" href="#additional-information" title="Permalink to this headline">¶</a></h2>
+<p>A wide variety of additional information is available on the <a class="reference external" href="http://llvm.org/">LLVM web page</a>, in particular in the <a class="reference external" href="http://llvm.org/docs/">documentation</a> 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 <tt class="docutils literal"><span class="pre">llvm/docs/</span></tt> directory in the LLVM tree.</p>
+<p>If you have any questions or comments about LLVM, please feel free to contact
+us via the <a class="reference external" href="http://llvm.org/docs/#maillist">mailing lists</a>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Passes.html" title="LLVMâs Analysis and Transform Passes"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="tutorial/OCamlLangImpl8.html" title="8. Kaleidoscope: Conclusion and other useful LLVM tidbits"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/SegmentedStacks.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/SegmentedStacks.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/SegmentedStacks.html (added)
+++ www-releases/trunk/3.3/docs/SegmentedStacks.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,169 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Segmented Stacks in LLVM — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="TableGen Fundamentals" href="TableGenFundamentals.html" />
+ <link rel="prev" title="LLVM Link Time Optimization: Design and Implementation" href="LinkTimeOptimization.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="TableGenFundamentals.html" title="TableGen Fundamentals"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="segmented-stacks-in-llvm">
+<h1>Segmented Stacks in LLVM<a class="headerlink" href="#segmented-stacks-in-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id2">Introduction</a></li>
+<li><a class="reference internal" href="#implementation-details" id="id3">Implementation Details</a><ul>
+<li><a class="reference internal" href="#allocating-stacklets" id="id4">Allocating Stacklets</a></li>
+<li><a class="reference internal" href="#variable-sized-allocas" id="id5">Variable Sized Allocas</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>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 <em>stacklets</em>) 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. When using <tt class="docutils literal"><span class="pre">llc</span></tt>,
+segmented stacks can be enabled by adding <tt class="docutils literal"><span class="pre">-segmented-stacks</span></tt> to the command
+line.</p>
+<p>The runtime functionality is <a class="reference external" href="http://gcc.gnu.org/wiki/SplitStacks">already there in libgcc</a>.</p>
+</div>
+<div class="section" id="implementation-details">
+<h2><a class="toc-backref" href="#id3">Implementation Details</a><a class="headerlink" href="#implementation-details" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="allocating-stacklets">
+<span id="id1"></span><h3><a class="toc-backref" href="#id4">Allocating Stacklets</a><a class="headerlink" href="#allocating-stacklets" title="Permalink to this headline">¶</a></h3>
+<p>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 <tt class="docutils literal"><span class="pre">libgcc</span></tt>. The generated
+assembly looks like this on x86-64:</p>
+<div class="highlight-nasm"><pre> 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</pre>
+</div>
+<p>The size of function arguments on the stack needs to be passed to
+<tt class="docutils literal"><span class="pre">__morestack</span></tt> (this function is implemented in <tt class="docutils literal"><span class="pre">libgcc</span></tt>) 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.</p>
+<p>The unusual <tt class="docutils literal"><span class="pre">ret</span></tt> is needed to have the function which made a call to
+<tt class="docutils literal"><span class="pre">__morestack</span></tt> return correctly. <tt class="docutils literal"><span class="pre">__morestack</span></tt>, instead of returning, calls
+into <tt class="docutils literal"><span class="pre">.LBB0_2</span></tt>. This is possible since both, the size of the <tt class="docutils literal"><span class="pre">ret</span></tt>
+instruction and the PC of call to <tt class="docutils literal"><span class="pre">__morestack</span></tt> are known. When the function
+body returns, control is transferred back to <tt class="docutils literal"><span class="pre">__morestack</span></tt>. <tt class="docutils literal"><span class="pre">__morestack</span></tt>
+then de-allocates the new stacklet, restores the correct SP value, and does a
+second return, which returns control to the correct caller.</p>
+</div>
+<div class="section" id="variable-sized-allocas">
+<h3><a class="toc-backref" href="#id5">Variable Sized Allocas</a><a class="headerlink" href="#variable-sized-allocas" title="Permalink to this headline">¶</a></h3>
+<p>The section on <a class="reference internal" href="#allocating-stacklets">allocating stacklets</a> automatically assumes that every stack
+frame will be of fixed size. However, LLVM allows the use of the <tt class="docutils literal"><span class="pre">llvm.alloca</span></tt>
+intrinsic to allocate dynamically sized blocks of memory on the stack. When
+faced with such a variable-sized alloca, code is generated to:</p>
+<ul class="simple">
+<li>Check if the current stacklet has enough space. If yes, just bump the SP, like
+in the normal case.</li>
+<li>If not, generate a call to <tt class="docutils literal"><span class="pre">libgcc</span></tt>, which allocates the memory from the
+heap.</li>
+</ul>
+<p>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.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="TableGenFundamentals.html" title="TableGen Fundamentals"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/SourceLevelDebugging.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/SourceLevelDebugging.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/SourceLevelDebugging.html (added)
+++ www-releases/trunk/3.3/docs/SourceLevelDebugging.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,2240 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Source Level Debugging with LLVM — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="Auto-Vectorization in LLVM" href="Vectorizers.html" />
+ <link rel="prev" title="System Library" href="SystemLibrary.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SystemLibrary.html" title="System Library"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="source-level-debugging-with-llvm">
+<h1>Source Level Debugging with LLVM<a class="headerlink" href="#source-level-debugging-with-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id5">Introduction</a><ul>
+<li><a class="reference internal" href="#philosophy-behind-llvm-debugging-information" id="id6">Philosophy behind LLVM debugging information</a></li>
+<li><a class="reference internal" href="#debug-information-consumers" id="id7">Debug information consumers</a></li>
+<li><a class="reference internal" href="#debugging-optimized-code" id="id8">Debugging optimized code</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#debugging-information-format" id="id9">Debugging information format</a><ul>
+<li><a class="reference internal" href="#debug-information-descriptors" id="id10">Debug information descriptors</a><ul>
+<li><a class="reference internal" href="#compile-unit-descriptors" id="id11">Compile unit descriptors</a></li>
+<li><a class="reference internal" href="#file-descriptors" id="id12">File descriptors</a></li>
+<li><a class="reference internal" href="#global-variable-descriptors" id="id13">Global variable descriptors</a></li>
+<li><a class="reference internal" href="#subprogram-descriptors" id="id14">Subprogram descriptors</a></li>
+<li><a class="reference internal" href="#block-descriptors" id="id15">Block descriptors</a></li>
+<li><a class="reference internal" href="#basic-type-descriptors" id="id16">Basic type descriptors</a></li>
+<li><a class="reference internal" href="#derived-type-descriptors" id="id17">Derived type descriptors</a></li>
+<li><a class="reference internal" href="#composite-type-descriptors" id="id18">Composite type descriptors</a></li>
+<li><a class="reference internal" href="#subrange-descriptors" id="id19">Subrange descriptors</a></li>
+<li><a class="reference internal" href="#enumerator-descriptors" id="id20">Enumerator descriptors</a></li>
+<li><a class="reference internal" href="#local-variables" id="id21">Local variables</a></li>
+<li><a class="reference internal" href="#debugger-intrinsic-functions" id="id22">Debugger intrinsic functions</a></li>
+<li><a class="reference internal" href="#llvm-dbg-declare" id="id23"><tt class="docutils literal"><span class="pre">llvm.dbg.declare</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-dbg-value" id="id24"><tt class="docutils literal"><span class="pre">llvm.dbg.value</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#object-lifetimes-and-scoping" id="id25">Object lifetimes and scoping</a></li>
+<li><a class="reference internal" href="#c-c-front-end-specific-debug-information" id="id26">C/C++ front-end specific debug information</a><ul>
+<li><a class="reference internal" href="#c-c-source-file-information" id="id27">C/C++ source file information</a></li>
+<li><a class="reference internal" href="#c-c-global-variable-information" id="id28">C/C++ global variable information</a></li>
+<li><a class="reference internal" href="#c-c-function-information" id="id29">C/C++ function information</a></li>
+<li><a class="reference internal" href="#c-c-basic-types" id="id30">C/C++ basic types</a><ul>
+<li><a class="reference internal" href="#bool" id="id31">bool</a></li>
+<li><a class="reference internal" href="#char" id="id32">char</a></li>
+<li><a class="reference internal" href="#unsigned-char" id="id33">unsigned char</a></li>
+<li><a class="reference internal" href="#short" id="id34">short</a></li>
+<li><a class="reference internal" href="#unsigned-short" id="id35">unsigned short</a></li>
+<li><a class="reference internal" href="#int" id="id36">int</a></li>
+<li><a class="reference internal" href="#unsigned-int" id="id37">unsigned int</a></li>
+<li><a class="reference internal" href="#long-long" id="id38">long long</a></li>
+<li><a class="reference internal" href="#unsigned-long-long" id="id39">unsigned long long</a></li>
+<li><a class="reference internal" href="#float" id="id40">float</a></li>
+<li><a class="reference internal" href="#double" id="id41">double</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#c-c-derived-types" id="id42">C/C++ derived types</a></li>
+<li><a class="reference internal" href="#c-c-struct-union-types" id="id43">C/C++ struct/union types</a></li>
+<li><a class="reference internal" href="#c-c-enumeration-types" id="id44">C/C++ enumeration types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id1" id="id45">Debugging information format</a><ul>
+<li><a class="reference internal" href="#debugging-information-extension-for-objective-c-properties" id="id46">Debugging Information Extension for Objective C Properties</a><ul>
+<li><a class="reference internal" href="#id2" id="id47">Introduction</a></li>
+<li><a class="reference internal" href="#proposal" id="id48">Proposal</a></li>
+<li><a class="reference internal" href="#new-dwarf-tags" id="id49">New DWARF Tags</a></li>
+<li><a class="reference internal" href="#new-dwarf-attributes" id="id50">New DWARF Attributes</a></li>
+<li><a class="reference internal" href="#new-dwarf-constants" id="id51">New DWARF Constants</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#name-accelerator-tables" id="id52">Name Accelerator Tables</a><ul>
+<li><a class="reference internal" href="#id3" id="id53">Introduction</a></li>
+<li><a class="reference internal" href="#hash-tables" id="id54">Hash Tables</a><ul>
+<li><a class="reference internal" href="#standard-hash-tables" id="id55">Standard Hash Tables</a></li>
+<li><a class="reference internal" href="#name-hash-tables" id="id56">Name Hash Tables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#details" id="id57">Details</a><ul>
+<li><a class="reference internal" href="#header-layout" id="id58">Header Layout</a></li>
+<li><a class="reference internal" href="#fixed-lookup" id="id59">Fixed Lookup</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id4" id="id60">Contents</a></li>
+<li><a class="reference internal" href="#language-extensions-and-file-format-changes" id="id61">Language Extensions and File Format Changes</a><ul>
+<li><a class="reference internal" href="#objective-c-extensions" id="id62">Objective-C Extensions</a></li>
+<li><a class="reference internal" href="#mach-o-changes" id="id63">Mach-O Changes</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id5">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is the central repository for all information pertaining to debug
+information in LLVM. It describes the <a class="reference internal" href="#format"><em>actual format that the LLVM debug
+information takes</em></a>, 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.</p>
+<div class="section" id="philosophy-behind-llvm-debugging-information">
+<h3><a class="toc-backref" href="#id6">Philosophy behind LLVM debugging information</a><a class="headerlink" href="#philosophy-behind-llvm-debugging-information" title="Permalink to this headline">¶</a></h3>
+<p>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:</p>
+<ul class="simple">
+<li>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.</li>
+<li>LLVM optimizations should interact in <a class="reference internal" href="#intro-debugopt"><em>well-defined and easily described
+ways</em></a> with the debugging information.</li>
+<li>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.</li>
+<li>Source-level languages are often <strong>widely</strong> 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.</li>
+<li>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.</li>
+</ul>
+<p>The approach used by the LLVM implementation is to use a small set of
+<a class="reference internal" href="#format-common-intrinsics"><em>intrinsic functions</em></a> 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
+<a class="reference internal" href="#ccxx-frontend"><em>implementation-defined format</em></a> (the C/C++ front-end
+currently uses working draft 7 of the <a class="reference external" href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3 standard</a>).</p>
+<p>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.</p>
+</div>
+<div class="section" id="debug-information-consumers">
+<h3><a class="toc-backref" href="#id7">Debug information consumers</a><a class="headerlink" href="#debug-information-consumers" title="Permalink to this headline">¶</a></h3>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+<p>TODO - expound a bit more.</p>
+</div>
+<div class="section" id="debugging-optimized-code">
+<span id="intro-debugopt"></span><h3><a class="toc-backref" href="#id8">Debugging optimized code</a><a class="headerlink" href="#debugging-optimized-code" title="Permalink to this headline">¶</a></h3>
+<p>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:</p>
+<ul class="simple">
+<li>LLVM debug information <strong>always provides information to accurately read
+the source-level state of the program</strong>, 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.</li>
+<li>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.</li>
+<li>LLVM debug information does not prevent optimizations from
+happening (for example inlining, basic block reordering/merging/cleanup,
+tail duplication, etc).</li>
+<li>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.</li>
+</ul>
+<p>Basically, the debug information allows you to compile a program with
+“<tt class="docutils literal"><span class="pre">-O0</span> <span class="pre">-g</span></tt>” and get full debug information, allowing you to arbitrarily modify
+the program as it executes from a debugger. Compiling a program with
+“<tt class="docutils literal"><span class="pre">-O3</span> <span class="pre">-g</span></tt>” 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.</p>
+<p><a class="reference internal" href="TestingGuide.html#test-suite-quickstart"><em>LLVM test suite</em></a> provides a framework to test
+optimizer’s handling of debugging information. It can be run like this:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd </span>llvm/projects/test-suite/MultiSource/Benchmarks <span class="c"># or some other level</span>
+% make <span class="nv">TEST</span><span class="o">=</span>dbgopt
+</pre></div>
+</div>
+<p>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 <a class="reference internal" href="TestingGuide.html"><em>LLVM Testing Infrastructure Guide</em></a> for more information on LLVM test
+infrastructure and how to run various tests.</p>
+</div>
+</div>
+<div class="section" id="debugging-information-format">
+<span id="format"></span><h2><a class="toc-backref" href="#id9">Debugging information format</a><a class="headerlink" href="#debugging-information-format" title="Permalink to this headline">¶</a></h2>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+<p>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 <a class="reference internal" href="#format-files"><em>source files</em></a>, and <a class="reference internal" href="#format-global-variables"><em>program objects</em></a>. These abstract objects are used by a debugger to
+form stack traces, show information about local variables, etc.</p>
+<p>This section of the documentation first describes the representation aspects
+common to any source-language. <a class="reference internal" href="#ccxx-frontend"><em>C/C++ front-end specific debug information</em></a> describes the data layout
+conventions used by the C and C++ front-ends.</p>
+<div class="section" id="debug-information-descriptors">
+<h3><a class="toc-backref" href="#id10">Debug information descriptors</a><a class="headerlink" href="#debug-information-descriptors" title="Permalink to this headline">¶</a></h3>
+<p>In consideration of the complexity and volume of debug information, LLVM
+provides a specification for well formed debug descriptors.</p>
+<p>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 LLVM
+debugging information is versioned, allowing backwards compatibility in the
+case that the core structures need to change in some way. Also, 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 <tt class="docutils literal"><span class="pre">enum</span> <span class="pre">DW_TAG_user_base</span> <span class="pre">=</span> <span class="pre">0x1000</span></tt>.)</p>
+<p>The fields of debug descriptors used internally by LLVM are restricted to only
+the simple data types <tt class="docutils literal"><span class="pre">i32</span></tt>, <tt class="docutils literal"><span class="pre">i1</span></tt>, <tt class="docutils literal"><span class="pre">float</span></tt>, <tt class="docutils literal"><span class="pre">double</span></tt>, <tt class="docutils literal"><span class="pre">mdstring</span></tt> and
+<tt class="docutils literal"><span class="pre">mdnode</span></tt>.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; A tag</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p><a name=”LLVMDebugVersion”>The first field of a descriptor is always an
+<tt class="docutils literal"><span class="pre">i32</span></tt> 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. To
+facilitate versioning of debug information, the tag is augmented with the
+current debug version (<tt class="docutils literal"><span class="pre">LLVMDebugVersion</span> <span class="pre">=</span> <span class="pre">8</span> <span class="pre"><<</span> <span class="pre">16</span></tt> or 0x80000 or
+524288.)</p>
+<p>The details of the various descriptors follow.</p>
+<div class="section" id="compile-unit-descriptors">
+<h4><a class="toc-backref" href="#id11">Compile unit descriptors</a><a class="headerlink" href="#compile-unit-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag = 17 + LLVMDebugVersion (DW_TAG_compile_unit)</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Unused field.</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; DWARF language identifier (ex. DW_LANG_C89)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Source file name</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Source file directory (includes trailing slash)</span>
+ <span class="kt">metadata</span> <span class="c">;; Producer (ex. "4.0.1 LLVM (LLVM research group)")</span>
+ <span class="k">i1</span><span class="p">,</span> <span class="c">;; True if this is a main compile unit.</span>
+ <span class="k">i1</span><span class="p">,</span> <span class="c">;; True if this is optimized.</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="c">;; Runtime version</span>
+ <span class="kt">metadata</span> <span class="c">;; List of enums types</span>
+ <span class="kt">metadata</span> <span class="c">;; List of retained types</span>
+ <span class="kt">metadata</span> <span class="c">;; List of subprograms</span>
+ <span class="kt">metadata</span> <span class="c">;; List of global variables</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>These descriptors contain a source language ID for the file (we use the DWARF
+3.0 ID numbers, such as <tt class="docutils literal"><span class="pre">DW_LANG_C89</span></tt>, <tt class="docutils literal"><span class="pre">DW_LANG_C_plus_plus</span></tt>,
+<tt class="docutils literal"><span class="pre">DW_LANG_Cobol74</span></tt>, etc), three strings describing the filename, working
+directory of the compiler, and an identifier string for the compiler that
+produced it.</p>
+<p>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 <tt class="docutils literal"><span class="pre">!llvm.dbg.cu</span></tt>. They
+keep track of subprograms, global variables and type information.</p>
+</div>
+<div class="section" id="file-descriptors">
+<span id="format-files"></span><h4><a class="toc-backref" href="#id12">File descriptors</a><a class="headerlink" href="#file-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag = 41 + LLVMDebugVersion (DW_TAG_file_type)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Source file name</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Source file directory (includes trailing slash)</span>
+ <span class="kt">metadata</span> <span class="c">;; Unused</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>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.</p>
+<p>Each input file is encoded as a separate file descriptor in LLVM debugging
+information output.</p>
+</div>
+<div class="section" id="global-variable-descriptors">
+<span id="format-global-variables"></span><h4><a class="toc-backref" href="#id13">Global variable descriptors</a><a class="headerlink" href="#global-variable-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag = 52 + LLVMDebugVersion (DW_TAG_variable)</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Unused field.</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to context descriptor</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Display name (fully qualified C++ name)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; MIPS linkage name (for C++)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to file where defined</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Line number where defined</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to type descriptor</span>
+ <span class="k">i1</span><span class="p">,</span> <span class="c">;; True if the global is local to compile unit (static)</span>
+ <span class="k">i1</span><span class="p">,</span> <span class="c">;; True if the global is defined in the compile unit (not extern)</span>
+ <span class="p">{}*</span> <span class="c">;; Reference to the global variable</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>These descriptors provide debug information about globals variables. They
+provide details such as name, type and where the variable is defined. All
+global variables are collected inside the named metadata <tt class="docutils literal"><span class="pre">!llvm.dbg.cu</span></tt>.</p>
+</div>
+<div class="section" id="subprogram-descriptors">
+<span id="format-subprograms"></span><h4><a class="toc-backref" href="#id14">Subprogram descriptors</a><a class="headerlink" href="#subprogram-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><pre>!2 = metadata !{
+ i32, ;; Tag = 46 + LLVMDebugVersion (DW_TAG_subprogram)
+ 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)
+ 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 - Artifical, Private, Protected, Explicit, Prototyped.
+ i1, ;; isOptimized
+ Function * , ;; Pointer to 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
+}</pre>
+</div>
+<p>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.</p>
+</div>
+<div class="section" id="block-descriptors">
+<h4><a class="toc-backref" href="#id15">Block descriptors</a><a class="headerlink" href="#block-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!3</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag = 11 + LLVMDebugVersion (DW_TAG_lexical_block)</span>
+ <span class="kt">metadata</span><span class="p">,</span><span class="c">;; Reference to context descriptor</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Column number</span>
+ <span class="kt">metadata</span><span class="p">,</span><span class="c">;; Reference to source file</span>
+ <span class="k">i32</span> <span class="c">;; Unique ID to identify blocks from a template function</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>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.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!3</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag = 11 + LLVMDebugVersion (DW_TAG_lexical_block)</span>
+ <span class="kt">metadata</span> <span class="c">;; Reference to the scope we're annotating with a file change</span>
+ <span class="kt">metadata</span><span class="p">,</span><span class="c">;; Reference to the file the scope is enclosed in.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This descriptor provides a wrapper around a lexical scope to handle file
+changes in the middle of a lexical block.</p>
+</div>
+<div class="section" id="basic-type-descriptors">
+<span id="format-basic-type"></span><h4><a class="toc-backref" href="#id16">Basic type descriptors</a><a class="headerlink" href="#basic-type-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!4</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag = 36 + LLVMDebugVersion (DW_TAG_base_type)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to context</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Name (may be "" for anonymous types)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to file where defined (may be NULL)</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Line number where defined (may be 0)</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Alignment in bits</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="c">;; DWARF type encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>These descriptors define primitive types used in the code. Example <tt class="docutils literal"><span class="pre">int</span></tt>,
+<tt class="docutils literal"><span class="pre">bool</span></tt> and <tt class="docutils literal"><span class="pre">float</span></tt>. 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 <a class="reference internal" href="#format-composite-type"><em>composite type</em></a> (example to keep float doubles on 64 bit boundaries).
+The offset is the bit offset if embedded in a <a class="reference internal" href="#format-composite-type"><em>composite type</em></a>.</p>
+<p>The type encoding provides the details of the type. The values are typically
+one of the following:</p>
+<div class="highlight-llvm"><pre>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</pre>
+</div>
+</div>
+<div class="section" id="derived-type-descriptors">
+<span id="format-derived-type"></span><h4><a class="toc-backref" href="#id17">Derived type descriptors</a><a class="headerlink" href="#derived-type-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!5</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag (see below)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to context</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Name (may be "" for anonymous types)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to file where defined (may be NULL)</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Line number where defined (may be 0)</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Alignment in bits</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Flags to encode attributes, e.g. private</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to type derived from</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; (optional) Name of the Objective C property associated with</span>
+ <span class="c">;; Objective-C an ivar, or the type of which this</span>
+ <span class="c">;; pointer-to-member is pointing to members of.</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; (optional) Name of the Objective C property getter selector.</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; (optional) Name of the Objective C property setter selector.</span>
+ <span class="k">i32</span> <span class="c">;; (optional) Objective C property attributes.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>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:</p>
+<div class="highlight-llvm"><pre>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</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">DW_TAG_member</span></tt> is used to define a member of a <a class="reference internal" href="#format-composite-type"><em>composite type</em></a> or <a class="reference internal" href="#format-subprograms"><em>subprogram</em></a>. The type
+of the member is the <a class="reference internal" href="#format-derived-type"><em>derived type</em></a>.
+<tt class="docutils literal"><span class="pre">DW_TAG_formal_parameter</span></tt> is used to define a member which is a formal
+argument of a subprogram.</p>
+<p><tt class="docutils literal"><span class="pre">DW_TAG_typedef</span></tt> is used to provide a name for the derived type.</p>
+<p><tt class="docutils literal"><span class="pre">DW_TAG_pointer_type</span></tt>, <tt class="docutils literal"><span class="pre">DW_TAG_reference_type</span></tt>, <tt class="docutils literal"><span class="pre">DW_TAG_const_type</span></tt>,
+<tt class="docutils literal"><span class="pre">DW_TAG_volatile_type</span></tt> and <tt class="docutils literal"><span class="pre">DW_TAG_restrict_type</span></tt> are used to qualify the
+<a class="reference internal" href="#format-derived-type"><em>derived type</em></a>.</p>
+<p><a class="reference internal" href="#format-derived-type"><em>Derived type</em></a> 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 <a class="reference internal" href="#format-composite-type"><em>composite type</em></a> (example to keep
+float doubles on 64 bit boundaries.) The offset is the bit offset if embedded
+in a <a class="reference internal" href="#format-composite-type"><em>composite type</em></a>.</p>
+<p>Note that the <tt class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></tt> type is expressed as a type derived from NULL.</p>
+</div>
+<div class="section" id="composite-type-descriptors">
+<span id="format-composite-type"></span><h4><a class="toc-backref" href="#id18">Composite type descriptors</a><a class="headerlink" href="#composite-type-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!6</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag (see below)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to context</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Name (may be "" for anonymous types)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to file where defined (may be NULL)</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Line number where defined (may be 0)</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Alignment in bits</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to type derived from</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to array of member descriptors</span>
+ <span class="k">i32</span> <span class="c">;; Runtime languages</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>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:</p>
+<div class="highlight-llvm"><pre>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</pre>
+</div>
+<p>The vector flag indicates that an array type is a native packed vector.</p>
+<p>The members of array types (tag = <tt class="docutils literal"><span class="pre">DW_TAG_array_type</span></tt>) are
+<a class="reference internal" href="#format-subrange"><em>subrange descriptors</em></a>, each
+representing the range of subscripts at that level of indexing.</p>
+<p>The members of enumeration types (tag = <tt class="docutils literal"><span class="pre">DW_TAG_enumeration_type</span></tt>) are
+<a class="reference internal" href="#format-enumerator"><em>enumerator descriptors</em></a>, each representing the
+definition of enumeration value for the set. All enumeration type descriptors
+are collected inside the named metadata <tt class="docutils literal"><span class="pre">!llvm.dbg.cu</span></tt>.</p>
+<p>The members of structure (tag = <tt class="docutils literal"><span class="pre">DW_TAG_structure_type</span></tt>) or union (tag =
+<tt class="docutils literal"><span class="pre">DW_TAG_union_type</span></tt>) types are any one of the <a class="reference internal" href="#format-basic-type"><em>basic</em></a>, <a class="reference internal" href="#format-derived-type"><em>derived</em></a> or <a class="reference internal" href="#format-composite-type"><em>composite</em></a> type descriptors, each representing a field member of
+the structure or union.</p>
+<p>For C++ classes (tag = <tt class="docutils literal"><span class="pre">DW_TAG_structure_type</span></tt>), member descriptors provide
+information about base classes, static members and member functions. If a
+member is a <a class="reference internal" href="#format-derived-type"><em>derived type descriptor</em></a> and has a tag
+of <tt class="docutils literal"><span class="pre">DW_TAG_inheritance</span></tt>, then the type represents a base class. If the member
+of is a <a class="reference internal" href="#format-global-variables"><em>global variable descriptor</em></a> then it
+represents a static member. And, if the member is a <a class="reference internal" href="#format-subprograms"><em>subprogram
+descriptor</em></a> then it represents a member function. For
+static members and member functions, <tt class="docutils literal"><span class="pre">getName()</span></tt> returns the members link or
+the C++ mangled name. <tt class="docutils literal"><span class="pre">getDisplayName()</span></tt> the simplied version of the name.</p>
+<p>The first member of subroutine (tag = <tt class="docutils literal"><span class="pre">DW_TAG_subroutine_type</span></tt>) type elements
+is the return type for the subroutine. The remaining elements are the formal
+arguments to the subroutine.</p>
+<p><a class="reference internal" href="#format-composite-type"><em>Composite type</em></a> 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 <a class="reference internal" href="#format-composite-type"><em>composite type</em></a> (as an example, to
+keep float doubles on 64 bit boundaries). The offset is the bit offset if
+embedded in a <a class="reference internal" href="#format-composite-type"><em>composite type</em></a>.</p>
+</div>
+<div class="section" id="subrange-descriptors">
+<span id="format-subrange"></span><h4><a class="toc-backref" href="#id19">Subrange descriptors</a><a class="headerlink" href="#subrange-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!42</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag = 33 + LLVMDebugVersion (DW_TAG_subrange_type)</span>
+ <span class="k">i64</span><span class="p">,</span> <span class="c">;; Low value</span>
+ <span class="k">i64</span> <span class="c">;; High value</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>These descriptors are used to define ranges of array subscripts for an array
+<a class="reference internal" href="#format-composite-type"><em>composite type</em></a>. The low value defines the lower
+bounds typically zero for C/C++. The high value is the upper bounds. Values
+are 64 bit. <tt class="docutils literal"><span class="pre">High</span> <span class="pre">-</span> <span class="pre">Low</span> <span class="pre">+</span> <span class="pre">1</span></tt> is the size of the array. If <tt class="docutils literal"><span class="pre">Low</span> <span class="pre">></span> <span class="pre">High</span></tt>
+the array bounds are not included in generated debugging information.</p>
+</div>
+<div class="section" id="enumerator-descriptors">
+<span id="format-enumerator"></span><h4><a class="toc-backref" href="#id20">Enumerator descriptors</a><a class="headerlink" href="#enumerator-descriptors" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!6</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag = 40 + LLVMDebugVersion (DW_TAG_enumerator)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="k">i64</span> <span class="c">;; Value</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>These descriptors are used to define members of an enumeration <a class="reference internal" href="#format-composite-type"><em>composite
+type</em></a>, it associates the name to the value.</p>
+</div>
+<div class="section" id="local-variables">
+<h4><a class="toc-backref" href="#id21">Local variables</a><a class="headerlink" href="#local-variables" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!7</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; Tag (see below)</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Reference to file where defined</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; 24 bit - Line number where defined</span>
+ <span class="c">;; 8 bit - Argument number. 1 indicates 1st argument.</span>
+ <span class="kt">metadata</span><span class="p">,</span> <span class="c">;; Type descriptor</span>
+ <span class="k">i32</span><span class="p">,</span> <span class="c">;; flags</span>
+ <span class="kt">metadata</span> <span class="c">;; (optional) Reference to inline location</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>These descriptors are used to define variables local to a sub program. The
+value of the tag depends on the usage of the variable:</p>
+<div class="highlight-llvm"><pre>DW_TAG_auto_variable = 256
+DW_TAG_arg_variable = 257</pre>
+</div>
+<p>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.</p>
+<p>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.</p>
+</div>
+<div class="section" id="debugger-intrinsic-functions">
+<span id="format-common-intrinsics"></span><h4><a class="toc-backref" href="#id22">Debugger intrinsic functions</a><a class="headerlink" href="#debugger-intrinsic-functions" title="Permalink to this headline">¶</a></h4>
+<p>LLVM uses several intrinsic functions (name prefixed with “<tt class="docutils literal"><span class="pre">llvm.dbg</span></tt>”) to
+provide debug information at various points in generated code.</p>
+</div>
+<div class="section" id="llvm-dbg-declare">
+<h4><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">llvm.dbg.declare</span></tt></a><a class="headerlink" href="#llvm-dbg-declare" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="nv">%llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span><span class="p">,</span> <span class="kt">metadata</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>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.</p>
+</div>
+<div class="section" id="llvm-dbg-value">
+<h4><a class="toc-backref" href="#id24"><tt class="docutils literal"><span class="pre">llvm.dbg.value</span></tt></a><a class="headerlink" href="#llvm-dbg-value" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="nv">%llvm.dbg.value</span><span class="p">(</span><span class="kt">metadata</span><span class="p">,</span> <span class="k">i64</span><span class="p">,</span> <span class="kt">metadata</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>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.</p>
+</div>
+</div>
+</div>
+<div class="section" id="object-lifetimes-and-scoping">
+<h2><a class="toc-backref" href="#id25">Object lifetimes and scoping</a><a class="headerlink" href="#object-lifetimes-and-scoping" title="Permalink to this headline">¶</a></h2>
+<p>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.</p>
+<p>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:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="mf">1.</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span>
+<span class="mf">2.</span> <span class="kt">int</span> <span class="n">X</span> <span class="o">=</span> <span class="mi">21</span><span class="p">;</span>
+<span class="mf">3.</span> <span class="kt">int</span> <span class="n">Y</span> <span class="o">=</span> <span class="mi">22</span><span class="p">;</span>
+<span class="mf">4.</span> <span class="p">{</span>
+<span class="mf">5.</span> <span class="kt">int</span> <span class="n">Z</span> <span class="o">=</span> <span class="mi">23</span><span class="p">;</span>
+<span class="mf">6.</span> <span class="n">Z</span> <span class="o">=</span> <span class="n">X</span><span class="p">;</span>
+<span class="mf">7.</span> <span class="p">}</span>
+<span class="mf">8.</span> <span class="n">X</span> <span class="o">=</span> <span class="n">Y</span><span class="p">;</span>
+<span class="mf">9.</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Compiled to LLVM, this function would be represented like this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="k">nounwind</span> <span class="k">ssp</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span> <span class="c">; <i32*> [#uses=4]</span>
+ <span class="nv">%Y</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span> <span class="c">; <i32*> [#uses=4]</span>
+ <span class="nv">%Z</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span> <span class="c">; <i32*> [#uses=3]</span>
+ <span class="nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span> <span class="k">to</span> <span class="p">{}*</span> <span class="c">; <{}*> [#uses=1]</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="p">*</span> <span class="nv">%X</span><span class="p">},</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!0</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!7</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="m">21</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!8</span>
+ <span class="nv-Anonymous">%1</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%Y</span> <span class="k">to</span> <span class="p">{}*</span> <span class="c">; <{}*> [#uses=1]</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="p">*</span> <span class="nv">%Y</span><span class="p">},</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!9</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!10</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="m">22</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%Y</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!11</span>
+ <span class="nv-Anonymous">%2</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%Z</span> <span class="k">to</span> <span class="p">{}*</span> <span class="c">; <{}*> [#uses=1]</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="p">*</span> <span class="nv">%Z</span><span class="p">},</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!12</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!14</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="m">23</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%Z</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!15</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!16</span> <span class="c">; <i32> [#uses=1]</span>
+ <span class="nv">%tmp1</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%Y</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!16</span> <span class="c">; <i32> [#uses=1]</span>
+ <span class="nv">%add</span> <span class="p">=</span> <span class="k">add</span> <span class="k">nsw</span> <span class="k">i32</span> <span class="nv">%tmp</span><span class="p">,</span> <span class="nv">%tmp1</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!16</span> <span class="c">; <i32> [#uses=1]</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%add</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%Z</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!16</span>
+ <span class="nv">%tmp2</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%Y</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!17</span> <span class="c">; <i32> [#uses=1]</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%tmp2</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!17</span>
+ <span class="k">ret</span> <span class="kt">void</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!18</span>
+<span class="p">}</span>
+
+<span class="k">declare</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span><span class="p">,</span> <span class="kt">metadata</span><span class="p">)</span> <span class="k">nounwind</span> <span class="k">readnone</span>
+
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">459008</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"X"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!6</span><span class="p">}</span><span class="c">; [ DW_TAG_auto_variable ]</span>
+<span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">458763</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span><span class="p">}</span><span class="c">; [DW_TAG_lexical_block ]</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">458798</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"foo"</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"foo"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv">!"foo"</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!4</span><span class="p">,</span>
+ <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">i1</span> <span class="k">true</span><span class="p">}</span><span class="c">; [DW_TAG_subprogram ]</span>
+<span class="nv-Anonymous">!3</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">458769</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">12</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"foo.c"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv">!"/private/tmp"</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"clang 1.1"</span><span class="p">,</span> <span class="k">i1</span> <span class="k">true</span><span class="p">,</span>
+ <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!""</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">}</span><span class="c">; [DW_TAG_compile_unit ]</span>
+<span class="nv-Anonymous">!4</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">458773</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!""</span><span class="p">,</span> <span class="k">null</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">null</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!5</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">}</span><span class="c">; [DW_TAG_subroutine_type ]</span>
+<span class="nv-Anonymous">!5</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!6</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">458788</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"int"</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">5</span><span class="p">}</span><span class="c">; [DW_TAG_base_type ]</span>
+<span class="nv-Anonymous">!7</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">7</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!8</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">3</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!9</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">459008</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"Y"</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="k">i32</span> <span class="m">3</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!6</span><span class="p">}</span><span class="c">; [ DW_TAG_auto_variable ]</span>
+<span class="nv-Anonymous">!10</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">3</span><span class="p">,</span> <span class="k">i32</span> <span class="m">7</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!11</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">3</span><span class="p">,</span> <span class="k">i32</span> <span class="m">3</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!12</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">459008</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!13</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"Z"</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="k">i32</span> <span class="m">5</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!6</span><span class="p">}</span><span class="c">; [ DW_TAG_auto_variable ]</span>
+<span class="nv-Anonymous">!13</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">458763</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">}</span><span class="c">; [DW_TAG_lexical_block ]</span>
+<span class="nv-Anonymous">!14</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">5</span><span class="p">,</span> <span class="k">i32</span> <span class="m">9</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!13</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!15</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">5</span><span class="p">,</span> <span class="k">i32</span> <span class="m">5</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!13</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!16</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">6</span><span class="p">,</span> <span class="k">i32</span> <span class="m">5</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!13</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!17</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">8</span><span class="p">,</span> <span class="k">i32</span> <span class="m">3</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!18</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">9</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>This example illustrates a few important details about LLVM debugging
+information. In particular, it shows how the <tt class="docutils literal"><span class="pre">llvm.dbg.declare</span></tt> 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.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!0</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!7</span>
+</pre></div>
+</div>
+<p>The first intrinsic <tt class="docutils literal"><span class="pre">%llvm.dbg.declare</span></tt> encodes debugging information for the
+variable <tt class="docutils literal"><span class="pre">X</span></tt>. The metadata <tt class="docutils literal"><span class="pre">!dbg</span> <span class="pre">!7</span></tt> attached to the intrinsic provides
+scope information for the variable <tt class="docutils literal"><span class="pre">X</span></tt>.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!7</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">7</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+<span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">458763</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span><span class="p">}</span><span class="c">; [DW_TAG_lexical_block ]</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">458798</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"foo"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv">!"foo"</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"foo"</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!4</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">i1</span> <span class="k">true</span><span class="p">}</span><span class="c">; [DW_TAG_subprogram ]</span>
+</pre></div>
+</div>
+<p>Here <tt class="docutils literal"><span class="pre">!7</span></tt> 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 <tt class="docutils literal"><span class="pre">!1</span></tt>. <tt class="docutils literal"><span class="pre">!1</span></tt>
+represents a lexical block inside the scope <tt class="docutils literal"><span class="pre">!2</span></tt>, where <tt class="docutils literal"><span class="pre">!2</span></tt> is a
+<a class="reference internal" href="#format-subprograms"><em>subprogram descriptor</em></a>. This way the location
+information attached to the intrinsics indicates that the variable <tt class="docutils literal"><span class="pre">X</span></tt> is
+declared at line number 2 at a function level scope in function <tt class="docutils literal"><span class="pre">foo</span></tt>.</p>
+<p>Now lets take another example.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!12</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!14</span>
+</pre></div>
+</div>
+<p>The second intrinsic <tt class="docutils literal"><span class="pre">%llvm.dbg.declare</span></tt> encodes debugging information for
+variable <tt class="docutils literal"><span class="pre">Z</span></tt>. The metadata <tt class="docutils literal"><span class="pre">!dbg</span> <span class="pre">!14</span></tt> attached to the intrinsic provides
+scope information for the variable <tt class="docutils literal"><span class="pre">Z</span></tt>.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!13</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">458763</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">}</span><span class="c">; [DW_TAG_lexical_block ]</span>
+<span class="nv-Anonymous">!14</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">5</span><span class="p">,</span> <span class="k">i32</span> <span class="m">9</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!13</span><span class="p">,</span> <span class="k">null</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>Here <tt class="docutils literal"><span class="pre">!14</span></tt> indicates that <tt class="docutils literal"><span class="pre">Z</span></tt> is declared at line number 5 and
+column number 9 inside of lexical scope <tt class="docutils literal"><span class="pre">!13</span></tt>. The lexical scope itself
+resides inside of lexical scope <tt class="docutils literal"><span class="pre">!1</span></tt> described above.</p>
+<p>The scope information attached with each instruction provides a straightforward
+way to find instructions covered by a scope.</p>
+</div>
+<div class="section" id="c-c-front-end-specific-debug-information">
+<span id="ccxx-frontend"></span><h2><a class="toc-backref" href="#id26">C/C++ front-end specific debug information</a><a class="headerlink" href="#c-c-front-end-specific-debug-information" title="Permalink to this headline">¶</a></h2>
+<p>The C and C++ front-ends represent information about the program in a format
+that is effectively identical to <a class="reference external" href="http://www.eagercon.com/dwarf/dwarf3std.htm">DWARF 3.0</a> 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.</p>
+<p>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.</p>
+<p>The following sections provide examples of various C/C++ constructs and the
+debug information that would best describe those constructs.</p>
+<div class="section" id="c-c-source-file-information">
+<h3><a class="toc-backref" href="#id27">C/C++ source file information</a><a class="headerlink" href="#c-c-source-file-information" title="Permalink to this headline">¶</a></h3>
+<p>Given the source files <tt class="docutils literal"><span class="pre">MySource.cpp</span></tt> and <tt class="docutils literal"><span class="pre">MyHeader.h</span></tt> located in the
+directory <tt class="docutils literal"><span class="pre">/Users/mine/sources</span></tt>, the following code:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="cp">#include "MyHeader.h"</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>a C/C++ front-end would generate the following descriptors:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="p">...</span>
+<span class="c">;;</span>
+<span class="c">;; Define the compile unit for the main source file "/Users/mine/sources/MySource.cpp".</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524305</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Unused</span>
+ <span class="k">i32</span> <span class="m">4</span><span class="p">,</span> <span class="c">;; Language Id</span>
+ <span class="kt">metadata</span> <span class="nv">!"MySource.cpp"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv">!"/Users/mine/sources"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv">!"4.2.1 (Based on Apple Inc. build 5649) (LLVM build 00)"</span><span class="p">,</span>
+ <span class="k">i1</span> <span class="k">true</span><span class="p">,</span> <span class="c">;; Main Compile Unit</span>
+ <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="c">;; Optimized compile unit</span>
+ <span class="kt">metadata</span> <span class="nv">!""</span><span class="p">,</span> <span class="c">;; Compiler flags</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">}</span> <span class="c">;; Runtime version</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the file for the file "/Users/mine/sources/MySource.cpp".</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524329</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv">!"MySource.cpp"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv">!"/Users/mine/sources"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span> <span class="c">;; Compile unit</span>
+<span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the file for the file "/Users/mine/sources/Myheader.h"</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!3</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524329</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv">!"Myheader.h"</span>
+ <span class="kt">metadata</span> <span class="nv">!"/Users/mine/sources"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span> <span class="c">;; Compile unit</span>
+<span class="p">}</span>
+
+<span class="p">...</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">llvm::Instruction</span></tt> provides easy access to metadata attached with an
+instruction. One can extract line number information encoded in LLVM IR using
+<tt class="docutils literal"><span class="pre">Instruction::getMetadata()</span></tt> and <tt class="docutils literal"><span class="pre">DILocation::getLineNumber()</span></tt>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">MDNode</span> <span class="o">*</span><span class="n">N</span> <span class="o">=</span> <span class="n">I</span><span class="o">-></span><span class="n">getMetadata</span><span class="p">(</span><span class="s">"dbg"</span><span class="p">))</span> <span class="p">{</span> <span class="c1">// Here I is an LLVM instruction</span>
+ <span class="n">DILocation</span> <span class="n">Loc</span><span class="p">(</span><span class="n">N</span><span class="p">);</span> <span class="c1">// DILocation is in DebugInfo.h</span>
+ <span class="kt">unsigned</span> <span class="n">Line</span> <span class="o">=</span> <span class="n">Loc</span><span class="p">.</span><span class="n">getLineNumber</span><span class="p">();</span>
+ <span class="n">StringRef</span> <span class="n">File</span> <span class="o">=</span> <span class="n">Loc</span><span class="p">.</span><span class="n">getFilename</span><span class="p">();</span>
+ <span class="n">StringRef</span> <span class="n">Dir</span> <span class="o">=</span> <span class="n">Loc</span><span class="p">.</span><span class="n">getDirectory</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="c-c-global-variable-information">
+<h3><a class="toc-backref" href="#id28">C/C++ global variable information</a><a class="headerlink" href="#c-c-global-variable-information" title="Permalink to this headline">¶</a></h3>
+<p>Given an integer global variable declared as follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="n">MyGlobal</span> <span class="o">=</span> <span class="mi">100</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>a C/C++ front-end would generate the following descriptors:</p>
+<div class="highlight-llvm"><pre>;;
+;; 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
+} ; [ DW_TAG_compile_unit ]
+
+;; The Array of Global Variables
+!3 = metadata !{
+ metadata !4
+}
+
+!4 = metadata !{
+ metadata !5
+}
+
+;;
+;; Define the global variable itself.
+;;
+!5 = 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
+} ; [ DW_TAG_variable ]
+
+;;
+;; Define the file
+;;
+!6 = metadata !{
+ i32 786473, ;; Tag
+ metadata !"foo.cpp", ;; File
+ metadata !"/Volumes/Data/tmp", ;; Directory
+ null ;; Unused
+} ; [ DW_TAG_file_type ]
+
+;;
+;; Define the type
+;;
+!7 = metadata !{
+ i32 786468, ;; Tag
+ null, ;; Unused
+ metadata !"int", ;; Name
+ null, ;; Unused
+ 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 ]</pre>
+</div>
+</div>
+<div class="section" id="c-c-function-information">
+<h3><a class="toc-backref" href="#id29">C/C++ function information</a><a class="headerlink" href="#c-c-function-information" title="Permalink to this headline">¶</a></h3>
+<p>Given a function declared as follows:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>a C/C++ front-end would generate the following descriptors:</p>
+<div class="highlight-llvm"><pre>;;
+;; Define the anchor for subprograms. Note that the second field of the
+;; anchor is 46, which is the same as the tag for subprograms
+;; (46 = DW_TAG_subprogram.)
+;;
+!6 = metadata !{
+ i32 524334, ;; Tag
+ i32 0, ;; Unused
+ metadata !1, ;; Context
+ metadata !"main", ;; Name
+ metadata !"main", ;; Display name
+ metadata !"main", ;; Linkage name
+ metadata !1, ;; File
+ 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
+}
+;;
+;; Define the subprogram itself.
+;;
+define i32 @main(i32 %argc, i8** %argv) {
+...
+}</pre>
+</div>
+</div>
+<div class="section" id="c-c-basic-types">
+<h3><a class="toc-backref" href="#id30">C/C++ basic types</a><a class="headerlink" href="#c-c-basic-types" title="Permalink to this headline">¶</a></h3>
+<p>The following are the basic type descriptors for C/C++ core types:</p>
+<div class="section" id="bool">
+<h4><a class="toc-backref" href="#id31">bool</a><a class="headerlink" href="#bool" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"bool"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">8</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">8</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">2</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="char">
+<h4><a class="toc-backref" href="#id32">char</a><a class="headerlink" href="#char" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"char"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">8</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">8</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">6</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="unsigned-char">
+<h4><a class="toc-backref" href="#id33">unsigned char</a><a class="headerlink" href="#unsigned-char" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"unsigned char"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">8</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">8</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">8</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="short">
+<h4><a class="toc-backref" href="#id34">short</a><a class="headerlink" href="#short" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"short int"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">16</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">16</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">5</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="unsigned-short">
+<h4><a class="toc-backref" href="#id35">unsigned short</a><a class="headerlink" href="#unsigned-short" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"short unsigned int"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">16</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">16</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">7</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="int">
+<h4><a class="toc-backref" href="#id36">int</a><a class="headerlink" href="#int" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"int"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">5</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="unsigned-int">
+<h4><a class="toc-backref" href="#id37">unsigned int</a><a class="headerlink" href="#unsigned-int" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"unsigned int"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">7</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="long-long">
+<h4><a class="toc-backref" href="#id38">long long</a><a class="headerlink" href="#long-long" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"long long int"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">64</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">64</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">5</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="unsigned-long-long">
+<h4><a class="toc-backref" href="#id39">unsigned long long</a><a class="headerlink" href="#unsigned-long-long" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"long long unsigned int"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">64</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">64</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">7</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="float">
+<h4><a class="toc-backref" href="#id40">float</a><a class="headerlink" href="#float" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"float"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">4</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="double">
+<h4><a class="toc-backref" href="#id41">double</a><a class="headerlink" href="#double" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"double"</span><span class="p">,</span><span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">64</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">64</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">4</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="c-c-derived-types">
+<h3><a class="toc-backref" href="#id42">C/C++ derived types</a><a class="headerlink" href="#c-c-derived-types" title="Permalink to this headline">¶</a></h3>
+<p>Given the following as an example of C/C++ derived type:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">const</span> <span class="kt">int</span> <span class="o">*</span><span class="n">IntPtr</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>a C/C++ front-end would generate the following descriptors:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">;;</span>
+<span class="c">;; Define the typedef "IntPtr".</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524310</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"IntPtr"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Align in bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!4</span> <span class="c">;; Derived From type</span>
+<span class="p">}</span>
+<span class="c">;;</span>
+<span class="c">;; Define the pointer type.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!4</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524303</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!""</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">64</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span> <span class="m">64</span><span class="p">,</span> <span class="c">;; Align in bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!5</span> <span class="c">;; Derived From type</span>
+<span class="p">}</span>
+<span class="c">;;</span>
+<span class="c">;; Define the const type.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!5</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524326</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!""</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!6</span> <span class="c">;; Derived From type</span>
+<span class="p">}</span>
+<span class="c">;;</span>
+<span class="c">;; Define the int type.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!6</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"int"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="m">5</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="c-c-struct-union-types">
+<h3><a class="toc-backref" href="#id43">C/C++ struct/union types</a><a class="headerlink" href="#c-c-struct-union-types" title="Permalink to this headline">¶</a></h3>
+<p>Given the following as an example of C/C++ struct type:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Color</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">Red</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">Green</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">Blue</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>a C/C++ front-end would generate the following descriptors:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">;;</span>
+<span class="c">;; Define basic type for unsigned int.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!5</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524324</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"unsigned int"</span><span class="p">,</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in Bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in Bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in Bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">i32</span> <span class="m">7</span> <span class="c">;; Encoding</span>
+<span class="p">}</span>
+<span class="c">;;</span>
+<span class="c">;; Define composite type for struct Color.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524307</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"Color"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Compile unit</span>
+ <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">96</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">null</span><span class="p">,</span> <span class="c">;; Derived From</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="c">;; Elements</span>
+ <span class="k">i32</span> <span class="m">0</span> <span class="c">;; Runtime Language</span>
+<span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the Red field.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!4</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524301</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"Red"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!5</span> <span class="c">;; Derived From type</span>
+<span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the Green field.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!6</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524301</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"Green"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">3</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!5</span> <span class="c">;; Derived From type</span>
+<span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the Blue field.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!7</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524301</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"Blue"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">4</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in bits</span>
+ <span class="k">i64</span> <span class="m">64</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!5</span> <span class="c">;; Derived From type</span>
+<span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the array of fields used by the composite type Color.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!3</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">metadata</span> <span class="nv-Anonymous">!4</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!6</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!7</span><span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="c-c-enumeration-types">
+<h3><a class="toc-backref" href="#id44">C/C++ enumeration types</a><a class="headerlink" href="#c-c-enumeration-types" title="Permalink to this headline">¶</a></h3>
+<p>Given the following as an example of C/C++ enumeration type:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="n">Trees</span> <span class="p">{</span>
+ <span class="n">Spruce</span> <span class="o">=</span> <span class="mi">100</span><span class="p">,</span>
+ <span class="n">Oak</span> <span class="o">=</span> <span class="mi">200</span><span class="p">,</span>
+ <span class="n">Maple</span> <span class="o">=</span> <span class="mi">300</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>a C/C++ front-end would generate the following descriptors:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">;;</span>
+<span class="c">;; Define composite type for enum Trees</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+ <span class="k">i32</span> <span class="m">524292</span><span class="p">,</span> <span class="c">;; Tag</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; Context</span>
+ <span class="kt">metadata</span> <span class="nv">!"Trees"</span><span class="p">,</span> <span class="c">;; Name</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="c">;; File</span>
+ <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="c">;; Line number</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Size in bits</span>
+ <span class="k">i64</span> <span class="m">32</span><span class="p">,</span> <span class="c">;; Align in bits</span>
+ <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Offset in bits</span>
+ <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="c">;; Flags</span>
+ <span class="k">null</span><span class="p">,</span> <span class="c">;; Derived From type</span>
+ <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="c">;; Elements</span>
+ <span class="k">i32</span> <span class="m">0</span> <span class="c">;; Runtime language</span>
+<span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the array of enumerators used by composite type Trees.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!3</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">metadata</span> <span class="nv-Anonymous">!4</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!5</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!6</span><span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define Spruce enumerator.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!4</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">524328</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"Spruce"</span><span class="p">,</span> <span class="k">i64</span> <span class="m">100</span><span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define Oak enumerator.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!5</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">524328</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"Oak"</span><span class="p">,</span> <span class="k">i64</span> <span class="m">200</span><span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define Maple enumerator.</span>
+<span class="c">;;</span>
+<span class="nv-Anonymous">!6</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">524328</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"Maple"</span><span class="p">,</span> <span class="k">i64</span> <span class="m">300</span><span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="id1">
+<h2><a class="toc-backref" href="#id45">Debugging information format</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="debugging-information-extension-for-objective-c-properties">
+<h3><a class="toc-backref" href="#id46">Debugging Information Extension for Objective C Properties</a><a class="headerlink" href="#debugging-information-extension-for-objective-c-properties" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id2">
+<h4><a class="toc-backref" href="#id47">Introduction</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p>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.</p>
+<p>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.</p>
+</div>
+<div class="section" id="proposal">
+<h4><a class="toc-backref" href="#id48">Proposal</a><a class="headerlink" href="#proposal" title="Permalink to this headline">¶</a></h4>
+<p>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 <tt class="docutils literal"><span class="pre">@interface</span></tt> declaration corresponding to this ivar.</p>
+<p>To facilitate debugging, these properties we will add a new DWARF TAG into the
+<tt class="docutils literal"><span class="pre">DW_TAG_structure_type</span></tt> 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.</p>
+<p>If there is a related ivar, there will also be a DWARF property attribute placed
+in the <tt class="docutils literal"><span class="pre">DW_TAG_member</span></tt> 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 <tt class="docutils literal"><span class="pre">DW_TAG_member</span></tt> for that
+ivar (with the <tt class="docutils literal"><span class="pre">DW_AT_artificial</span></tt> 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.</p>
+<p>The following examples will serve as illustration for our discussion:</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">I1</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">n2</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="k">@property</span> <span class="kt">int</span> <span class="n">p1</span><span class="p">;</span>
+<span class="k">@property</span> <span class="kt">int</span> <span class="n">p2</span><span class="p">;</span>
+<span class="k">@end</span>
+
+<span class="k">@implementation</span> <span class="nc">I1</span>
+<span class="k">@synthesize</span> <span class="n">p1</span><span class="p">;</span>
+<span class="k">@synthesize</span> <span class="n">p2</span> <span class="o">=</span> <span class="n">n2</span><span class="p">;</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>This produces the following DWARF (this is a “pseudo dwarfdump” output):</p>
+<div class="highlight-none"><div class="highlight"><pre>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 ) )
+</pre></div>
+</div>
+<p>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.</p>
+<p>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.</p>
+<p>Developers can decorate a property with attributes which are encoded using
+<tt class="docutils literal"><span class="pre">DW_AT_APPLE_property_attribute</span></tt>.</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@property</span> <span class="p">(</span><span class="n">readonly</span><span class="p">,</span> <span class="n">nonatomic</span><span class="p">)</span> <span class="kt">int</span> <span class="n">pr</span><span class="p">;</span>
+</pre></div>
+</div>
+<div class="highlight-none"><div class="highlight"><pre>TAG_APPLE_property [8]
+ AT_name( "pr" )
+ AT_type ( {0x00000147} (int) )
+ AT_APPLE_property_attribute (DW_APPLE_PROPERTY_readonly, DW_APPLE_PROPERTY_nonatomic)
+</pre></div>
+</div>
+<p>The setter and getter method names are attached to the property using
+<tt class="docutils literal"><span class="pre">DW_AT_APPLE_property_setter</span></tt> and <tt class="docutils literal"><span class="pre">DW_AT_APPLE_property_getter</span></tt> attributes.</p>
+<div class="highlight-objc"><div class="highlight"><pre><span class="k">@interface</span> <span class="nc">I1</span>
+<span class="k">@property</span> <span class="p">(</span><span class="n">setter</span><span class="o">=</span><span class="n">myOwnP3Setter</span><span class="o">:</span><span class="p">)</span> <span class="kt">int</span> <span class="n">p3</span><span class="p">;</span>
+<span class="k">-</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">myOwnP3Setter:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">a</span><span class="p">;</span>
+<span class="k">@end</span>
+
+<span class="k">@implementation</span> <span class="nc">I1</span>
+<span class="k">@synthesize</span> <span class="n">p3</span><span class="p">;</span>
+<span class="k">-</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span><span class="nf">myOwnP3Setter:</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span><span class="nv">a</span><span class="p">{</span> <span class="p">}</span>
+<span class="k">@end</span>
+</pre></div>
+</div>
+<p>The DWARF for this would be:</p>
+<div class="highlight-none"><div class="highlight"><pre>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 )
+</pre></div>
+</div>
+</div>
+<div class="section" id="new-dwarf-tags">
+<h4><a class="toc-backref" href="#id49">New DWARF Tags</a><a class="headerlink" href="#new-dwarf-tags" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils">
+<colgroup>
+<col width="74%" />
+<col width="26%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">TAG</th>
+<th class="head">Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>DW_TAG_APPLE_property</td>
+<td>0x4200</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="new-dwarf-attributes">
+<h4><a class="toc-backref" href="#id50">New DWARF Attributes</a><a class="headerlink" href="#new-dwarf-attributes" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils">
+<colgroup>
+<col width="63%" />
+<col width="16%" />
+<col width="22%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Attribute</th>
+<th class="head">Value</th>
+<th class="head">Classes</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>DW_AT_APPLE_property</td>
+<td>0x3fed</td>
+<td>Reference</td>
+</tr>
+<tr class="row-odd"><td>DW_AT_APPLE_property_getter</td>
+<td>0x3fe9</td>
+<td>String</td>
+</tr>
+<tr class="row-even"><td>DW_AT_APPLE_property_setter</td>
+<td>0x3fea</td>
+<td>String</td>
+</tr>
+<tr class="row-odd"><td>DW_AT_APPLE_property_attribute</td>
+<td>0x3feb</td>
+<td>Constant</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="new-dwarf-constants">
+<h4><a class="toc-backref" href="#id51">New DWARF Constants</a><a class="headerlink" href="#new-dwarf-constants" title="Permalink to this headline">¶</a></h4>
+<table border="1" class="docutils">
+<colgroup>
+<col width="82%" />
+<col width="18%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Name</th>
+<th class="head">Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>DW_AT_APPLE_PROPERTY_readonly</td>
+<td>0x1</td>
+</tr>
+<tr class="row-odd"><td>DW_AT_APPLE_PROPERTY_readwrite</td>
+<td>0x2</td>
+</tr>
+<tr class="row-even"><td>DW_AT_APPLE_PROPERTY_assign</td>
+<td>0x4</td>
+</tr>
+<tr class="row-odd"><td>DW_AT_APPLE_PROPERTY_retain</td>
+<td>0x8</td>
+</tr>
+<tr class="row-even"><td>DW_AT_APPLE_PROPERTY_copy</td>
+<td>0x10</td>
+</tr>
+<tr class="row-odd"><td>DW_AT_APPLE_PROPERTY_nonatomic</td>
+<td>0x20</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="name-accelerator-tables">
+<h3><a class="toc-backref" href="#id52">Name Accelerator Tables</a><a class="headerlink" href="#name-accelerator-tables" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id3">
+<h4><a class="toc-backref" href="#id53">Introduction</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p>The “<tt class="docutils literal"><span class="pre">.debug_pubnames</span></tt>” and “<tt class="docutils literal"><span class="pre">.debug_pubtypes</span></tt>” formats are not what a
+debugger needs. The “<tt class="docutils literal"><span class="pre">pub</span></tt>” 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 “<tt class="docutils literal"><span class="pre">.debug_pubnames</span></tt>”. No static variables or private
+class variables are in the “<tt class="docutils literal"><span class="pre">.debug_pubtypes</span></tt>”. Many compilers add different
+things to these tables, so we can’t rely upon the contents between gcc, icc, or
+clang.</p>
+<p>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 “<tt class="docutils literal"><span class="pre">.debug_pubnames</span></tt>” section is not the simple name
+given by the <tt class="docutils literal"><span class="pre">DW_AT_name</span> <span class="pre">attribute</span></tt> 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
+“<tt class="docutils literal"><span class="pre">a::b::c(int,const</span> <span class="pre">Foo&)</span> <span class="pre">const</span></tt>”, but rather as “<tt class="docutils literal"><span class="pre">c</span></tt>”, “<tt class="docutils literal"><span class="pre">b::c</span></tt>” , or
+“<tt class="docutils literal"><span class="pre">a::b::c</span></tt>”. 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.</p>
+<p>All debuggers currently ignore the “<tt class="docutils literal"><span class="pre">.debug_pubnames</span></tt>” 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.</p>
+<p>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.</p>
+<p>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 “<tt class="docutils literal"><span class="pre">foo</span></tt>” or namespace “<tt class="docutils literal"><span class="pre">bar</span></tt>”, or list items in
+namespace “<tt class="docutils literal"><span class="pre">baz</span></tt>”. 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.</p>
+<p>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:</p>
+<ul class="simple">
+<li>Have a format that can be mapped into memory from disk and used as is</li>
+<li>Lookups should be very fast</li>
+<li>Extensible table format so these tables can be made by many producers</li>
+<li>Contain all of the names needed for typical lookups out of the box</li>
+<li>Strict rules for the contents of tables</li>
+</ul>
+<p>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.</p>
+<p>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.</p>
+<p>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.</p>
+</div>
+<div class="section" id="hash-tables">
+<h4><a class="toc-backref" href="#id54">Hash Tables</a><a class="headerlink" href="#hash-tables" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="standard-hash-tables">
+<h5><a class="toc-backref" href="#id55">Standard Hash Tables</a><a class="headerlink" href="#standard-hash-tables" title="Permalink to this headline">¶</a></h5>
+<p>Typical hash tables have a header, buckets, and each bucket points to the
+bucket contents:</p>
+<div class="highlight-none"><div class="highlight"><pre>.------------.
+| HEADER |
+|------------|
+| BUCKETS |
+|------------|
+| DATA |
+`------------'
+</pre></div>
+</div>
+<p>The BUCKETS are an array of offsets to DATA for each hash:</p>
+<div class="highlight-none"><div class="highlight"><pre>.------------.
+| 0x00001000 | BUCKETS[0]
+| 0x00002000 | BUCKETS[1]
+| 0x00002200 | BUCKETS[2]
+| 0x000034f0 | BUCKETS[3]
+| | ...
+| 0xXXXXXXXX | BUCKETS[n_buckets]
+'------------'
+</pre></div>
+</div>
+<p>So for <tt class="docutils literal"><span class="pre">bucket[3]</span></tt> 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.</p>
+<div class="highlight-none"><div class="highlight"><pre> .------------.
+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
+ `------------'
+</pre></div>
+</div>
+<p>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 “<tt class="docutils literal"><span class="pre">printf</span></tt>” in the table above, we would make a 32 hash
+for “<tt class="docutils literal"><span class="pre">printf</span></tt>”, it might match <tt class="docutils literal"><span class="pre">bucket[3]</span></tt>. 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.</p>
+</div>
+<div class="section" id="name-hash-tables">
+<h5><a class="toc-backref" href="#id56">Name Hash Tables</a><a class="headerlink" href="#name-hash-tables" title="Permalink to this headline">¶</a></h5>
+<p>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:</p>
+<div class="highlight-none"><div class="highlight"><pre>.-------------.
+| HEADER |
+|-------------|
+| BUCKETS |
+|-------------|
+| HASHES |
+|-------------|
+| OFFSETS |
+|-------------|
+| DATA |
+`-------------'
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">BUCKETS</span></tt> in the name tables are an index into the <tt class="docutils literal"><span class="pre">HASHES</span></tt> 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 “<tt class="docutils literal"><span class="pre">n_buckets</span></tt>” buckets, and “<tt class="docutils literal"><span class="pre">n_hashes</span></tt>” unique 32 bit hash
+values, we can clarify the contents of the <tt class="docutils literal"><span class="pre">BUCKETS</span></tt>, <tt class="docutils literal"><span class="pre">HASHES</span></tt> and
+<tt class="docutils literal"><span class="pre">OFFSETS</span></tt> as:</p>
+<div class="highlight-none"><div class="highlight"><pre>.-------------------------.
+| 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 |
+`-------------------------'
+</pre></div>
+</div>
+<p>So taking the exact same data from the standard hash example above we end up
+with:</p>
+<div class="highlight-none"><div class="highlight"><pre> .------------.
+ | 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)
+ `------------'
+</pre></div>
+</div>
+<p>So we still have all of the same data, we just organize it more efficiently for
+debugger lookup. If we repeat the same “<tt class="docutils literal"><span class="pre">printf</span></tt>” lookup from above, we
+would hash “<tt class="docutils literal"><span class="pre">printf</span></tt>” and find it matches <tt class="docutils literal"><span class="pre">BUCKETS[3]</span></tt> by taking the 32 bit
+hash value and modulo it by <tt class="docutils literal"><span class="pre">n_buckets</span></tt>. <tt class="docutils literal"><span class="pre">BUCKETS[3]</span></tt> contains “6” which
+is the index into the <tt class="docutils literal"><span class="pre">HASHES</span></tt> table. We would then compare any consecutive
+32 bit hashes values in the <tt class="docutils literal"><span class="pre">HASHES</span></tt> array as long as the hashes would be in
+<tt class="docutils literal"><span class="pre">BUCKETS[3]</span></tt>. We do this by verifying that each subsequent hash value modulo
+<tt class="docutils literal"><span class="pre">n_buckets</span></tt> is still 3. In the case of a failed lookup we would access the
+memory for <tt class="docutils literal"><span class="pre">BUCKETS[3]</span></tt>, 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.</p>
+<p>The string hash that is used for these lookup tables is the Daniel J.
+Bernstein hash which is also used in the ELF <tt class="docutils literal"><span class="pre">GNU_HASH</span></tt> sections. It is a
+very good hash for all kinds of names in programs with very few hash
+collisions.</p>
+<p>Empty buckets are designated by using an invalid hash index of <tt class="docutils literal"><span class="pre">UINT32_MAX</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="details">
+<h4><a class="toc-backref" href="#id57">Details</a><a class="headerlink" href="#details" title="Permalink to this headline">¶</a></h4>
+<p>These name hash tables are designed to be generic where specializations of the
+table get to define additional data that goes into the header (“<tt class="docutils literal"><span class="pre">HeaderData</span></tt>”),
+how the string value is stored (“<tt class="docutils literal"><span class="pre">KeyType</span></tt>”) and the content of the data for each
+hash value.</p>
+<div class="section" id="header-layout">
+<h5><a class="toc-backref" href="#id58">Header Layout</a><a class="headerlink" href="#header-layout" title="Permalink to this headline">¶</a></h5>
+<p>The header has a fixed part, and the specialized part. The exact format of the
+header is:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Header</span>
+<span class="p">{</span>
+ <span class="kt">uint32_t</span> <span class="n">magic</span><span class="p">;</span> <span class="c1">// 'HASH' magic value to allow endian detection</span>
+ <span class="kt">uint16_t</span> <span class="n">version</span><span class="p">;</span> <span class="c1">// Version number</span>
+ <span class="kt">uint16_t</span> <span class="n">hash_function</span><span class="p">;</span> <span class="c1">// The hash function enumeration that was used</span>
+ <span class="kt">uint32_t</span> <span class="n">bucket_count</span><span class="p">;</span> <span class="c1">// The number of buckets in this hash table</span>
+ <span class="kt">uint32_t</span> <span class="n">hashes_count</span><span class="p">;</span> <span class="c1">// The total number of unique hash values and hash data offsets in this table</span>
+ <span class="kt">uint32_t</span> <span class="n">header_data_len</span><span class="p">;</span> <span class="c1">// The bytes to skip to get to the hash indexes (buckets) for correct alignment</span>
+ <span class="c1">// Specifically the length of the following HeaderData field - this does not</span>
+ <span class="c1">// include the size of the preceding fields</span>
+ <span class="n">HeaderData</span> <span class="n">header_data</span><span class="p">;</span> <span class="c1">// Implementation specific header data</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The header starts with a 32 bit “<tt class="docutils literal"><span class="pre">magic</span></tt>” value which must be <tt class="docutils literal"><span class="pre">'HASH'</span></tt>
+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 “<tt class="docutils literal"><span class="pre">magic</span></tt>” value is followed by a 16 bit
+<tt class="docutils literal"><span class="pre">version</span></tt> number which allows the table to be revised and modified in the
+future. The current version number is 1. <tt class="docutils literal"><span class="pre">hash_function</span></tt> is a <tt class="docutils literal"><span class="pre">uint16_t</span></tt>
+enumeration that specifies which hash function was used to produce this table.
+The current values for the hash function enumerations include:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="n">HashFunctionType</span>
+<span class="p">{</span>
+ <span class="n">eHashFunctionDJB</span> <span class="o">=</span> <span class="mi">0u</span><span class="p">,</span> <span class="c1">// Daniel J Bernstein hash function</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">bucket_count</span></tt> is a 32 bit unsigned integer that represents how many buckets
+are in the <tt class="docutils literal"><span class="pre">BUCKETS</span></tt> array. <tt class="docutils literal"><span class="pre">hashes_count</span></tt> is the number of unique 32 bit
+hash values that are in the <tt class="docutils literal"><span class="pre">HASHES</span></tt> array, and is the same number of offsets
+are contained in the <tt class="docutils literal"><span class="pre">OFFSETS</span></tt> array. <tt class="docutils literal"><span class="pre">header_data_len</span></tt> specifies the size
+in bytes of the <tt class="docutils literal"><span class="pre">HeaderData</span></tt> that is filled in by specialized versions of
+this table.</p>
+</div>
+<div class="section" id="fixed-lookup">
+<h5><a class="toc-backref" href="#id59">Fixed Lookup</a><a class="headerlink" href="#fixed-lookup" title="Permalink to this headline">¶</a></h5>
+<p>The header is followed by the buckets, hashes, offsets, and hash value data.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">FixedTable</span>
+<span class="p">{</span>
+ <span class="kt">uint32_t</span> <span class="n">buckets</span><span class="p">[</span><span class="n">Header</span><span class="p">.</span><span class="n">bucket_count</span><span class="p">];</span> <span class="c1">// An array of hash indexes into the "hashes[]" array below</span>
+ <span class="kt">uint32_t</span> <span class="n">hashes</span> <span class="p">[</span><span class="n">Header</span><span class="p">.</span><span class="n">hashes_count</span><span class="p">];</span> <span class="c1">// Every unique 32 bit hash for the entire table is in this table</span>
+ <span class="kt">uint32_t</span> <span class="n">offsets</span><span class="p">[</span><span class="n">Header</span><span class="p">.</span><span class="n">hashes_count</span><span class="p">];</span> <span class="c1">// An offset that corresponds to each item in the "hashes[]" array above</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">buckets</span></tt> is an array of 32 bit indexes into the <tt class="docutils literal"><span class="pre">hashes</span></tt> array. The
+<tt class="docutils literal"><span class="pre">hashes</span></tt> array contains all of the 32 bit hash values for all names in the
+hash table. Each hash in the <tt class="docutils literal"><span class="pre">hashes</span></tt> table has an offset in the <tt class="docutils literal"><span class="pre">offsets</span></tt>
+array that points to the data for the hash value.</p>
+<p>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.</p>
+<p>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.</p>
+<p>The <tt class="docutils literal"><span class="pre">HeaderData</span></tt> 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:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">enum</span> <span class="n">AtomType</span>
+<span class="p">{</span>
+ <span class="n">eAtomTypeNULL</span> <span class="o">=</span> <span class="mi">0u</span><span class="p">,</span>
+ <span class="n">eAtomTypeDIEOffset</span> <span class="o">=</span> <span class="mi">1u</span><span class="p">,</span> <span class="c1">// DIE offset, check form for encoding</span>
+ <span class="n">eAtomTypeCUOffset</span> <span class="o">=</span> <span class="mi">2u</span><span class="p">,</span> <span class="c1">// DIE offset of the compiler unit header that contains the item in question</span>
+ <span class="n">eAtomTypeTag</span> <span class="o">=</span> <span class="mi">3u</span><span class="p">,</span> <span class="c1">// DW_TAG_xxx value, should be encoded as DW_FORM_data1 (if no tags exceed 255) or DW_FORM_data2</span>
+ <span class="n">eAtomTypeNameFlags</span> <span class="o">=</span> <span class="mi">4u</span><span class="p">,</span> <span class="c1">// Flags from enum NameFlags</span>
+ <span class="n">eAtomTypeTypeFlags</span> <span class="o">=</span> <span class="mi">5u</span><span class="p">,</span> <span class="c1">// Flags from enum TypeFlags</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The enumeration values and their meanings are:</p>
+<div class="highlight-none"><div class="highlight"><pre>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, ...)
+</pre></div>
+</div>
+<p>Then we allow each atom type to define the atom type and how the data for each
+atom type data is encoded:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Atom</span>
+<span class="p">{</span>
+ <span class="kt">uint16_t</span> <span class="n">type</span><span class="p">;</span> <span class="c1">// AtomType enum value</span>
+ <span class="kt">uint16_t</span> <span class="n">form</span><span class="p">;</span> <span class="c1">// DWARF DW_FORM_XXX defines</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">form</span></tt> 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
+<tt class="docutils literal"><span class="pre">DW_FORM_</span></tt> definitions.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">HeaderData</span>
+<span class="p">{</span>
+ <span class="kt">uint32_t</span> <span class="n">die_offset_base</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">atom_count</span><span class="p">;</span>
+ <span class="n">Atoms</span> <span class="n">atoms</span><span class="p">[</span><span class="n">atom_count0</span><span class="p">];</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">HeaderData</span></tt> defines the base DIE offset that should be added to any atoms
+that are encoded using the <tt class="docutils literal"><span class="pre">DW_FORM_ref1</span></tt>, <tt class="docutils literal"><span class="pre">DW_FORM_ref2</span></tt>,
+<tt class="docutils literal"><span class="pre">DW_FORM_ref4</span></tt>, <tt class="docutils literal"><span class="pre">DW_FORM_ref8</span></tt> or <tt class="docutils literal"><span class="pre">DW_FORM_ref_udata</span></tt>. It also defines
+what is contained in each <tt class="docutils literal"><span class="pre">HashData</span></tt> object – <tt class="docutils literal"><span class="pre">Atom.form</span></tt> tells us how large
+each field will be in the <tt class="docutils literal"><span class="pre">HashData</span></tt> and the <tt class="docutils literal"><span class="pre">Atom.type</span></tt> tells us how this data
+should be interpreted.</p>
+<p>For the current implementations of the “<tt class="docutils literal"><span class="pre">.apple_names</span></tt>” (all functions +
+globals), the “<tt class="docutils literal"><span class="pre">.apple_types</span></tt>” (names of all types that are defined), and
+the “<tt class="docutils literal"><span class="pre">.apple_namespaces</span></tt>” (all namespaces), we currently set the <tt class="docutils literal"><span class="pre">Atom</span></tt>
+array to be:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="n">HeaderData</span><span class="p">.</span><span class="n">atom_count</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="n">HeaderData</span><span class="p">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">type</span> <span class="o">=</span> <span class="n">eAtomTypeDIEOffset</span><span class="p">;</span>
+<span class="n">HeaderData</span><span class="p">.</span><span class="n">atoms</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">form</span> <span class="o">=</span> <span class="n">DW_FORM_data4</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>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.</p>
+<p>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.</p>
+<p>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:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">uint32_t</span> <span class="n">str_offset</span>
+<span class="kt">uint32_t</span> <span class="n">hash_data_count</span>
+<span class="n">HashData</span><span class="p">[</span><span class="n">hash_data_count</span><span class="p">]</span>
+</pre></div>
+</div>
+<p>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):</p>
+<div class="highlight-none"><div class="highlight"><pre>.------------.
+| 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)
+`------------'
+</pre></div>
+</div>
+<p>If there are collisions, you will have multiple valid string offsets:</p>
+<div class="highlight-none"><div class="highlight"><pre>.------------.
+| 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)
+`------------'
+</pre></div>
+</div>
+<p>Current testing with real world C++ binaries has shown that there is around 1
+32 bit hash collision per 100,000 name entries.</p>
+</div>
+</div>
+<div class="section" id="id4">
+<h4><a class="toc-backref" href="#id60">Contents</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<p>As we said, we want to strictly define exactly what is included in the
+different tables. For DWARF, we have 3 tables: “<tt class="docutils literal"><span class="pre">.apple_names</span></tt>”,
+“<tt class="docutils literal"><span class="pre">.apple_types</span></tt>”, and “<tt class="docutils literal"><span class="pre">.apple_namespaces</span></tt>”.</p>
+<p>“<tt class="docutils literal"><span class="pre">.apple_names</span></tt>” sections should contain an entry for each DWARF DIE whose
+<tt class="docutils literal"><span class="pre">DW_TAG</span></tt> is a <tt class="docutils literal"><span class="pre">DW_TAG_label</span></tt>, <tt class="docutils literal"><span class="pre">DW_TAG_inlined_subroutine</span></tt>, or
+<tt class="docutils literal"><span class="pre">DW_TAG_subprogram</span></tt> that has address attributes: <tt class="docutils literal"><span class="pre">DW_AT_low_pc</span></tt>,
+<tt class="docutils literal"><span class="pre">DW_AT_high_pc</span></tt>, <tt class="docutils literal"><span class="pre">DW_AT_ranges</span></tt> or <tt class="docutils literal"><span class="pre">DW_AT_entry_pc</span></tt>. It also contains
+<tt class="docutils literal"><span class="pre">DW_TAG_variable</span></tt> DIEs that have a <tt class="docutils literal"><span class="pre">DW_OP_addr</span></tt> 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:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">static</span> <span class="kt">int</span> <span class="n">var</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">f</span> <span class="p">()</span>
+<span class="p">{</span>
+ <span class="k">static</span> <span class="kt">int</span> <span class="n">var</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Both of the static <tt class="docutils literal"><span class="pre">var</span></tt> 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
+<tt class="docutils literal"><span class="pre">DW_AT_MIPS_linkage_name</span></tt> attribute, and the <tt class="docutils literal"><span class="pre">DW_AT_name</span></tt> contains the
+function basename. If global or static variables have a mangled name in a
+<tt class="docutils literal"><span class="pre">DW_AT_MIPS_linkage_name</span></tt> attribute, this should be emitted along with the
+simple name found in the <tt class="docutils literal"><span class="pre">DW_AT_name</span></tt> attribute.</p>
+<p>“<tt class="docutils literal"><span class="pre">.apple_types</span></tt>” sections should contain an entry for each DWARF DIE whose
+tag is one of:</p>
+<ul class="simple">
+<li>DW_TAG_array_type</li>
+<li>DW_TAG_class_type</li>
+<li>DW_TAG_enumeration_type</li>
+<li>DW_TAG_pointer_type</li>
+<li>DW_TAG_reference_type</li>
+<li>DW_TAG_string_type</li>
+<li>DW_TAG_structure_type</li>
+<li>DW_TAG_subroutine_type</li>
+<li>DW_TAG_typedef</li>
+<li>DW_TAG_union_type</li>
+<li>DW_TAG_ptr_to_member_type</li>
+<li>DW_TAG_set_type</li>
+<li>DW_TAG_subrange_type</li>
+<li>DW_TAG_base_type</li>
+<li>DW_TAG_const_type</li>
+<li>DW_TAG_constant</li>
+<li>DW_TAG_file_type</li>
+<li>DW_TAG_namelist</li>
+<li>DW_TAG_packed_type</li>
+<li>DW_TAG_volatile_type</li>
+<li>DW_TAG_restrict_type</li>
+<li>DW_TAG_interface_type</li>
+<li>DW_TAG_unspecified_type</li>
+<li>DW_TAG_shared_type</li>
+</ul>
+<p>Only entries with a <tt class="docutils literal"><span class="pre">DW_AT_name</span></tt> attribute are included, and the entry must
+not be a forward declaration (<tt class="docutils literal"><span class="pre">DW_AT_declaration</span></tt> attribute with a non-zero
+value). For example, using the following code:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main</span> <span class="p">()</span>
+<span class="p">{</span>
+ <span class="kt">int</span> <span class="o">*</span><span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">return</span> <span class="o">*</span><span class="n">b</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>We get a few type DIEs:</p>
+<div class="highlight-none"><div class="highlight"><pre>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 )
+</pre></div>
+</div>
+<p>The DW_TAG_pointer_type is not included because it does not have a <tt class="docutils literal"><span class="pre">DW_AT_name</span></tt>.</p>
+<p>“<tt class="docutils literal"><span class="pre">.apple_namespaces</span></tt>” section should contain all <tt class="docutils literal"><span class="pre">DW_TAG_namespace</span></tt> DIEs.
+If we run into a namespace that has no name this is an anonymous namespace, and
+the name should be output as “<tt class="docutils literal"><span class="pre">(anonymous</span> <span class="pre">namespace)</span></tt>” (without the quotes).
+Why? This matches the output of the <tt class="docutils literal"><span class="pre">abi::cxa_demangle()</span></tt> that is in the
+standard C++ library that demangles mangled names.</p>
+</div>
+<div class="section" id="language-extensions-and-file-format-changes">
+<h4><a class="toc-backref" href="#id61">Language Extensions and File Format Changes</a><a class="headerlink" href="#language-extensions-and-file-format-changes" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="objective-c-extensions">
+<h5><a class="toc-backref" href="#id62">Objective-C Extensions</a><a class="headerlink" href="#objective-c-extensions" title="Permalink to this headline">¶</a></h5>
+<p>“<tt class="docutils literal"><span class="pre">.apple_objc</span></tt>” section should contain all <tt class="docutils literal"><span class="pre">DW_TAG_subprogram</span></tt> 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 “<tt class="docutils literal"><span class="pre">-[NSString(my_additions)</span> <span class="pre">stringWithSpecialString:]</span></tt>”, we would add
+an entry for “<tt class="docutils literal"><span class="pre">NSString</span></tt>” that points to DIE 0x1234, and an entry for
+“<tt class="docutils literal"><span class="pre">NSString(my_additions)</span></tt>” 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 “<tt class="docutils literal"><span class="pre">.debug_names</span></tt>” section.</p>
+<p>In the “<tt class="docutils literal"><span class="pre">.apple_names</span></tt>” section for Objective-C functions, the full name is
+the entire function name with the brackets (“<tt class="docutils literal"><span class="pre">-[NSString</span>
+<span class="pre">stringWithCString:]</span></tt>”) and the basename is the selector only
+(“<tt class="docutils literal"><span class="pre">stringWithCString:</span></tt>”).</p>
+</div>
+<div class="section" id="mach-o-changes">
+<h5><a class="toc-backref" href="#id63">Mach-O Changes</a><a class="headerlink" href="#mach-o-changes" title="Permalink to this headline">¶</a></h5>
+<p>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 <tt class="docutils literal"><span class="pre">__DWARF</span></tt> segment with
+names as follows:</p>
+<ul class="simple">
+<li>“<tt class="docutils literal"><span class="pre">.apple_names</span></tt>” -> “<tt class="docutils literal"><span class="pre">__apple_names</span></tt>“</li>
+<li>“<tt class="docutils literal"><span class="pre">.apple_types</span></tt>” -> “<tt class="docutils literal"><span class="pre">__apple_types</span></tt>“</li>
+<li>“<tt class="docutils literal"><span class="pre">.apple_namespaces</span></tt>” -> “<tt class="docutils literal"><span class="pre">__apple_namespac</span></tt>” (16 character limit)</li>
+<li>“<tt class="docutils literal"><span class="pre">.apple_objc</span></tt>” -> “<tt class="docutils literal"><span class="pre">__apple_objc</span></tt>“</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SystemLibrary.html" title="System Library"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/SphinxQuickstartTemplate.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/SphinxQuickstartTemplate.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/SphinxQuickstartTemplate.html (added)
+++ www-releases/trunk/3.3/docs/SphinxQuickstartTemplate.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,222 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Sphinx Quickstart Template — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="Code Reviews with Phabricator" href="Phabricator.html" />
+ <link rel="prev" title="How to submit an LLVM bug report" href="HowToSubmitABug.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Phabricator.html" title="Code Reviews with Phabricator"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="sphinx-quickstart-template">
+<h1>Sphinx Quickstart Template<a class="headerlink" href="#sphinx-quickstart-template" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction-and-quickstart">
+<h2>Introduction and Quickstart<a class="headerlink" href="#introduction-and-quickstart" title="Permalink to this headline">¶</a></h2>
+<p>This document is meant to get you writing documentation as fast as possible
+even if you have no previous experience with Sphinx. The goal is to take
+someone in the state of “I want to write documentation and get it added to
+LLVM’s docs” and turn that into useful documentation mailed to llvm-commits
+with as little nonsense as possible.</p>
+<p>You can find this document in <tt class="docutils literal"><span class="pre">docs/SphinxQuickstartTemplate.rst</span></tt>. You
+should copy it, open the new file in your text editor, write your docs, and
+then send the new document to llvm-commits for review.</p>
+<p>Focus on <em>content</em>. It is easy to fix the Sphinx (reStructuredText) syntax
+later if necessary, although reStructuredText tries to imitate common
+plain-text conventions so it should be quite natural. A basic knowledge of
+reStructuredText syntax is useful when writing the document, so the last
+~half of this document (starting with <a class="reference internal" href="#example-section">Example Section</a>) gives examples
+which should cover 99% of use cases.</p>
+<p>Let me say that again: focus on <em>content</em>. But if you really need to verify
+Sphinx’s output, see <tt class="docutils literal"><span class="pre">docs/README.txt</span></tt> for information.</p>
+<p>Once you have finished with the content, please send the <tt class="docutils literal"><span class="pre">.rst</span></tt> file to
+llvm-commits for review.</p>
+</div>
+<div class="section" id="guidelines">
+<h2>Guidelines<a class="headerlink" href="#guidelines" title="Permalink to this headline">¶</a></h2>
+<p>Try to answer the following questions in your first section:</p>
+<ol class="arabic simple">
+<li>Why would I want to read this document?</li>
+<li>What should I know to be able to follow along with this document?</li>
+<li>What will I have learned by the end of this document?</li>
+</ol>
+<p>Common names for the first section are <tt class="docutils literal"><span class="pre">Introduction</span></tt>, <tt class="docutils literal"><span class="pre">Overview</span></tt>, or
+<tt class="docutils literal"><span class="pre">Background</span></tt>.</p>
+<p>If possible, make your document a “how to”. Give it a name <tt class="docutils literal"><span class="pre">HowTo*.rst</span></tt>
+like the other “how to” documents. This format is usually the easiest
+for another person to understand and also the most useful.</p>
+<p>You generally should not be writing documentation other than a “how to”
+unless there is already a “how to” about your topic. The reason for this
+is that without a “how to” document to read first, it is difficult for a
+person to understand a more advanced document.</p>
+<p>Focus on content (yes, I had to say it again).</p>
+<p>The rest of this document shows example reStructuredText markup constructs
+that are meant to be read by you in your text editor after you have copied
+this file into a new file for the documentation you are about to write.</p>
+</div>
+<div class="section" id="example-section">
+<h2>Example Section<a class="headerlink" href="#example-section" title="Permalink to this headline">¶</a></h2>
+<p>Your text can be <em>emphasized</em>, <strong>bold</strong>, or <tt class="docutils literal"><span class="pre">monospace</span></tt>.</p>
+<p>Use blank lines to separate paragraphs.</p>
+<p>Headings (like <tt class="docutils literal"><span class="pre">Example</span> <span class="pre">Section</span></tt> just above) give your document its
+structure. Use the same kind of adornments (e.g. <tt class="docutils literal"><span class="pre">======</span></tt> vs. <tt class="docutils literal"><span class="pre">------</span></tt>)
+as are used in this document. The adornment must be the same length as the
+text above it. For Vim users, variations of <tt class="docutils literal"><span class="pre">yypVr=</span></tt> might be handy.</p>
+<div class="section" id="example-subsection">
+<h3>Example Subsection<a class="headerlink" href="#example-subsection" title="Permalink to this headline">¶</a></h3>
+<p>Make a link <a class="reference external" href="http://llvm.org/">like this</a>. There is also a more
+sophisticated syntax which <a class="reference external" href="http://en.wikipedia.org/wiki/LLVM">can be more readable</a> for longer links since
+it disrupts the flow less. You can put the <tt class="docutils literal"><span class="pre">..</span> <span class="pre">_`link</span> <span class="pre">text`:</span> <span class="pre"><URL></span></tt> block
+pretty much anywhere later in the document.</p>
+<p>Lists can be made like this:</p>
+<ol class="arabic simple">
+<li>A list starting with <tt class="docutils literal"><span class="pre">#.</span></tt> will be automatically numbered.</li>
+<li>This is a second list element.<ol class="arabic">
+<li>Use indentation to create nested lists.</li>
+</ol>
+</li>
+</ol>
+<p>You can also use unordered lists.</p>
+<ul class="simple">
+<li>Stuff.<ul>
+<li>Deeper stuff.</li>
+</ul>
+</li>
+<li>More stuff.</li>
+</ul>
+<div class="section" id="example-subsubsection">
+<h4>Example Subsubsection<a class="headerlink" href="#example-subsubsection" title="Permalink to this headline">¶</a></h4>
+<p>You can make blocks of code like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For a shell session, use a <tt class="docutils literal"><span class="pre">console</span></tt> code block (some existing docs use
+<tt class="docutils literal"><span class="pre">bash</span></tt>):</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> <span class="nb">echo</span> <span class="s2">"Goodbye cruel world!"</span>
+<span class="gp">$</span> rm -rf /
+</pre></div>
+</div>
+<p>If you need to show LLVM IR use the <tt class="docutils literal"><span class="pre">llvm</span></tt> code block.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@test1</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Some other common code blocks you might need are <tt class="docutils literal"><span class="pre">c</span></tt>, <tt class="docutils literal"><span class="pre">objc</span></tt>, <tt class="docutils literal"><span class="pre">make</span></tt>,
+and <tt class="docutils literal"><span class="pre">cmake</span></tt>. If you need something beyond that, you can look at the <a class="reference external" href="http://pygments.org/docs/lexers/">full
+list</a> of supported code blocks.</p>
+<p>However, don’t waste time fiddling with syntax highlighting when you could
+be adding meaningful content. When in doubt, show preformatted text
+without any syntax highlighting like this:</p>
+<div class="highlight-python"><pre> .
+ +:.
+ ..:: ::
+ .++:+:: ::+:.:.
+ .:+ :
+ ::.::..:: .+.
+ ..:+ :: :
+......+:. ..
+ :++. .. :
+ .+:::+:: :
+ .. . .+ ::
+ +.: .::+.
+ ...+. .: .
+ .++:..
+ ...</pre>
+</div>
+<div class="section" id="hopefully-you-won-t-need-to-be-this-deep">
+<h5>Hopefully you won’t need to be this deep<a class="headerlink" href="#hopefully-you-won-t-need-to-be-this-deep" title="Permalink to this headline">¶</a></h5>
+<p>If you need to do fancier things than what has been shown in this document,
+you can mail the list or check Sphinx’s <a class="reference external" href="http://sphinx.pocoo.org/rest.html">reStructuredText Primer</a>.</p>
+</div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Phabricator.html" title="Code Reviews with Phabricator"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToSubmitABug.html" title="How to submit an LLVM bug report"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/SystemLibrary.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/SystemLibrary.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/SystemLibrary.html (added)
+++ www-releases/trunk/3.3/docs/SystemLibrary.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,311 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>System Library — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="Source Level Debugging with LLVM" href="SourceLevelDebugging.html" />
+ <link rel="prev" title="LLVMâs Optional Rich Disassembly Output" href="MarkedUpDisassembly.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="system-library">
+<h1>System Library<a class="headerlink" href="#system-library" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="abstract">
+<h2>Abstract<a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>This document provides some details on LLVM’s System Library, located in the
+source at <tt class="docutils literal"><span class="pre">lib/System</span></tt> and <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt>. The library’s purpose is
+to shield LLVM from the differences between operating systems for the few
+services LLVM needs from the operating system. Much of LLVM is written using
+portability features of standard C++. However, in a few areas, system dependent
+facilities are needed and the System Library is the wrapper around those system
+calls.</p>
+<p>By centralizing LLVM’s use of operating system interfaces, we make it possible
+for the LLVM tool chain and runtime libraries to be more easily ported to new
+platforms since (theoretically) only <tt class="docutils literal"><span class="pre">lib/System</span></tt> needs to be ported. This
+library also unclutters the rest of LLVM from #ifdef use and special cases for
+specific operating systems. Such uses are replaced with simple calls to the
+interfaces provided in <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt>.</p>
+<p>Note that the System Library is not intended to be a complete operating system
+wrapper (such as the Adaptive Communications Environment (ACE) or Apache
+Portable Runtime (APR)), but only provides the functionality necessary to
+support LLVM.</p>
+<p>The System Library was written by Reid Spencer who formulated the design based
+on similar work originating from the eXtensible Programming System (XPS).
+Several people helped with the effort; especially, Jeff Cohen and Henrik Bach
+on the Win32 port.</p>
+</div>
+<div class="section" id="keeping-llvm-portable">
+<h2>Keeping LLVM Portable<a class="headerlink" href="#keeping-llvm-portable" title="Permalink to this headline">¶</a></h2>
+<p>In order to keep LLVM portable, LLVM developers should adhere to a set of
+portability rules associated with the System Library. Adherence to these rules
+should help the System Library achieve its goal of shielding LLVM from the
+variations in operating system interfaces and doing so efficiently. The
+following sections define the rules needed to fulfill this objective.</p>
+<div class="section" id="don-t-include-system-headers">
+<h3>Don’t Include System Headers<a class="headerlink" href="#don-t-include-system-headers" title="Permalink to this headline">¶</a></h3>
+<p>Except in <tt class="docutils literal"><span class="pre">lib/System</span></tt>, no LLVM source code should directly <tt class="docutils literal"><span class="pre">#include</span></tt> a
+system header. Care has been taken to remove all such <tt class="docutils literal"><span class="pre">#includes</span></tt> from LLVM
+while <tt class="docutils literal"><span class="pre">lib/System</span></tt> was being developed. Specifically this means that header
+files like “<tt class="docutils literal"><span class="pre">unistd.h</span></tt>”, “<tt class="docutils literal"><span class="pre">windows.h</span></tt>”, “<tt class="docutils literal"><span class="pre">stdio.h</span></tt>”, and “<tt class="docutils literal"><span class="pre">string.h</span></tt>”
+are forbidden to be included by LLVM source code outside the implementation of
+<tt class="docutils literal"><span class="pre">lib/System</span></tt>.</p>
+<p>To obtain system-dependent functionality, existing interfaces to the system
+found in <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt> should be used. If an appropriate interface is
+not available, it should be added to <tt class="docutils literal"><span class="pre">include/llvm/System</span></tt> and implemented in
+<tt class="docutils literal"><span class="pre">lib/System</span></tt> for all supported platforms.</p>
+</div>
+<div class="section" id="don-t-expose-system-headers">
+<h3>Don’t Expose System Headers<a class="headerlink" href="#don-t-expose-system-headers" title="Permalink to this headline">¶</a></h3>
+<p>The System Library must shield LLVM from <strong>all</strong> system headers. To obtain
+system level functionality, LLVM source must <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">"llvm/System/Thing.h"</span></tt>
+and nothing else. This means that <tt class="docutils literal"><span class="pre">Thing.h</span></tt> cannot expose any system header
+files. This protects LLVM from accidentally using system specific functionality
+and only allows it via the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface.</p>
+</div>
+<div class="section" id="use-standard-c-headers">
+<h3>Use Standard C Headers<a class="headerlink" href="#use-standard-c-headers" title="Permalink to this headline">¶</a></h3>
+<p>The <strong>standard</strong> C headers (the ones beginning with “c”) are allowed to be
+exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface. These headers and the things they
+declare are considered to be platform agnostic. LLVM source files may include
+them directly or obtain their inclusion through <tt class="docutils literal"><span class="pre">lib/System</span></tt> interfaces.</p>
+</div>
+<div class="section" id="id1">
+<h3>Use Standard C++ Headers<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>The <strong>standard</strong> C++ headers from the standard C++ library and standard
+template library may be exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface. These
+headers and the things they declare are considered to be platform agnostic.
+LLVM source files may include them or obtain their inclusion through
+<tt class="docutils literal"><span class="pre">lib/System</span></tt> interfaces.</p>
+</div>
+<div class="section" id="high-level-interface">
+<h3>High Level Interface<a class="headerlink" href="#high-level-interface" title="Permalink to this headline">¶</a></h3>
+<p>The entry points specified in the interface of <tt class="docutils literal"><span class="pre">lib/System</span></tt> must be aimed at
+completing some reasonably high level task needed by LLVM. We do not want to
+simply wrap each operating system call. It would be preferable to wrap several
+operating system calls that are always used in conjunction with one another by
+LLVM.</p>
+<p>For example, consider what is needed to execute a program, wait for it to
+complete, and return its result code. On Unix, this involves the following
+operating system calls: <tt class="docutils literal"><span class="pre">getenv</span></tt>, <tt class="docutils literal"><span class="pre">fork</span></tt>, <tt class="docutils literal"><span class="pre">execve</span></tt>, and <tt class="docutils literal"><span class="pre">wait</span></tt>. The
+correct thing for <tt class="docutils literal"><span class="pre">lib/System</span></tt> to provide is a function, say
+<tt class="docutils literal"><span class="pre">ExecuteProgramAndWait</span></tt>, that implements the functionality completely. what
+we don’t want is wrappers for the operating system calls involved.</p>
+<p>There must <strong>not</strong> be a one-to-one relationship between operating system
+calls and the System library’s interface. Any such interface function will be
+suspicious.</p>
+</div>
+<div class="section" id="no-unused-functionality">
+<h3>No Unused Functionality<a class="headerlink" href="#no-unused-functionality" title="Permalink to this headline">¶</a></h3>
+<p>There must be no functionality specified in the interface of <tt class="docutils literal"><span class="pre">lib/System</span></tt>
+that isn’t actually used by LLVM. We’re not writing a general purpose operating
+system wrapper here, just enough to satisfy LLVM’s needs. And, LLVM doesn’t
+need much. This design goal aims to keep the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface small and
+understandable which should foster its actual use and adoption.</p>
+</div>
+<div class="section" id="no-duplicate-implementations">
+<h3>No Duplicate Implementations<a class="headerlink" href="#no-duplicate-implementations" title="Permalink to this headline">¶</a></h3>
+<p>The implementation of a function for a given platform must be written exactly
+once. This implies that it must be possible to apply a function’s
+implementation to multiple operating systems if those operating systems can
+share the same implementation. This rule applies to the set of operating
+systems supported for a given class of operating system (e.g. Unix, Win32).</p>
+</div>
+<div class="section" id="no-virtual-methods">
+<h3>No Virtual Methods<a class="headerlink" href="#no-virtual-methods" title="Permalink to this headline">¶</a></h3>
+<p>The System Library interfaces can be called quite frequently by LLVM. In order
+to make those calls as efficient as possible, we discourage the use of virtual
+methods. There is no need to use inheritance for implementation differences, it
+just adds complexity. The <tt class="docutils literal"><span class="pre">#include</span></tt> mechanism works just fine.</p>
+</div>
+<div class="section" id="no-exposed-functions">
+<h3>No Exposed Functions<a class="headerlink" href="#no-exposed-functions" title="Permalink to this headline">¶</a></h3>
+<p>Any functions defined by system libraries (i.e. not defined by <tt class="docutils literal"><span class="pre">lib/System</span></tt>)
+must not be exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface, even if the header
+file for that function is not exposed. This prevents inadvertent use of system
+specific functionality.</p>
+<p>For example, the <tt class="docutils literal"><span class="pre">stat</span></tt> system call is notorious for having variations in the
+data it provides. <tt class="docutils literal"><span class="pre">lib/System</span></tt> must not declare <tt class="docutils literal"><span class="pre">stat</span></tt> nor allow it to be
+declared. Instead it should provide its own interface to discovering
+information about files and directories. Those interfaces may be implemented in
+terms of <tt class="docutils literal"><span class="pre">stat</span></tt> but that is strictly an implementation detail. The interface
+provided by the System Library must be implemented on all platforms (even those
+without <tt class="docutils literal"><span class="pre">stat</span></tt>).</p>
+</div>
+<div class="section" id="no-exposed-data">
+<h3>No Exposed Data<a class="headerlink" href="#no-exposed-data" title="Permalink to this headline">¶</a></h3>
+<p>Any data defined by system libraries (i.e. not defined by <tt class="docutils literal"><span class="pre">lib/System</span></tt>) must
+not be exposed through the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface, even if the header file
+for that function is not exposed. As with functions, this prevents inadvertent
+use of data that might not exist on all platforms.</p>
+</div>
+<div class="section" id="minimize-soft-errors">
+<h3>Minimize Soft Errors<a class="headerlink" href="#minimize-soft-errors" title="Permalink to this headline">¶</a></h3>
+<p>Operating system interfaces will generally provide error results for every
+little thing that could go wrong. In almost all cases, you can divide these
+error results into two groups: normal/good/soft and abnormal/bad/hard. That is,
+some of the errors are simply information like “file not found”, “insufficient
+privileges”, etc. while other errors are much harder like “out of space”, “bad
+disk sector”, or “system call interrupted”. We’ll call the first group “<em>soft</em>”
+errors and the second group “<em>hard</em>” errors.</p>
+<p><tt class="docutils literal"><span class="pre">lib/System</span></tt> must always attempt to minimize soft errors. This is a design
+requirement because the minimization of soft errors can affect the granularity
+and the nature of the interface. In general, if you find that you’re wanting to
+throw soft errors, you must review the granularity of the interface because it
+is likely you’re trying to implement something that is too low level. The rule
+of thumb is to provide interface functions that <strong>can’t</strong> fail, except when
+faced with hard errors.</p>
+<p>For a trivial example, suppose we wanted to add an “<tt class="docutils literal"><span class="pre">OpenFileForWriting</span></tt>”
+function. For many operating systems, if the file doesn’t exist, attempting to
+open the file will produce an error. However, <tt class="docutils literal"><span class="pre">lib/System</span></tt> should not simply
+throw that error if it occurs because its a soft error. The problem is that the
+interface function, <tt class="docutils literal"><span class="pre">OpenFileForWriting</span></tt> is too low level. It should be
+<tt class="docutils literal"><span class="pre">OpenOrCreateFileForWriting</span></tt>. In the case of the soft “doesn’t exist” error,
+this function would just create it and then open it for writing.</p>
+<p>This design principle needs to be maintained in <tt class="docutils literal"><span class="pre">lib/System</span></tt> because it
+avoids the propagation of soft error handling throughout the rest of LLVM.
+Hard errors will generally just cause a termination for an LLVM tool so don’t
+be bashful about throwing them.</p>
+<p>Rules of thumb:</p>
+<ol class="arabic simple">
+<li>Don’t throw soft errors, only hard errors.</li>
+<li>If you’re tempted to throw a soft error, re-think the interface.</li>
+<li>Handle internally the most common normal/good/soft error conditions
+so the rest of LLVM doesn’t have to.</li>
+</ol>
+</div>
+<div class="section" id="no-throw-specifications">
+<h3>No throw Specifications<a class="headerlink" href="#no-throw-specifications" title="Permalink to this headline">¶</a></h3>
+<p>None of the <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface functions may be declared with C++
+<tt class="docutils literal"><span class="pre">throw()</span></tt> specifications on them. This requirement makes sure that the
+compiler does not insert additional exception handling code into the interface
+functions. This is a performance consideration: <tt class="docutils literal"><span class="pre">lib/System</span></tt> functions are at
+the bottom of many call chains and as such can be frequently called. We need
+them to be as efficient as possible. However, no routines in the system
+library should actually throw exceptions.</p>
+</div>
+<div class="section" id="code-organization">
+<h3>Code Organization<a class="headerlink" href="#code-organization" title="Permalink to this headline">¶</a></h3>
+<p>Implementations of the System Library interface are separated by their general
+class of operating system. Currently only Unix and Win32 classes are defined
+but more could be added for other operating system classifications. To
+distinguish which implementation to compile, the code in <tt class="docutils literal"><span class="pre">lib/System</span></tt> uses
+the <tt class="docutils literal"><span class="pre">LLVM_ON_UNIX</span></tt> and <tt class="docutils literal"><span class="pre">LLVM_ON_WIN32</span></tt> <tt class="docutils literal"><span class="pre">#defines</span></tt> provided via configure
+through the <tt class="docutils literal"><span class="pre">llvm/Config/config.h</span></tt> file. Each source file in <tt class="docutils literal"><span class="pre">lib/System</span></tt>,
+after implementing the generic (operating system independent) functionality
+needs to include the correct implementation using a set of
+<tt class="docutils literal"><span class="pre">#if</span> <span class="pre">defined(LLVM_ON_XYZ)</span></tt> directives. For example, if we had
+<tt class="docutils literal"><span class="pre">lib/System/File.cpp</span></tt>, we’d expect to see in that file:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if defined(LLVM_ON_UNIX)</span>
+<span class="cp">#include "Unix/File.cpp"</span>
+<span class="cp">#endif</span>
+<span class="cp">#if defined(LLVM_ON_WIN32)</span>
+<span class="cp">#include "Win32/File.cpp"</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>The implementation in <tt class="docutils literal"><span class="pre">lib/System/Unix/File.cpp</span></tt> should handle all Unix
+variants. The implementation in <tt class="docutils literal"><span class="pre">lib/System/Win32/File.cpp</span></tt> should handle all
+Win32 variants. What this does is quickly differentiate the basic class of
+operating system that will provide the implementation. The specific details for
+a given platform must still be determined through the use of <tt class="docutils literal"><span class="pre">#ifdef</span></tt>.</p>
+</div>
+<div class="section" id="consistent-semantics">
+<h3>Consistent Semantics<a class="headerlink" href="#consistent-semantics" title="Permalink to this headline">¶</a></h3>
+<p>The implementation of a <tt class="docutils literal"><span class="pre">lib/System</span></tt> interface can vary drastically between
+platforms. That’s okay as long as the end result of the interface function is
+the same. For example, a function to create a directory is pretty straight
+forward on all operating system. System V IPC on the other hand isn’t even
+supported on all platforms. Instead of “supporting” System V IPC,
+<tt class="docutils literal"><span class="pre">lib/System</span></tt> should provide an interface to the basic concept of
+inter-process communications. The implementations might use System V IPC if
+that was available or named pipes, or whatever gets the job done effectively
+for a given operating system. In all cases, the interface and the
+implementation must be semantically consistent.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="MarkedUpDisassembly.html" title="LLVMâs Optional Rich Disassembly Output"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/TableGen/LangRef.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/TableGen/LangRef.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/TableGen/LangRef.html (added)
+++ www-releases/trunk/3.3/docs/TableGen/LangRef.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,432 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Language Reference — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="../index.html" />
+ <link rel="next" title="How To Use Attributes" href="../HowToUseAttributes.html" />
+ <link rel="prev" title="Writing an LLVM Pass" href="../WritingAnLLVMPass.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../HowToUseAttributes.html" title="How To Use Attributes"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-language-reference">
+<h1>TableGen Language Reference<a class="headerlink" href="#tablegen-language-reference" title="Permalink to this headline">¶</a></h1>
+<p><em>Section author: Sean Silva <<a class="reference external" href="mailto:silvas%40purdue.edu">silvas<span>@</span>purdue<span>.</span>edu</a>></em></p>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id10">Introduction</a></li>
+<li><a class="reference internal" href="#notation" id="id11">Notation</a></li>
+<li><a class="reference internal" href="#lexical-analysis" id="id12">Lexical Analysis</a></li>
+<li><a class="reference internal" href="#syntax" id="id13">Syntax</a><ul>
+<li><a class="reference internal" href="#classes" id="id14"><tt class="docutils literal"><span class="pre">class</span></tt>es</a></li>
+<li><a class="reference internal" href="#declarations" id="id15">Declarations</a></li>
+<li><a class="reference internal" href="#types" id="id16">Types</a></li>
+<li><a class="reference internal" href="#values" id="id17">Values</a></li>
+<li><a class="reference internal" href="#bodies" id="id18">Bodies</a></li>
+<li><a class="reference internal" href="#def" id="id19"><tt class="docutils literal"><span class="pre">def</span></tt></a></li>
+<li><a class="reference internal" href="#defm" id="id20"><tt class="docutils literal"><span class="pre">defm</span></tt></a></li>
+<li><a class="reference internal" href="#foreach" id="id21"><tt class="docutils literal"><span class="pre">foreach</span></tt></a></li>
+<li><a class="reference internal" href="#top-level-let" id="id22">Top-Level <tt class="docutils literal"><span class="pre">let</span></tt></a></li>
+<li><a class="reference internal" href="#multiclass" id="id23"><tt class="docutils literal"><span class="pre">multiclass</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document is extremely rough. If you find something lacking, please
+fix it, file a documentation bug, or ask about it on llvmdev.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id10">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is meant to be a normative spec about the TableGen language
+in and of itself (i.e. how to understand a given construct in terms of how
+it affects the final set of records represented by the TableGen file). If
+you are unsure if this document is really what you are looking for, please
+read <a class="reference internal" href="../TableGenFundamentals.html"><em>TableGen Fundamentals</em></a> first.</p>
+</div>
+<div class="section" id="notation">
+<h2><a class="toc-backref" href="#id11">Notation</a><a class="headerlink" href="#notation" title="Permalink to this headline">¶</a></h2>
+<p>The lexical and syntax notation used here is intended to imitate
+<a class="reference external" href="http://docs.python.org/py3k/reference/introduction.html#notation">Python’s</a>. In particular, for lexical definitions, the productions
+operate at the character level and there is no implied whitespace between
+elements. The syntax definitions operate at the token level, so there is
+implied whitespace between tokens.</p>
+</div>
+<div class="section" id="lexical-analysis">
+<h2><a class="toc-backref" href="#id12">Lexical Analysis</a><a class="headerlink" href="#lexical-analysis" title="Permalink to this headline">¶</a></h2>
+<p>TableGen supports BCPL (<tt class="docutils literal"><span class="pre">//</span> <span class="pre">...</span></tt>) and nestable C-style (<tt class="docutils literal"><span class="pre">/*</span> <span class="pre">...</span> <span class="pre">*/</span></tt>)
+comments.</p>
+<p>The following is a listing of the basic punctuation tokens:</p>
+<div class="highlight-python"><pre>- + [ ] { } ( ) < > : ; . = ? #</pre>
+</div>
+<p>Numeric literals take one of the following forms:</p>
+<pre>
+<strong id="grammar-token-TokInteger">TokInteger </strong> ::= <a class="reference internal" href="#grammar-token-DecimalInteger"><tt class="xref docutils literal"><span class="pre">DecimalInteger</span></tt></a> | <a class="reference internal" href="#grammar-token-HexInteger"><tt class="xref docutils literal"><span class="pre">HexInteger</span></tt></a> | <a class="reference internal" href="#grammar-token-BinInteger"><tt class="xref docutils literal"><span class="pre">BinInteger</span></tt></a>
+<strong id="grammar-token-DecimalInteger">DecimalInteger</strong> ::= ["+" | "-"] ("0"..."9")+
+<strong id="grammar-token-HexInteger">HexInteger </strong> ::= "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
+<strong id="grammar-token-BinInteger">BinInteger </strong> ::= "0b" ("0" | "1")+
+</pre>
+<p>One aspect to note is that the <a class="reference internal" href="#grammar-token-DecimalInteger"><tt class="xref std std-token docutils literal"><span class="pre">DecimalInteger</span></tt></a> token <em>includes</em> the
+<tt class="docutils literal"><span class="pre">+</span></tt> or <tt class="docutils literal"><span class="pre">-</span></tt>, as opposed to having <tt class="docutils literal"><span class="pre">+</span></tt> and <tt class="docutils literal"><span class="pre">-</span></tt> be unary operators as
+most languages do.</p>
+<p>TableGen has identifier-like tokens:</p>
+<pre>
+<strong id="grammar-token-ualpha">ualpha </strong> ::= "a"..."z" | "A"..."Z" | "_"
+<strong id="grammar-token-TokIdentifier">TokIdentifier</strong> ::= ("0"..."9")* <a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> (<a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> | "0"..."9")*
+<strong id="grammar-token-TokVarName">TokVarName </strong> ::= "$" <a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> (<a class="reference internal" href="#grammar-token-ualpha"><tt class="xref docutils literal"><span class="pre">ualpha</span></tt></a> | "0"..."9")*
+</pre>
+<p>Note that unlike most languages, TableGen allows <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref std std-token docutils literal"><span class="pre">TokIdentifier</span></tt></a> to
+begin with a number. In case of ambiguity, a token will be interpreted as a
+numeric literal rather than an identifier.</p>
+<p>TableGen also has two string-like literals:</p>
+<pre>
+<strong id="grammar-token-TokString">TokString </strong> ::= '"' <non-'"' characters and C-like escapes> '"'
+<strong id="grammar-token-TokCodeFragment">TokCodeFragment</strong> ::= "[{" <shortest text not containing "}]"> "}]"
+</pre>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>The current implementation accepts the following C-like escapes:</p>
+<div class="last highlight-python"><pre>\\ \' \" \t \n</pre>
+</div>
+</div>
+<p>TableGen also has the following keywords:</p>
+<div class="highlight-python"><pre>bit bits class code dag
+def foreach defm field in
+int let list multiclass string</pre>
+</div>
+<p>TableGen also has “bang operators” which have a
+wide variety of meanings:</p>
+<pre>
+<strong id="grammar-token-BangOperator">BangOperator</strong> ::= one of
+ !eq !if !head !tail !con
+ !add !shl !sra !srl
+ !cast !empty !subst !foreach !strconcat
+</pre>
+</div>
+<div class="section" id="syntax">
+<h2><a class="toc-backref" href="#id13">Syntax</a><a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h2>
+<p>TableGen has an <tt class="docutils literal"><span class="pre">include</span></tt> mechanism. It does not play a role in the
+syntax per se, since it is lexically replaced with the contents of the
+included file.</p>
+<pre>
+<strong id="grammar-token-IncludeDirective">IncludeDirective</strong> ::= "include" <a class="reference internal" href="#grammar-token-TokString"><tt class="xref docutils literal"><span class="pre">TokString</span></tt></a>
+</pre>
+<p>TableGen’s top-level production consists of “objects”.</p>
+<pre>
+<strong id="grammar-token-TableGenFile">TableGenFile</strong> ::= <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>*
+<strong id="grammar-token-Object">Object </strong> ::= <a class="reference internal" href="#grammar-token-Class"><tt class="xref docutils literal"><span class="pre">Class</span></tt></a> | <a class="reference internal" href="#grammar-token-Def"><tt class="xref docutils literal"><span class="pre">Def</span></tt></a> | <a class="reference internal" href="#grammar-token-Defm"><tt class="xref docutils literal"><span class="pre">Defm</span></tt></a> | <a class="reference internal" href="#grammar-token-Let"><tt class="xref docutils literal"><span class="pre">Let</span></tt></a> | <a class="reference internal" href="#grammar-token-MultiClass"><tt class="xref docutils literal"><span class="pre">MultiClass</span></tt></a> | <a class="reference internal" href="#grammar-token-Foreach"><tt class="xref docutils literal"><span class="pre">Foreach</span></tt></a>
+</pre>
+<div class="section" id="classes">
+<h3><a class="toc-backref" href="#id14"><tt class="docutils literal"><span class="pre">class</span></tt>es</a><a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Class">Class</strong> ::= "class" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref docutils literal"><span class="pre">TemplateArgList</span></tt></a>] <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref docutils literal"><span class="pre">ObjectBody</span></tt></a>
+</pre>
+<p>A <tt class="docutils literal"><span class="pre">class</span></tt> declaration creates a record which other records can inherit
+from. A class can be parametrized by a list of “template arguments”, whose
+values can be used in the class body.</p>
+<p>A given class can only be defined once. A <tt class="docutils literal"><span class="pre">class</span></tt> declaration is
+considered to define the class if any of the following is true:</p>
+<ol class="arabic simple">
+<li>The <a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref std std-token docutils literal"><span class="pre">TemplateArgList</span></tt></a> is present.</li>
+<li>The <a class="reference internal" href="#grammar-token-Body"><tt class="xref std std-token docutils literal"><span class="pre">Body</span></tt></a> in the <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref std std-token docutils literal"><span class="pre">ObjectBody</span></tt></a> is present and is not empty.</li>
+<li>The <a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref std std-token docutils literal"><span class="pre">BaseClassList</span></tt></a> in the <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref std std-token docutils literal"><span class="pre">ObjectBody</span></tt></a> is present.</li>
+</ol>
+<p>You can declare an empty class by giving and empty <a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref std std-token docutils literal"><span class="pre">TemplateArgList</span></tt></a>
+and an empty <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref std std-token docutils literal"><span class="pre">ObjectBody</span></tt></a>. This can serve as a restricted form of
+forward declaration: note that records deriving from the forward-declared
+class will inherit no fields from it since the record expansion is done
+when the record is parsed.</p>
+<pre>
+<strong id="grammar-token-TemplateArgList">TemplateArgList</strong> ::= "<" <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> ("," <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a>)* ">"
+</pre>
+</div>
+<div class="section" id="declarations">
+<h3><a class="toc-backref" href="#id15">Declarations</a><a class="headerlink" href="#declarations" title="Permalink to this headline">¶</a></h3>
+<p>The declaration syntax is pretty much what you would expect as a C++
+programmer.</p>
+<pre>
+<strong id="grammar-token-Declaration">Declaration</strong> ::= <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> ["=" <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a>]
+</pre>
+<p>It assigns the value to the identifer.</p>
+</div>
+<div class="section" id="types">
+<h3><a class="toc-backref" href="#id16">Types</a><a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Type">Type </strong> ::= "string" | "code" | "bit" | "int" | "dag"
+ | "bits" "<" <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a> ">"
+ | "list" "<" <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> ">"
+ | <a class="reference internal" href="#grammar-token-ClassID"><tt class="xref docutils literal"><span class="pre">ClassID</span></tt></a>
+<strong id="grammar-token-ClassID">ClassID</strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+</pre>
+<p>Both <tt class="docutils literal"><span class="pre">string</span></tt> and <tt class="docutils literal"><span class="pre">code</span></tt> correspond to the string type; the difference
+is purely to indicate programmer intention.</p>
+<p>The <a class="reference internal" href="#grammar-token-ClassID"><tt class="xref std std-token docutils literal"><span class="pre">ClassID</span></tt></a> must identify a class that has been previously
+declared or defined.</p>
+</div>
+<div class="section" id="values">
+<h3><a class="toc-backref" href="#id17">Values</a><a class="headerlink" href="#values" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Value">Value </strong> ::= <a class="reference internal" href="#grammar-token-SimpleValue"><tt class="xref docutils literal"><span class="pre">SimpleValue</span></tt></a> <a class="reference internal" href="#grammar-token-ValueSuffix"><tt class="xref docutils literal"><span class="pre">ValueSuffix</span></tt></a>*
+<strong id="grammar-token-ValueSuffix">ValueSuffix</strong> ::= "{" <a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a> "}"
+ | "[" <a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a> "]"
+ | "." <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+<strong id="grammar-token-RangeList">RangeList </strong> ::= <a class="reference internal" href="#grammar-token-RangePiece"><tt class="xref docutils literal"><span class="pre">RangePiece</span></tt></a> ("," <a class="reference internal" href="#grammar-token-RangePiece"><tt class="xref docutils literal"><span class="pre">RangePiece</span></tt></a>)*
+<strong id="grammar-token-RangePiece">RangePiece </strong> ::= <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+ | <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a> "-" <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+ | <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a> <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+</pre>
+<p>The peculiar last form of <a class="reference internal" href="#grammar-token-RangePiece"><tt class="xref std std-token docutils literal"><span class="pre">RangePiece</span></tt></a> is due to the fact that the
+“<tt class="docutils literal"><span class="pre">-</span></tt>” is included in the <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref std std-token docutils literal"><span class="pre">TokInteger</span></tt></a>, hence <tt class="docutils literal"><span class="pre">1-5</span></tt> gets lexed as
+two consecutive <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref std std-token docutils literal"><span class="pre">TokInteger</span></tt></a>‘s, with values <tt class="docutils literal"><span class="pre">1</span></tt> and <tt class="docutils literal"><span class="pre">-5</span></tt>,
+instead of “1”, “-”, and “5”.
+The <a class="reference internal" href="#grammar-token-RangeList"><tt class="xref std std-token docutils literal"><span class="pre">RangeList</span></tt></a> can be thought of as specifying “list slice” in some
+contexts.</p>
+<p><a class="reference internal" href="#grammar-token-SimpleValue"><tt class="xref std std-token docutils literal"><span class="pre">SimpleValue</span></tt></a> has a number of forms:</p>
+<pre>
+<strong id="grammar-token-SimpleValue">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+</pre>
+<p>The value will be the variable referenced by the identifier. It can be one
+of:</p>
+<ul>
+<li><p class="first">name of a <tt class="docutils literal"><span class="pre">def</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><pre>def Bar : SomeClass {
+ int X = 5;
+}
+
+def Foo {
+ SomeClass Baz = Bar;
+}</pre>
+</div>
+</li>
+<li><p class="first">value local to a <tt class="docutils literal"><span class="pre">def</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><pre>def Foo {
+ int Bar = 5;
+ int Baz = Bar;
+}</pre>
+</div>
+</li>
+<li><p class="first">a template arg of a <tt class="docutils literal"><span class="pre">class</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><pre>class Foo<int Bar> {
+ int Baz = Bar;
+}</pre>
+</div>
+</li>
+<li><p class="first">value local to a <tt class="docutils literal"><span class="pre">multiclass</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><pre>multiclass Foo {
+ int Bar = 5;
+ int Baz = Bar;
+}</pre>
+</div>
+</li>
+<li><p class="first">a template arg to a <tt class="docutils literal"><span class="pre">multiclass</span></tt>, such as the use of <tt class="docutils literal"><span class="pre">Bar</span></tt> in:</p>
+<div class="highlight-python"><pre>multiclass Foo<int Bar> {
+ int Baz = Bar;
+}</pre>
+</div>
+</li>
+</ul>
+<pre>
+<strong id="id1">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokInteger"><tt class="xref docutils literal"><span class="pre">TokInteger</span></tt></a>
+</pre>
+<p>This represents the numeric value of the integer.</p>
+<pre>
+<strong id="id2">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokString"><tt class="xref docutils literal"><span class="pre">TokString</span></tt></a>+
+</pre>
+<p>Multiple adjacent string literals are concatenated like in C/C++. The value
+is the concatenation of the strings.</p>
+<pre>
+<strong id="id3">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-TokCodeFragment"><tt class="xref docutils literal"><span class="pre">TokCodeFragment</span></tt></a>
+</pre>
+<p>The value is the string value of the code fragment.</p>
+<pre>
+<strong id="id4">SimpleValue</strong> ::= "?"
+</pre>
+<p><tt class="docutils literal"><span class="pre">?</span></tt> represents an “unset” initializer.</p>
+<pre>
+<strong id="id5">SimpleValue</strong> ::= "{" <a class="reference internal" href="#grammar-token-ValueList"><tt class="xref docutils literal"><span class="pre">ValueList</span></tt></a> "}"
+<strong id="grammar-token-ValueList">ValueList </strong> ::= [<a class="reference internal" href="#grammar-token-ValueListNE"><tt class="xref docutils literal"><span class="pre">ValueListNE</span></tt></a>]
+<strong id="grammar-token-ValueListNE">ValueListNE</strong> ::= <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a> ("," <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a>)*
+</pre>
+<p>This represents a sequence of bits, as would be used to initialize a
+<tt class="docutils literal"><span class="pre">bits<n></span></tt> field (where <tt class="docutils literal"><span class="pre">n</span></tt> is the number of bits).</p>
+<pre>
+<strong id="id6">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-ClassID"><tt class="xref docutils literal"><span class="pre">ClassID</span></tt></a> "<" <a class="reference internal" href="#grammar-token-ValueListNE"><tt class="xref docutils literal"><span class="pre">ValueListNE</span></tt></a> ">"
+</pre>
+<p>This generates a new anonymous record definition (as would be created by an
+unnamed <tt class="docutils literal"><span class="pre">def</span></tt> inheriting from the given class with the given template
+arguments) and the value is the value of that record definition.</p>
+<pre>
+<strong id="id7">SimpleValue</strong> ::= "[" <a class="reference internal" href="#grammar-token-ValueList"><tt class="xref docutils literal"><span class="pre">ValueList</span></tt></a> "]" ["<" <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> ">"]
+</pre>
+<p>A list initializer. The optional <a class="reference internal" href="#grammar-token-Type"><tt class="xref std std-token docutils literal"><span class="pre">Type</span></tt></a> can be used to indicate a
+specific element type, otherwise the element type will be deduced from the
+given values.</p>
+<pre>
+<strong id="id8">SimpleValue</strong> ::= "(" <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref docutils literal"><span class="pre">DagArg</span></tt></a> <a class="reference internal" href="#grammar-token-DagArgList"><tt class="xref docutils literal"><span class="pre">DagArgList</span></tt></a> ")"
+<strong id="grammar-token-DagArgList">DagArgList </strong> ::= <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref docutils literal"><span class="pre">DagArg</span></tt></a> ("," <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref docutils literal"><span class="pre">DagArg</span></tt></a>)*
+<strong id="grammar-token-DagArg">DagArg </strong> ::= <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a> [":" <a class="reference internal" href="#grammar-token-TokVarName"><tt class="xref docutils literal"><span class="pre">TokVarName</span></tt></a>] | <a class="reference internal" href="#grammar-token-TokVarName"><tt class="xref docutils literal"><span class="pre">TokVarName</span></tt></a>
+</pre>
+<p>The initial <a class="reference internal" href="#grammar-token-DagArg"><tt class="xref std std-token docutils literal"><span class="pre">DagArg</span></tt></a> is called the “operator” of the dag.</p>
+<pre>
+<strong id="id9">SimpleValue</strong> ::= <a class="reference internal" href="#grammar-token-BangOperator"><tt class="xref docutils literal"><span class="pre">BangOperator</span></tt></a> ["<" <a class="reference internal" href="#grammar-token-Type"><tt class="xref docutils literal"><span class="pre">Type</span></tt></a> ">"] "(" <a class="reference internal" href="#grammar-token-ValueListNE"><tt class="xref docutils literal"><span class="pre">ValueListNE</span></tt></a> ")"
+</pre>
+</div>
+<div class="section" id="bodies">
+<h3><a class="toc-backref" href="#id18">Bodies</a><a class="headerlink" href="#bodies" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-ObjectBody">ObjectBody </strong> ::= <a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref docutils literal"><span class="pre">BaseClassList</span></tt></a> <a class="reference internal" href="#grammar-token-Body"><tt class="xref docutils literal"><span class="pre">Body</span></tt></a>
+<strong id="grammar-token-BaseClassList">BaseClassList </strong> ::= [":" <a class="reference internal" href="#grammar-token-BaseClassListNE"><tt class="xref docutils literal"><span class="pre">BaseClassListNE</span></tt></a>]
+<strong id="grammar-token-BaseClassListNE">BaseClassListNE</strong> ::= <a class="reference internal" href="#grammar-token-SubClassRef"><tt class="xref docutils literal"><span class="pre">SubClassRef</span></tt></a> ("," <a class="reference internal" href="#grammar-token-SubClassRef"><tt class="xref docutils literal"><span class="pre">SubClassRef</span></tt></a>)*
+<strong id="grammar-token-SubClassRef">SubClassRef </strong> ::= (<a class="reference internal" href="#grammar-token-ClassID"><tt class="xref docutils literal"><span class="pre">ClassID</span></tt></a> | <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref docutils literal"><span class="pre">MultiClassID</span></tt></a>) ["<" <a class="reference internal" href="#grammar-token-ValueList"><tt class="xref docutils literal"><span class="pre">ValueList</span></tt></a> ">"]
+<strong id="grammar-token-DefmID">DefmID </strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+</pre>
+<p>The version with the <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref std std-token docutils literal"><span class="pre">MultiClassID</span></tt></a> is only valid in the
+<a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref std std-token docutils literal"><span class="pre">BaseClassList</span></tt></a> of a <tt class="docutils literal"><span class="pre">defm</span></tt>.
+The <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref std std-token docutils literal"><span class="pre">MultiClassID</span></tt></a> should be the name of a <tt class="docutils literal"><span class="pre">multiclass</span></tt>.</p>
+<p>It is after parsing the base class list that the “let stack” is applied.</p>
+<pre>
+<strong id="grammar-token-Body">Body </strong> ::= ";" | "{" BodyList "}"
+<strong id="grammar-token-BodyList">BodyList</strong> ::= BodyItem*
+<strong id="grammar-token-BodyItem">BodyItem</strong> ::= <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> ";"
+ | "let" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a>] "=" <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a> ";"
+</pre>
+<p>The <tt class="docutils literal"><span class="pre">let</span></tt> form allows overriding the value of an inherited field.</p>
+</div>
+<div class="section" id="def">
+<h3><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">def</span></tt></a><a class="headerlink" href="#def" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Def">Def</strong> ::= "def" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> <a class="reference internal" href="#grammar-token-ObjectBody"><tt class="xref docutils literal"><span class="pre">ObjectBody</span></tt></a>
+</pre>
+<p>Defines a record whose name is given by the <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref std std-token docutils literal"><span class="pre">TokIdentifier</span></tt></a>. The
+fields of the record are inherited from the base classes and defined in the
+body.</p>
+<p>Special handling occurs if this <tt class="docutils literal"><span class="pre">def</span></tt> appears inside a <tt class="docutils literal"><span class="pre">multiclass</span></tt> or
+a <tt class="docutils literal"><span class="pre">foreach</span></tt>.</p>
+</div>
+<div class="section" id="defm">
+<h3><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">defm</span></tt></a><a class="headerlink" href="#defm" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Defm">Defm</strong> ::= "defm" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> ":" <a class="reference internal" href="#grammar-token-BaseClassListNE"><tt class="xref docutils literal"><span class="pre">BaseClassListNE</span></tt></a> ";"
+</pre>
+<p>Note that in the <a class="reference internal" href="#grammar-token-BaseClassList"><tt class="xref std std-token docutils literal"><span class="pre">BaseClassList</span></tt></a>, all of the <tt class="docutils literal"><span class="pre">multiclass</span></tt>‘s must
+precede any <tt class="docutils literal"><span class="pre">class</span></tt>‘s that appear.</p>
+</div>
+<div class="section" id="foreach">
+<h3><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">foreach</span></tt></a><a class="headerlink" href="#foreach" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Foreach">Foreach</strong> ::= "foreach" <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> "in" "{" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>* "}"
+ | "foreach" <a class="reference internal" href="#grammar-token-Declaration"><tt class="xref docutils literal"><span class="pre">Declaration</span></tt></a> "in" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>
+</pre>
+<p>The value assigned to the variable in the declaration is iterated over and
+the object or object list is reevaluated with the variable set at each
+iterated value.</p>
+</div>
+<div class="section" id="top-level-let">
+<h3><a class="toc-backref" href="#id22">Top-Level <tt class="docutils literal"><span class="pre">let</span></tt></a><a class="headerlink" href="#top-level-let" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-Let">Let </strong> ::= "let" <a class="reference internal" href="#grammar-token-LetList"><tt class="xref docutils literal"><span class="pre">LetList</span></tt></a> "in" "{" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>* "}"
+ | "let" <a class="reference internal" href="#grammar-token-LetList"><tt class="xref docutils literal"><span class="pre">LetList</span></tt></a> "in" <a class="reference internal" href="#grammar-token-Object"><tt class="xref docutils literal"><span class="pre">Object</span></tt></a>
+<strong id="grammar-token-LetList">LetList</strong> ::= <a class="reference internal" href="#grammar-token-LetItem"><tt class="xref docutils literal"><span class="pre">LetItem</span></tt></a> ("," <a class="reference internal" href="#grammar-token-LetItem"><tt class="xref docutils literal"><span class="pre">LetItem</span></tt></a>)*
+<strong id="grammar-token-LetItem">LetItem</strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-RangeList"><tt class="xref docutils literal"><span class="pre">RangeList</span></tt></a>] "=" <a class="reference internal" href="#grammar-token-Value"><tt class="xref docutils literal"><span class="pre">Value</span></tt></a>
+</pre>
+<p>This is effectively equivalent to <tt class="docutils literal"><span class="pre">let</span></tt> inside the body of a record
+except that it applies to multiple records at a time. The bindings are
+applied at the end of parsing the base classes of a record.</p>
+</div>
+<div class="section" id="multiclass">
+<h3><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">multiclass</span></tt></a><a class="headerlink" href="#multiclass" title="Permalink to this headline">¶</a></h3>
+<pre>
+<strong id="grammar-token-MultiClass">MultiClass </strong> ::= "multiclass" <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a> [<a class="reference internal" href="#grammar-token-TemplateArgList"><tt class="xref docutils literal"><span class="pre">TemplateArgList</span></tt></a>]
+ [":" <a class="reference internal" href="#grammar-token-BaseMultiClassList"><tt class="xref docutils literal"><span class="pre">BaseMultiClassList</span></tt></a>] "{" <a class="reference internal" href="#grammar-token-MultiClassObject"><tt class="xref docutils literal"><span class="pre">MultiClassObject</span></tt></a>+ "}"
+<strong id="grammar-token-BaseMultiClassList">BaseMultiClassList</strong> ::= <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref docutils literal"><span class="pre">MultiClassID</span></tt></a> ("," <a class="reference internal" href="#grammar-token-MultiClassID"><tt class="xref docutils literal"><span class="pre">MultiClassID</span></tt></a>)*
+<strong id="grammar-token-MultiClassID">MultiClassID </strong> ::= <a class="reference internal" href="#grammar-token-TokIdentifier"><tt class="xref docutils literal"><span class="pre">TokIdentifier</span></tt></a>
+<strong id="grammar-token-MultiClassObject">MultiClassObject </strong> ::= <a class="reference internal" href="#grammar-token-Def"><tt class="xref docutils literal"><span class="pre">Def</span></tt></a> | <a class="reference internal" href="#grammar-token-Defm"><tt class="xref docutils literal"><span class="pre">Defm</span></tt></a> | <a class="reference internal" href="#grammar-token-Let"><tt class="xref docutils literal"><span class="pre">Let</span></tt></a> | <a class="reference internal" href="#grammar-token-Foreach"><tt class="xref docutils literal"><span class="pre">Foreach</span></tt></a>
+</pre>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../HowToUseAttributes.html" title="How To Use Attributes"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/TableGenFundamentals.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/TableGenFundamentals.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/TableGenFundamentals.html (added)
+++ www-releases/trunk/3.3/docs/TableGenFundamentals.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,789 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>TableGen Fundamentals — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="Debugging JIT-ed Code With GDB" href="DebuggingJITedCode.html" />
+ <link rel="prev" title="Segmented Stacks in LLVM" href="SegmentedStacks.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SegmentedStacks.html" title="Segmented Stacks in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tablegen-fundamentals">
+<h1>TableGen Fundamentals<a class="headerlink" href="#tablegen-fundamentals" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id5">Introduction</a><ul>
+<li><a class="reference internal" href="#basic-concepts" id="id6">Basic concepts</a></li>
+<li><a class="reference internal" href="#an-example-record" id="id7">An example record</a></li>
+<li><a class="reference internal" href="#running-tablegen" id="id8">Running TableGen</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tablegen-syntax" id="id9">TableGen syntax</a><ul>
+<li><a class="reference internal" href="#tablegen-primitives" id="id10">TableGen primitives</a><ul>
+<li><a class="reference internal" href="#tablegen-comments" id="id11">TableGen comments</a></li>
+<li><a class="reference internal" href="#the-tablegen-type-system" id="id12">The TableGen type system</a></li>
+<li><a class="reference internal" href="#tablegen-values-and-expressions" id="id13">TableGen values and expressions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#classes-and-definitions" id="id14">Classes and definitions</a><ul>
+<li><a class="reference internal" href="#value-definitions" id="id15">Value definitions</a></li>
+<li><a class="reference internal" href="#let-expressions-within-a-record" id="id16">‘let’ expressions</a></li>
+<li><a class="reference internal" href="#class-template-arguments" id="id17">Class template arguments</a></li>
+<li><a class="reference internal" href="#multiclass-definitions-and-instances" id="id18">Multiclass definitions and instances</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#file-scope-entities" id="id19">File scope entities</a><ul>
+<li><a class="reference internal" href="#file-inclusion" id="id20">File inclusion</a></li>
+<li><a class="reference internal" href="#id3" id="id21">‘let’ expressions</a></li>
+<li><a class="reference internal" href="#looping" id="id22">Looping</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#code-generator-backend-info" id="id23">Code Generator backend info</a></li>
+<li><a class="reference internal" href="#write-a-backend" id="id24">TableGen backends</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id5">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>TableGen’s purpose is to help a human develop and maintain records of
+domain-specific information. Because there may be a large number of these
+records, it is specifically designed to allow writing flexible descriptions and
+for common features of these records to be factored out. This reduces the
+amount of duplication in the description, reduces the chance of error, and makes
+it easier to structure domain specific information.</p>
+<p>The core part of TableGen <a class="reference internal" href="#parses-a-file">parses a file</a>, instantiates the declarations, and
+hands the result off to a domain-specific <a class="reference internal" href="#tablegen-backend">TableGen backend</a> for processing.
+The current major user of TableGen is the <a class="reference external" href="CodeGenerator.html">LLVM code
+generator</a>.</p>
+<p>Note that if you work on TableGen much, and use emacs or vim, that you can find
+an emacs “TableGen mode” and a vim language file in the <tt class="docutils literal"><span class="pre">llvm/utils/emacs</span></tt> and
+<tt class="docutils literal"><span class="pre">llvm/utils/vim</span></tt> directories of your LLVM distribution, respectively.</p>
+<div class="section" id="basic-concepts">
+<span id="intro"></span><h3><a class="toc-backref" href="#id6">Basic concepts</a><a class="headerlink" href="#basic-concepts" title="Permalink to this headline">¶</a></h3>
+<p>TableGen files consist of two key parts: ‘classes’ and ‘definitions’, both of
+which are considered ‘records’.</p>
+<p><strong>TableGen records</strong> have a unique name, a list of values, and a list of
+superclasses. The list of values is the main data that TableGen builds for each
+record; it is this that holds the domain specific information for the
+application. The interpretation of this data is left to a specific <a class="reference internal" href="#tablegen-backend">TableGen
+backend</a>, but the structure and format rules are taken care of and are fixed by
+TableGen.</p>
+<p><strong>TableGen definitions</strong> are the concrete form of ‘records’. These generally do
+not have any undefined values, and are marked with the ‘<tt class="docutils literal"><span class="pre">def</span></tt>‘ keyword.</p>
+<p><strong>TableGen classes</strong> are abstract records that are used to build and describe
+other records. These ‘classes’ allow the end-user to build abstractions for
+either the domain they are targeting (such as “Register”, “RegisterClass”, and
+“Instruction” in the LLVM code generator) or for the implementor to help factor
+out common properties of records (such as “FPInst”, which is used to represent
+floating point instructions in the X86 backend). TableGen keeps track of all of
+the classes that are used to build up a definition, so the backend can find all
+definitions of a particular class, such as “Instruction”.</p>
+<p><strong>TableGen multiclasses</strong> are groups of abstract records that are instantiated
+all at once. Each instantiation can result in multiple TableGen definitions.
+If a multiclass inherits from another multiclass, the definitions in the
+sub-multiclass become part of the current multiclass, as if they were declared
+in the current multiclass.</p>
+</div>
+<div class="section" id="an-example-record">
+<span id="described-above"></span><h3><a class="toc-backref" href="#id7">An example record</a><a class="headerlink" href="#an-example-record" title="Permalink to this headline">¶</a></h3>
+<p>With no other arguments, TableGen parses the specified file and prints out all
+of the classes, then all of the definitions. This is a good way to see what the
+various definitions expand to fully. Running this on the <tt class="docutils literal"><span class="pre">X86.td</span></tt> file prints
+this (at the time of this writing):</p>
+<div class="highlight-llvm"><pre>...
+def ADD32rr { // Instruction X86Inst I
+ string Namespace = "X86";
+ dag OutOperandList = (outs GR32:$dst);
+ dag InOperandList = (ins GR32:$src1, GR32:$src2);
+ string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
+ list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
+ list<Register> Uses = [];
+ list<Register> Defs = [EFLAGS];
+ list<Predicate> Predicates = [];
+ int CodeSize = 3;
+ int AddedComplexity = 0;
+ bit isReturn = 0;
+ bit isBranch = 0;
+ bit isIndirectBranch = 0;
+ bit isBarrier = 0;
+ bit isCall = 0;
+ bit canFoldAsLoad = 0;
+ bit mayLoad = 0;
+ bit mayStore = 0;
+ bit isImplicitDef = 0;
+ bit isConvertibleToThreeAddress = 1;
+ bit isCommutable = 1;
+ bit isTerminator = 0;
+ bit isReMaterializable = 0;
+ bit isPredicable = 0;
+ bit hasDelaySlot = 0;
+ bit usesCustomInserter = 0;
+ bit hasCtrlDep = 0;
+ bit isNotDuplicable = 0;
+ bit hasSideEffects = 0;
+ bit neverHasSideEffects = 0;
+ InstrItinClass Itinerary = NoItinerary;
+ string Constraints = "";
+ string DisableEncoding = "";
+ bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
+ Format Form = MRMDestReg;
+ bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
+ ImmType ImmT = NoImm;
+ bits<3> ImmTypeBits = { 0, 0, 0 };
+ bit hasOpSizePrefix = 0;
+ bit hasAdSizePrefix = 0;
+ bits<4> Prefix = { 0, 0, 0, 0 };
+ bit hasREX_WPrefix = 0;
+ FPFormat FPForm = ?;
+ bits<3> FPFormBits = { 0, 0, 0 };
+}
+...</pre>
+</div>
+<p>This definition corresponds to the 32-bit register-register <tt class="docutils literal"><span class="pre">add</span></tt> instruction
+of the x86 architecture. <tt class="docutils literal"><span class="pre">def</span> <span class="pre">ADD32rr</span></tt> defines a record named
+<tt class="docutils literal"><span class="pre">ADD32rr</span></tt>, and the comment at the end of the line indicates the superclasses
+of the definition. The body of the record contains all of the data that
+TableGen assembled for the record, indicating that the instruction is part of
+the “X86” namespace, the pattern indicating how the instruction should be
+emitted into the assembly file, that it is a two-address instruction, has a
+particular encoding, etc. The contents and semantics of the information in the
+record are specific to the needs of the X86 backend, and are only shown as an
+example.</p>
+<p>As you can see, a lot of information is needed for every instruction supported
+by the code generator, and specifying it all manually would be unmaintainable,
+prone to bugs, and tiring to do in the first place. Because we are using
+TableGen, all of the information was derived from the following definition:</p>
+<div class="highlight-llvm"><pre>let Defs = [EFLAGS],
+ isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
+ isConvertibleToThreeAddress = 1 in // Can transform into LEA.
+def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
+ (ins GR32:$src1, GR32:$src2),
+ "add{l}\t{$src2, $dst|$dst, $src2}",
+ [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;</pre>
+</div>
+<p>This definition makes use of the custom class <tt class="docutils literal"><span class="pre">I</span></tt> (extended from the custom
+class <tt class="docutils literal"><span class="pre">X86Inst</span></tt>), which is defined in the X86-specific TableGen file, to
+factor out the common features that instructions of its class share. A key
+feature of TableGen is that it allows the end-user to define the abstractions
+they prefer to use when describing their information.</p>
+<p>Each <tt class="docutils literal"><span class="pre">def</span></tt> record has a special entry called “NAME”. This is the name of the
+record (“<tt class="docutils literal"><span class="pre">ADD32rr</span></tt>” above). In the general case <tt class="docutils literal"><span class="pre">def</span></tt> names can be formed
+from various kinds of string processing expressions and <tt class="docutils literal"><span class="pre">NAME</span></tt> resolves to the
+final value obtained after resolving all of those expressions. The user may
+refer to <tt class="docutils literal"><span class="pre">NAME</span></tt> anywhere she desires to use the ultimate name of the <tt class="docutils literal"><span class="pre">def</span></tt>.
+<tt class="docutils literal"><span class="pre">NAME</span></tt> should not be defined anywhere else in user code to avoid conflicts.</p>
+</div>
+<div class="section" id="running-tablegen">
+<h3><a class="toc-backref" href="#id8">Running TableGen</a><a class="headerlink" href="#running-tablegen" title="Permalink to this headline">¶</a></h3>
+<p>TableGen runs just like any other LLVM tool. The first (optional) argument
+specifies the file to read. If a filename is not specified, <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt>
+reads from standard input.</p>
+<p>To be useful, one of the <a class="reference internal" href="#tablegen-backends">TableGen backends</a> must be used. These backends are
+selectable on the command line (type ‘<tt class="docutils literal"><span class="pre">llvm-tblgen</span> <span class="pre">-help</span></tt>‘ for a list). For
+example, to get a list of all of the definitions that subclass a particular type
+(which can be useful for building up an enum list of these records), use the
+<tt class="docutils literal"><span class="pre">-print-enums</span></tt> option:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>llvm-tblgen X86.td -print-enums -class<span class="o">=</span>Register
+AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
+ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
+MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
+R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
+R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
+RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
+XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
+XMM6, XMM7, XMM8, XMM9,
+
+<span class="nv">$ </span>llvm-tblgen X86.td -print-enums -class<span class="o">=</span>Instruction
+ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
+ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
+ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
+ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
+ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
+</pre></div>
+</div>
+<p>The default backend prints out all of the records, as <a class="reference internal" href="#described-above">described above</a>.</p>
+<p>If you plan to use TableGen, you will most likely have to <a class="reference internal" href="#write-a-backend">write a backend</a>
+that extracts the information specific to what you need and formats it in the
+appropriate way.</p>
+</div>
+</div>
+<div class="section" id="tablegen-syntax">
+<span id="parses-a-file"></span><h2><a class="toc-backref" href="#id9">TableGen syntax</a><a class="headerlink" href="#tablegen-syntax" title="Permalink to this headline">¶</a></h2>
+<p>TableGen doesn’t care about the meaning of data (that is up to the backend to
+define), but it does care about syntax, and it enforces a simple type system.
+This section describes the syntax and the constructs allowed in a TableGen file.</p>
+<div class="section" id="tablegen-primitives">
+<h3><a class="toc-backref" href="#id10">TableGen primitives</a><a class="headerlink" href="#tablegen-primitives" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="tablegen-comments">
+<h4><a class="toc-backref" href="#id11">TableGen comments</a><a class="headerlink" href="#tablegen-comments" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports BCPL style “<tt class="docutils literal"><span class="pre">//</span></tt>” comments, which run to the end of the
+line, and it also supports <strong>nestable</strong> “<tt class="docutils literal"><span class="pre">/*</span> <span class="pre">*/</span></tt>” comments.</p>
+</div>
+<div class="section" id="the-tablegen-type-system">
+<span id="tablegen-type"></span><h4><a class="toc-backref" href="#id12">The TableGen type system</a><a class="headerlink" href="#the-tablegen-type-system" title="Permalink to this headline">¶</a></h4>
+<p>TableGen files are strongly typed, in a simple (but complete) type-system.
+These types are used to perform automatic conversions, check for errors, and to
+help interface designers constrain the input that they allow. Every <a class="reference internal" href="#value-definition">value
+definition</a> is required to have an associated type.</p>
+<p>TableGen supports a mixture of very low-level types (such as <tt class="docutils literal"><span class="pre">bit</span></tt>) and very
+high-level types (such as <tt class="docutils literal"><span class="pre">dag</span></tt>). This flexibility is what allows it to
+describe a wide range of information conveniently and compactly. The TableGen
+types are:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">bit</span></tt></dt>
+<dd>A ‘bit’ is a boolean value that can hold either 0 or 1.</dd>
+<dt><tt class="docutils literal"><span class="pre">int</span></tt></dt>
+<dd>The ‘int’ type represents a simple 32-bit integer value, such as 5.</dd>
+<dt><tt class="docutils literal"><span class="pre">string</span></tt></dt>
+<dd>The ‘string’ type represents an ordered sequence of characters of arbitrary
+length.</dd>
+<dt><tt class="docutils literal"><span class="pre">bits<n></span></tt></dt>
+<dd>A ‘bits’ type is an arbitrary, but fixed, size integer that is broken up
+into individual bits. This type is useful because it can handle some bits
+being defined while others are undefined.</dd>
+<dt><tt class="docutils literal"><span class="pre">list<ty></span></tt></dt>
+<dd>This type represents a list whose elements are some other type. The
+contained type is arbitrary: it can even be another list type.</dd>
+<dt>Class type</dt>
+<dd>Specifying a class name in a type context means that the defined value must
+be a subclass of the specified class. This is useful in conjunction with
+the <tt class="docutils literal"><span class="pre">list</span></tt> type, for example, to constrain the elements of the list to a
+common base class (e.g., a <tt class="docutils literal"><span class="pre">list<Register></span></tt> can only contain definitions
+derived from the “<tt class="docutils literal"><span class="pre">Register</span></tt>” class).</dd>
+<dt><tt class="docutils literal"><span class="pre">dag</span></tt></dt>
+<dd>This type represents a nestable directed graph of elements.</dd>
+<dt><tt class="docutils literal"><span class="pre">code</span></tt></dt>
+<dd>This represents a big hunk of text. This is lexically distinct from string
+values because it doesn’t require escaping double quotes and other common
+characters that occur in code.</dd>
+</dl>
+<p>To date, these types have been sufficient for describing things that TableGen
+has been used for, but it is straight-forward to extend this list if needed.</p>
+</div>
+<div class="section" id="tablegen-values-and-expressions">
+<span id="tablegen-expressions"></span><h4><a class="toc-backref" href="#id13">TableGen values and expressions</a><a class="headerlink" href="#tablegen-values-and-expressions" title="Permalink to this headline">¶</a></h4>
+<p>TableGen allows for a pretty reasonable number of different expression forms
+when building up values. These forms allow the TableGen file to be written in a
+natural syntax and flavor for the application. The current expression forms
+supported include:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">?</span></tt></dt>
+<dd>uninitialized field</dd>
+<dt><tt class="docutils literal"><span class="pre">0b1001011</span></tt></dt>
+<dd>binary integer value</dd>
+<dt><tt class="docutils literal"><span class="pre">07654321</span></tt></dt>
+<dd>octal integer value (indicated by a leading 0)</dd>
+<dt><tt class="docutils literal"><span class="pre">7</span></tt></dt>
+<dd>decimal integer value</dd>
+<dt><tt class="docutils literal"><span class="pre">0x7F</span></tt></dt>
+<dd>hexadecimal integer value</dd>
+<dt><tt class="docutils literal"><span class="pre">"foo"</span></tt></dt>
+<dd>string value</dd>
+<dt><tt class="docutils literal"><span class="pre">[{</span> <span class="pre">...</span> <span class="pre">}]</span></tt></dt>
+<dd>code fragment</dd>
+<dt><tt class="docutils literal"><span class="pre">[</span> <span class="pre">X,</span> <span class="pre">Y,</span> <span class="pre">Z</span> <span class="pre">]<type></span></tt></dt>
+<dd>list value. <type> is the type of the list element and is usually optional.
+In rare cases, TableGen is unable to deduce the element type in which case
+the user must specify it explicitly.</dd>
+<dt><tt class="docutils literal"><span class="pre">{</span> <span class="pre">a,</span> <span class="pre">b,</span> <span class="pre">c</span> <span class="pre">}</span></tt></dt>
+<dd>initializer for a “bits<3>” value</dd>
+<dt><tt class="docutils literal"><span class="pre">value</span></tt></dt>
+<dd>value reference</dd>
+<dt><tt class="docutils literal"><span class="pre">value{17}</span></tt></dt>
+<dd>access to one bit of a value</dd>
+<dt><tt class="docutils literal"><span class="pre">value{15-17}</span></tt></dt>
+<dd>access to multiple bits of a value</dd>
+<dt><tt class="docutils literal"><span class="pre">DEF</span></tt></dt>
+<dd>reference to a record definition</dd>
+<dt><tt class="docutils literal"><span class="pre">CLASS<val</span> <span class="pre">list></span></tt></dt>
+<dd>reference to a new anonymous definition of CLASS with the specified template
+arguments.</dd>
+<dt><tt class="docutils literal"><span class="pre">X.Y</span></tt></dt>
+<dd>reference to the subfield of a value</dd>
+<dt><tt class="docutils literal"><span class="pre">list[4-7,17,2-3]</span></tt></dt>
+<dd>A slice of the ‘list’ list, including elements 4,5,6,7,17,2, and 3 from it.
+Elements may be included multiple times.</dd>
+</dl>
+<p><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">[</span> <span class="pre"><list></span> <span class="pre">]</span> <span class="pre">in</span> <span class="pre">{</span> <span class="pre"><body></span> <span class="pre">}</span></tt></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">[</span> <span class="pre"><list></span> <span class="pre">]</span> <span class="pre">in</span> <span class="pre"><def></span></tt></dt>
+<dd>Replicate <body> or <def>, replacing instances of <var> with each value
+in <list>. <var> is scoped at the level of the <tt class="docutils literal"><span class="pre">foreach</span></tt> loop and must
+not conflict with any other object introduced in <body> or <def>. Currently
+only <tt class="docutils literal"><span class="pre">def</span></tt>s are expanded within <body>.</dd>
+</dl>
+<p><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">0-15</span> <span class="pre">in</span> <span class="pre">...</span></tt></p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">foreach</span> <span class="pre"><var></span> <span class="pre">=</span> <span class="pre">{0-15,32-47}</span> <span class="pre">in</span> <span class="pre">...</span></tt></dt>
+<dd>Loop over ranges of integers. The braces are required for multiple ranges.</dd>
+<dt><tt class="docutils literal"><span class="pre">(DEF</span> <span class="pre">a,</span> <span class="pre">b)</span></tt></dt>
+<dd>a dag value. The first element is required to be a record definition, the
+remaining elements in the list may be arbitrary other values, including
+nested <tt class="docutils literal"><span class="pre">`dag</span></tt>‘ values.</dd>
+<dt><tt class="docutils literal"><span class="pre">!strconcat(a,</span> <span class="pre">b)</span></tt></dt>
+<dd>A string value that is the result of concatenating the ‘a’ and ‘b’ strings.</dd>
+<dt><tt class="docutils literal"><span class="pre">str1#str2</span></tt></dt>
+<dd>“#” (paste) is a shorthand for !strconcat. It may concatenate things that
+are not quoted strings, in which case an implicit !cast<string> is done on
+the operand of the paste.</dd>
+<dt><tt class="docutils literal"><span class="pre">!cast<type>(a)</span></tt></dt>
+<dd>A symbol of type <em>type</em> obtained by looking up the string ‘a’ in the symbol
+table. If the type of ‘a’ does not match <em>type</em>, TableGen aborts with an
+error. !cast<string> is a special case in that the argument must be an
+object defined by a ‘def’ construct.</dd>
+<dt><tt class="docutils literal"><span class="pre">!subst(a,</span> <span class="pre">b,</span> <span class="pre">c)</span></tt></dt>
+<dd>If ‘a’ and ‘b’ are of string type or are symbol references, substitute ‘b’
+for ‘a’ in ‘c.’ This operation is analogous to $(subst) in GNU make.</dd>
+<dt><tt class="docutils literal"><span class="pre">!foreach(a,</span> <span class="pre">b,</span> <span class="pre">c)</span></tt></dt>
+<dd>For each member ‘b’ of dag or list ‘a’ apply operator ‘c.’ ‘b’ is a dummy
+variable that should be declared as a member variable of an instantiated
+class. This operation is analogous to $(foreach) in GNU make.</dd>
+<dt><tt class="docutils literal"><span class="pre">!head(a)</span></tt></dt>
+<dd>The first element of list ‘a.’</dd>
+<dt><tt class="docutils literal"><span class="pre">!tail(a)</span></tt></dt>
+<dd>The 2nd-N elements of list ‘a.’</dd>
+<dt><tt class="docutils literal"><span class="pre">!empty(a)</span></tt></dt>
+<dd>An integer {0,1} indicating whether list ‘a’ is empty.</dd>
+<dt><tt class="docutils literal"><span class="pre">!if(a,b,c)</span></tt></dt>
+<dd>‘b’ if the result of ‘int’ or ‘bit’ operator ‘a’ is nonzero, ‘c’ otherwise.</dd>
+<dt><tt class="docutils literal"><span class="pre">!eq(a,b)</span></tt></dt>
+<dd>‘bit 1’ if string a is equal to string b, 0 otherwise. This only operates
+on string, int and bit objects. Use !cast<string> to compare other types of
+objects.</dd>
+</dl>
+<p>Note that all of the values have rules specifying how they convert to values
+for different types. These rules allow you to assign a value like “<tt class="docutils literal"><span class="pre">7</span></tt>”
+to a “<tt class="docutils literal"><span class="pre">bits<4></span></tt>” value, for example.</p>
+</div>
+</div>
+<div class="section" id="classes-and-definitions">
+<h3><a class="toc-backref" href="#id14">Classes and definitions</a><a class="headerlink" href="#classes-and-definitions" title="Permalink to this headline">¶</a></h3>
+<p>As mentioned in the <a class="reference internal" href="#intro">intro</a>, classes and definitions (collectively known as
+‘records’) in TableGen are the main high-level unit of information that TableGen
+collects. Records are defined with a <tt class="docutils literal"><span class="pre">def</span></tt> or <tt class="docutils literal"><span class="pre">class</span></tt> keyword, the record
+name, and an optional list of “<a class="reference internal" href="#template-arguments">template arguments</a>”. If the record has
+superclasses, they are specified as a comma separated list that starts with a
+colon character (“<tt class="docutils literal"><span class="pre">:</span></tt>”). If <a class="reference internal" href="#value-definitions">value definitions</a> or <a class="reference internal" href="#let-expressions">let expressions</a> are
+needed for the class, they are enclosed in curly braces (“<tt class="docutils literal"><span class="pre">{}</span></tt>”); otherwise,
+the record ends with a semicolon.</p>
+<p>Here is a simple TableGen file:</p>
+<div class="highlight-llvm"><pre>class C { bit V = 1; }
+def X : C;
+def Y : C {
+ string Greeting = "hello";
+}</pre>
+</div>
+<p>This example defines two definitions, <tt class="docutils literal"><span class="pre">X</span></tt> and <tt class="docutils literal"><span class="pre">Y</span></tt>, both of which derive from
+the <tt class="docutils literal"><span class="pre">C</span></tt> class. Because of this, they both get the <tt class="docutils literal"><span class="pre">V</span></tt> bit value. The <tt class="docutils literal"><span class="pre">Y</span></tt>
+definition also gets the Greeting member as well.</p>
+<p>In general, classes are useful for collecting together the commonality between a
+group of records and isolating it in a single place. Also, classes permit the
+specification of default values for their subclasses, allowing the subclasses to
+override them as they wish.</p>
+<div class="section" id="value-definitions">
+<span id="value-definition"></span><span id="id1"></span><h4><a class="toc-backref" href="#id15">Value definitions</a><a class="headerlink" href="#value-definitions" title="Permalink to this headline">¶</a></h4>
+<p>Value definitions define named entries in records. A value must be defined
+before it can be referred to as the operand for another value definition or
+before the value is reset with a <a class="reference internal" href="#let-expression">let expression</a>. A value is defined by
+specifying a <a class="reference internal" href="#tablegen-type">TableGen type</a> and a name. If an initial value is available, it
+may be specified after the type with an equal sign. Value definitions require
+terminating semicolons.</p>
+</div>
+<div class="section" id="let-expressions-within-a-record">
+<span id="let-expressions"></span><span id="let-expression"></span><span id="id2"></span><h4><a class="toc-backref" href="#id16">‘let’ expressions</a><a class="headerlink" href="#let-expressions-within-a-record" title="Permalink to this headline">¶</a></h4>
+<p>A record-level let expression is used to change the value of a value definition
+in a record. This is primarily useful when a superclass defines a value that a
+derived class or definition wants to override. Let expressions consist of the
+‘<tt class="docutils literal"><span class="pre">let</span></tt>‘ keyword followed by a value name, an equal sign (“<tt class="docutils literal"><span class="pre">=</span></tt>”), and a new
+value. For example, a new class could be added to the example above, redefining
+the <tt class="docutils literal"><span class="pre">V</span></tt> field for all of its subclasses:</p>
+<div class="highlight-llvm"><pre>class D : C { let V = 0; }
+def Z : D;</pre>
+</div>
+<p>In this case, the <tt class="docutils literal"><span class="pre">Z</span></tt> definition will have a zero value for its <tt class="docutils literal"><span class="pre">V</span></tt> value,
+despite the fact that it derives (indirectly) from the <tt class="docutils literal"><span class="pre">C</span></tt> class, because the
+<tt class="docutils literal"><span class="pre">D</span></tt> class overrode its value.</p>
+</div>
+<div class="section" id="class-template-arguments">
+<span id="template-arguments"></span><h4><a class="toc-backref" href="#id17">Class template arguments</a><a class="headerlink" href="#class-template-arguments" title="Permalink to this headline">¶</a></h4>
+<p>TableGen permits the definition of parameterized classes as well as normal
+concrete classes. Parameterized TableGen classes specify a list of variable
+bindings (which may optionally have defaults) that are bound when used. Here is
+a simple example:</p>
+<div class="highlight-llvm"><pre>class FPFormat<bits<3> val> {
+ bits<3> Value = val;
+}
+def NotFP : FPFormat<0>;
+def ZeroArgFP : FPFormat<1>;
+def OneArgFP : FPFormat<2>;
+def OneArgFPRW : FPFormat<3>;
+def TwoArgFP : FPFormat<4>;
+def CompareFP : FPFormat<5>;
+def CondMovFP : FPFormat<6>;
+def SpecialFP : FPFormat<7>;</pre>
+</div>
+<p>In this case, template arguments are used as a space efficient way to specify a
+list of “enumeration values”, each with a “<tt class="docutils literal"><span class="pre">Value</span></tt>” field set to the specified
+integer.</p>
+<p>The more esoteric forms of <a class="reference internal" href="#tablegen-expressions">TableGen expressions</a> are useful in conjunction
+with template arguments. As an example:</p>
+<div class="highlight-llvm"><pre>class ModRefVal<bits<2> val> {
+ bits<2> Value = val;
+}
+
+def None : ModRefVal<0>;
+def Mod : ModRefVal<1>;
+def Ref : ModRefVal<2>;
+def ModRef : ModRefVal<3>;
+
+class Value<ModRefVal MR> {
+ // Decode some information into a more convenient format, while providing
+ // a nice interface to the user of the "Value" class.
+ bit isMod = MR.Value{0};
+ bit isRef = MR.Value{1};
+
+ // other stuff...
+}
+
+// Example uses
+def bork : Value<Mod>;
+def zork : Value<Ref>;
+def hork : Value<ModRef>;</pre>
+</div>
+<p>This is obviously a contrived example, but it shows how template arguments can
+be used to decouple the interface provided to the user of the class from the
+actual internal data representation expected by the class. In this case,
+running <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt> on the example prints the following definitions:</p>
+<div class="highlight-llvm"><pre>def bork { // Value
+ bit isMod = 1;
+ bit isRef = 0;
+}
+def hork { // Value
+ bit isMod = 1;
+ bit isRef = 1;
+}
+def zork { // Value
+ bit isMod = 0;
+ bit isRef = 1;
+}</pre>
+</div>
+<p>This shows that TableGen was able to dig into the argument and extract a piece
+of information that was requested by the designer of the “Value” class. For
+more realistic examples, please see existing users of TableGen, such as the X86
+backend.</p>
+</div>
+<div class="section" id="multiclass-definitions-and-instances">
+<h4><a class="toc-backref" href="#id18">Multiclass definitions and instances</a><a class="headerlink" href="#multiclass-definitions-and-instances" title="Permalink to this headline">¶</a></h4>
+<p>While classes with template arguments are a good way to factor commonality
+between two instances of a definition, multiclasses allow a convenient notation
+for defining multiple definitions at once (instances of implicitly constructed
+classes). For example, consider an 3-address instruction set whose instructions
+come in two forms: “<tt class="docutils literal"><span class="pre">reg</span> <span class="pre">=</span> <span class="pre">reg</span> <span class="pre">op</span> <span class="pre">reg</span></tt>” and “<tt class="docutils literal"><span class="pre">reg</span> <span class="pre">=</span> <span class="pre">reg</span> <span class="pre">op</span> <span class="pre">imm</span></tt>”
+(e.g. SPARC). In this case, you’d like to specify in one place that this
+commonality exists, then in a separate place indicate what all the ops are.</p>
+<p>Here is an example TableGen fragment that shows this idea:</p>
+<div class="highlight-llvm"><pre>def ops;
+def GPR;
+def Imm;
+class inst<int opc, string asmstr, dag operandlist>;
+
+multiclass ri_inst<int opc, string asmstr> {
+ def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+ def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+}
+
+// Instantiations of the ri_inst multiclass.
+defm ADD : ri_inst<0b111, "add">;
+defm SUB : ri_inst<0b101, "sub">;
+defm MUL : ri_inst<0b100, "mul">;
+...</pre>
+</div>
+<p>The name of the resultant definitions has the multidef fragment names appended
+to them, so this defines <tt class="docutils literal"><span class="pre">ADD_rr</span></tt>, <tt class="docutils literal"><span class="pre">ADD_ri</span></tt>, <tt class="docutils literal"><span class="pre">SUB_rr</span></tt>, etc. A defm may
+inherit from multiple multiclasses, instantiating definitions from each
+multiclass. Using a multiclass this way is exactly equivalent to instantiating
+the classes multiple times yourself, e.g. by writing:</p>
+<div class="highlight-llvm"><pre>def ops;
+def GPR;
+def Imm;
+class inst<int opc, string asmstr, dag operandlist>;
+
+class rrinst<int opc, string asmstr>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+
+class riinst<int opc, string asmstr>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+
+// Instantiations of the ri_inst multiclass.
+def ADD_rr : rrinst<0b111, "add">;
+def ADD_ri : riinst<0b111, "add">;
+def SUB_rr : rrinst<0b101, "sub">;
+def SUB_ri : riinst<0b101, "sub">;
+def MUL_rr : rrinst<0b100, "mul">;
+def MUL_ri : riinst<0b100, "mul">;
+...</pre>
+</div>
+<p>A <tt class="docutils literal"><span class="pre">defm</span></tt> can also be used inside a multiclass providing several levels of
+multiclass instanciations.</p>
+<div class="highlight-llvm"><pre>class Instruction<bits<4> opc, string Name> {
+ bits<4> opcode = opc;
+ string name = Name;
+}
+
+multiclass basic_r<bits<4> opc> {
+ def rr : Instruction<opc, "rr">;
+ def rm : Instruction<opc, "rm">;
+}
+
+multiclass basic_s<bits<4> opc> {
+ defm SS : basic_r<opc>;
+ defm SD : basic_r<opc>;
+ def X : Instruction<opc, "x">;
+}
+
+multiclass basic_p<bits<4> opc> {
+ defm PS : basic_r<opc>;
+ defm PD : basic_r<opc>;
+ def Y : Instruction<opc, "y">;
+}
+
+defm ADD : basic_s<0xf>, basic_p<0xf>;
+...
+
+// Results
+def ADDPDrm { ...
+def ADDPDrr { ...
+def ADDPSrm { ...
+def ADDPSrr { ...
+def ADDSDrm { ...
+def ADDSDrr { ...
+def ADDY { ...
+def ADDX { ...</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">defm</span></tt> declarations can inherit from classes too, the rule to follow is that
+the class list must start after the last multiclass, and there must be at least
+one multiclass before them.</p>
+<div class="highlight-llvm"><pre>class XD { bits<4> Prefix = 11; }
+class XS { bits<4> Prefix = 12; }
+
+class I<bits<4> op> {
+ bits<4> opcode = op;
+}
+
+multiclass R {
+ def rr : I<4>;
+ def rm : I<2>;
+}
+
+multiclass Y {
+ defm SS : R, XD;
+ defm SD : R, XS;
+}
+
+defm Instr : Y;
+
+// Results
+def InstrSDrm {
+ bits<4> opcode = { 0, 0, 1, 0 };
+ bits<4> Prefix = { 1, 1, 0, 0 };
+}
+...
+def InstrSSrr {
+ bits<4> opcode = { 0, 1, 0, 0 };
+ bits<4> Prefix = { 1, 0, 1, 1 };
+}</pre>
+</div>
+</div>
+</div>
+<div class="section" id="file-scope-entities">
+<h3><a class="toc-backref" href="#id19">File scope entities</a><a class="headerlink" href="#file-scope-entities" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="file-inclusion">
+<h4><a class="toc-backref" href="#id20">File inclusion</a><a class="headerlink" href="#file-inclusion" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports the ‘<tt class="docutils literal"><span class="pre">include</span></tt>‘ token, which textually substitutes the
+specified file in place of the include directive. The filename should be
+specified as a double quoted string immediately after the ‘<tt class="docutils literal"><span class="pre">include</span></tt>‘ keyword.
+Example:</p>
+<div class="highlight-llvm"><pre>include "foo.td"</pre>
+</div>
+</div>
+<div class="section" id="id3">
+<h4><a class="toc-backref" href="#id21">‘let’ expressions</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p>“Let” expressions at file scope are similar to <a class="reference internal" href="#let-expressions-within-a-record">“let” expressions within a
+record</a>, except they can specify a value binding for multiple records at a
+time, and may be useful in certain other cases. File-scope let expressions are
+really just another way that TableGen allows the end-user to factor out
+commonality from the records.</p>
+<p>File-scope “let” expressions take a comma-separated list of bindings to apply,
+and one or more records to bind the values in. Here are some examples:</p>
+<div class="highlight-llvm"><pre>let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
+ def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
+
+let isCall = 1 in
+ // All calls clobber the non-callee saved registers...
+ let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
+ MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
+ XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
+ def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
+ "call\t${dst:call}", []>;
+ def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
+ "call\t{*}$dst", [(X86call GR32:$dst)]>;
+ def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
+ "call\t{*}$dst", []>;
+ }</pre>
+</div>
+<p>File-scope “let” expressions are often useful when a couple of definitions need
+to be added to several records, and the records do not otherwise need to be
+opened, as in the case with the <tt class="docutils literal"><span class="pre">CALL*</span></tt> instructions above.</p>
+<p>It’s also possible to use “let” expressions inside multiclasses, providing more
+ways to factor out commonality from the records, specially if using several
+levels of multiclass instanciations. This also avoids the need of using “let”
+expressions within subsequent records inside a multiclass.</p>
+<div class="highlight-llvm"><pre>multiclass basic_r<bits<4> opc> {
+ let Predicates = [HasSSE2] in {
+ def rr : Instruction<opc, "rr">;
+ def rm : Instruction<opc, "rm">;
+ }
+ let Predicates = [HasSSE3] in
+ def rx : Instruction<opc, "rx">;
+}
+
+multiclass basic_ss<bits<4> opc> {
+ let IsDouble = 0 in
+ defm SS : basic_r<opc>;
+
+ let IsDouble = 1 in
+ defm SD : basic_r<opc>;
+}
+
+defm ADD : basic_ss<0xf>;</pre>
+</div>
+</div>
+<div class="section" id="looping">
+<h4><a class="toc-backref" href="#id22">Looping</a><a class="headerlink" href="#looping" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports the ‘<tt class="docutils literal"><span class="pre">foreach</span></tt>‘ block, which textually replicates the loop
+body, substituting iterator values for iterator references in the body.
+Example:</p>
+<div class="highlight-llvm"><pre>foreach i = [0, 1, 2, 3] in {
+ def R#i : Register<...>;
+ def F#i : Register<...>;
+}</pre>
+</div>
+<p>This will create objects <tt class="docutils literal"><span class="pre">R0</span></tt>, <tt class="docutils literal"><span class="pre">R1</span></tt>, <tt class="docutils literal"><span class="pre">R2</span></tt> and <tt class="docutils literal"><span class="pre">R3</span></tt>. <tt class="docutils literal"><span class="pre">foreach</span></tt> blocks
+may be nested. If there is only one item in the body the braces may be
+elided:</p>
+<div class="highlight-llvm"><pre>foreach i = [0, 1, 2, 3] in
+ def R#i : Register<...>;</pre>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="code-generator-backend-info">
+<h2><a class="toc-backref" href="#id23">Code Generator backend info</a><a class="headerlink" href="#code-generator-backend-info" title="Permalink to this headline">¶</a></h2>
+<p>Expressions used by code generator to describe instructions and isel patterns:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">(implicit</span> <span class="pre">a)</span></tt></dt>
+<dd>an implicitly defined physical register. This tells the dag instruction
+selection emitter the input pattern’s extra definitions matches implicit
+physical register definitions.</dd>
+</dl>
+</div>
+<div class="section" id="write-a-backend">
+<span id="tablegen-backends"></span><span id="tablegen-backend"></span><span id="id4"></span><h2><a class="toc-backref" href="#id24">TableGen backends</a><a class="headerlink" href="#write-a-backend" title="Permalink to this headline">¶</a></h2>
+<p>Until we get a step-by-step HowTo for writing TableGen backends, you can at
+least grab the boilerplate (build system, new files, etc.) from Clang’s
+r173931.</p>
+<p>TODO: How they work, how to write one. This section should not contain details
+about any particular backend, except maybe <tt class="docutils literal"><span class="pre">-print-enums</span></tt> as an example. This
+should highlight the APIs in <tt class="docutils literal"><span class="pre">TableGen/Record.h</span></tt>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SegmentedStacks.html" title="Segmented Stacks in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/TestSuiteMakefileGuide.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/TestSuiteMakefileGuide.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/TestSuiteMakefileGuide.html (added)
+++ www-releases/trunk/3.3/docs/TestSuiteMakefileGuide.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,346 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM test-suite Makefile Guide — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="up" title="LLVM Testing Infrastructure Guide" href="TestingGuide.html" />
+ <link rel="next" title="LLVM Tutorial: Table of Contents" href="tutorial/index.html" />
+ <link rel="prev" title="LLVM Testing Infrastructure Guide" href="TestingGuide.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="tutorial/index.html" title="LLVM Tutorial: Table of Contents"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TestingGuide.html" title="LLVM Testing Infrastructure Guide"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ <li><a href="TestingGuide.html" accesskey="U">LLVM Testing Infrastructure Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-test-suite-makefile-guide">
+<h1>LLVM test-suite Makefile Guide<a class="headerlink" href="#llvm-test-suite-makefile-guide" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
+<li><a class="reference internal" href="#test-suite-structure" id="id2">Test suite Structure</a></li>
+<li><a class="reference internal" href="#running-the-test-suite" id="id3">Running the test suite</a><ul>
+<li><a class="reference internal" href="#configuring-external-tests" id="id4">Configuring External Tests</a></li>
+<li><a class="reference internal" href="#running-different-tests" id="id5">Running different tests</a></li>
+<li><a class="reference internal" href="#generating-test-output" id="id6">Generating test output</a></li>
+<li><a class="reference internal" href="#writing-custom-tests-for-the-test-suite" id="id7">Writing custom tests for the test suite</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id1">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the features of the Makefile-based LLVM
+test-suite. This way of interacting with the test-suite is deprecated in
+favor of running the test-suite using LNT, but may continue to prove
+useful for some users. See the Testing Guide’s <a class="reference internal" href="TestingGuide.html#test-suite-quickstart"><em>test-suite Quickstart</em></a> section for more information.</p>
+</div>
+<div class="section" id="test-suite-structure">
+<h2><a class="toc-backref" href="#id2">Test suite Structure</a><a class="headerlink" href="#test-suite-structure" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">test-suite</span></tt> module contains a number of programs that can be
+compiled with LLVM and executed. These programs are compiled using the
+native compiler and various LLVM backends. The output from the program
+compiled with the native compiler is assumed correct; the results from
+the other programs are compared to the native program output and pass if
+they match.</p>
+<p>When executing tests, it is usually a good idea to start out with a
+subset of the available tests or programs. This makes test run times
+smaller at first and later on this is useful to investigate individual
+test failures. To run some test only on a subset of programs, simply
+change directory to the programs you want tested and run <tt class="docutils literal"><span class="pre">gmake</span></tt>
+there. Alternatively, you can run a different test using the <tt class="docutils literal"><span class="pre">TEST</span></tt>
+variable to change what tests or run on the selected programs (see below
+for more info).</p>
+<p>In addition for testing correctness, the <tt class="docutils literal"><span class="pre">test-suite</span></tt> directory also
+performs timing tests of various LLVM optimizations. It also records
+compilation times for the compilers and the JIT. This information can be
+used to compare the effectiveness of LLVM’s optimizations and code
+generation.</p>
+<p><tt class="docutils literal"><span class="pre">test-suite</span></tt> tests are divided into three types of tests: MultiSource,
+SingleSource, and External.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/SingleSource</span></tt></p>
+<p>The SingleSource directory contains test programs that are only a
+single source file in size. These are usually small benchmark
+programs or small programs that calculate a particular value. Several
+such programs are grouped together in each directory.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/MultiSource</span></tt></p>
+<p>The MultiSource directory contains subdirectories which contain
+entire programs with multiple source files. Large benchmarks and
+whole applications go here.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/External</span></tt></p>
+<p>The External directory contains Makefiles for building code that is
+external to (i.e., not distributed with) LLVM. The most prominent
+members of this directory are the SPEC 95 and SPEC 2000 benchmark
+suites. The <tt class="docutils literal"><span class="pre">External</span></tt> directory does not contain these actual
+tests, but only the Makefiles that know how to properly compile these
+programs from somewhere else. The presence and location of these
+external programs is configured by the test-suite <tt class="docutils literal"><span class="pre">configure</span></tt>
+script.</p>
+</li>
+</ul>
+<p>Each tree is then subdivided into several categories, including
+applications, benchmarks, regression tests, code that is strange
+grammatically, etc. These organizations should be relatively self
+explanatory.</p>
+<p>Some tests are known to fail. Some are bugs that we have not fixed yet;
+others are features that we haven’t added yet (or may never add). In the
+regression tests, the result for such tests will be XFAIL (eXpected
+FAILure). In this way, you can tell the difference between an expected
+and unexpected failure.</p>
+<p>The tests in the test suite have no such feature at this time. If the
+test passes, only warnings and other miscellaneous output will be
+generated. If a test fails, a large <program> FAILED message will be
+displayed. This will help you separate benign warnings from actual test
+failures.</p>
+</div>
+<div class="section" id="running-the-test-suite">
+<h2><a class="toc-backref" href="#id3">Running the test suite</a><a class="headerlink" href="#running-the-test-suite" title="Permalink to this headline">¶</a></h2>
+<p>First, all tests are executed within the LLVM object directory tree.
+They <em>are not</em> executed inside of the LLVM source tree. This is because
+the test suite creates temporary files during execution.</p>
+<p>To run the test suite, you need to use the following steps:</p>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">cd</span></tt> into the <tt class="docutils literal"><span class="pre">llvm/projects</span></tt> directory in your source tree.</p>
+</li>
+<li><p class="first">Check out the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module with:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% svn co http://llvm.org/svn/llvm-project/test-suite/trunk <span class="nb">test</span>-suite
+</pre></div>
+</div>
+<p>This will get the test suite into <tt class="docutils literal"><span class="pre">llvm/projects/test-suite</span></tt>.</p>
+</li>
+<li><p class="first">Configure and build <tt class="docutils literal"><span class="pre">llvm</span></tt>.</p>
+</li>
+<li><p class="first">Configure and build <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>.</p>
+</li>
+<li><p class="first">Install <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> somewhere.</p>
+</li>
+<li><p class="first"><em>Re-configure</em> <tt class="docutils literal"><span class="pre">llvm</span></tt> from the top level of each build tree (LLVM
+object directory tree) in which you want to run the test suite, just
+as you do before building LLVM.</p>
+<p>During the <em>re-configuration</em>, you must either: (1) have <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>
+you just built in your path, or (2) specify the directory where your
+just-built <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt> is installed using
+<tt class="docutils literal"><span class="pre">--with-llvmgccdir=$LLVM_GCC_DIR</span></tt>.</p>
+<p>You must also tell the configure machinery that the test suite is
+available so it can be configured for your build tree:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd</span> <span class="nv">$LLVM_OBJ_ROOT</span> ; <span class="nv">$LLVM_SRC_ROOT</span>/configure <span class="o">[</span>--with-llvmgccdir<span class="o">=</span><span class="nv">$LLVM_GCC_DIR</span><span class="o">]</span>
+</pre></div>
+</div>
+<p>[Remember that <tt class="docutils literal"><span class="pre">$LLVM_GCC_DIR</span></tt> is the directory where you
+<em>installed</em> llvm-gcc, not its src or obj directory.]</p>
+</li>
+<li><p class="first">You can now run the test suite from your build tree as follows:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd</span> <span class="nv">$LLVM_OBJ_ROOT</span>/projects/test-suite
+% make
+</pre></div>
+</div>
+</li>
+</ol>
+<p>Note that the second and third steps only need to be done once. After
+you have the suite checked out and configured, you don’t need to do it
+again (unless the test code or configure script changes).</p>
+<div class="section" id="configuring-external-tests">
+<h3><a class="toc-backref" href="#id4">Configuring External Tests</a><a class="headerlink" href="#configuring-external-tests" title="Permalink to this headline">¶</a></h3>
+<p>In order to run the External tests in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module, you
+must specify <em>–with-externals</em>. This must be done during the
+<em>re-configuration</em> step (see above), and the <tt class="docutils literal"><span class="pre">llvm</span></tt> re-configuration
+must recognize the previously-built <tt class="docutils literal"><span class="pre">llvm-gcc</span></tt>. If any of these is
+missing or neglected, the External tests won’t work.</p>
+<ul class="simple">
+<li><em>–with-externals</em></li>
+<li><em>–with-externals=<directory></em></li>
+</ul>
+<p>This tells LLVM where to find any external tests. They are expected to
+be in specifically named subdirectories of <<tt class="docutils literal"><span class="pre">directory</span></tt>>. If
+<tt class="docutils literal"><span class="pre">directory</span></tt> is left unspecified, <tt class="docutils literal"><span class="pre">configure</span></tt> uses the default value
+<tt class="docutils literal"><span class="pre">/home/vadve/shared/benchmarks/speccpu2000/benchspec</span></tt>. Subdirectory
+names known to LLVM include:</p>
+<ul class="simple">
+<li>spec95</li>
+<li>speccpu2000</li>
+<li>speccpu2006</li>
+<li>povray31</li>
+</ul>
+<p>Others are added from time to time, and can be determined from
+<tt class="docutils literal"><span class="pre">configure</span></tt>.</p>
+</div>
+<div class="section" id="running-different-tests">
+<h3><a class="toc-backref" href="#id5">Running different tests</a><a class="headerlink" href="#running-different-tests" title="Permalink to this headline">¶</a></h3>
+<p>In addition to the regular “whole program” tests, the <tt class="docutils literal"><span class="pre">test-suite</span></tt>
+module also provides a mechanism for compiling the programs in different
+ways. If the variable TEST is defined on the <tt class="docutils literal"><span class="pre">gmake</span></tt> command line, the
+test system will include a Makefile named
+<tt class="docutils literal"><span class="pre">TEST.<value</span> <span class="pre">of</span> <span class="pre">TEST</span> <span class="pre">variable>.Makefile</span></tt>. This Makefile can modify
+build rules to yield different results.</p>
+<p>For example, the LLVM nightly tester uses <tt class="docutils literal"><span class="pre">TEST.nightly.Makefile</span></tt> to
+create the nightly test reports. To run the nightly tests, run
+<tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TEST=nightly</span></tt>.</p>
+<p>There are several TEST Makefiles available in the tree. Some of them are
+designed for internal LLVM research and will not work outside of the
+LLVM research group. They may still be valuable, however, as a guide to
+writing your own TEST Makefile for any optimization or analysis passes
+that you develop with LLVM.</p>
+</div>
+<div class="section" id="generating-test-output">
+<h3><a class="toc-backref" href="#id6">Generating test output</a><a class="headerlink" href="#generating-test-output" title="Permalink to this headline">¶</a></h3>
+<p>There are a number of ways to run the tests and generate output. The
+most simple one is simply running <tt class="docutils literal"><span class="pre">gmake</span></tt> with no arguments. This will
+compile and run all programs in the tree using a number of different
+methods and compare results. Any failures are reported in the output,
+but are likely drowned in the other output. Passes are not reported
+explicitly.</p>
+<p>Somewhat better is running <tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TEST=sometest</span> <span class="pre">test</span></tt>, which runs the
+specified test and usually adds per-program summaries to the output
+(depending on which sometest you use). For example, the <tt class="docutils literal"><span class="pre">nightly</span></tt> test
+explicitly outputs TEST-PASS or TEST-FAIL for every test after each
+program. Though these lines are still drowned in the output, it’s easy
+to grep the output logs in the Output directories.</p>
+<p>Even better are the <tt class="docutils literal"><span class="pre">report</span></tt> and <tt class="docutils literal"><span class="pre">report.format</span></tt> targets (where
+<tt class="docutils literal"><span class="pre">format</span></tt> is one of <tt class="docutils literal"><span class="pre">html</span></tt>, <tt class="docutils literal"><span class="pre">csv</span></tt>, <tt class="docutils literal"><span class="pre">text</span></tt> or <tt class="docutils literal"><span class="pre">graphs</span></tt>). The
+exact contents of the report are dependent on which <tt class="docutils literal"><span class="pre">TEST</span></tt> you are
+running, but the text results are always shown at the end of the run and
+the results are always stored in the <tt class="docutils literal"><span class="pre">report.<type>.format</span></tt> file (when
+running with <tt class="docutils literal"><span class="pre">TEST=<type></span></tt>). The <tt class="docutils literal"><span class="pre">report</span></tt> also generate a file
+called <tt class="docutils literal"><span class="pre">report.<type>.raw.out</span></tt> containing the output of the entire
+test run.</p>
+</div>
+<div class="section" id="writing-custom-tests-for-the-test-suite">
+<h3><a class="toc-backref" href="#id7">Writing custom tests for the test suite</a><a class="headerlink" href="#writing-custom-tests-for-the-test-suite" title="Permalink to this headline">¶</a></h3>
+<p>Assuming you can run the test suite, (e.g.
+“<tt class="docutils literal"><span class="pre">gmake</span> <span class="pre">TEST=nightly</span> <span class="pre">report</span></tt>” should work), it is really easy to run
+optimizations or code generator components against every program in the
+tree, collecting statistics or running custom checks for correctness. At
+base, this is how the nightly tester works, it’s just one example of a
+general framework.</p>
+<p>Lets say that you have an LLVM optimization pass, and you want to see
+how many times it triggers. First thing you should do is add an LLVM
+<a class="reference external" href="ProgrammersManual.html#Statistic">statistic</a> to your pass, which will
+tally counts of things you care about.</p>
+<p>Following this, you can set up a test and a report that collects these
+and formats them for easy viewing. This consists of two files, a
+“<tt class="docutils literal"><span class="pre">test-suite/TEST.XXX.Makefile</span></tt>” fragment (where XXX is the name of
+your test) and a “<tt class="docutils literal"><span class="pre">test-suite/TEST.XXX.report</span></tt>” file that indicates
+how to format the output into a table. There are many example reports of
+various levels of sophistication included with the test suite, and the
+framework is very general.</p>
+<p>If you are interested in testing an optimization pass, check out the
+“libcalls” test as an example. It can be run like this:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd </span>llvm/projects/test-suite/MultiSource/Benchmarks <span class="c"># or some other level</span>
+% make <span class="nv">TEST</span><span class="o">=</span>libcalls report
+</pre></div>
+</div>
+<p>This will do a bunch of stuff, then eventually print a table like this:</p>
+<div class="highlight-python"><pre>Name | total | #exit |
+...
+FreeBench/analyzer/analyzer | 51 | 6 |
+FreeBench/fourinarow/fourinarow | 1 | 1 |
+FreeBench/neural/neural | 19 | 9 |
+FreeBench/pifft/pifft | 5 | 3 |
+MallocBench/cfrac/cfrac | 1 | * |
+MallocBench/espresso/espresso | 52 | 12 |
+MallocBench/gs/gs | 4 | * |
+Prolangs-C/TimberWolfMC/timberwolfmc | 302 | * |
+Prolangs-C/agrep/agrep | 33 | 12 |
+Prolangs-C/allroots/allroots | * | * |
+Prolangs-C/assembler/assembler | 47 | * |
+Prolangs-C/bison/mybison | 74 | * |
+...</pre>
+</div>
+<p>This basically is grepping the -stats output and displaying it in a
+table. You can also use the “TEST=libcalls report.html” target to get
+the table in HTML form, similarly for report.csv and report.tex.</p>
+<p>The source for this is in <tt class="docutils literal"><span class="pre">test-suite/TEST.libcalls.*</span></tt>. The format is
+pretty simple: the Makefile indicates how to run the test (in this case,
+“<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-simplify-libcalls</span> <span class="pre">-stats</span></tt>”), and the report contains one line
+for each column of the output. The first value is the header for the
+column and the second is the regex to grep the output of the command
+for. There are lots of example reports that can do fancy stuff.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="tutorial/index.html" title="LLVM Tutorial: Table of Contents"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TestingGuide.html" title="LLVM Testing Infrastructure Guide"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ <li><a href="TestingGuide.html" >LLVM Testing Infrastructure Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/TestingGuide.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/TestingGuide.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/TestingGuide.html (added)
+++ www-releases/trunk/3.3/docs/TestingGuide.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,497 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Testing Infrastructure Guide — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="LLVM test-suite Makefile Guide" href="TestSuiteMakefileGuide.html" />
+ <link rel="prev" title="Code Reviews with Phabricator" href="Phabricator.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="TestSuiteMakefileGuide.html" title="LLVM test-suite Makefile Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Phabricator.html" title="Code Reviews with Phabricator"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-testing-infrastructure-guide">
+<h1>LLVM Testing Infrastructure Guide<a class="headerlink" href="#llvm-testing-infrastructure-guide" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id4">Overview</a></li>
+<li><a class="reference internal" href="#requirements" id="id5">Requirements</a></li>
+<li><a class="reference internal" href="#llvm-testing-infrastructure-organization" id="id6">LLVM testing infrastructure organization</a><ul>
+<li><a class="reference internal" href="#regression-tests" id="id7">Regression tests</a></li>
+<li><a class="reference internal" href="#test-suite" id="id8"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a></li>
+<li><a class="reference internal" href="#debugging-information-tests" id="id9">Debugging Information tests</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#quick-start" id="id10">Quick start</a><ul>
+<li><a class="reference internal" href="#id1" id="id11">Regression tests</a></li>
+<li><a class="reference internal" href="#id2" id="id12">Debugging Information tests</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#regression-test-structure" id="id13">Regression test structure</a><ul>
+<li><a class="reference internal" href="#writing-new-regression-tests" id="id14">Writing new regression tests</a></li>
+<li><a class="reference internal" href="#fragile-tests" id="id15">Fragile tests</a></li>
+<li><a class="reference internal" href="#variables-and-substitutions" id="id16">Variables and substitutions</a></li>
+<li><a class="reference internal" href="#other-features" id="id17">Other Features</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#test-suite-overview" id="id18"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Overview</a><ul>
+<li><a class="reference internal" href="#test-suite-quickstart" id="id19"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Quickstart</a></li>
+<li><a class="reference internal" href="#test-suite-makefiles" id="id20"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Makefiles</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id4">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>This document is the reference manual for the LLVM testing
+infrastructure. It documents the structure of the LLVM testing
+infrastructure, the tools needed to use it, and how to add and run
+tests.</p>
+</div>
+<div class="section" id="requirements">
+<h2><a class="toc-backref" href="#id5">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
+<p>In order to use the LLVM testing infrastructure, you will need all of
+the software required to build LLVM, as well as
+<a class="reference external" href="http://python.org">Python</a> 2.4 or later.</p>
+</div>
+<div class="section" id="llvm-testing-infrastructure-organization">
+<h2><a class="toc-backref" href="#id6">LLVM testing infrastructure organization</a><a class="headerlink" href="#llvm-testing-infrastructure-organization" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM testing infrastructure contains two major categories of tests:
+regression tests and whole programs. The regression tests are contained
+inside the LLVM repository itself under <tt class="docutils literal"><span class="pre">llvm/test</span></tt> and are expected
+to always pass – they should be run before every commit.</p>
+<p>The whole programs tests are referred to as the “LLVM test suite” (or
+“test-suite”) and are in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module in subversion. For
+historical reasons, these tests are also referred to as the “nightly
+tests” in places, which is less ambiguous than “test-suite” and remains
+in use although we run them much more often than nightly.</p>
+<div class="section" id="regression-tests">
+<h3><a class="toc-backref" href="#id7">Regression tests</a><a class="headerlink" href="#regression-tests" title="Permalink to this headline">¶</a></h3>
+<p>The regression tests are small pieces of code that test a specific
+feature of LLVM or trigger a specific bug in LLVM. The language they are
+written in depends on the part of LLVM being tested. These tests are driven by
+the <a class="reference internal" href="CommandGuide/lit.html"><em>Lit</em></a> testing tool (which is part of LLVM), and
+are located in the <tt class="docutils literal"><span class="pre">llvm/test</span></tt> directory.</p>
+<p>Typically when a bug is found in LLVM, a regression test containing just
+enough code to reproduce the problem should be written and placed
+somewhere underneath this directory. For example, it can be a small
+piece of LLVM IR distilled from an actual application or benchmark.</p>
+</div>
+<div class="section" id="test-suite">
+<h3><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">test-suite</span></tt></a><a class="headerlink" href="#test-suite" title="Permalink to this headline">¶</a></h3>
+<p>The test suite contains whole programs, which are pieces of code which
+can be compiled and linked into a stand-alone program that can be
+executed. These programs are generally written in high level languages
+such as C or C++.</p>
+<p>These programs are compiled using a user specified compiler and set of
+flags, and then executed to capture the program output and timing
+information. The output of these programs is compared to a reference
+output to ensure that the program is being compiled correctly.</p>
+<p>In addition to compiling and executing programs, whole program tests
+serve as a way of benchmarking LLVM performance, both in terms of the
+efficiency of the programs generated as well as the speed with which
+LLVM compiles, optimizes, and generates code.</p>
+<p>The test-suite is located in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> Subversion module.</p>
+</div>
+<div class="section" id="debugging-information-tests">
+<h3><a class="toc-backref" href="#id9">Debugging Information tests</a><a class="headerlink" href="#debugging-information-tests" title="Permalink to this headline">¶</a></h3>
+<p>The test suite contains tests to check quality of debugging information.
+The test are written in C based languages or in LLVM assembly language.</p>
+<p>These tests are compiled and run under a debugger. The debugger output
+is checked to validate of debugging information. See README.txt in the
+test suite for more information . This test suite is located in the
+<tt class="docutils literal"><span class="pre">debuginfo-tests</span></tt> Subversion module.</p>
+</div>
+</div>
+<div class="section" id="quick-start">
+<h2><a class="toc-backref" href="#id10">Quick start</a><a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
+<p>The tests are located in two separate Subversion modules. The
+regressions tests are in the main “llvm” module under the directory
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> (so you get these tests for free with the main LLVM tree).
+Use <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-all</span></tt> to run the regression tests after building LLVM.</p>
+<p>The more comprehensive test suite that includes whole programs in C and C++
+is in the <tt class="docutils literal"><span class="pre">test-suite</span></tt> module. See <a class="reference internal" href="#test-suite-quickstart"><em>test-suite Quickstart</em></a> for more information on running these tests.</p>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id11">Regression tests</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>To run all of the LLVM regression tests, use the master Makefile in the
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> directory. LLVM Makefiles require GNU Make (read the <a class="reference internal" href="MakefileGuide.html"><em>LLVM
+Makefile Guide</em></a> for more details):</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make -C llvm/test
+</pre></div>
+</div>
+<p>or:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make check
+</pre></div>
+</div>
+<p>If you have <a class="reference external" href="http://clang.llvm.org/">Clang</a> checked out and built, you
+can run the LLVM and Clang tests simultaneously using:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make check-all
+</pre></div>
+</div>
+<p>To run the tests with Valgrind (Memcheck by default), just append
+<tt class="docutils literal"><span class="pre">VG=1</span></tt> to the commands above, e.g.:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% make check <span class="nv">VG</span><span class="o">=</span>1
+</pre></div>
+</div>
+<p>To run individual tests or subsets of tests, you can use the <tt class="docutils literal"><span class="pre">llvm-lit</span></tt>
+script which is built as part of LLVM. For example, to run the
+<tt class="docutils literal"><span class="pre">Integer/BitPacked.ll</span></tt> test by itself you can run:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% llvm-lit ~/llvm/test/Integer/BitPacked.ll
+</pre></div>
+</div>
+<p>or to run all of the ARM CodeGen tests:</p>
+<div class="highlight-bash"><div class="highlight"><pre>% llvm-lit ~/llvm/test/CodeGen/ARM
+</pre></div>
+</div>
+<p>For more information on using the <strong class="program">lit</strong> tool, see <tt class="docutils literal"><span class="pre">llvm-lit</span> <span class="pre">--help</span></tt>
+or the <a class="reference internal" href="CommandGuide/lit.html"><em>lit man page</em></a>.</p>
+</div>
+<div class="section" id="id2">
+<h3><a class="toc-backref" href="#id12">Debugging Information tests</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<p>To run debugging information tests simply checkout the tests inside
+clang/test directory.</p>
+<div class="highlight-bash"><div class="highlight"><pre>% <span class="nb">cd </span>clang/test
+% svn co http://llvm.org/svn/llvm-project/debuginfo-tests/trunk debuginfo-tests
+</pre></div>
+</div>
+<p>These tests are already set up to run as part of clang regression tests.</p>
+</div>
+</div>
+<div class="section" id="regression-test-structure">
+<h2><a class="toc-backref" href="#id13">Regression test structure</a><a class="headerlink" href="#regression-test-structure" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM regression tests are driven by <strong class="program">lit</strong> and are located in the
+<tt class="docutils literal"><span class="pre">llvm/test</span></tt> directory.</p>
+<p>This directory contains a large array of small tests that exercise
+various features of LLVM and to ensure that regressions do not occur.
+The directory is broken into several sub-directories, each focused on a
+particular area of LLVM.</p>
+<div class="section" id="writing-new-regression-tests">
+<h3><a class="toc-backref" href="#id14">Writing new regression tests</a><a class="headerlink" href="#writing-new-regression-tests" title="Permalink to this headline">¶</a></h3>
+<p>The regression test structure is very simple, but does require some
+information to be set. This information is gathered via <tt class="docutils literal"><span class="pre">configure</span></tt>
+and is written to a file, <tt class="docutils literal"><span class="pre">test/lit.site.cfg</span></tt> in the build directory.
+The <tt class="docutils literal"><span class="pre">llvm/test</span></tt> Makefile does this work for you.</p>
+<p>In order for the regression tests to work, each directory of tests must
+have a <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> file. <strong class="program">lit</strong> looks for this file to determine
+how to run the tests. This file is just Python code and thus is very
+flexible, but we’ve standardized it for the LLVM regression tests. If
+you’re adding a directory of tests, just copy <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> from
+another directory to get running. The standard <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> simply
+specifies which files to look in for tests. Any directory that contains
+only directories does not need the <tt class="docutils literal"><span class="pre">lit.local.cfg</span></tt> file. Read the <a class="reference internal" href="CommandGuide/lit.html"><em>Lit
+documentation</em></a> for more information.</p>
+<p>Each test file must contain lines starting with “RUN:” that tell <strong class="program">lit</strong>
+how to run it. If there are no RUN lines, <strong class="program">lit</strong> will issue an error
+while running a test.</p>
+<p>RUN lines are specified in the comments of the test program using the
+keyword <tt class="docutils literal"><span class="pre">RUN</span></tt> followed by a colon, and lastly the command (pipeline)
+to execute. Together, these lines form the “script” that <strong class="program">lit</strong>
+executes to run the test case. The syntax of the RUN lines is similar to a
+shell’s syntax for pipelines including I/O redirection and variable
+substitution. However, even though these lines may <em>look</em> like a shell
+script, they are not. RUN lines are interpreted by <strong class="program">lit</strong>.
+Consequently, the syntax differs from shell in a few ways. You can specify
+as many RUN lines as needed.</p>
+<p><strong class="program">lit</strong> performs substitution on each RUN line to replace LLVM tool names
+with the full paths to the executable built for each tool (in
+<tt class="docutils literal"><span class="pre">$(LLVM_OBJ_ROOT)/$(BuildMode)/bin)</span></tt>. This ensures that <strong class="program">lit</strong> does
+not invoke any stray LLVM tools in the user’s path during testing.</p>
+<p>Each RUN line is executed on its own, distinct from other lines unless
+its last character is <tt class="docutils literal"><span class="pre">\</span></tt>. This continuation character causes the RUN
+line to be concatenated with the next one. In this way you can build up
+long pipelines of commands without making huge line lengths. The lines
+ending in <tt class="docutils literal"><span class="pre">\</span></tt> are concatenated until a RUN line that doesn’t end in
+<tt class="docutils literal"><span class="pre">\</span></tt> is found. This concatenated set of RUN lines then constitutes one
+execution. <strong class="program">lit</strong> will substitute variables and arrange for the pipeline
+to be executed. If any process in the pipeline fails, the entire line (and
+test case) fails too.</p>
+<p>Below is an example of legal RUN lines in a <tt class="docutils literal"><span class="pre">.ll</span></tt> file:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: llvm-as < %s | llvm-dis > %t1</span>
+<span class="c">; RUN: llvm-dis < %s.bc-13 > %t2</span>
+<span class="c">; RUN: diff %t1 %t2</span>
+</pre></div>
+</div>
+<p>As with a Unix shell, the RUN lines permit pipelines and I/O
+redirection to be used.</p>
+<p>There are some quoting rules that you must pay attention to when writing
+your RUN lines. In general nothing needs to be quoted. <strong class="program">lit</strong> won’t
+strip off any quote characters so they will get passed to the invoked program.
+To avoid this use curly braces to tell <strong class="program">lit</strong> that it should treat
+everything enclosed as one value.</p>
+<p>In general, you should strive to keep your RUN lines as simple as possible,
+using them only to run tools that generate textual output you can then examine.
+The recommended way to examine output to figure out if the test passes is using
+the <a class="reference internal" href="CommandGuide/FileCheck.html"><em>FileCheck tool</em></a>. <em>[The usage of grep in RUN
+lines is deprecated - please do not send or commit patches that use it.]</em></p>
+</div>
+<div class="section" id="fragile-tests">
+<h3><a class="toc-backref" href="#id15">Fragile tests</a><a class="headerlink" href="#fragile-tests" title="Permalink to this headline">¶</a></h3>
+<p>It is easy to write a fragile test that would fail spuriously if the tool being
+tested outputs a full path to the input file. For example, <strong class="program">opt</strong> by
+default outputs a <tt class="docutils literal"><span class="pre">ModuleID</span></tt>:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat example.ll
+<span class="go">define i32 @main() nounwind {</span>
+<span class="go"> ret i32 0</span>
+<span class="go">}</span>
+
+<span class="gp">$</span> opt -S /path/to/example.ll
+<span class="go">; ModuleID = '/path/to/example.ll'</span>
+
+<span class="go">define i32 @main() nounwind {</span>
+<span class="go"> ret i32 0</span>
+<span class="go">}</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">ModuleID</span></tt> can unexpetedly match against <tt class="docutils literal"><span class="pre">CHECK</span></tt> lines. For example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; RUN: opt -S %s | FileCheck</span>
+
+<span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="k">nounwind</span> <span class="p">{</span>
+ <span class="c">; CHECK-NOT: load</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This test will fail if placed into a <tt class="docutils literal"><span class="pre">download</span></tt> directory.</p>
+<p>To make your tests robust, always use <tt class="docutils literal"><span class="pre">opt</span> <span class="pre">...</span> <span class="pre"><</span> <span class="pre">%s</span></tt> in the RUN line.
+<strong class="program">opt</strong> does not output a <tt class="docutils literal"><span class="pre">ModuleID</span></tt> when input comes from stdin.</p>
+</div>
+<div class="section" id="variables-and-substitutions">
+<h3><a class="toc-backref" href="#id16">Variables and substitutions</a><a class="headerlink" href="#variables-and-substitutions" title="Permalink to this headline">¶</a></h3>
+<p>With a RUN line there are a number of substitutions that are permitted.
+To make a substitution just write the variable’s name preceded by a <tt class="docutils literal"><span class="pre">$</span></tt>.
+Additionally, for compatibility reasons with previous versions of the
+test library, certain names can be accessed with an alternate syntax: a
+% prefix. These alternates are deprecated and may go away in a future
+version.</p>
+<p>Here are the available variable names. The alternate syntax is listed in
+parentheses.</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">$test</span></tt> (<tt class="docutils literal"><span class="pre">%s</span></tt>)</dt>
+<dd>The full path to the test case’s source. This is suitable for passing on
+the command line as the input to an LLVM tool.</dd>
+<dt><tt class="docutils literal"><span class="pre">%(line)</span></tt>, <tt class="docutils literal"><span class="pre">%(line+<number>)</span></tt>, <tt class="docutils literal"><span class="pre">%(line-<number>)</span></tt></dt>
+<dd>The number of the line where this variable is used, with an optional
+integer offset. This can be used in tests with multiple RUN lines,
+which reference test file’s line numbers.</dd>
+<dt><tt class="docutils literal"><span class="pre">$srcdir</span></tt></dt>
+<dd>The source directory from where the <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check</span></tt> was run.</dd>
+<dt><tt class="docutils literal"><span class="pre">objdir</span></tt></dt>
+<dd>The object directory that corresponds to the <tt class="docutils literal"><span class="pre">$srcdir</span></tt>.</dd>
+<dt><tt class="docutils literal"><span class="pre">subdir</span></tt></dt>
+<dd>A partial path from the <tt class="docutils literal"><span class="pre">test</span></tt> directory that contains the
+sub-directory that contains the test source being executed.</dd>
+<dt><tt class="docutils literal"><span class="pre">srcroot</span></tt></dt>
+<dd>The root directory of the LLVM src tree.</dd>
+<dt><tt class="docutils literal"><span class="pre">objroot</span></tt></dt>
+<dd>The root directory of the LLVM object tree. This could be the same as
+the srcroot.</dd>
+<dt><tt class="docutils literal"><span class="pre">path</span></tt></dt>
+<dd>The path to the directory that contains the test case source. This is
+for locating any supporting files that are not generated by the test,
+but used by the test.</dd>
+<dt><tt class="docutils literal"><span class="pre">tmp</span></tt></dt>
+<dd>The path to a temporary file name that could be used for this test case.
+The file name won’t conflict with other test cases. You can append to it
+if you need multiple temporaries. This is useful as the destination of
+some redirected output.</dd>
+<dt><tt class="docutils literal"><span class="pre">target_triplet</span></tt> (<tt class="docutils literal"><span class="pre">%target_triplet</span></tt>)</dt>
+<dd>The target triplet that corresponds to the current host machine (the one
+running the test cases). This should probably be called “host”.</dd>
+<dt><tt class="docutils literal"><span class="pre">link</span></tt> (<tt class="docutils literal"><span class="pre">%link</span></tt>)</dt>
+<dd>This full link command used to link LLVM executables. This has all the
+configured <tt class="docutils literal"><span class="pre">-I</span></tt>, <tt class="docutils literal"><span class="pre">-L</span></tt> and <tt class="docutils literal"><span class="pre">-l</span></tt> options.</dd>
+<dt><tt class="docutils literal"><span class="pre">shlibext</span></tt> (<tt class="docutils literal"><span class="pre">%shlibext</span></tt>)</dt>
+<dd>The suffix for the host platforms shared library (DLL) files. This
+includes the period as the first character.</dd>
+</dl>
+<p>To add more variables, look at <tt class="docutils literal"><span class="pre">test/lit.cfg</span></tt>.</p>
+</div>
+<div class="section" id="other-features">
+<h3><a class="toc-backref" href="#id17">Other Features</a><a class="headerlink" href="#other-features" title="Permalink to this headline">¶</a></h3>
+<p>To make RUN line writing easier, there are several helper scripts and programs
+in the <tt class="docutils literal"><span class="pre">llvm/test/Scripts</span></tt> directory. This directory is in the PATH
+when running tests, so you can just call these scripts using their name.
+For example:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">ignore</span></tt></dt>
+<dd>This script runs its arguments and then always returns 0. This is useful
+in cases where the test needs to cause a tool to generate an error (e.g.
+to check the error output). However, any program in a pipeline that
+returns a non-zero result will cause the test to fail. This script
+overcomes that issue and nicely documents that the test case is
+purposefully ignoring the result code of the tool</dd>
+<dt><tt class="docutils literal"><span class="pre">not</span></tt></dt>
+<dd>This script runs its arguments and then inverts the result code from it.
+Zero result codes become 1. Non-zero result codes become 0.</dd>
+</dl>
+<p>Sometimes it is necessary to mark a test case as “expected fail” or
+XFAIL. You can easily mark a test as XFAIL just by including <tt class="docutils literal"><span class="pre">XFAIL:</span></tt>
+on a line near the top of the file. This signals that the test case
+should succeed if the test fails. Such test cases are counted separately
+by the testing tool. To specify an expected fail, use the XFAIL keyword
+in the comments of the test program followed by a colon and one or more
+failure patterns. Each failure pattern can be either <tt class="docutils literal"><span class="pre">*</span></tt> (to specify
+fail everywhere), or a part of a target triple (indicating the test
+should fail on that platform), or the name of a configurable feature
+(for example, <tt class="docutils literal"><span class="pre">loadable_module</span></tt>). If there is a match, the test is
+expected to fail. If not, the test is expected to succeed. To XFAIL
+everywhere just specify <tt class="docutils literal"><span class="pre">XFAIL:</span> <span class="pre">*</span></tt>. Here is an example of an <tt class="docutils literal"><span class="pre">XFAIL</span></tt>
+line:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">; XFAIL: darwin,sun</span>
+</pre></div>
+</div>
+<p>To make the output more useful, <strong class="program">lit</strong> will scan
+the lines of the test case for ones that contain a pattern that matches
+<tt class="docutils literal"><span class="pre">PR[0-9]+</span></tt>. This is the syntax for specifying a PR (Problem Report) number
+that is related to the test case. The number after “PR” specifies the
+LLVM bugzilla number. When a PR number is specified, it will be used in
+the pass/fail reporting. This is useful to quickly get some context when
+a test fails.</p>
+<p>Finally, any line that contains “END.” will cause the special
+interpretation of lines to terminate. This is generally done right after
+the last RUN: line. This has two side effects:</p>
+<ol class="loweralpha simple">
+<li>it prevents special interpretation of lines that are part of the test
+program, not the instructions to the test case, and</li>
+<li>it speeds things up for really big test cases by avoiding
+interpretation of the remainder of the file.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="test-suite-overview">
+<h2><a class="toc-backref" href="#id18"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Overview</a><a class="headerlink" href="#test-suite-overview" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">test-suite</span></tt> module contains a number of programs that can be
+compiled and executed. The <tt class="docutils literal"><span class="pre">test-suite</span></tt> includes reference outputs for
+all of the programs, so that the output of the executed program can be
+checked for correctness.</p>
+<p><tt class="docutils literal"><span class="pre">test-suite</span></tt> tests are divided into three types of tests: MultiSource,
+SingleSource, and External.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/SingleSource</span></tt></p>
+<p>The SingleSource directory contains test programs that are only a
+single source file in size. These are usually small benchmark
+programs or small programs that calculate a particular value. Several
+such programs are grouped together in each directory.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/MultiSource</span></tt></p>
+<p>The MultiSource directory contains subdirectories which contain
+entire programs with multiple source files. Large benchmarks and
+whole applications go here.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">test-suite/External</span></tt></p>
+<p>The External directory contains Makefiles for building code that is
+external to (i.e., not distributed with) LLVM. The most prominent
+members of this directory are the SPEC 95 and SPEC 2000 benchmark
+suites. The <tt class="docutils literal"><span class="pre">External</span></tt> directory does not contain these actual
+tests, but only the Makefiles that know how to properly compile these
+programs from somewhere else. When using <tt class="docutils literal"><span class="pre">LNT</span></tt>, use the
+<tt class="docutils literal"><span class="pre">--test-externals</span></tt> option to include these tests in the results.</p>
+</li>
+</ul>
+<div class="section" id="test-suite-quickstart">
+<span id="id3"></span><h3><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Quickstart</a><a class="headerlink" href="#test-suite-quickstart" title="Permalink to this headline">¶</a></h3>
+<p>The modern way of running the <tt class="docutils literal"><span class="pre">test-suite</span></tt> is focused on testing and
+benchmarking complete compilers using the
+<a class="reference external" href="http://llvm.org/docs/lnt">LNT</a> testing infrastructure.</p>
+<p>For more information on using LNT to execute the <tt class="docutils literal"><span class="pre">test-suite</span></tt>, please
+see the <a class="reference external" href="http://llvm.org/docs/lnt/quickstart.html">LNT Quickstart</a>
+documentation.</p>
+</div>
+<div class="section" id="test-suite-makefiles">
+<h3><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">test-suite</span></tt> Makefiles</a><a class="headerlink" href="#test-suite-makefiles" title="Permalink to this headline">¶</a></h3>
+<p>Historically, the <tt class="docutils literal"><span class="pre">test-suite</span></tt> was executed using a complicated setup
+of Makefiles. The LNT based approach above is recommended for most
+users, but there are some testing scenarios which are not supported by
+the LNT approach. In addition, LNT currently uses the Makefile setup
+under the covers and so developers who are interested in how LNT works
+under the hood may want to understand the Makefile based setup.</p>
+<p>For more information on the <tt class="docutils literal"><span class="pre">test-suite</span></tt> Makefile setup, please see
+the <a class="reference internal" href="TestSuiteMakefileGuide.html"><em>Test Suite Makefile Guide</em></a>.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="TestSuiteMakefileGuide.html" title="LLVM test-suite Makefile Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Phabricator.html" title="Code Reviews with Phabricator"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/Vectorizers.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/Vectorizers.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/Vectorizers.html (added)
+++ www-releases/trunk/3.3/docs/Vectorizers.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,476 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Auto-Vectorization in LLVM — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="Writing an LLVM Compiler Backend" href="WritingAnLLVMBackend.html" />
+ <link rel="prev" title="Source Level Debugging with LLVM" href="SourceLevelDebugging.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Compiler Backend"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="auto-vectorization-in-llvm">
+<h1>Auto-Vectorization in LLVM<a class="headerlink" href="#auto-vectorization-in-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#the-loop-vectorizer" id="id2">The Loop Vectorizer</a><ul>
+<li><a class="reference internal" href="#usage" id="id3">Usage</a><ul>
+<li><a class="reference internal" href="#command-line-flags" id="id4">Command line flags</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#features" id="id5">Features</a><ul>
+<li><a class="reference internal" href="#loops-with-unknown-trip-count" id="id6">Loops with unknown trip count</a></li>
+<li><a class="reference internal" href="#runtime-checks-of-pointers" id="id7">Runtime Checks of Pointers</a></li>
+<li><a class="reference internal" href="#reductions" id="id8">Reductions</a></li>
+<li><a class="reference internal" href="#inductions" id="id9">Inductions</a></li>
+<li><a class="reference internal" href="#if-conversion" id="id10">If Conversion</a></li>
+<li><a class="reference internal" href="#pointer-induction-variables" id="id11">Pointer Induction Variables</a></li>
+<li><a class="reference internal" href="#reverse-iterators" id="id12">Reverse Iterators</a></li>
+<li><a class="reference internal" href="#scatter-gather" id="id13">Scatter / Gather</a></li>
+<li><a class="reference internal" href="#vectorization-of-mixed-types" id="id14">Vectorization of Mixed Types</a></li>
+<li><a class="reference internal" href="#global-structures-alias-analysis" id="id15">Global Structures Alias Analysis</a></li>
+<li><a class="reference internal" href="#vectorization-of-function-calls" id="id16">Vectorization of function calls</a></li>
+<li><a class="reference internal" href="#partial-unrolling-during-vectorization" id="id17">Partial unrolling during vectorization</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#performance" id="id18">Performance</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-slp-vectorizer" id="id19">The SLP Vectorizer</a><ul>
+<li><a class="reference internal" href="#details" id="id20">Details</a></li>
+<li><a class="reference internal" href="#id1" id="id21">Usage</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<p>LLVM has two vectorizers: The <a class="reference internal" href="#loop-vectorizer"><em>Loop Vectorizer</em></a>,
+which operates on Loops, and the <a class="reference internal" href="#slp-vectorizer"><em>SLP Vectorizer</em></a>, which optimizes straight-line code. These vectorizers
+focus on different optimization opportunities and use different techniques.
+The SLP vectorizer merges multiple scalars that are found in the code into
+vectors while the Loop Vectorizer widens instructions in the original loop
+to operate on multiple consecutive loop iterations.</p>
+<div class="section" id="the-loop-vectorizer">
+<span id="loop-vectorizer"></span><h2><a class="toc-backref" href="#id2">The Loop Vectorizer</a><a class="headerlink" href="#the-loop-vectorizer" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="usage">
+<h3><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h3>
+<p>LLVM’s Loop Vectorizer is now enabled by default for -O3.
+We plan to enable parts of the Loop Vectorizer on -O2 and -Os in future releases.
+The vectorizer can be disabled using the command line:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang ... -fno-vectorize file.c
+</pre></div>
+</div>
+<div class="section" id="command-line-flags">
+<h4><a class="toc-backref" href="#id4">Command line flags</a><a class="headerlink" href="#command-line-flags" title="Permalink to this headline">¶</a></h4>
+<p>The loop vectorizer uses a cost model to decide on the optimal vectorization factor
+and unroll factor. However, users of the vectorizer can force the vectorizer to use
+specific values. Both ‘clang’ and ‘opt’ support the flags below.</p>
+<p>Users can control the vectorization SIMD width using the command line flag “-force-vector-width”.</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -mllvm -force-vector-width<span class="o">=</span>8 ...
+<span class="gp">$</span> opt -loop-vectorize -force-vector-width<span class="o">=</span>8 ...
+</pre></div>
+</div>
+<p>Users can control the unroll factor using the command line flag “-force-vector-unroll”</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -mllvm -force-vector-unroll<span class="o">=</span>2 ...
+<span class="gp">$</span> opt -loop-vectorize -force-vector-unroll<span class="o">=</span>2 ...
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="features">
+<h3><a class="toc-backref" href="#id5">Features</a><a class="headerlink" href="#features" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM Loop Vectorizer has a number of features that allow it to vectorize
+complex loops.</p>
+<div class="section" id="loops-with-unknown-trip-count">
+<h4><a class="toc-backref" href="#id6">Loops with unknown trip count</a><a class="headerlink" href="#loops-with-unknown-trip-count" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer supports loops with an unknown trip count.
+In the loop below, the iteration <tt class="docutils literal"><span class="pre">start</span></tt> and <tt class="docutils literal"><span class="pre">finish</span></tt> points are unknown,
+and the Loop Vectorizer has a mechanism to vectorize loops that do not start
+at zero. In this example, ‘n’ may not be a multiple of the vector width, and
+the vectorizer has to execute the last few iterations as scalar code. Keeping
+a scalar copy of the loop increases the code size.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">float</span> <span class="n">K</span><span class="p">,</span> <span class="kt">int</span> <span class="n">start</span><span class="p">,</span> <span class="kt">int</span> <span class="n">end</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">start</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">end</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*=</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="n">K</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="runtime-checks-of-pointers">
+<h4><a class="toc-backref" href="#id7">Runtime Checks of Pointers</a><a class="headerlink" href="#runtime-checks-of-pointers" title="Permalink to this headline">¶</a></h4>
+<p>In the example below, if the pointers A and B point to consecutive addresses,
+then it is illegal to vectorize the code because some elements of A will be
+written before they are read from array B.</p>
+<p>Some programmers use the ‘restrict’ keyword to notify the compiler that the
+pointers are disjointed, but in our example, the Loop Vectorizer has no way of
+knowing that the pointers A and B are unique. The Loop Vectorizer handles this
+loop by placing code that checks, at runtime, if the arrays A and B point to
+disjointed memory locations. If arrays A and B overlap, then the scalar version
+of the loop is executed.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">float</span> <span class="n">K</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">*=</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="n">K</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="reductions">
+<h4><a class="toc-backref" href="#id8">Reductions</a><a class="headerlink" href="#reductions" title="Permalink to this headline">¶</a></h4>
+<p>In this example the <tt class="docutils literal"><span class="pre">sum</span></tt> variable is used by consecutive iterations of
+the loop. Normally, this would prevent vectorization, but the vectorizer can
+detect that ‘sum’ is a reduction variable. The variable ‘sum’ becomes a vector
+of integers, and at the end of the loop the elements of the array are added
+together to create the correct result. We support a number of different
+reduction operations, such as addition, multiplication, XOR, AND and OR.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">sum</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">5</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">sum</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>We support floating point reduction operations when <cite>-ffast-math</cite> is used.</p>
+</div>
+<div class="section" id="inductions">
+<h4><a class="toc-backref" href="#id9">Inductions</a><a class="headerlink" href="#inductions" title="Permalink to this headline">¶</a></h4>
+<p>In this example the value of the induction variable <tt class="docutils literal"><span class="pre">i</span></tt> is saved into an
+array. The Loop Vectorizer knows to vectorize induction variables.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">bar</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">float</span><span class="o">*</span> <span class="n">B</span><span class="p">,</span> <span class="kt">float</span> <span class="n">K</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="if-conversion">
+<h4><a class="toc-backref" href="#id10">If Conversion</a><a class="headerlink" href="#if-conversion" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer is able to “flatten” the IF statement in the code and
+generate a single stream of instructions. The Loop Vectorizer supports any
+control flow in the innermost loop. The innermost loop may contain complex
+nesting of IFs, ELSEs and even GOTOs.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">></span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
+ <span class="n">sum</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">5</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">sum</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pointer-induction-variables">
+<h4><a class="toc-backref" href="#id11">Pointer Induction Variables</a><a class="headerlink" href="#pointer-induction-variables" title="Permalink to this headline">¶</a></h4>
+<p>This example uses the “accumulate” function of the standard c++ library. This
+loop uses C++ iterators, which are pointers, and not integer indices.
+The Loop Vectorizer detects pointer induction variables and can vectorize
+this loop. This feature is important because many C++ programs use iterators.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">baz</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">accumulate</span><span class="p">(</span><span class="n">A</span><span class="p">,</span> <span class="n">A</span> <span class="o">+</span> <span class="n">n</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="reverse-iterators">
+<h4><a class="toc-backref" href="#id12">Reverse Iterators</a><a class="headerlink" href="#reverse-iterators" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer can vectorize loops that count backwards.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="n">n</span><span class="p">;</span> <span class="n">i</span> <span class="o">></span> <span class="mi">0</span><span class="p">;</span> <span class="o">--</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span><span class="mi">1</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="scatter-gather">
+<h4><a class="toc-backref" href="#id13">Scatter / Gather</a><a class="headerlink" href="#scatter-gather" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer can vectorize code that becomes a sequence of scalar instructions
+that scatter/gathers memory.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">,</span> <span class="kt">int</span> <span class="n">k</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="o">*</span><span class="mi">7</span><span class="p">]</span> <span class="o">+=</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="o">*</span><span class="n">k</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="vectorization-of-mixed-types">
+<h4><a class="toc-backref" href="#id14">Vectorization of Mixed Types</a><a class="headerlink" href="#vectorization-of-mixed-types" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorizer can vectorize programs with mixed types. The Vectorizer
+cost model can estimate the cost of the type conversion and decide if
+vectorization is profitable.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">,</span> <span class="kt">int</span> <span class="n">k</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+=</span> <span class="mi">4</span> <span class="o">*</span> <span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="global-structures-alias-analysis">
+<h4><a class="toc-backref" href="#id15">Global Structures Alias Analysis</a><a class="headerlink" href="#global-structures-alias-analysis" title="Permalink to this headline">¶</a></h4>
+<p>Access to global structures can also be vectorized, with alias analysis being
+used to make sure accesses don’t alias. Run-time checks can also be added on
+pointer access to structure members.</p>
+<p>Many variations are supported, but some that rely on undefined behaviour being
+ignored (as other compilers do) are still being left un-vectorized.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">A</span><span class="p">[</span><span class="mi">100</span><span class="p">],</span> <span class="n">K</span><span class="p">,</span> <span class="n">B</span><span class="p">[</span><span class="mi">100</span><span class="p">];</span> <span class="p">}</span> <span class="n">Foo</span><span class="p">;</span>
+
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="mi">100</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">Foo</span><span class="p">.</span><span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">Foo</span><span class="p">.</span><span class="n">B</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">+</span> <span class="mi">100</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="vectorization-of-function-calls">
+<h4><a class="toc-backref" href="#id16">Vectorization of function calls</a><a class="headerlink" href="#vectorization-of-function-calls" title="Permalink to this headline">¶</a></h4>
+<p>The Loop Vectorize can vectorize intrinsic math functions.
+See the table below for a list of these functions.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="26%" />
+<col width="26%" />
+<col width="47%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>pow</td>
+<td>exp</td>
+<td>exp2</td>
+</tr>
+<tr class="row-even"><td>sin</td>
+<td>cos</td>
+<td>sqrt</td>
+</tr>
+<tr class="row-odd"><td>log</td>
+<td>log2</td>
+<td>log10</td>
+</tr>
+<tr class="row-even"><td>fabs</td>
+<td>floor</td>
+<td>ceil</td>
+</tr>
+<tr class="row-odd"><td>fma</td>
+<td>trunc</td>
+<td>nearbyint</td>
+</tr>
+<tr class="row-even"><td> </td>
+<td> </td>
+<td>fmuladd</td>
+</tr>
+</tbody>
+</table>
+<p>The loop vectorizer knows about special instructions on the target and will
+vectorize a loop containing a function call that maps to the instructions. For
+example, the loop below will be vectorized on Intel x86 if the SSE4.1 roundps
+instruction is available.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">float</span> <span class="o">*</span><span class="n">f</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="mi">1024</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">f</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">floorf</span><span class="p">(</span><span class="n">f</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="partial-unrolling-during-vectorization">
+<h4><a class="toc-backref" href="#id17">Partial unrolling during vectorization</a><a class="headerlink" href="#partial-unrolling-during-vectorization" title="Permalink to this headline">¶</a></h4>
+<p>Modern processors feature multiple execution units, and only programs that contain a
+high degree of parallelism can fully utilize the entire width of the machine.
+The Loop Vectorizer increases the instruction level parallelism (ILP) by
+performing partial-unrolling of loops.</p>
+<p>In the example below the entire array is accumulated into the variable ‘sum’.
+This is inefficient because only a single execution port can be used by the processor.
+By unrolling the code the Loop Vectorizer allows two or more execution ports
+to be used simultaneously.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">B</span><span class="p">,</span> <span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">sum</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">sum</span> <span class="o">+=</span> <span class="n">A</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
+ <span class="k">return</span> <span class="n">sum</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The Loop Vectorizer uses a cost model to decide when it is profitable to unroll loops.
+The decision to unroll the loop depends on the register pressure and the generated code size.</p>
+</div>
+</div>
+<div class="section" id="performance">
+<h3><a class="toc-backref" href="#id18">Performance</a><a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h3>
+<p>This section shows the the execution time of Clang on a simple benchmark:
+<a class="reference external" href="http://llvm.org/viewvc/llvm-project/test-suite/trunk/SingleSource/UnitTests/Vectorizer/">gcc-loops</a>.
+This benchmarks is a collection of loops from the GCC autovectorization
+<a class="reference external" href="http://gcc.gnu.org/projects/tree-ssa/vectorization.html">page</a> by Dorit Nuzman.</p>
+<p>The chart below compares GCC-4.7, ICC-13, and Clang-SVN with and without loop vectorization at -O3, tuned for “corei7-avx”, running on a Sandybridge iMac.
+The Y-axis shows the time in msec. Lower is better. The last column shows the geomean of all the kernels.</p>
+<img alt="_images/gcc-loops.png" src="_images/gcc-loops.png" />
+<p>And Linpack-pc with the same configuration. Result is Mflops, higher is better.</p>
+<img alt="_images/linpack-pc.png" src="_images/linpack-pc.png" />
+</div>
+</div>
+<div class="section" id="the-slp-vectorizer">
+<span id="slp-vectorizer"></span><h2><a class="toc-backref" href="#id19">The SLP Vectorizer</a><a class="headerlink" href="#the-slp-vectorizer" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="details">
+<h3><a class="toc-backref" href="#id20">Details</a><a class="headerlink" href="#details" title="Permalink to this headline">¶</a></h3>
+<p>The goal of SLP vectorization (a.k.a. superword-level parallelism) is
+to combine similar independent instructions within simple control-flow regions
+into vector instructions. Memory accesses, arithemetic operations, comparison
+operations and some math functions can all be vectorized using this technique
+(subject to the capabilities of the target architecture).</p>
+<p>For example, the following function performs very similar operations on its
+inputs (a1, b1) and (a2, b2). The basic-block vectorizer may combine these
+into vector operations.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">a1</span><span class="p">,</span> <span class="kt">int</span> <span class="n">a2</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b1</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b2</span><span class="p">,</span> <span class="kt">int</span> <span class="o">*</span><span class="n">A</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">A</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">=</span> <span class="n">a1</span><span class="o">*</span><span class="p">(</span><span class="n">a1</span> <span class="o">+</span> <span class="n">b1</span><span class="p">)</span><span class="o">/</span><span class="n">b1</span> <span class="o">+</span> <span class="mi">50</span><span class="o">*</span><span class="n">b1</span><span class="o">/</span><span class="n">a1</span><span class="p">;</span>
+ <span class="n">A</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">=</span> <span class="n">a2</span><span class="o">*</span><span class="p">(</span><span class="n">a2</span> <span class="o">+</span> <span class="n">b2</span><span class="p">)</span><span class="o">/</span><span class="n">b2</span> <span class="o">+</span> <span class="mi">50</span><span class="o">*</span><span class="n">b2</span><span class="o">/</span><span class="n">a2</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The SLP-vectorizer has two phases, bottom-up, and top-down. The top-down vectorization
+phase is more aggressive, but takes more time to run.</p>
+</div>
+<div class="section" id="id1">
+<h3><a class="toc-backref" href="#id21">Usage</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p>The SLP Vectorizer is not enabled by default, but it can be enabled
+through clang using the command line flag:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -fslp-vectorize file.c
+</pre></div>
+</div>
+<p>LLVM has a second basic block vectorization phase
+which is more compile-time intensive (The BB vectorizer). This optimization
+can be enabled through clang using the command line flag:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang -fslp-vectorize-aggressive file.c
+</pre></div>
+</div>
+<p>The SLP vectorizer is in early development stages but can already vectorize
+and accelerate many programs in the LLVM test suite.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="66%" />
+<col width="34%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Benchmark Name</th>
+<th class="head">Gain</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>Misc/flops-7</td>
+<td>-32.70%</td>
+</tr>
+<tr class="row-odd"><td>Misc/matmul_f64_4x4</td>
+<td>-23.23%</td>
+</tr>
+<tr class="row-even"><td>Olden/power</td>
+<td>-21.45%</td>
+</tr>
+<tr class="row-odd"><td>Misc/flops-4</td>
+<td>-14.90%</td>
+</tr>
+<tr class="row-even"><td>ASC_Sequoia/AMGmk</td>
+<td>-13.85%</td>
+</tr>
+<tr class="row-odd"><td>TSVC/LoopRerolling-flt</td>
+<td>-11.76%</td>
+</tr>
+<tr class="row-even"><td>Misc/flops-6</td>
+<td>-9.70%</td>
+</tr>
+<tr class="row-odd"><td>Misc/flops-5</td>
+<td>-8.54%</td>
+</tr>
+<tr class="row-even"><td>Misc/flops</td>
+<td>-8.12%</td>
+</tr>
+<tr class="row-odd"><td>TSVC/NodeSplitting-dbl</td>
+<td>-6.96%</td>
+</tr>
+<tr class="row-even"><td>Misc-C++/sphereflake</td>
+<td>-6.74%</td>
+</tr>
+<tr class="row-odd"><td>Ptrdist/yacr2</td>
+<td>-6.31%</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMBackend.html" title="Writing an LLVM Compiler Backend"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SourceLevelDebugging.html" title="Source Level Debugging with LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/3.3/docs/WritingAnLLVMBackend.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.3/docs/WritingAnLLVMBackend.html?rev=184142&view=auto
==============================================================================
--- www-releases/trunk/3.3/docs/WritingAnLLVMBackend.html (added)
+++ www-releases/trunk/3.3/docs/WritingAnLLVMBackend.html Mon Jun 17 18:07:11 2013
@@ -0,0 +1,1705 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Writing an LLVM Compiler Backend — LLVM 3.3 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '3.3',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 3.3 documentation" href="index.html" />
+ <link rel="next" title="How To Use Instruction Mappings" href="HowToUseInstrMappings.html" />
+ <link rel="prev" title="Auto-Vectorization in LLVM" href="Vectorizers.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="writing-an-llvm-compiler-backend">
+<h1>Writing an LLVM Compiler Backend<a class="headerlink" href="#writing-an-llvm-compiler-backend" title="Permalink to this headline">¶</a></h1>
+<div class="toctree-wrapper compound">
+</div>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id3">Introduction</a><ul>
+<li><a class="reference internal" href="#audience" id="id4">Audience</a></li>
+<li><a class="reference internal" href="#prerequisite-reading" id="id5">Prerequisite Reading</a></li>
+<li><a class="reference internal" href="#basic-steps" id="id6">Basic Steps</a></li>
+<li><a class="reference internal" href="#preliminaries" id="id7">Preliminaries</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-machine" id="id8">Target Machine</a></li>
+<li><a class="reference internal" href="#target-registration" id="id9">Target Registration</a></li>
+<li><a class="reference internal" href="#register-set-and-register-classes" id="id10">Register Set and Register Classes</a><ul>
+<li><a class="reference internal" href="#defining-a-register" id="id11">Defining a Register</a></li>
+<li><a class="reference internal" href="#defining-a-register-class" id="id12">Defining a Register Class</a></li>
+<li><a class="reference internal" href="#implement-a-subclass-of-targetregisterinfo" id="id13">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instruction-set" id="id14">Instruction Set</a><ul>
+<li><a class="reference internal" href="#instruction-operand-mapping" id="id15">Instruction Operand Mapping</a></li>
+<li><a class="reference internal" href="#instruction-relation-mapping" id="id16">Instruction Relation Mapping</a></li>
+<li><a class="reference internal" href="#implement-a-subclass-of-targetinstrinfo" id="id17">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetInstrInfo</span></tt></a></li>
+<li><a class="reference internal" href="#branch-folding-and-if-conversion" id="id18">Branch Folding and If Conversion</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#instruction-selector" id="id19">Instruction Selector</a><ul>
+<li><a class="reference internal" href="#the-selectiondag-legalize-phase" id="id20">The SelectionDAG Legalize Phase</a><ul>
+<li><a class="reference internal" href="#promote" id="id21">Promote</a></li>
+<li><a class="reference internal" href="#expand" id="id22">Expand</a></li>
+<li><a class="reference internal" href="#custom" id="id23">Custom</a></li>
+<li><a class="reference internal" href="#legal" id="id24">Legal</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#calling-conventions" id="id25">Calling Conventions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#assembly-printer" id="id26">Assembly Printer</a></li>
+<li><a class="reference internal" href="#subtarget-support" id="id27">Subtarget Support</a></li>
+<li><a class="reference internal" href="#jit-support" id="id28">JIT Support</a><ul>
+<li><a class="reference internal" href="#machine-code-emitter" id="id29">Machine Code Emitter</a></li>
+<li><a class="reference internal" href="#target-jit-info" id="id30">Target JIT Info</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes techniques for writing compiler backends that convert
+the LLVM Intermediate Representation (IR) to code for a specified machine or
+other languages. Code intended for a specific machine can take the form of
+either assembly code or binary code (usable for a JIT compiler).</p>
+<p>The backend of LLVM features a target-independent code generator that may
+create output for several types of target CPUs — including X86, PowerPC,
+ARM, and SPARC. The backend may also be used to generate code targeted at SPUs
+of the Cell processor or GPUs to support the execution of compute kernels.</p>
+<p>The document focuses on existing examples found in subdirectories of
+<tt class="docutils literal"><span class="pre">llvm/lib/Target</span></tt> in a downloaded LLVM release. In particular, this document
+focuses on the example of creating a static compiler (one that emits text
+assembly) for a SPARC target, because SPARC has fairly standard
+characteristics, such as a RISC instruction set and straightforward calling
+conventions.</p>
+<div class="section" id="audience">
+<h3><a class="toc-backref" href="#id4">Audience</a><a class="headerlink" href="#audience" title="Permalink to this headline">¶</a></h3>
+<p>The audience for this document is anyone who needs to write an LLVM backend to
+generate code for a specific hardware or software target.</p>
+</div>
+<div class="section" id="prerequisite-reading">
+<h3><a class="toc-backref" href="#id5">Prerequisite Reading</a><a class="headerlink" href="#prerequisite-reading" title="Permalink to this headline">¶</a></h3>
+<p>These essential documents must be read before reading this document:</p>
+<ul class="simple">
+<li><a class="reference external" href="LangRef.html">LLVM Language Reference Manual</a> — a reference manual for
+the LLVM assembly language.</li>
+<li><a class="reference internal" href="CodeGenerator.html"><em>The LLVM Target-Independent Code Generator</em></a> — a guide to the components (classes and code
+generation algorithms) for translating the LLVM internal representation into
+machine code for a specified target. Pay particular attention to the
+descriptions of code generation stages: Instruction Selection, Scheduling and
+Formation, SSA-based Optimization, Register Allocation, Prolog/Epilog Code
+Insertion, Late Machine Code Optimizations, and Code Emission.</li>
+<li><a class="reference internal" href="TableGenFundamentals.html"><em>TableGen Fundamentals</em></a> — a document that describes the TableGen
+(<tt class="docutils literal"><span class="pre">tblgen</span></tt>) application that manages domain-specific information to support
+LLVM code generation. TableGen processes input from a target description
+file (<tt class="docutils literal"><span class="pre">.td</span></tt> suffix) and generates C++ code that can be used for code
+generation.</li>
+<li><a class="reference internal" href="WritingAnLLVMPass.html"><em>Writing an LLVM Pass</em></a> — The assembly printer is a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>, as
+are several <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> processing steps.</li>
+</ul>
+<p>To follow the SPARC examples in this document, have a copy of <a class="reference external" href="http://www.sparc.org/standards/V8.pdf">The SPARC
+Architecture Manual, Version 8</a> for
+reference. For details about the ARM instruction set, refer to the <a class="reference external" href="http://infocenter.arm.com/">ARM
+Architecture Reference Manual</a>. For more about
+the GNU Assembler format (<tt class="docutils literal"><span class="pre">GAS</span></tt>), see <a class="reference external" href="http://sourceware.org/binutils/docs/as/index.html">Using As</a>, especially for the
+assembly printer. “Using As” contains a list of target machine dependent
+features.</p>
+</div>
+<div class="section" id="basic-steps">
+<h3><a class="toc-backref" href="#id6">Basic Steps</a><a class="headerlink" href="#basic-steps" title="Permalink to this headline">¶</a></h3>
+<p>To write a compiler backend for LLVM that converts the LLVM IR to code for a
+specified target (machine or other language), follow these steps:</p>
+<ul class="simple">
+<li>Create a subclass of the <tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class that describes
+characteristics of your target machine. Copy existing examples of specific
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class and header files; for example, start with
+<tt class="docutils literal"><span class="pre">SparcTargetMachine.cpp</span></tt> and <tt class="docutils literal"><span class="pre">SparcTargetMachine.h</span></tt>, but change the file
+names for your target. Similarly, change code that references “<tt class="docutils literal"><span class="pre">Sparc</span></tt>” to
+reference your target.</li>
+<li>Describe the register set of the target. Use TableGen to generate code for
+register definition, register aliases, and register classes from a
+target-specific <tt class="docutils literal"><span class="pre">RegisterInfo.td</span></tt> input file. You should also write
+additional code for a subclass of the <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt> class that
+represents the class register file data used for register allocation and also
+describes the interactions between registers.</li>
+<li>Describe the instruction set of the target. Use TableGen to generate code
+for target-specific instructions from target-specific versions of
+<tt class="docutils literal"><span class="pre">TargetInstrFormats.td</span></tt> and <tt class="docutils literal"><span class="pre">TargetInstrInfo.td</span></tt>. You should write
+additional code for a subclass of the <tt class="docutils literal"><span class="pre">TargetInstrInfo</span></tt> class to represent
+machine instructions supported by the target machine.</li>
+<li>Describe the selection and conversion of the LLVM IR from a Directed Acyclic
+Graph (DAG) representation of instructions to native target-specific
+instructions. Use TableGen to generate code that matches patterns and
+selects instructions based on additional information in a target-specific
+version of <tt class="docutils literal"><span class="pre">TargetInstrInfo.td</span></tt>. Write code for <tt class="docutils literal"><span class="pre">XXXISelDAGToDAG.cpp</span></tt>,
+where <tt class="docutils literal"><span class="pre">XXX</span></tt> identifies the specific target, to perform pattern matching and
+DAG-to-DAG instruction selection. Also write code in <tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt>
+to replace or remove operations and data types that are not supported
+natively in a SelectionDAG.</li>
+<li>Write code for an assembly printer that converts LLVM IR to a GAS format for
+your target machine. You should add assembly strings to the instructions
+defined in your target-specific version of <tt class="docutils literal"><span class="pre">TargetInstrInfo.td</span></tt>. You
+should also write code for a subclass of <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> that performs the
+LLVM-to-assembly conversion and a trivial subclass of <tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt>.</li>
+<li>Optionally, add support for subtargets (i.e., variants with different
+capabilities). You should also write code for a subclass of the
+<tt class="docutils literal"><span class="pre">TargetSubtarget</span></tt> class, which allows you to use the <tt class="docutils literal"><span class="pre">-mcpu=</span></tt> and
+<tt class="docutils literal"><span class="pre">-mattr=</span></tt> command-line options.</li>
+<li>Optionally, add JIT support and create a machine code emitter (subclass of
+<tt class="docutils literal"><span class="pre">TargetJITInfo</span></tt>) that is used to emit binary code directly into memory.</li>
+</ul>
+<p>In the <tt class="docutils literal"><span class="pre">.cpp</span></tt> and <tt class="docutils literal"><span class="pre">.h</span></tt>. files, initially stub up these methods and then
+implement them later. Initially, you may not know which private members that
+the class will need and which components will need to be subclassed.</p>
+</div>
+<div class="section" id="preliminaries">
+<h3><a class="toc-backref" href="#id7">Preliminaries</a><a class="headerlink" href="#preliminaries" title="Permalink to this headline">¶</a></h3>
+<p>To actually create your compiler backend, you need to create and modify a few
+files. The absolute minimum is discussed here. But to actually use the LLVM
+target-independent code generator, you must perform the steps described in the
+<a class="reference internal" href="CodeGenerator.html"><em>LLVM Target-Independent Code Generator</em></a> document.</p>
+<p>First, you should create a subdirectory under <tt class="docutils literal"><span class="pre">lib/Target</span></tt> to hold all the
+files related to your target. If your target is called “Dummy”, create the
+directory <tt class="docutils literal"><span class="pre">lib/Target/Dummy</span></tt>.</p>
+<p>In this new directory, create a <tt class="docutils literal"><span class="pre">Makefile</span></tt>. It is easiest to copy a
+<tt class="docutils literal"><span class="pre">Makefile</span></tt> of another target and modify it. It should at least contain the
+<tt class="docutils literal"><span class="pre">LEVEL</span></tt>, <tt class="docutils literal"><span class="pre">LIBRARYNAME</span></tt> and <tt class="docutils literal"><span class="pre">TARGET</span></tt> variables, and then include
+<tt class="docutils literal"><span class="pre">$(LEVEL)/Makefile.common</span></tt>. The library can be named <tt class="docutils literal"><span class="pre">LLVMDummy</span></tt> (for
+example, see the MIPS target). Alternatively, you can split the library into
+<tt class="docutils literal"><span class="pre">LLVMDummyCodeGen</span></tt> and <tt class="docutils literal"><span class="pre">LLVMDummyAsmPrinter</span></tt>, the latter of which should be
+implemented in a subdirectory below <tt class="docutils literal"><span class="pre">lib/Target/Dummy</span></tt> (for example, see the
+PowerPC target).</p>
+<p>Note that these two naming schemes are hardcoded into <tt class="docutils literal"><span class="pre">llvm-config</span></tt>. Using
+any other naming scheme will confuse <tt class="docutils literal"><span class="pre">llvm-config</span></tt> and produce a lot of
+(seemingly unrelated) linker errors when linking <tt class="docutils literal"><span class="pre">llc</span></tt>.</p>
+<p>To make your target actually do something, you need to implement a subclass of
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt>. This implementation should typically be in the file
+<tt class="docutils literal"><span class="pre">lib/Target/DummyTargetMachine.cpp</span></tt>, but any file in the <tt class="docutils literal"><span class="pre">lib/Target</span></tt>
+directory will be built and should work. To use LLVM’s target independent code
+generator, you should do what all current machine backends do: create a
+subclass of <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt>. (To create a target from scratch, create a
+subclass of <tt class="docutils literal"><span class="pre">TargetMachine</span></tt>.)</p>
+<p>To get LLVM to actually build and link your target, you need to add it to the
+<tt class="docutils literal"><span class="pre">TARGETS_TO_BUILD</span></tt> variable. To do this, you modify the configure script to
+know about your target when parsing the <tt class="docutils literal"><span class="pre">--enable-targets</span></tt> option. Search
+the configure script for <tt class="docutils literal"><span class="pre">TARGETS_TO_BUILD</span></tt>, add your target to the lists
+there (some creativity required), and then reconfigure. Alternatively, you can
+change <tt class="docutils literal"><span class="pre">autotools/configure.ac</span></tt> and regenerate configure by running
+<tt class="docutils literal"><span class="pre">./autoconf/AutoRegen.sh</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="target-machine">
+<h2><a class="toc-backref" href="#id8">Target Machine</a><a class="headerlink" href="#target-machine" title="Permalink to this headline">¶</a></h2>
+<p><tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt> is designed as a base class for targets implemented with
+the LLVM target-independent code generator. The <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt> class
+should be specialized by a concrete target class that implements the various
+virtual methods. <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt> is defined as a subclass of
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt> in <tt class="docutils literal"><span class="pre">include/llvm/Target/TargetMachine.h</span></tt>. The
+<tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class implementation (<tt class="docutils literal"><span class="pre">TargetMachine.cpp</span></tt>) also processes
+numerous command-line options.</p>
+<p>To create a concrete target-specific subclass of <tt class="docutils literal"><span class="pre">LLVMTargetMachine</span></tt>, start
+by copying an existing <tt class="docutils literal"><span class="pre">TargetMachine</span></tt> class and header. You should name the
+files that you create to reflect your specific target. For instance, for the
+SPARC target, name the files <tt class="docutils literal"><span class="pre">SparcTargetMachine.h</span></tt> and
+<tt class="docutils literal"><span class="pre">SparcTargetMachine.cpp</span></tt>.</p>
+<p>For a target machine <tt class="docutils literal"><span class="pre">XXX</span></tt>, the implementation of <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> must
+have access methods to obtain objects that represent target components. These
+methods are named <tt class="docutils literal"><span class="pre">get*Info</span></tt>, and are intended to obtain the instruction set
+(<tt class="docutils literal"><span class="pre">getInstrInfo</span></tt>), register set (<tt class="docutils literal"><span class="pre">getRegisterInfo</span></tt>), stack frame layout
+(<tt class="docutils literal"><span class="pre">getFrameInfo</span></tt>), and similar information. <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> must also
+implement the <tt class="docutils literal"><span class="pre">getDataLayout</span></tt> method to access an object with target-specific
+data characteristics, such as data type size and alignment requirements.</p>
+<p>For instance, for the SPARC target, the header file <tt class="docutils literal"><span class="pre">SparcTargetMachine.h</span></tt>
+declares prototypes for several <tt class="docutils literal"><span class="pre">get*Info</span></tt> and <tt class="docutils literal"><span class="pre">getDataLayout</span></tt> methods that
+simply return a class member.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">llvm</span> <span class="p">{</span>
+
+<span class="k">class</span> <span class="nc">Module</span><span class="p">;</span>
+
+<span class="k">class</span> <span class="nc">SparcTargetMachine</span> <span class="o">:</span> <span class="k">public</span> <span class="n">LLVMTargetMachine</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="n">DataLayout</span> <span class="n">DataLayout</span><span class="p">;</span> <span class="c1">// Calculates type size & alignment</span>
+ <span class="n">SparcSubtarget</span> <span class="n">Subtarget</span><span class="p">;</span>
+ <span class="n">SparcInstrInfo</span> <span class="n">InstrInfo</span><span class="p">;</span>
+ <span class="n">TargetFrameInfo</span> <span class="n">FrameInfo</span><span class="p">;</span>
+
+<span class="nl">protected:</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetAsmInfo</span> <span class="o">*</span><span class="n">createTargetAsmInfo</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
+
+<span class="nl">public:</span>
+ <span class="n">SparcTargetMachine</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">,</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">FS</span><span class="p">);</span>
+
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">SparcInstrInfo</span> <span class="o">*</span><span class="n">getInstrInfo</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span><span class="k">return</span> <span class="o">&</span><span class="n">InstrInfo</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetFrameInfo</span> <span class="o">*</span><span class="n">getFrameInfo</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span><span class="k">return</span> <span class="o">&</span><span class="n">FrameInfo</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetSubtarget</span> <span class="o">*</span><span class="n">getSubtargetImpl</span><span class="p">()</span> <span class="k">const</span><span class="p">{</span><span class="k">return</span> <span class="o">&</span><span class="n">Subtarget</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">TargetRegisterInfo</span> <span class="o">*</span><span class="n">getRegisterInfo</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="o">&</span><span class="n">InstrInfo</span><span class="p">.</span><span class="n">getRegisterInfo</span><span class="p">();</span>
+ <span class="p">}</span>
+ <span class="k">virtual</span> <span class="k">const</span> <span class="n">DataLayout</span> <span class="o">*</span><span class="n">getDataLayout</span><span class="p">()</span> <span class="k">const</span> <span class="p">{</span> <span class="k">return</span> <span class="o">&</span><span class="n">DataLayout</span><span class="p">;</span> <span class="p">}</span>
+ <span class="k">static</span> <span class="kt">unsigned</span> <span class="n">getModuleMatchQuality</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">);</span>
+
+ <span class="c1">// Pass Pipeline Configuration</span>
+ <span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">addInstSelector</span><span class="p">(</span><span class="n">PassManagerBase</span> <span class="o">&</span><span class="n">PM</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">Fast</span><span class="p">);</span>
+ <span class="k">virtual</span> <span class="kt">bool</span> <span class="nf">addPreEmitPass</span><span class="p">(</span><span class="n">PassManagerBase</span> <span class="o">&</span><span class="n">PM</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">Fast</span><span class="p">);</span>
+<span class="p">};</span>
+
+<span class="p">}</span> <span class="c1">// end namespace llvm</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getInstrInfo()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getRegisterInfo()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getFrameInfo()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getDataLayout()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getSubtargetImpl()</span></tt></li>
+</ul>
+<p>For some targets, you also need to support the following methods:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getTargetLowering()</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">getJITInfo()</span></tt></li>
+</ul>
+<p>In addition, the <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> constructor should specify a
+<tt class="docutils literal"><span class="pre">TargetDescription</span></tt> string that determines the data layout for the target
+machine, including characteristics such as pointer size, alignment, and
+endianness. For example, the constructor for <tt class="docutils literal"><span class="pre">SparcTargetMachine</span></tt> contains
+the following:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SparcTargetMachine</span><span class="o">::</span><span class="n">SparcTargetMachine</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">,</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">FS</span><span class="p">)</span>
+ <span class="o">:</span> <span class="n">DataLayout</span><span class="p">(</span><span class="s">"E-p:32:32-f128:128:128"</span><span class="p">),</span>
+ <span class="n">Subtarget</span><span class="p">(</span><span class="n">M</span><span class="p">,</span> <span class="n">FS</span><span class="p">),</span> <span class="n">InstrInfo</span><span class="p">(</span><span class="n">Subtarget</span><span class="p">),</span>
+ <span class="n">FrameInfo</span><span class="p">(</span><span class="n">TargetFrameInfo</span><span class="o">::</span><span class="n">StackGrowsDown</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Hyphens separate portions of the <tt class="docutils literal"><span class="pre">TargetDescription</span></tt> string.</p>
+<ul class="simple">
+<li>An upper-case “<tt class="docutils literal"><span class="pre">E</span></tt>” in the string indicates a big-endian target data model.
+A lower-case “<tt class="docutils literal"><span class="pre">e</span></tt>” indicates little-endian.</li>
+<li>“<tt class="docutils literal"><span class="pre">p:</span></tt>” is followed by pointer information: size, ABI alignment, and
+preferred alignment. If only two figures follow “<tt class="docutils literal"><span class="pre">p:</span></tt>”, then the first
+value is pointer size, and the second value is both ABI and preferred
+alignment.</li>
+<li>Then a letter for numeric type alignment: “<tt class="docutils literal"><span class="pre">i</span></tt>”, “<tt class="docutils literal"><span class="pre">f</span></tt>”, “<tt class="docutils literal"><span class="pre">v</span></tt>”, or
+“<tt class="docutils literal"><span class="pre">a</span></tt>” (corresponding to integer, floating point, vector, or aggregate).
+“<tt class="docutils literal"><span class="pre">i</span></tt>”, “<tt class="docutils literal"><span class="pre">v</span></tt>”, or “<tt class="docutils literal"><span class="pre">a</span></tt>” are followed by ABI alignment and preferred
+alignment. “<tt class="docutils literal"><span class="pre">f</span></tt>” is followed by three values: the first indicates the size
+of a long double, then ABI alignment, and then ABI preferred alignment.</li>
+</ul>
+</div>
+<div class="section" id="target-registration">
+<h2><a class="toc-backref" href="#id9">Target Registration</a><a class="headerlink" href="#target-registration" title="Permalink to this headline">¶</a></h2>
+<p>You must also register your target with the <tt class="docutils literal"><span class="pre">TargetRegistry</span></tt>, which is what
+other LLVM tools use to be able to lookup and use your target at runtime. The
+<tt class="docutils literal"><span class="pre">TargetRegistry</span></tt> can be used directly, but for most targets there are helper
+templates which should take care of the work for you.</p>
+<p>All targets should declare a global <tt class="docutils literal"><span class="pre">Target</span></tt> object which is used to
+represent the target during registration. Then, in the target’s <tt class="docutils literal"><span class="pre">TargetInfo</span></tt>
+library, the target should define that object and use the <tt class="docutils literal"><span class="pre">RegisterTarget</span></tt>
+template to register the target. For example, the Sparc registration code
+looks like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">Target</span> <span class="n">llvm</span><span class="o">::</span><span class="n">TheSparcTarget</span><span class="p">;</span>
+
+<span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">LLVMInitializeSparcTargetInfo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">RegisterTarget</span><span class="o"><</span><span class="n">Triple</span><span class="o">::</span><span class="n">sparc</span><span class="p">,</span> <span class="cm">/*HasJIT=*/</span><span class="nb">false</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="n">TheSparcTarget</span><span class="p">,</span> <span class="s">"sparc"</span><span class="p">,</span> <span class="s">"Sparc"</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This allows the <tt class="docutils literal"><span class="pre">TargetRegistry</span></tt> to look up the target by name or by target
+triple. In addition, most targets will also register additional features which
+are available in separate libraries. These registration steps are separate,
+because some clients may wish to only link in some parts of the target — the
+JIT code generator does not require the use of the assembler printer, for
+example. Here is an example of registering the Sparc assembly printer:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">extern</span> <span class="s">"C"</span> <span class="kt">void</span> <span class="n">LLVMInitializeSparcAsmPrinter</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">RegisterAsmPrinter</span><span class="o"><</span><span class="n">SparcAsmPrinter</span><span class="o">></span> <span class="n">X</span><span class="p">(</span><span class="n">TheSparcTarget</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For more information, see “<a class="reference external" href="/doxygen/TargetRegistry_8h-source.html">llvm/Target/TargetRegistry.h</a>”.</p>
+</div>
+<div class="section" id="register-set-and-register-classes">
+<h2><a class="toc-backref" href="#id10">Register Set and Register Classes</a><a class="headerlink" href="#register-set-and-register-classes" title="Permalink to this headline">¶</a></h2>
+<p>You should describe a concrete target-specific class that represents the
+register file of a target machine. This class is called <tt class="docutils literal"><span class="pre">XXXRegisterInfo</span></tt>
+(where <tt class="docutils literal"><span class="pre">XXX</span></tt> identifies the target) and represents the class register file
+data that is used for register allocation. It also describes the interactions
+between registers.</p>
+<p>You also need to define register classes to categorize related registers. A
+register class should be added for groups of registers that are all treated the
+same way for some instruction. Typical examples are register classes for
+integer, floating-point, or vector registers. A register allocator allows an
+instruction to use any register in a specified register class to perform the
+instruction in a similar manner. Register classes allocate virtual registers
+to instructions from these sets, and register classes let the
+target-independent register allocator automatically choose the actual
+registers.</p>
+<p>Much of the code for registers, including register definition, register
+aliases, and register classes, is generated by TableGen from
+<tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> input files and placed in <tt class="docutils literal"><span class="pre">XXXGenRegisterInfo.h.inc</span></tt>
+and <tt class="docutils literal"><span class="pre">XXXGenRegisterInfo.inc</span></tt> output files. Some of the code in the
+implementation of <tt class="docutils literal"><span class="pre">XXXRegisterInfo</span></tt> requires hand-coding.</p>
+<div class="section" id="defining-a-register">
+<h3><a class="toc-backref" href="#id11">Defining a Register</a><a class="headerlink" href="#defining-a-register" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> file typically starts with register definitions for
+a target machine. The <tt class="docutils literal"><span class="pre">Register</span></tt> class (specified in <tt class="docutils literal"><span class="pre">Target.td</span></tt>) is used
+to define an object for each register. The specified string <tt class="docutils literal"><span class="pre">n</span></tt> becomes the
+<tt class="docutils literal"><span class="pre">Name</span></tt> of the register. The basic <tt class="docutils literal"><span class="pre">Register</span></tt> object does not have any
+subregisters and does not specify any aliases.</p>
+<div class="highlight-llvm"><pre>class Register<string n> {
+ string Namespace = "";
+ string AsmName = n;
+ string Name = n;
+ int SpillSize = 0;
+ int SpillAlignment = 0;
+ list<Register> Aliases = [];
+ list<Register> SubRegs = [];
+ list<int> DwarfNumbers = [];
+}</pre>
+</div>
+<p>For example, in the <tt class="docutils literal"><span class="pre">X86RegisterInfo.td</span></tt> file, there are register definitions
+that utilize the <tt class="docutils literal"><span class="pre">Register</span></tt> class, such as:</p>
+<div class="highlight-llvm"><pre>def AL : Register<"AL">, DwarfRegNum<[0, 0, 0]>;</pre>
+</div>
+<p>This defines the register <tt class="docutils literal"><span class="pre">AL</span></tt> and assigns it values (with <tt class="docutils literal"><span class="pre">DwarfRegNum</span></tt>)
+that are used by <tt class="docutils literal"><span class="pre">gcc</span></tt>, <tt class="docutils literal"><span class="pre">gdb</span></tt>, or a debug information writer to identify a
+register. For register <tt class="docutils literal"><span class="pre">AL</span></tt>, <tt class="docutils literal"><span class="pre">DwarfRegNum</span></tt> takes an array of 3 values
+representing 3 different modes: the first element is for X86-64, the second for
+exception handling (EH) on X86-32, and the third is generic. -1 is a special
+Dwarf number that indicates the gcc number is undefined, and -2 indicates the
+register number is invalid for this mode.</p>
+<p>From the previously described line in the <tt class="docutils literal"><span class="pre">X86RegisterInfo.td</span></tt> file, TableGen
+generates this code in the <tt class="docutils literal"><span class="pre">X86GenRegisterInfo.inc</span></tt> file:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="k">const</span> <span class="kt">unsigned</span> <span class="n">GR8</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="n">X86</span><span class="o">::</span><span class="n">AL</span><span class="p">,</span> <span class="p">...</span> <span class="p">};</span>
+
+<span class="k">const</span> <span class="kt">unsigned</span> <span class="n">AL_AliasSet</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="n">X86</span><span class="o">::</span><span class="n">AX</span><span class="p">,</span> <span class="n">X86</span><span class="o">::</span><span class="n">EAX</span><span class="p">,</span> <span class="n">X86</span><span class="o">::</span><span class="n">RAX</span><span class="p">,</span> <span class="mi">0</span> <span class="p">};</span>
+
+<span class="k">const</span> <span class="n">TargetRegisterDesc</span> <span class="n">RegisterDescriptors</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">{</span> <span class="s">"AL"</span><span class="p">,</span> <span class="s">"AL"</span><span class="p">,</span> <span class="n">AL_AliasSet</span><span class="p">,</span> <span class="n">Empty_SubRegsSet</span><span class="p">,</span> <span class="n">Empty_SubRegsSet</span><span class="p">,</span> <span class="n">AL_SuperRegsSet</span> <span class="p">},</span> <span class="p">...</span>
+</pre></div>
+</div>
+<p>From the register info file, TableGen generates a <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt> object
+for each register. <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt> is defined in
+<tt class="docutils literal"><span class="pre">include/llvm/Target/TargetRegisterInfo.h</span></tt> with the following fields:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">TargetRegisterDesc</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">AsmName</span><span class="p">;</span> <span class="c1">// Assembly language name for the register</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">Name</span><span class="p">;</span> <span class="c1">// Printable name for the reg (for debugging)</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">AliasSet</span><span class="p">;</span> <span class="c1">// Register Alias Set</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">SubRegs</span><span class="p">;</span> <span class="c1">// Sub-register set</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">ImmSubRegs</span><span class="p">;</span> <span class="c1">// Immediate sub-register set</span>
+ <span class="k">const</span> <span class="kt">unsigned</span> <span class="o">*</span><span class="n">SuperRegs</span><span class="p">;</span> <span class="c1">// Super-register set</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>TableGen uses the entire target description file (<tt class="docutils literal"><span class="pre">.td</span></tt>) to determine text
+names for the register (in the <tt class="docutils literal"><span class="pre">AsmName</span></tt> and <tt class="docutils literal"><span class="pre">Name</span></tt> fields of
+<tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt>) and the relationships of other registers to the defined
+register (in the other <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt> fields). In this example, other
+definitions establish the registers “<tt class="docutils literal"><span class="pre">AX</span></tt>”, “<tt class="docutils literal"><span class="pre">EAX</span></tt>”, and “<tt class="docutils literal"><span class="pre">RAX</span></tt>” as
+aliases for one another, so TableGen generates a null-terminated array
+(<tt class="docutils literal"><span class="pre">AL_AliasSet</span></tt>) for this register alias set.</p>
+<p>The <tt class="docutils literal"><span class="pre">Register</span></tt> class is commonly used as a base class for more complex
+classes. In <tt class="docutils literal"><span class="pre">Target.td</span></tt>, the <tt class="docutils literal"><span class="pre">Register</span></tt> class is the base for the
+<tt class="docutils literal"><span class="pre">RegisterWithSubRegs</span></tt> class that is used to define registers that need to
+specify subregisters in the <tt class="docutils literal"><span class="pre">SubRegs</span></tt> list, as shown here:</p>
+<div class="highlight-llvm"><pre>class RegisterWithSubRegs<string n, list<Register> subregs> : Register<n> {
+ let SubRegs = subregs;
+}</pre>
+</div>
+<p>In <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt>, additional register classes are defined for SPARC:
+a <tt class="docutils literal"><span class="pre">Register</span></tt> subclass, <tt class="docutils literal"><span class="pre">SparcReg</span></tt>, and further subclasses: <tt class="docutils literal"><span class="pre">Ri</span></tt>, <tt class="docutils literal"><span class="pre">Rf</span></tt>,
+and <tt class="docutils literal"><span class="pre">Rd</span></tt>. SPARC registers are identified by 5-bit ID numbers, which is a
+feature common to these subclasses. Note the use of “<tt class="docutils literal"><span class="pre">let</span></tt>” expressions to
+override values that are initially defined in a superclass (such as <tt class="docutils literal"><span class="pre">SubRegs</span></tt>
+field in the <tt class="docutils literal"><span class="pre">Rd</span></tt> class).</p>
+<div class="highlight-llvm"><pre>class SparcReg<string n> : Register<n> {
+ field bits<5> Num;
+ let Namespace = "SP";
+}
+// Ri - 32-bit integer registers
+class Ri<bits<5> num, string n> :
+SparcReg<n> {
+ let Num = num;
+}
+// Rf - 32-bit floating-point registers
+class Rf<bits<5> num, string n> :
+SparcReg<n> {
+ let Num = num;
+}
+// Rd - Slots in the FP register file for 64-bit floating-point values.
+class Rd<bits<5> num, string n, list<Register> subregs> : SparcReg<n> {
+ let Num = num;
+ let SubRegs = subregs;
+}</pre>
+</div>
+<p>In the <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> file, there are register definitions that
+utilize these subclasses of <tt class="docutils literal"><span class="pre">Register</span></tt>, such as:</p>
+<div class="highlight-llvm"><pre>def G0 : Ri< 0, "G0">, DwarfRegNum<[0]>;
+def G1 : Ri< 1, "G1">, DwarfRegNum<[1]>;
+...
+def F0 : Rf< 0, "F0">, DwarfRegNum<[32]>;
+def F1 : Rf< 1, "F1">, DwarfRegNum<[33]>;
+...
+def D0 : Rd< 0, "F0", [F0, F1]>, DwarfRegNum<[32]>;
+def D1 : Rd< 2, "F2", [F2, F3]>, DwarfRegNum<[34]>;</pre>
+</div>
+<p>The last two registers shown above (<tt class="docutils literal"><span class="pre">D0</span></tt> and <tt class="docutils literal"><span class="pre">D1</span></tt>) are double-precision
+floating-point registers that are aliases for pairs of single-precision
+floating-point sub-registers. In addition to aliases, the sub-register and
+super-register relationships of the defined register are in fields of a
+register’s <tt class="docutils literal"><span class="pre">TargetRegisterDesc</span></tt>.</p>
+</div>
+<div class="section" id="defining-a-register-class">
+<h3><a class="toc-backref" href="#id12">Defining a Register Class</a><a class="headerlink" href="#defining-a-register-class" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">RegisterClass</span></tt> class (specified in <tt class="docutils literal"><span class="pre">Target.td</span></tt>) is used to define an
+object that represents a group of related registers and also defines the
+default allocation order of the registers. A target description file
+<tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> that uses <tt class="docutils literal"><span class="pre">Target.td</span></tt> can construct register classes
+using the following class:</p>
+<div class="highlight-llvm"><pre>class RegisterClass<string namespace,
+list<ValueType> regTypes, int alignment, dag regList> {
+ string Namespace = namespace;
+ list<ValueType> RegTypes = regTypes;
+ int Size = 0; // spill size, in bits; zero lets tblgen pick the size
+ int Alignment = alignment;
+
+ // CopyCost is the cost of copying a value between two registers
+ // default value 1 means a single instruction
+ // A negative value means copying is extremely expensive or impossible
+ int CopyCost = 1;
+ dag MemberList = regList;
+
+ // for register classes that are subregisters of this class
+ list<RegisterClass> SubRegClassList = [];
+
+ code MethodProtos = [{}]; // to insert arbitrary code
+ code MethodBodies = [{}];
+}</pre>
+</div>
+<p>To define a <tt class="docutils literal"><span class="pre">RegisterClass</span></tt>, use the following 4 arguments:</p>
+<ul class="simple">
+<li>The first argument of the definition is the name of the namespace.</li>
+<li>The second argument is a list of <tt class="docutils literal"><span class="pre">ValueType</span></tt> register type values that are
+defined in <tt class="docutils literal"><span class="pre">include/llvm/CodeGen/ValueTypes.td</span></tt>. Defined values include
+integer types (such as <tt class="docutils literal"><span class="pre">i16</span></tt>, <tt class="docutils literal"><span class="pre">i32</span></tt>, and <tt class="docutils literal"><span class="pre">i1</span></tt> for Boolean),
+floating-point types (<tt class="docutils literal"><span class="pre">f32</span></tt>, <tt class="docutils literal"><span class="pre">f64</span></tt>), and vector types (for example,
+<tt class="docutils literal"><span class="pre">v8i16</span></tt> for an <tt class="docutils literal"><span class="pre">8</span> <span class="pre">x</span> <span class="pre">i16</span></tt> vector). All registers in a <tt class="docutils literal"><span class="pre">RegisterClass</span></tt>
+must have the same <tt class="docutils literal"><span class="pre">ValueType</span></tt>, but some registers may store vector data in
+different configurations. For example a register that can process a 128-bit
+vector may be able to handle 16 8-bit integer elements, 8 16-bit integers, 4
+32-bit integers, and so on.</li>
+<li>The third argument of the <tt class="docutils literal"><span class="pre">RegisterClass</span></tt> definition specifies the
+alignment required of the registers when they are stored or loaded to
+memory.</li>
+<li>The final argument, <tt class="docutils literal"><span class="pre">regList</span></tt>, specifies which registers are in this class.
+If an alternative allocation order method is not specified, then <tt class="docutils literal"><span class="pre">regList</span></tt>
+also defines the order of allocation used by the register allocator. Besides
+simply listing registers with <tt class="docutils literal"><span class="pre">(add</span> <span class="pre">R0,</span> <span class="pre">R1,</span> <span class="pre">...)</span></tt>, more advanced set
+operators are available. See <tt class="docutils literal"><span class="pre">include/llvm/Target/Target.td</span></tt> for more
+information.</li>
+</ul>
+<p>In <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt>, three <tt class="docutils literal"><span class="pre">RegisterClass</span></tt> objects are defined:
+<tt class="docutils literal"><span class="pre">FPRegs</span></tt>, <tt class="docutils literal"><span class="pre">DFPRegs</span></tt>, and <tt class="docutils literal"><span class="pre">IntRegs</span></tt>. For all three register classes, the
+first argument defines the namespace with the string “<tt class="docutils literal"><span class="pre">SP</span></tt>”. <tt class="docutils literal"><span class="pre">FPRegs</span></tt>
+defines a group of 32 single-precision floating-point registers (<tt class="docutils literal"><span class="pre">F0</span></tt> to
+<tt class="docutils literal"><span class="pre">F31</span></tt>); <tt class="docutils literal"><span class="pre">DFPRegs</span></tt> defines a group of 16 double-precision registers
+(<tt class="docutils literal"><span class="pre">D0-D15</span></tt>).</p>
+<div class="highlight-llvm"><pre>// F0, F1, F2, ..., F31
+def FPRegs : RegisterClass<"SP", [f32], 32, (sequence "F%u", 0, 31)>;
+
+def DFPRegs : RegisterClass<"SP", [f64], 64,
+ (add D0, D1, D2, D3, D4, D5, D6, D7, D8,
+ D9, D10, D11, D12, D13, D14, D15)>;
+
+def IntRegs : RegisterClass<"SP", [i32], 32,
+ (add L0, L1, L2, L3, L4, L5, L6, L7,
+ I0, I1, I2, I3, I4, I5,
+ O0, O1, O2, O3, O4, O5, O7,
+ G1,
+ // Non-allocatable regs:
+ G2, G3, G4,
+ O6, // stack ptr
+ I6, // frame ptr
+ I7, // return address
+ G0, // constant zero
+ G5, G6, G7 // reserved for kernel
+ )>;</pre>
+</div>
+<p>Using <tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> with TableGen generates several output files
+that are intended for inclusion in other source code that you write.
+<tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> generates <tt class="docutils literal"><span class="pre">SparcGenRegisterInfo.h.inc</span></tt>, which should
+be included in the header file for the implementation of the SPARC register
+implementation that you write (<tt class="docutils literal"><span class="pre">SparcRegisterInfo.h</span></tt>). In
+<tt class="docutils literal"><span class="pre">SparcGenRegisterInfo.h.inc</span></tt> a new structure is defined called
+<tt class="docutils literal"><span class="pre">SparcGenRegisterInfo</span></tt> that uses <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt> as its base. It also
+specifies types, based upon the defined register classes: <tt class="docutils literal"><span class="pre">DFPRegsClass</span></tt>,
+<tt class="docutils literal"><span class="pre">FPRegsClass</span></tt>, and <tt class="docutils literal"><span class="pre">IntRegsClass</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">SparcRegisterInfo.td</span></tt> also generates <tt class="docutils literal"><span class="pre">SparcGenRegisterInfo.inc</span></tt>, which is
+included at the bottom of <tt class="docutils literal"><span class="pre">SparcRegisterInfo.cpp</span></tt>, the SPARC register
+implementation. The code below shows only the generated integer registers and
+associated register classes. The order of registers in <tt class="docutils literal"><span class="pre">IntRegs</span></tt> reflects
+the order in the definition of <tt class="docutils literal"><span class="pre">IntRegs</span></tt> in the target description file.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// IntRegs Register Class...</span>
+<span class="k">static</span> <span class="k">const</span> <span class="kt">unsigned</span> <span class="n">IntRegs</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">L0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L3</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L5</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">L6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">L7</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I3</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">I4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I5</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O3</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">O4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O5</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O7</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G1</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G2</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G3</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">G4</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">O6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">I7</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G0</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G5</span><span class="p">,</span>
+ <span class="n">SP</span><span class="o">::</span><span class="n">G6</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">G7</span><span class="p">,</span>
+<span class="p">};</span>
+
+<span class="c1">// IntRegsVTs Register Class Value Types...</span>
+<span class="k">static</span> <span class="k">const</span> <span class="n">MVT</span><span class="o">::</span><span class="n">ValueType</span> <span class="n">IntRegsVTs</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">Other</span>
+<span class="p">};</span>
+
+<span class="k">namespace</span> <span class="n">SP</span> <span class="p">{</span> <span class="c1">// Register class instances</span>
+ <span class="n">DFPRegsClass</span> <span class="n">DFPRegsRegClass</span><span class="p">;</span>
+ <span class="n">FPRegsClass</span> <span class="n">FPRegsRegClass</span><span class="p">;</span>
+ <span class="n">IntRegsClass</span> <span class="n">IntRegsRegClass</span><span class="p">;</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Sub-register Classess...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSubRegClasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Super-register Classess...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSuperRegClasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Register Class sub-classes...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSubclasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+<span class="p">...</span>
+ <span class="c1">// IntRegs Register Class super-classes...</span>
+ <span class="k">static</span> <span class="k">const</span> <span class="n">TargetRegisterClass</span><span class="o">*</span> <span class="k">const</span> <span class="n">IntRegsSuperclasses</span> <span class="p">[]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="nb">NULL</span>
+ <span class="p">};</span>
+
+ <span class="n">IntRegsClass</span><span class="o">::</span><span class="n">IntRegsClass</span><span class="p">()</span> <span class="o">:</span> <span class="n">TargetRegisterClass</span><span class="p">(</span><span class="n">IntRegsRegClassID</span><span class="p">,</span>
+ <span class="n">IntRegsVTs</span><span class="p">,</span> <span class="n">IntRegsSubclasses</span><span class="p">,</span> <span class="n">IntRegsSuperclasses</span><span class="p">,</span> <span class="n">IntRegsSubRegClasses</span><span class="p">,</span>
+ <span class="n">IntRegsSuperRegClasses</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="n">IntRegs</span><span class="p">,</span> <span class="n">IntRegs</span> <span class="o">+</span> <span class="mi">32</span><span class="p">)</span> <span class="p">{}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The register allocators will avoid using reserved registers, and callee saved
+registers are not used until all the volatile registers have been used. That
+is usually good enough, but in some cases it may be necessary to provide custom
+allocation orders.</p>
+</div>
+<div class="section" id="implement-a-subclass-of-targetregisterinfo">
+<h3><a class="toc-backref" href="#id13">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetRegisterInfo</span></tt></a><a class="headerlink" href="#implement-a-subclass-of-targetregisterinfo" title="Permalink to this headline">¶</a></h3>
+<p>The final step is to hand code portions of <tt class="docutils literal"><span class="pre">XXXRegisterInfo</span></tt>, which
+implements the interface described in <tt class="docutils literal"><span class="pre">TargetRegisterInfo.h</span></tt> (see
+<a class="reference internal" href="CodeGenerator.html#targetregisterinfo"><em>The TargetRegisterInfo class</em></a>). These functions return <tt class="docutils literal"><span class="pre">0</span></tt>, <tt class="docutils literal"><span class="pre">NULL</span></tt>, or
+<tt class="docutils literal"><span class="pre">false</span></tt>, unless overridden. Here is a list of functions that are overridden
+for the SPARC implementation in <tt class="docutils literal"><span class="pre">SparcRegisterInfo.cpp</span></tt>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getCalleeSavedRegs</span></tt> — Returns a list of callee-saved registers in the
+order of the desired callee-save stack frame offset.</li>
+<li><tt class="docutils literal"><span class="pre">getReservedRegs</span></tt> — Returns a bitset indexed by physical register
+numbers, indicating if a particular register is unavailable.</li>
+<li><tt class="docutils literal"><span class="pre">hasFP</span></tt> — Return a Boolean indicating if a function should have a
+dedicated frame pointer register.</li>
+<li><tt class="docutils literal"><span class="pre">eliminateCallFramePseudoInstr</span></tt> — If call frame setup or destroy pseudo
+instructions are used, this can be called to eliminate them.</li>
+<li><tt class="docutils literal"><span class="pre">eliminateFrameIndex</span></tt> — Eliminate abstract frame indices from
+instructions that may use them.</li>
+<li><tt class="docutils literal"><span class="pre">emitPrologue</span></tt> — Insert prologue code into the function.</li>
+<li><tt class="docutils literal"><span class="pre">emitEpilogue</span></tt> — Insert epilogue code into the function.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="instruction-set">
+<span id="id1"></span><h2><a class="toc-backref" href="#id14">Instruction Set</a><a class="headerlink" href="#instruction-set" title="Permalink to this headline">¶</a></h2>
+<p>During the early stages of code generation, the LLVM IR code is converted to a
+<tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> with nodes that are instances of the <tt class="docutils literal"><span class="pre">SDNode</span></tt> class
+containing target instructions. An <tt class="docutils literal"><span class="pre">SDNode</span></tt> has an opcode, operands, type
+requirements, and operation properties. For example, is an operation
+commutative, does an operation load from memory. The various operation node
+types are described in the <tt class="docutils literal"><span class="pre">include/llvm/CodeGen/SelectionDAGNodes.h</span></tt> file
+(values of the <tt class="docutils literal"><span class="pre">NodeType</span></tt> enum in the <tt class="docutils literal"><span class="pre">ISD</span></tt> namespace).</p>
+<p>TableGen uses the following target description (<tt class="docutils literal"><span class="pre">.td</span></tt>) input files to
+generate much of the code for instruction definition:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">Target.td</span></tt> — Where the <tt class="docutils literal"><span class="pre">Instruction</span></tt>, <tt class="docutils literal"><span class="pre">Operand</span></tt>, <tt class="docutils literal"><span class="pre">InstrInfo</span></tt>, and
+other fundamental classes are defined.</li>
+<li><tt class="docutils literal"><span class="pre">TargetSelectionDAG.td</span></tt> — Used by <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> instruction selection
+generators, contains <tt class="docutils literal"><span class="pre">SDTC*</span></tt> classes (selection DAG type constraint),
+definitions of <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> nodes (such as <tt class="docutils literal"><span class="pre">imm</span></tt>, <tt class="docutils literal"><span class="pre">cond</span></tt>, <tt class="docutils literal"><span class="pre">bb</span></tt>,
+<tt class="docutils literal"><span class="pre">add</span></tt>, <tt class="docutils literal"><span class="pre">fadd</span></tt>, <tt class="docutils literal"><span class="pre">sub</span></tt>), and pattern support (<tt class="docutils literal"><span class="pre">Pattern</span></tt>, <tt class="docutils literal"><span class="pre">Pat</span></tt>,
+<tt class="docutils literal"><span class="pre">PatFrag</span></tt>, <tt class="docutils literal"><span class="pre">PatLeaf</span></tt>, <tt class="docutils literal"><span class="pre">ComplexPattern</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">XXXInstrFormats.td</span></tt> — Patterns for definitions of target-specific
+instructions.</li>
+<li><tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> — Target-specific definitions of instruction templates,
+condition codes, and instructions of an instruction set. For architecture
+modifications, a different file name may be used. For example, for Pentium
+with SSE instruction, this file is <tt class="docutils literal"><span class="pre">X86InstrSSE.td</span></tt>, and for Pentium with
+MMX, this file is <tt class="docutils literal"><span class="pre">X86InstrMMX.td</span></tt>.</li>
+</ul>
+<p>There is also a target-specific <tt class="docutils literal"><span class="pre">XXX.td</span></tt> file, where <tt class="docutils literal"><span class="pre">XXX</span></tt> is the name of
+the target. The <tt class="docutils literal"><span class="pre">XXX.td</span></tt> file includes the other <tt class="docutils literal"><span class="pre">.td</span></tt> input files, but
+its contents are only directly important for subtargets.</p>
+<p>You should describe a concrete target-specific class <tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt> that
+represents machine instructions supported by a target machine.
+<tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt> contains an array of <tt class="docutils literal"><span class="pre">XXXInstrDescriptor</span></tt> objects, each of
+which describes one instruction. An instruction descriptor defines:</p>
+<ul class="simple">
+<li>Opcode mnemonic</li>
+<li>Number of operands</li>
+<li>List of implicit register definitions and uses</li>
+<li>Target-independent properties (such as memory access, is commutable)</li>
+<li>Target-specific flags</li>
+</ul>
+<p>The Instruction class (defined in <tt class="docutils literal"><span class="pre">Target.td</span></tt>) is mostly used as a base for
+more complex instruction classes.</p>
+<div class="highlight-llvm"><pre>class Instruction {
+ string Namespace = "";
+ dag OutOperandList; // A dag containing the MI def operand list.
+ dag InOperandList; // A dag containing the MI use operand list.
+ string AsmString = ""; // The .s format to print the instruction with.
+ list<dag> Pattern; // Set to the DAG pattern for this instruction.
+ list<Register> Uses = [];
+ list<Register> Defs = [];
+ list<Predicate> Predicates = []; // predicates turned into isel match code
+ ... remainder not shown for space ...
+}</pre>
+</div>
+<p>A <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> node (<tt class="docutils literal"><span class="pre">SDNode</span></tt>) should contain an object representing a
+target-specific instruction that is defined in <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt>. The
+instruction objects should represent instructions from the architecture manual
+of the target machine (such as the SPARC Architecture Manual for the SPARC
+target).</p>
+<p>A single instruction from the architecture manual is often modeled as multiple
+target instructions, depending upon its operands. For example, a manual might
+describe an add instruction that takes a register or an immediate operand. An
+LLVM target could model this with two instructions named <tt class="docutils literal"><span class="pre">ADDri</span></tt> and
+<tt class="docutils literal"><span class="pre">ADDrr</span></tt>.</p>
+<p>You should define a class for each instruction category and define each opcode
+as a subclass of the category with appropriate parameters such as the fixed
+binary encoding of opcodes and extended opcodes. You should map the register
+bits to the bits of the instruction in which they are encoded (for the JIT).
+Also you should specify how the instruction should be printed when the
+automatic assembly printer is used.</p>
+<p>As is described in the SPARC Architecture Manual, Version 8, there are three
+major 32-bit formats for instructions. Format 1 is only for the <tt class="docutils literal"><span class="pre">CALL</span></tt>
+instruction. Format 2 is for branch on condition codes and <tt class="docutils literal"><span class="pre">SETHI</span></tt> (set high
+bits of a register) instructions. Format 3 is for other instructions.</p>
+<p>Each of these formats has corresponding classes in <tt class="docutils literal"><span class="pre">SparcInstrFormat.td</span></tt>.
+<tt class="docutils literal"><span class="pre">InstSP</span></tt> is a base class for other instruction classes. Additional base
+classes are specified for more precise formats: for example in
+<tt class="docutils literal"><span class="pre">SparcInstrFormat.td</span></tt>, <tt class="docutils literal"><span class="pre">F2_1</span></tt> is for <tt class="docutils literal"><span class="pre">SETHI</span></tt>, and <tt class="docutils literal"><span class="pre">F2_2</span></tt> is for
+branches. There are three other base classes: <tt class="docutils literal"><span class="pre">F3_1</span></tt> for register/register
+operations, <tt class="docutils literal"><span class="pre">F3_2</span></tt> for register/immediate operations, and <tt class="docutils literal"><span class="pre">F3_3</span></tt> for
+floating-point operations. <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> also adds the base class
+<tt class="docutils literal"><span class="pre">Pseudo</span></tt> for synthetic SPARC instructions.</p>
+<p><tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> largely consists of operand and instruction definitions
+for the SPARC target. In <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>, the following target
+description file entry, <tt class="docutils literal"><span class="pre">LDrr</span></tt>, defines the Load Integer instruction for a
+Word (the <tt class="docutils literal"><span class="pre">LD</span></tt> SPARC opcode) from a memory address to a register. The first
+parameter, the value 3 (<tt class="docutils literal"><span class="pre">11</span></tt><sub>2</sub>), is the operation value for this
+category of operation. The second parameter (<tt class="docutils literal"><span class="pre">000000</span></tt><sub>2</sub>) is the
+specific operation value for <tt class="docutils literal"><span class="pre">LD</span></tt>/Load Word. The third parameter is the
+output destination, which is a register operand and defined in the <tt class="docutils literal"><span class="pre">Register</span></tt>
+target description file (<tt class="docutils literal"><span class="pre">IntRegs</span></tt>).</p>
+<div class="highlight-llvm"><pre>def LDrr : F3_1 <3, 0b000000, (outs IntRegs:$dst), (ins MEMrr:$addr),
+ "ld [$addr], $dst",
+ [(set i32:$dst, (load ADDRrr:$addr))]>;</pre>
+</div>
+<p>The fourth parameter is the input source, which uses the address operand
+<tt class="docutils literal"><span class="pre">MEMrr</span></tt> that is defined earlier in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>:</p>
+<div class="highlight-llvm"><pre>def MEMrr : Operand<i32> {
+ let PrintMethod = "printMemOperand";
+ let MIOperandInfo = (ops IntRegs, IntRegs);
+}</pre>
+</div>
+<p>The fifth parameter is a string that is used by the assembly printer and can be
+left as an empty string until the assembly printer interface is implemented.
+The sixth and final parameter is the pattern used to match the instruction
+during the SelectionDAG Select Phase described in <a class="reference internal" href="CodeGenerator.html"><em>The LLVM Target-Independent Code Generator</em></a>.
+This parameter is detailed in the next section, <a class="reference internal" href="#instruction-selector"><em>Instruction Selector</em></a>.</p>
+<p>Instruction class definitions are not overloaded for different operand types,
+so separate versions of instructions are needed for register, memory, or
+immediate value operands. For example, to perform a Load Integer instruction
+for a Word from an immediate operand to a register, the following instruction
+class is defined:</p>
+<div class="highlight-llvm"><pre>def LDri : F3_2 <3, 0b000000, (outs IntRegs:$dst), (ins MEMri:$addr),
+ "ld [$addr], $dst",
+ [(set i32:$dst, (load ADDRri:$addr))]>;</pre>
+</div>
+<p>Writing these definitions for so many similar instructions can involve a lot of
+cut and paste. In <tt class="docutils literal"><span class="pre">.td</span></tt> files, the <tt class="docutils literal"><span class="pre">multiclass</span></tt> directive enables the
+creation of templates to define several instruction classes at once (using the
+<tt class="docutils literal"><span class="pre">defm</span></tt> directive). For example in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>, the <tt class="docutils literal"><span class="pre">multiclass</span></tt>
+pattern <tt class="docutils literal"><span class="pre">F3_12</span></tt> is defined to create 2 instruction classes each time
+<tt class="docutils literal"><span class="pre">F3_12</span></tt> is invoked:</p>
+<div class="highlight-llvm"><pre>multiclass F3_12 <string OpcStr, bits<6> Op3Val, SDNode OpNode> {
+ def rr : F3_1 <2, Op3Val,
+ (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
+ !strconcat(OpcStr, " $b, $c, $dst"),
+ [(set i32:$dst, (OpNode i32:$b, i32:$c))]>;
+ def ri : F3_2 <2, Op3Val,
+ (outs IntRegs:$dst), (ins IntRegs:$b, i32imm:$c),
+ !strconcat(OpcStr, " $b, $c, $dst"),
+ [(set i32:$dst, (OpNode i32:$b, simm13:$c))]>;
+}</pre>
+</div>
+<p>So when the <tt class="docutils literal"><span class="pre">defm</span></tt> directive is used for the <tt class="docutils literal"><span class="pre">XOR</span></tt> and <tt class="docutils literal"><span class="pre">ADD</span></tt>
+instructions, as seen below, it creates four instruction objects: <tt class="docutils literal"><span class="pre">XORrr</span></tt>,
+<tt class="docutils literal"><span class="pre">XORri</span></tt>, <tt class="docutils literal"><span class="pre">ADDrr</span></tt>, and <tt class="docutils literal"><span class="pre">ADDri</span></tt>.</p>
+<div class="highlight-llvm"><pre>defm XOR : F3_12<"xor", 0b000011, xor>;
+defm ADD : F3_12<"add", 0b000000, add>;</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> also includes definitions for condition codes that are
+referenced by branch instructions. The following definitions in
+<tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt> indicate the bit location of the SPARC condition code.
+For example, the 10<sup>th</sup> bit represents the “greater than” condition for
+integers, and the 22<sup>nd</sup> bit represents the “greater than” condition for
+floats.</p>
+<div class="highlight-llvm"><pre>def ICC_NE : ICC_VAL< 9>; // Not Equal
+def ICC_E : ICC_VAL< 1>; // Equal
+def ICC_G : ICC_VAL<10>; // Greater
+...
+def FCC_U : FCC_VAL<23>; // Unordered
+def FCC_G : FCC_VAL<22>; // Greater
+def FCC_UG : FCC_VAL<21>; // Unordered or Greater
+...</pre>
+</div>
+<p>(Note that <tt class="docutils literal"><span class="pre">Sparc.h</span></tt> also defines enums that correspond to the same SPARC
+condition codes. Care must be taken to ensure the values in <tt class="docutils literal"><span class="pre">Sparc.h</span></tt>
+correspond to the values in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>. I.e., <tt class="docutils literal"><span class="pre">SPCC::ICC_NE</span> <span class="pre">=</span> <span class="pre">9</span></tt>,
+<tt class="docutils literal"><span class="pre">SPCC::FCC_U</span> <span class="pre">=</span> <span class="pre">23</span></tt> and so on.)</p>
+<div class="section" id="instruction-operand-mapping">
+<h3><a class="toc-backref" href="#id15">Instruction Operand Mapping</a><a class="headerlink" href="#instruction-operand-mapping" title="Permalink to this headline">¶</a></h3>
+<p>The code generator backend maps instruction operands to fields in the
+instruction. Operands are assigned to unbound fields in the instruction in the
+order they are defined. Fields are bound when they are assigned a value. For
+example, the Sparc target defines the <tt class="docutils literal"><span class="pre">XNORrr</span></tt> instruction as a <tt class="docutils literal"><span class="pre">F3_1</span></tt>
+format instruction having three operands.</p>
+<div class="highlight-llvm"><pre>def XNORrr : F3_1<2, 0b000111,
+ (outs IntRegs:$dst), (ins IntRegs:$b, IntRegs:$c),
+ "xnor $b, $c, $dst",
+ [(set i32:$dst, (not (xor i32:$b, i32:$c)))]>;</pre>
+</div>
+<p>The instruction templates in <tt class="docutils literal"><span class="pre">SparcInstrFormats.td</span></tt> show the base class for
+<tt class="docutils literal"><span class="pre">F3_1</span></tt> is <tt class="docutils literal"><span class="pre">InstSP</span></tt>.</p>
+<div class="highlight-llvm"><pre>class InstSP<dag outs, dag ins, string asmstr, list<dag> pattern> : Instruction {
+ field bits<32> Inst;
+ let Namespace = "SP";
+ bits<2> op;
+ let Inst{31-30} = op;
+ dag OutOperandList = outs;
+ dag InOperandList = ins;
+ let AsmString = asmstr;
+ let Pattern = pattern;
+}</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">InstSP</span></tt> leaves the <tt class="docutils literal"><span class="pre">op</span></tt> field unbound.</p>
+<div class="highlight-llvm"><pre>class F3<dag outs, dag ins, string asmstr, list<dag> pattern>
+ : InstSP<outs, ins, asmstr, pattern> {
+ bits<5> rd;
+ bits<6> op3;
+ bits<5> rs1;
+ let op{1} = 1; // Op = 2 or 3
+ let Inst{29-25} = rd;
+ let Inst{24-19} = op3;
+ let Inst{18-14} = rs1;
+}</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">F3</span></tt> binds the <tt class="docutils literal"><span class="pre">op</span></tt> field and defines the <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">op3</span></tt>, and <tt class="docutils literal"><span class="pre">rs1</span></tt>
+fields. <tt class="docutils literal"><span class="pre">F3</span></tt> format instructions will bind the operands <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">op3</span></tt>, and
+<tt class="docutils literal"><span class="pre">rs1</span></tt> fields.</p>
+<div class="highlight-llvm"><pre>class F3_1<bits<2> opVal, bits<6> op3val, dag outs, dag ins,
+ string asmstr, list<dag> pattern> : F3<outs, ins, asmstr, pattern> {
+ bits<8> asi = 0; // asi not currently used
+ bits<5> rs2;
+ let op = opVal;
+ let op3 = op3val;
+ let Inst{13} = 0; // i field = 0
+ let Inst{12-5} = asi; // address space identifier
+ let Inst{4-0} = rs2;
+}</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">F3_1</span></tt> binds the <tt class="docutils literal"><span class="pre">op3</span></tt> field and defines the <tt class="docutils literal"><span class="pre">rs2</span></tt> fields. <tt class="docutils literal"><span class="pre">F3_1</span></tt>
+format instructions will bind the operands to the <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">rs1</span></tt>, and <tt class="docutils literal"><span class="pre">rs2</span></tt>
+fields. This results in the <tt class="docutils literal"><span class="pre">XNORrr</span></tt> instruction binding <tt class="docutils literal"><span class="pre">$dst</span></tt>, <tt class="docutils literal"><span class="pre">$b</span></tt>,
+and <tt class="docutils literal"><span class="pre">$c</span></tt> operands to the <tt class="docutils literal"><span class="pre">rd</span></tt>, <tt class="docutils literal"><span class="pre">rs1</span></tt>, and <tt class="docutils literal"><span class="pre">rs2</span></tt> fields respectively.</p>
+</div>
+<div class="section" id="instruction-relation-mapping">
+<h3><a class="toc-backref" href="#id16">Instruction Relation Mapping</a><a class="headerlink" href="#instruction-relation-mapping" title="Permalink to this headline">¶</a></h3>
+<p>This TableGen feature is used to relate instructions with each other. It is
+particularly useful when you have multiple instruction formats and need to
+switch between them after instruction selection. This entire feature is driven
+by relation models which can be defined in <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> files
+according to the target-specific instruction set. Relation models are defined
+using <tt class="docutils literal"><span class="pre">InstrMapping</span></tt> class as a base. TableGen parses all the models
+and generates instruction relation maps using the specified information.
+Relation maps are emitted as tables in the <tt class="docutils literal"><span class="pre">XXXGenInstrInfo.inc</span></tt> file
+along with the functions to query them. For the detailed information on how to
+use this feature, please refer to <a class="reference internal" href="HowToUseInstrMappings.html"><em>How To Use Instruction Mappings</em></a>.</p>
+</div>
+<div class="section" id="implement-a-subclass-of-targetinstrinfo">
+<h3><a class="toc-backref" href="#id17">Implement a subclass of <tt class="docutils literal"><span class="pre">TargetInstrInfo</span></tt></a><a class="headerlink" href="#implement-a-subclass-of-targetinstrinfo" title="Permalink to this headline">¶</a></h3>
+<p>The final step is to hand code portions of <tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt>, which implements
+the interface described in <tt class="docutils literal"><span class="pre">TargetInstrInfo.h</span></tt> (see <a class="reference internal" href="CodeGenerator.html#targetinstrinfo"><em>The TargetInstrInfo class</em></a>).
+These functions return <tt class="docutils literal"><span class="pre">0</span></tt> or a Boolean or they assert, unless overridden.
+Here’s a list of functions that are overridden for the SPARC implementation in
+<tt class="docutils literal"><span class="pre">SparcInstrInfo.cpp</span></tt>:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">isLoadFromStackSlot</span></tt> — If the specified machine instruction is a direct
+load from a stack slot, return the register number of the destination and the
+<tt class="docutils literal"><span class="pre">FrameIndex</span></tt> of the stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">isStoreToStackSlot</span></tt> — If the specified machine instruction is a direct
+store to a stack slot, return the register number of the destination and the
+<tt class="docutils literal"><span class="pre">FrameIndex</span></tt> of the stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">copyPhysReg</span></tt> — Copy values between a pair of physical registers.</li>
+<li><tt class="docutils literal"><span class="pre">storeRegToStackSlot</span></tt> — Store a register value to a stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">loadRegFromStackSlot</span></tt> — Load a register value from a stack slot.</li>
+<li><tt class="docutils literal"><span class="pre">storeRegToAddr</span></tt> — Store a register value to memory.</li>
+<li><tt class="docutils literal"><span class="pre">loadRegFromAddr</span></tt> — Load a register value from memory.</li>
+<li><tt class="docutils literal"><span class="pre">foldMemoryOperand</span></tt> — Attempt to combine instructions of any load or
+store instruction for the specified operand(s).</li>
+</ul>
+</div>
+<div class="section" id="branch-folding-and-if-conversion">
+<h3><a class="toc-backref" href="#id18">Branch Folding and If Conversion</a><a class="headerlink" href="#branch-folding-and-if-conversion" title="Permalink to this headline">¶</a></h3>
+<p>Performance can be improved by combining instructions or by eliminating
+instructions that are never reached. The <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> method in
+<tt class="docutils literal"><span class="pre">XXXInstrInfo</span></tt> may be implemented to examine conditional instructions and
+remove unnecessary instructions. <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> looks at the end of a
+machine basic block (MBB) for opportunities for improvement, such as branch
+folding and if conversion. The <tt class="docutils literal"><span class="pre">BranchFolder</span></tt> and <tt class="docutils literal"><span class="pre">IfConverter</span></tt> machine
+function passes (see the source files <tt class="docutils literal"><span class="pre">BranchFolding.cpp</span></tt> and
+<tt class="docutils literal"><span class="pre">IfConversion.cpp</span></tt> in the <tt class="docutils literal"><span class="pre">lib/CodeGen</span></tt> directory) call <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt>
+to improve the control flow graph that represents the instructions.</p>
+<p>Several implementations of <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (for ARM, Alpha, and X86) can be
+examined as models for your own <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> implementation. Since SPARC
+does not implement a useful <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt>, the ARM target implementation is
+shown below.</p>
+<p><tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> returns a Boolean value and takes four parameters:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">MachineBasicBlock</span> <span class="pre">&MBB</span></tt> — The incoming block to be examined.</li>
+<li><tt class="docutils literal"><span class="pre">MachineBasicBlock</span> <span class="pre">*&TBB</span></tt> — A destination block that is returned. For a
+conditional branch that evaluates to true, <tt class="docutils literal"><span class="pre">TBB</span></tt> is the destination.</li>
+<li><tt class="docutils literal"><span class="pre">MachineBasicBlock</span> <span class="pre">*&FBB</span></tt> — For a conditional branch that evaluates to
+false, <tt class="docutils literal"><span class="pre">FBB</span></tt> is returned as the destination.</li>
+<li><tt class="docutils literal"><span class="pre">std::vector<MachineOperand></span> <span class="pre">&Cond</span></tt> — List of operands to evaluate a
+condition for a conditional branch.</li>
+</ul>
+<p>In the simplest case, if a block ends without a branch, then it falls through
+to the successor block. No destination blocks are specified for either <tt class="docutils literal"><span class="pre">TBB</span></tt>
+or <tt class="docutils literal"><span class="pre">FBB</span></tt>, so both parameters return <tt class="docutils literal"><span class="pre">NULL</span></tt>. The start of the
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (see code below for the ARM target) shows the function
+parameters and the code for the simplest case.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">ARMInstrInfo</span><span class="o">::</span><span class="n">AnalyzeBranch</span><span class="p">(</span><span class="n">MachineBasicBlock</span> <span class="o">&</span><span class="n">MBB</span><span class="p">,</span>
+ <span class="n">MachineBasicBlock</span> <span class="o">*&</span><span class="n">TBB</span><span class="p">,</span>
+ <span class="n">MachineBasicBlock</span> <span class="o">*&</span><span class="n">FBB</span><span class="p">,</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">MachineOperand</span><span class="o">></span> <span class="o">&</span><span class="n">Cond</span><span class="p">)</span> <span class="k">const</span>
+<span class="p">{</span>
+ <span class="n">MachineBasicBlock</span><span class="o">::</span><span class="n">iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">MBB</span><span class="p">.</span><span class="n">end</span><span class="p">();</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">I</span> <span class="o">==</span> <span class="n">MBB</span><span class="p">.</span><span class="n">begin</span><span class="p">()</span> <span class="o">||</span> <span class="o">!</span><span class="n">isUnpredicatedTerminator</span><span class="p">(</span><span class="o">--</span><span class="n">I</span><span class="p">))</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>If a block ends with a single unconditional branch instruction, then
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (shown below) should return the destination of that branch in
+the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span> <span class="o">||</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If a block ends with two unconditional branches, then the second branch is
+never reached. In that situation, as shown below, remove the last branch
+instruction and return the penultimate branch in the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">((</span><span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span> <span class="o">||</span> <span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">)</span> <span class="o">&&</span>
+ <span class="p">(</span><span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span> <span class="o">||</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="n">I</span> <span class="o">=</span> <span class="n">LastInst</span><span class="p">;</span>
+ <span class="n">I</span><span class="o">-></span><span class="n">eraseFromParent</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>A block may end with a single conditional branch instruction that falls through
+to successor block if the condition evaluates to false. In that case,
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (shown below) should return the destination of that
+conditional branch in the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter and a list of operands in the
+<tt class="docutils literal"><span class="pre">Cond</span></tt> parameter to evaluate the condition.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">Bcc</span> <span class="o">||</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tBcc</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Block ends with fall-through condbranch.</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">2</span><span class="p">));</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If a block ends with both a conditional branch and an ensuing unconditional
+branch, then <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> (shown below) should return the conditional
+branch destination (assuming it corresponds to a conditional evaluation of
+“<tt class="docutils literal"><span class="pre">true</span></tt>”) in the <tt class="docutils literal"><span class="pre">TBB</span></tt> parameter and the unconditional branch destination
+in the <tt class="docutils literal"><span class="pre">FBB</span></tt> (corresponding to a conditional evaluation of “<tt class="docutils literal"><span class="pre">false</span></tt>”). A
+list of operands to evaluate the condition should be returned in the <tt class="docutils literal"><span class="pre">Cond</span></tt>
+parameter.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">unsigned</span> <span class="n">SecondLastOpc</span> <span class="o">=</span> <span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOpcode</span><span class="p">();</span>
+
+<span class="k">if</span> <span class="p">((</span><span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">Bcc</span> <span class="o">&&</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">B</span><span class="p">)</span> <span class="o">||</span>
+ <span class="p">(</span><span class="n">SecondLastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tBcc</span> <span class="o">&&</span> <span class="n">LastOpc</span> <span class="o">==</span> <span class="n">ARM</span><span class="o">::</span><span class="n">tB</span><span class="p">))</span> <span class="p">{</span>
+ <span class="n">TBB</span> <span class="o">=</span> <span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">));</span>
+ <span class="n">Cond</span><span class="p">.</span><span class="n">push_back</span><span class="p">(</span><span class="n">SecondLastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">2</span><span class="p">));</span>
+ <span class="n">FBB</span> <span class="o">=</span> <span class="n">LastInst</span><span class="o">-></span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">).</span><span class="n">getMBB</span><span class="p">();</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For the last two cases (ending with a single conditional branch or ending with
+one conditional and one unconditional branch), the operands returned in the
+<tt class="docutils literal"><span class="pre">Cond</span></tt> parameter can be passed to methods of other instructions to create new
+branches or perform other operations. An implementation of <tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt>
+requires the helper methods <tt class="docutils literal"><span class="pre">RemoveBranch</span></tt> and <tt class="docutils literal"><span class="pre">InsertBranch</span></tt> to manage
+subsequent operations.</p>
+<p><tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> should return false indicating success in most circumstances.
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> should only return true when the method is stumped about what
+to do, for example, if a block has three terminating branches.
+<tt class="docutils literal"><span class="pre">AnalyzeBranch</span></tt> may return true if it encounters a terminator it cannot
+handle, such as an indirect branch.</p>
+</div>
+</div>
+<div class="section" id="instruction-selector">
+<span id="id2"></span><h2><a class="toc-backref" href="#id19">Instruction Selector</a><a class="headerlink" href="#instruction-selector" title="Permalink to this headline">¶</a></h2>
+<p>LLVM uses a <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> to represent LLVM IR instructions, and nodes of
+the <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> ideally represent native target instructions. During code
+generation, instruction selection passes are performed to convert non-native
+DAG instructions into native target-specific instructions. The pass described
+in <tt class="docutils literal"><span class="pre">XXXISelDAGToDAG.cpp</span></tt> is used to match patterns and perform DAG-to-DAG
+instruction selection. Optionally, a pass may be defined (in
+<tt class="docutils literal"><span class="pre">XXXBranchSelector.cpp</span></tt>) to perform similar DAG-to-DAG operations for branch
+instructions. Later, the code in <tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt> replaces or removes
+operations and data types not supported natively (legalizes) in a
+<tt class="docutils literal"><span class="pre">SelectionDAG</span></tt>.</p>
+<p>TableGen generates code for instruction selection using the following target
+description input files:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> — Contains definitions of instructions in a
+target-specific instruction set, generates <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt>, which is
+included in <tt class="docutils literal"><span class="pre">XXXISelDAGToDAG.cpp</span></tt>.</li>
+<li><tt class="docutils literal"><span class="pre">XXXCallingConv.td</span></tt> — Contains the calling and return value conventions
+for the target architecture, and it generates <tt class="docutils literal"><span class="pre">XXXGenCallingConv.inc</span></tt>,
+which is included in <tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt>.</li>
+</ul>
+<p>The implementation of an instruction selection pass must include a header that
+declares the <tt class="docutils literal"><span class="pre">FunctionPass</span></tt> class or a subclass of <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>. In
+<tt class="docutils literal"><span class="pre">XXXTargetMachine.cpp</span></tt>, a Pass Manager (PM) should add each instruction
+selection pass into the queue of passes to run.</p>
+<p>The LLVM static compiler (<tt class="docutils literal"><span class="pre">llc</span></tt>) is an excellent tool for visualizing the
+contents of DAGs. To display the <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> before or after specific
+processing phases, use the command line options for <tt class="docutils literal"><span class="pre">llc</span></tt>, described at
+<a class="reference internal" href="CodeGenerator.html#selectiondag-process"><em>SelectionDAG Instruction Selection Process</em></a>.</p>
+<p>To describe instruction selector behavior, you should add patterns for lowering
+LLVM code into a <tt class="docutils literal"><span class="pre">SelectionDAG</span></tt> as the last parameter of the instruction
+definitions in <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt>. For example, in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>,
+this entry defines a register store operation, and the last parameter describes
+a pattern with the store DAG operator.</p>
+<div class="highlight-llvm"><pre>def STrr : F3_1< 3, 0b000100, (outs), (ins MEMrr:$addr, IntRegs:$src),
+ "st $src, [$addr]", [(store i32:$src, ADDRrr:$addr)]>;</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">ADDRrr</span></tt> is a memory mode that is also defined in <tt class="docutils literal"><span class="pre">SparcInstrInfo.td</span></tt>:</p>
+<div class="highlight-llvm"><pre>def ADDRrr : ComplexPattern<i32, 2, "SelectADDRrr", [], []>;</pre>
+</div>
+<p>The definition of <tt class="docutils literal"><span class="pre">ADDRrr</span></tt> refers to <tt class="docutils literal"><span class="pre">SelectADDRrr</span></tt>, which is a function
+defined in an implementation of the Instructor Selector (such as
+<tt class="docutils literal"><span class="pre">SparcISelDAGToDAG.cpp</span></tt>).</p>
+<p>In <tt class="docutils literal"><span class="pre">lib/Target/TargetSelectionDAG.td</span></tt>, the DAG operator for store is defined
+below:</p>
+<div class="highlight-llvm"><pre>def store : PatFrag<(ops node:$val, node:$ptr),
+ (st node:$val, node:$ptr), [{
+ if (StoreSDNode *ST = dyn_cast<StoreSDNode>(N))
+ return !ST->isTruncatingStore() &&
+ ST->getAddressingMode() == ISD::UNINDEXED;
+ return false;
+}]>;</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> also generates (in <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt>) the
+<tt class="docutils literal"><span class="pre">SelectCode</span></tt> method that is used to call the appropriate processing method
+for an instruction. In this example, <tt class="docutils literal"><span class="pre">SelectCode</span></tt> calls <tt class="docutils literal"><span class="pre">Select_ISD_STORE</span></tt>
+for the <tt class="docutils literal"><span class="pre">ISD::STORE</span></tt> opcode.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SDNode</span> <span class="o">*</span><span class="nf">SelectCode</span><span class="p">(</span><span class="n">SDValue</span> <span class="n">N</span><span class="p">)</span> <span class="p">{</span>
+ <span class="p">...</span>
+ <span class="n">MVT</span><span class="o">::</span><span class="n">ValueType</span> <span class="n">NVT</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getNode</span><span class="p">()</span><span class="o">-></span><span class="n">getValueType</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">N</span><span class="p">.</span><span class="n">getOpcode</span><span class="p">())</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">ISD</span>:<span class="o">:</span><span class="n">STORE</span><span class="o">:</span> <span class="p">{</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">NVT</span><span class="p">)</span> <span class="p">{</span>
+ <span class="nl">default:</span>
+ <span class="k">return</span> <span class="n">Select_ISD_STORE</span><span class="p">(</span><span class="n">N</span><span class="p">);</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">break</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+<p>The pattern for <tt class="docutils literal"><span class="pre">STrr</span></tt> is matched, so elsewhere in <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt>,
+code for <tt class="docutils literal"><span class="pre">STrr</span></tt> is created for <tt class="docutils literal"><span class="pre">Select_ISD_STORE</span></tt>. The <tt class="docutils literal"><span class="pre">Emit_22</span></tt> method
+is also generated in <tt class="docutils literal"><span class="pre">XXXGenDAGISel.inc</span></tt> to complete the processing of this
+instruction.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SDNode</span> <span class="o">*</span><span class="nf">Select_ISD_STORE</span><span class="p">(</span><span class="k">const</span> <span class="n">SDValue</span> <span class="o">&</span><span class="n">N</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">SDValue</span> <span class="n">Chain</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Predicate_store</span><span class="p">(</span><span class="n">N</span><span class="p">.</span><span class="n">getNode</span><span class="p">()))</span> <span class="p">{</span>
+ <span class="n">SDValue</span> <span class="n">N1</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
+ <span class="n">SDValue</span> <span class="n">N2</span> <span class="o">=</span> <span class="n">N</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">2</span><span class="p">);</span>
+ <span class="n">SDValue</span> <span class="n">CPTmp0</span><span class="p">;</span>
+ <span class="n">SDValue</span> <span class="n">CPTmp1</span><span class="p">;</span>
+
+ <span class="c1">// Pattern: (st:void i32:i32:$src,</span>
+ <span class="c1">// ADDRrr:i32:$addr)<<P:Predicate_store>></span>
+ <span class="c1">// Emits: (STrr:void ADDRrr:i32:$addr, IntRegs:i32:$src)</span>
+ <span class="c1">// Pattern complexity = 13 cost = 1 size = 0</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">SelectADDRrr</span><span class="p">(</span><span class="n">N</span><span class="p">,</span> <span class="n">N2</span><span class="p">,</span> <span class="n">CPTmp0</span><span class="p">,</span> <span class="n">CPTmp1</span><span class="p">)</span> <span class="o">&&</span>
+ <span class="n">N1</span><span class="p">.</span><span class="n">getNode</span><span class="p">()</span><span class="o">-></span><span class="n">getValueType</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span> <span class="o">&&</span>
+ <span class="n">N2</span><span class="p">.</span><span class="n">getNode</span><span class="p">()</span><span class="o">-></span><span class="n">getValueType</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> <span class="o">==</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">Emit_22</span><span class="p">(</span><span class="n">N</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">STrr</span><span class="p">,</span> <span class="n">CPTmp0</span><span class="p">,</span> <span class="n">CPTmp1</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<div class="section" id="the-selectiondag-legalize-phase">
+<h3><a class="toc-backref" href="#id20">The SelectionDAG Legalize Phase</a><a class="headerlink" href="#the-selectiondag-legalize-phase" title="Permalink to this headline">¶</a></h3>
+<p>The Legalize phase converts a DAG to use types and operations that are natively
+supported by the target. For natively unsupported types and operations, you
+need to add code to the target-specific <tt class="docutils literal"><span class="pre">XXXTargetLowering</span></tt> implementation to
+convert unsupported types and operations to supported ones.</p>
+<p>In the constructor for the <tt class="docutils literal"><span class="pre">XXXTargetLowering</span></tt> class, first use the
+<tt class="docutils literal"><span class="pre">addRegisterClass</span></tt> method to specify which types are supported and which
+register classes are associated with them. The code for the register classes
+are generated by TableGen from <tt class="docutils literal"><span class="pre">XXXRegisterInfo.td</span></tt> and placed in
+<tt class="docutils literal"><span class="pre">XXXGenRegisterInfo.h.inc</span></tt>. For example, the implementation of the
+constructor for the SparcTargetLowering class (in <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt>)
+starts with the following code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">addRegisterClass</span><span class="p">(</span><span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">IntRegsRegisterClass</span><span class="p">);</span>
+<span class="n">addRegisterClass</span><span class="p">(</span><span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">FPRegsRegisterClass</span><span class="p">);</span>
+<span class="n">addRegisterClass</span><span class="p">(</span><span class="n">MVT</span><span class="o">::</span><span class="n">f64</span><span class="p">,</span> <span class="n">SP</span><span class="o">::</span><span class="n">DFPRegsRegisterClass</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>You should examine the node types in the <tt class="docutils literal"><span class="pre">ISD</span></tt> namespace
+(<tt class="docutils literal"><span class="pre">include/llvm/CodeGen/SelectionDAGNodes.h</span></tt>) and determine which operations
+the target natively supports. For operations that do <strong>not</strong> have native
+support, add a callback to the constructor for the <tt class="docutils literal"><span class="pre">XXXTargetLowering</span></tt> class,
+so the instruction selection process knows what to do. The <tt class="docutils literal"><span class="pre">TargetLowering</span></tt>
+class callback methods (declared in <tt class="docutils literal"><span class="pre">llvm/Target/TargetLowering.h</span></tt>) are:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">setOperationAction</span></tt> — General operation.</li>
+<li><tt class="docutils literal"><span class="pre">setLoadExtAction</span></tt> — Load with extension.</li>
+<li><tt class="docutils literal"><span class="pre">setTruncStoreAction</span></tt> — Truncating store.</li>
+<li><tt class="docutils literal"><span class="pre">setIndexedLoadAction</span></tt> — Indexed load.</li>
+<li><tt class="docutils literal"><span class="pre">setIndexedStoreAction</span></tt> — Indexed store.</li>
+<li><tt class="docutils literal"><span class="pre">setConvertAction</span></tt> — Type conversion.</li>
+<li><tt class="docutils literal"><span class="pre">setCondCodeAction</span></tt> — Support for a given condition code.</li>
+</ul>
+<p>Note: on older releases, <tt class="docutils literal"><span class="pre">setLoadXAction</span></tt> is used instead of
+<tt class="docutils literal"><span class="pre">setLoadExtAction</span></tt>. Also, on older releases, <tt class="docutils literal"><span class="pre">setCondCodeAction</span></tt> may not
+be supported. Examine your release to see what methods are specifically
+supported.</p>
+<p>These callbacks are used to determine that an operation does or does not work
+with a specified type (or types). And in all cases, the third parameter is a
+<tt class="docutils literal"><span class="pre">LegalAction</span></tt> type enum value: <tt class="docutils literal"><span class="pre">Promote</span></tt>, <tt class="docutils literal"><span class="pre">Expand</span></tt>, <tt class="docutils literal"><span class="pre">Custom</span></tt>, or
+<tt class="docutils literal"><span class="pre">Legal</span></tt>. <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt> contains examples of all four
+<tt class="docutils literal"><span class="pre">LegalAction</span></tt> values.</p>
+<div class="section" id="promote">
+<h4><a class="toc-backref" href="#id21">Promote</a><a class="headerlink" href="#promote" title="Permalink to this headline">¶</a></h4>
+<p>For an operation without native support for a given type, the specified type
+may be promoted to a larger type that is supported. For example, SPARC does
+not support a sign-extending load for Boolean values (<tt class="docutils literal"><span class="pre">i1</span></tt> type), so in
+<tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt> the third parameter below, <tt class="docutils literal"><span class="pre">Promote</span></tt>, changes
+<tt class="docutils literal"><span class="pre">i1</span></tt> type values to a large type before loading.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setLoadExtAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">SEXTLOAD</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i1</span><span class="p">,</span> <span class="n">Promote</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="expand">
+<h4><a class="toc-backref" href="#id22">Expand</a><a class="headerlink" href="#expand" title="Permalink to this headline">¶</a></h4>
+<p>For a type without native support, a value may need to be broken down further,
+rather than promoted. For an operation without native support, a combination
+of other operations may be used to similar effect. In SPARC, the
+floating-point sine and cosine trig operations are supported by expansion to
+other operations, as indicated by the third parameter, <tt class="docutils literal"><span class="pre">Expand</span></tt>, to
+<tt class="docutils literal"><span class="pre">setOperationAction</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">FSIN</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">Expand</span><span class="p">);</span>
+<span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">FCOS</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">Expand</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="custom">
+<h4><a class="toc-backref" href="#id23">Custom</a><a class="headerlink" href="#custom" title="Permalink to this headline">¶</a></h4>
+<p>For some operations, simple type promotion or operation expansion may be
+insufficient. In some cases, a special intrinsic function must be implemented.</p>
+<p>For example, a constant value may require special treatment, or an operation
+may require spilling and restoring registers in the stack and working with
+register allocators.</p>
+<p>As seen in <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt> code below, to perform a type conversion
+from a floating point value to a signed integer, first the
+<tt class="docutils literal"><span class="pre">setOperationAction</span></tt> should be called with <tt class="docutils literal"><span class="pre">Custom</span></tt> as the third parameter:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">FP_TO_SINT</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Custom</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In the <tt class="docutils literal"><span class="pre">LowerOperation</span></tt> method, for each <tt class="docutils literal"><span class="pre">Custom</span></tt> operation, a case
+statement should be added to indicate what function to call. In the following
+code, an <tt class="docutils literal"><span class="pre">FP_TO_SINT</span></tt> opcode will call the <tt class="docutils literal"><span class="pre">LowerFP_TO_SINT</span></tt> method:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SDValue</span> <span class="n">SparcTargetLowering</span><span class="o">::</span><span class="n">LowerOperation</span><span class="p">(</span><span class="n">SDValue</span> <span class="n">Op</span><span class="p">,</span> <span class="n">SelectionDAG</span> <span class="o">&</span><span class="n">DAG</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">Op</span><span class="p">.</span><span class="n">getOpcode</span><span class="p">())</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="n">ISD</span>:<span class="o">:</span><span class="n">FP_TO_SINT</span><span class="o">:</span> <span class="k">return</span> <span class="n">LowerFP_TO_SINT</span><span class="p">(</span><span class="n">Op</span><span class="p">,</span> <span class="n">DAG</span><span class="p">);</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Finally, the <tt class="docutils literal"><span class="pre">LowerFP_TO_SINT</span></tt> method is implemented, using an FP register to
+convert the floating-point value to an integer.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">SDValue</span> <span class="nf">LowerFP_TO_SINT</span><span class="p">(</span><span class="n">SDValue</span> <span class="n">Op</span><span class="p">,</span> <span class="n">SelectionDAG</span> <span class="o">&</span><span class="n">DAG</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Op</span><span class="p">.</span><span class="n">getValueType</span><span class="p">()</span> <span class="o">==</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">);</span>
+ <span class="n">Op</span> <span class="o">=</span> <span class="n">DAG</span><span class="p">.</span><span class="n">getNode</span><span class="p">(</span><span class="n">SPISD</span><span class="o">::</span><span class="n">FTOI</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">f32</span><span class="p">,</span> <span class="n">Op</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span>
+ <span class="k">return</span> <span class="n">DAG</span><span class="p">.</span><span class="n">getNode</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">BITCAST</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Op</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="legal">
+<h4><a class="toc-backref" href="#id24">Legal</a><a class="headerlink" href="#legal" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">Legal</span></tt> <tt class="docutils literal"><span class="pre">LegalizeAction</span></tt> enum value simply indicates that an operation
+<strong>is</strong> natively supported. <tt class="docutils literal"><span class="pre">Legal</span></tt> represents the default condition, so it
+is rarely used. In <tt class="docutils literal"><span class="pre">SparcISelLowering.cpp</span></tt>, the action for <tt class="docutils literal"><span class="pre">CTPOP</span></tt> (an
+operation to count the bits set in an integer) is natively supported only for
+SPARC v9. The following code enables the <tt class="docutils literal"><span class="pre">Expand</span></tt> conversion technique for
+non-v9 SPARC implementations.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">CTPOP</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Expand</span><span class="p">);</span>
+<span class="p">...</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">TM</span><span class="p">.</span><span class="n">getSubtarget</span><span class="o"><</span><span class="n">SparcSubtarget</span><span class="o">></span><span class="p">().</span><span class="n">isV9</span><span class="p">())</span>
+ <span class="n">setOperationAction</span><span class="p">(</span><span class="n">ISD</span><span class="o">::</span><span class="n">CTPOP</span><span class="p">,</span> <span class="n">MVT</span><span class="o">::</span><span class="n">i32</span><span class="p">,</span> <span class="n">Legal</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="calling-conventions">
+<h3><a class="toc-backref" href="#id25">Calling Conventions</a><a class="headerlink" href="#calling-conventions" title="Permalink to this headline">¶</a></h3>
+<p>To support target-specific calling conventions, <tt class="docutils literal"><span class="pre">XXXGenCallingConv.td</span></tt> uses
+interfaces (such as <tt class="docutils literal"><span class="pre">CCIfType</span></tt> and <tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt>) that are defined in
+<tt class="docutils literal"><span class="pre">lib/Target/TargetCallingConv.td</span></tt>. TableGen can take the target descriptor
+file <tt class="docutils literal"><span class="pre">XXXGenCallingConv.td</span></tt> and generate the header file
+<tt class="docutils literal"><span class="pre">XXXGenCallingConv.inc</span></tt>, which is typically included in
+<tt class="docutils literal"><span class="pre">XXXISelLowering.cpp</span></tt>. You can use the interfaces in
+<tt class="docutils literal"><span class="pre">TargetCallingConv.td</span></tt> to specify:</p>
+<ul class="simple">
+<li>The order of parameter allocation.</li>
+<li>Where parameters and return values are placed (that is, on the stack or in
+registers).</li>
+<li>Which registers may be used.</li>
+<li>Whether the caller or callee unwinds the stack.</li>
+</ul>
+<p>The following example demonstrates the use of the <tt class="docutils literal"><span class="pre">CCIfType</span></tt> and
+<tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt> interfaces. If the <tt class="docutils literal"><span class="pre">CCIfType</span></tt> predicate is true (that is,
+if the current argument is of type <tt class="docutils literal"><span class="pre">f32</span></tt> or <tt class="docutils literal"><span class="pre">f64</span></tt>), then the action is
+performed. In this case, the <tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt> action assigns the argument
+value to the first available register: either <tt class="docutils literal"><span class="pre">R0</span></tt> or <tt class="docutils literal"><span class="pre">R1</span></tt>.</p>
+<div class="highlight-llvm"><pre>CCIfType<[f32,f64], CCAssignToReg<[R0, R1]>></pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">SparcCallingConv.td</span></tt> contains definitions for a target-specific return-value
+calling convention (<tt class="docutils literal"><span class="pre">RetCC_Sparc32</span></tt>) and a basic 32-bit C calling convention
+(<tt class="docutils literal"><span class="pre">CC_Sparc32</span></tt>). The definition of <tt class="docutils literal"><span class="pre">RetCC_Sparc32</span></tt> (shown below) indicates
+which registers are used for specified scalar return types. A single-precision
+float is returned to register <tt class="docutils literal"><span class="pre">F0</span></tt>, and a double-precision float goes to
+register <tt class="docutils literal"><span class="pre">D0</span></tt>. A 32-bit integer is returned in register <tt class="docutils literal"><span class="pre">I0</span></tt> or <tt class="docutils literal"><span class="pre">I1</span></tt>.</p>
+<div class="highlight-llvm"><pre>def RetCC_Sparc32 : CallingConv<[
+ CCIfType<[i32], CCAssignToReg<[I0, I1]>>,
+ CCIfType<[f32], CCAssignToReg<[F0]>>,
+ CCIfType<[f64], CCAssignToReg<[D0]>>
+]>;</pre>
+</div>
+<p>The definition of <tt class="docutils literal"><span class="pre">CC_Sparc32</span></tt> in <tt class="docutils literal"><span class="pre">SparcCallingConv.td</span></tt> introduces
+<tt class="docutils literal"><span class="pre">CCAssignToStack</span></tt>, which assigns the value to a stack slot with the specified
+size and alignment. In the example below, the first parameter, 4, indicates
+the size of the slot, and the second parameter, also 4, indicates the stack
+alignment along 4-byte units. (Special cases: if size is zero, then the ABI
+size is used; if alignment is zero, then the ABI alignment is used.)</p>
+<div class="highlight-llvm"><pre>def CC_Sparc32 : CallingConv<[
+ // All arguments get passed in integer registers if there is space.
+ CCIfType<[i32, f32, f64], CCAssignToReg<[I0, I1, I2, I3, I4, I5]>>,
+ CCAssignToStack<4, 4>
+]>;</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">CCDelegateTo</span></tt> is another commonly used interface, which tries to find a
+specified sub-calling convention, and, if a match is found, it is invoked. In
+the following example (in <tt class="docutils literal"><span class="pre">X86CallingConv.td</span></tt>), the definition of
+<tt class="docutils literal"><span class="pre">RetCC_X86_32_C</span></tt> ends with <tt class="docutils literal"><span class="pre">CCDelegateTo</span></tt>. After the current value is
+assigned to the register <tt class="docutils literal"><span class="pre">ST0</span></tt> or <tt class="docutils literal"><span class="pre">ST1</span></tt>, the <tt class="docutils literal"><span class="pre">RetCC_X86Common</span></tt> is
+invoked.</p>
+<div class="highlight-llvm"><pre>def RetCC_X86_32_C : CallingConv<[
+ CCIfType<[f32], CCAssignToReg<[ST0, ST1]>>,
+ CCIfType<[f64], CCAssignToReg<[ST0, ST1]>>,
+ CCDelegateTo<RetCC_X86Common>
+]>;</pre>
+</div>
+<p><tt class="docutils literal"><span class="pre">CCIfCC</span></tt> is an interface that attempts to match the given name to the current
+calling convention. If the name identifies the current calling convention,
+then a specified action is invoked. In the following example (in
+<tt class="docutils literal"><span class="pre">X86CallingConv.td</span></tt>), if the <tt class="docutils literal"><span class="pre">Fast</span></tt> calling convention is in use, then
+<tt class="docutils literal"><span class="pre">RetCC_X86_32_Fast</span></tt> is invoked. If the <tt class="docutils literal"><span class="pre">SSECall</span></tt> calling convention is in
+use, then <tt class="docutils literal"><span class="pre">RetCC_X86_32_SSE</span></tt> is invoked.</p>
+<div class="highlight-llvm"><pre>def RetCC_X86_32 : CallingConv<[
+ CCIfCC<"CallingConv::Fast", CCDelegateTo<RetCC_X86_32_Fast>>,
+ CCIfCC<"CallingConv::X86_SSECall", CCDelegateTo<RetCC_X86_32_SSE>>,
+ CCDelegateTo<RetCC_X86_32_C>
+]>;</pre>
+</div>
+<p>Other calling convention interfaces include:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">CCIf</span> <span class="pre"><predicate,</span> <span class="pre">action></span></tt> — If the predicate matches, apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCIfInReg</span> <span class="pre"><action></span></tt> — If the argument is marked with the “<tt class="docutils literal"><span class="pre">inreg</span></tt>”
+attribute, then apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCIfNest</span> <span class="pre"><action></span></tt> — If the argument is marked with the “<tt class="docutils literal"><span class="pre">nest</span></tt>”
+attribute, then apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCIfNotVarArg</span> <span class="pre"><action></span></tt> — If the current function does not take a
+variable number of arguments, apply the action.</li>
+<li><tt class="docutils literal"><span class="pre">CCAssignToRegWithShadow</span> <span class="pre"><registerList,</span> <span class="pre">shadowList></span></tt> — similar to
+<tt class="docutils literal"><span class="pre">CCAssignToReg</span></tt>, but with a shadow list of registers.</li>
+<li><tt class="docutils literal"><span class="pre">CCPassByVal</span> <span class="pre"><size,</span> <span class="pre">align></span></tt> — Assign value to a stack slot with the
+minimum specified size and alignment.</li>
+<li><tt class="docutils literal"><span class="pre">CCPromoteToType</span> <span class="pre"><type></span></tt> — Promote the current value to the specified
+type.</li>
+<li><tt class="docutils literal"><span class="pre">CallingConv</span> <span class="pre"><[actions]></span></tt> — Define each calling convention that is
+supported.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="assembly-printer">
+<h2><a class="toc-backref" href="#id26">Assembly Printer</a><a class="headerlink" href="#assembly-printer" title="Permalink to this headline">¶</a></h2>
+<p>During the code emission stage, the code generator may utilize an LLVM pass to
+produce assembly output. To do this, you want to implement the code for a
+printer that converts LLVM IR to a GAS-format assembly language for your target
+machine, using the following steps:</p>
+<ul class="simple">
+<li>Define all the assembly strings for your target, adding them to the
+instructions defined in the <tt class="docutils literal"><span class="pre">XXXInstrInfo.td</span></tt> file. (See
+<a class="reference internal" href="#instruction-set"><em>Instruction Set</em></a>.) TableGen will produce an output file
+(<tt class="docutils literal"><span class="pre">XXXGenAsmWriter.inc</span></tt>) with an implementation of the <tt class="docutils literal"><span class="pre">printInstruction</span></tt>
+method for the <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt> class.</li>
+<li>Write <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.h</span></tt>, which contains the bare-bones declaration of
+the <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo</span></tt> class (a subclass of <tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt>).</li>
+<li>Write <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.cpp</span></tt>, which contains target-specific values for
+<tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt> properties and sometimes new implementations for methods.</li>
+<li>Write <tt class="docutils literal"><span class="pre">XXXAsmPrinter.cpp</span></tt>, which implements the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> class that
+performs the LLVM-to-assembly conversion.</li>
+</ul>
+<p>The code in <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.h</span></tt> is usually a trivial declaration of the
+<tt class="docutils literal"><span class="pre">XXXTargetAsmInfo</span></tt> class for use in <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.cpp</span></tt>. Similarly,
+<tt class="docutils literal"><span class="pre">XXXTargetAsmInfo.cpp</span></tt> usually has a few declarations of <tt class="docutils literal"><span class="pre">XXXTargetAsmInfo</span></tt>
+replacement values that override the default values in <tt class="docutils literal"><span class="pre">TargetAsmInfo.cpp</span></tt>.
+For example in <tt class="docutils literal"><span class="pre">SparcTargetAsmInfo.cpp</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">SparcTargetAsmInfo</span><span class="o">::</span><span class="n">SparcTargetAsmInfo</span><span class="p">(</span><span class="k">const</span> <span class="n">SparcTargetMachine</span> <span class="o">&</span><span class="n">TM</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Data16bitsDirective</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.half</span><span class="se">\t</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">Data32bitsDirective</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.word</span><span class="se">\t</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">Data64bitsDirective</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">// .xword is only supported by V9.</span>
+ <span class="n">ZeroDirective</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.skip</span><span class="se">\t</span><span class="s">"</span><span class="p">;</span>
+ <span class="n">CommentString</span> <span class="o">=</span> <span class="s">"!"</span><span class="p">;</span>
+ <span class="n">ConstantPoolSection</span> <span class="o">=</span> <span class="s">"</span><span class="se">\t</span><span class="s">.section </span><span class="se">\"</span><span class="s">.rodata</span><span class="se">\"</span><span class="s">,#alloc</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The X86 assembly printer implementation (<tt class="docutils literal"><span class="pre">X86TargetAsmInfo</span></tt>) is an example
+where the target specific <tt class="docutils literal"><span class="pre">TargetAsmInfo</span></tt> class uses an overridden methods:
+<tt class="docutils literal"><span class="pre">ExpandInlineAsm</span></tt>.</p>
+<p>A target-specific implementation of <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> is written in
+<tt class="docutils literal"><span class="pre">XXXAsmPrinter.cpp</span></tt>, which implements the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> class that converts
+the LLVM to printable assembly. The implementation must include the following
+headers that have declarations for the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> and
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> classes. The <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt> is a subclass of
+<tt class="docutils literal"><span class="pre">FunctionPass</span></tt>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/CodeGen/AsmPrinter.h"</span>
+<span class="cp">#include "llvm/CodeGen/MachineFunctionPass.h"</span>
+</pre></div>
+</div>
+<p>As a <tt class="docutils literal"><span class="pre">FunctionPass</span></tt>, <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> first calls <tt class="docutils literal"><span class="pre">doInitialization</span></tt> to set
+up the <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt>. In <tt class="docutils literal"><span class="pre">SparcAsmPrinter</span></tt>, a <tt class="docutils literal"><span class="pre">Mangler</span></tt> object is
+instantiated to process variable names.</p>
+<p>In <tt class="docutils literal"><span class="pre">XXXAsmPrinter.cpp</span></tt>, the <tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> method (declared in
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>) must be implemented for <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt>. In
+<tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>, the <tt class="docutils literal"><span class="pre">runOnFunction</span></tt> method invokes
+<tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt>. Target-specific implementations of
+<tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> differ, but generally do the following to process each
+machine function:</p>
+<ul class="simple">
+<li>Call <tt class="docutils literal"><span class="pre">SetupMachineFunction</span></tt> to perform initialization.</li>
+<li>Call <tt class="docutils literal"><span class="pre">EmitConstantPool</span></tt> to print out (to the output stream) constants which
+have been spilled to memory.</li>
+<li>Call <tt class="docutils literal"><span class="pre">EmitJumpTableInfo</span></tt> to print out jump tables used by the current
+function.</li>
+<li>Print out the label for the current function.</li>
+<li>Print out the code for the function, including basic block labels and the
+assembly for the instruction (using <tt class="docutils literal"><span class="pre">printInstruction</span></tt>)</li>
+</ul>
+<p>The <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt> implementation must also include the code generated by
+TableGen that is output in the <tt class="docutils literal"><span class="pre">XXXGenAsmWriter.inc</span></tt> file. The code in
+<tt class="docutils literal"><span class="pre">XXXGenAsmWriter.inc</span></tt> contains an implementation of the <tt class="docutils literal"><span class="pre">printInstruction</span></tt>
+method that may call these methods:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">printOperand</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printMemOperand</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printCCOperand</span></tt> (for conditional statements)</li>
+<li><tt class="docutils literal"><span class="pre">printDataDirective</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printDeclare</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printImplicitDef</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">printInlineAsm</span></tt></li>
+</ul>
+<p>The implementations of <tt class="docutils literal"><span class="pre">printDeclare</span></tt>, <tt class="docutils literal"><span class="pre">printImplicitDef</span></tt>,
+<tt class="docutils literal"><span class="pre">printInlineAsm</span></tt>, and <tt class="docutils literal"><span class="pre">printLabel</span></tt> in <tt class="docutils literal"><span class="pre">AsmPrinter.cpp</span></tt> are generally
+adequate for printing assembly and do not need to be overridden.</p>
+<p>The <tt class="docutils literal"><span class="pre">printOperand</span></tt> method is implemented with a long <tt class="docutils literal"><span class="pre">switch</span></tt>/<tt class="docutils literal"><span class="pre">case</span></tt>
+statement for the type of operand: register, immediate, basic block, external
+symbol, global address, constant pool index, or jump table index. For an
+instruction with a memory address operand, the <tt class="docutils literal"><span class="pre">printMemOperand</span></tt> method
+should be implemented to generate the proper output. Similarly,
+<tt class="docutils literal"><span class="pre">printCCOperand</span></tt> should be used to print a conditional operand.</p>
+<p><tt class="docutils literal"><span class="pre">doFinalization</span></tt> should be overridden in <tt class="docutils literal"><span class="pre">XXXAsmPrinter</span></tt>, and it should be
+called to shut down the assembly printer. During <tt class="docutils literal"><span class="pre">doFinalization</span></tt>, global
+variables and constants are printed to output.</p>
+</div>
+<div class="section" id="subtarget-support">
+<h2><a class="toc-backref" href="#id27">Subtarget Support</a><a class="headerlink" href="#subtarget-support" title="Permalink to this headline">¶</a></h2>
+<p>Subtarget support is used to inform the code generation process of instruction
+set variations for a given chip set. For example, the LLVM SPARC
+implementation provided covers three major versions of the SPARC microprocessor
+architecture: Version 8 (V8, which is a 32-bit architecture), Version 9 (V9, a
+64-bit architecture), and the UltraSPARC architecture. V8 has 16
+double-precision floating-point registers that are also usable as either 32
+single-precision or 8 quad-precision registers. V8 is also purely big-endian.
+V9 has 32 double-precision floating-point registers that are also usable as 16
+quad-precision registers, but cannot be used as single-precision registers.
+The UltraSPARC architecture combines V9 with UltraSPARC Visual Instruction Set
+extensions.</p>
+<p>If subtarget support is needed, you should implement a target-specific
+<tt class="docutils literal"><span class="pre">XXXSubtarget</span></tt> class for your architecture. This class should process the
+command-line options <tt class="docutils literal"><span class="pre">-mcpu=</span></tt> and <tt class="docutils literal"><span class="pre">-mattr=</span></tt>.</p>
+<p>TableGen uses definitions in the <tt class="docutils literal"><span class="pre">Target.td</span></tt> and <tt class="docutils literal"><span class="pre">Sparc.td</span></tt> files to
+generate code in <tt class="docutils literal"><span class="pre">SparcGenSubtarget.inc</span></tt>. In <tt class="docutils literal"><span class="pre">Target.td</span></tt>, shown below, the
+<tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> interface is defined. The first 4 string parameters of
+the <tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> interface are a feature name, an attribute set by the
+feature, the value of the attribute, and a description of the feature. (The
+fifth parameter is a list of features whose presence is implied, and its
+default value is an empty array.)</p>
+<div class="highlight-llvm"><pre>class SubtargetFeature<string n, string a, string v, string d,
+ list<SubtargetFeature> i = []> {
+ string Name = n;
+ string Attribute = a;
+ string Value = v;
+ string Desc = d;
+ list<SubtargetFeature> Implies = i;
+}</pre>
+</div>
+<p>In the <tt class="docutils literal"><span class="pre">Sparc.td</span></tt> file, the <tt class="docutils literal"><span class="pre">SubtargetFeature</span></tt> is used to define the
+following features.</p>
+<div class="highlight-llvm"><pre>def FeatureV9 : SubtargetFeature<"v9", "IsV9", "true",
+ "Enable SPARC-V9 instructions">;
+def FeatureV8Deprecated : SubtargetFeature<"deprecated-v8",
+ "V8DeprecatedInsts", "true",
+ "Enable deprecated V8 instructions in V9 mode">;
+def FeatureVIS : SubtargetFeature<"vis", "IsVIS", "true",
+ "Enable UltraSPARC Visual Instruction Set extensions">;</pre>
+</div>
+<p>Elsewhere in <tt class="docutils literal"><span class="pre">Sparc.td</span></tt>, the <tt class="docutils literal"><span class="pre">Proc</span></tt> class is defined and then is used to
+define particular SPARC processor subtypes that may have the previously
+described features.</p>
+<div class="highlight-llvm"><pre>class Proc<string Name, list<SubtargetFeature> Features>
+ : Processor<Name, NoItineraries, Features>;
+
+def : Proc<"generic", []>;
+def : Proc<"v8", []>;
+def : Proc<"supersparc", []>;
+def : Proc<"sparclite", []>;
+def : Proc<"f934", []>;
+def : Proc<"hypersparc", []>;
+def : Proc<"sparclite86x", []>;
+def : Proc<"sparclet", []>;
+def : Proc<"tsc701", []>;
+def : Proc<"v9", [FeatureV9]>;
+def : Proc<"ultrasparc", [FeatureV9, FeatureV8Deprecated]>;
+def : Proc<"ultrasparc3", [FeatureV9, FeatureV8Deprecated]>;
+def : Proc<"ultrasparc3-vis", [FeatureV9, FeatureV8Deprecated, FeatureVIS]>;</pre>
+</div>
+<p>From <tt class="docutils literal"><span class="pre">Target.td</span></tt> and <tt class="docutils literal"><span class="pre">Sparc.td</span></tt> files, the resulting
+<tt class="docutils literal"><span class="pre">SparcGenSubtarget.inc</span></tt> specifies enum values to identify the features,
+arrays of constants to represent the CPU features and CPU subtypes, and the
+<tt class="docutils literal"><span class="pre">ParseSubtargetFeatures</span></tt> method that parses the features string that sets
+specified subtarget options. The generated <tt class="docutils literal"><span class="pre">SparcGenSubtarget.inc</span></tt> file
+should be included in the <tt class="docutils literal"><span class="pre">SparcSubtarget.cpp</span></tt>. The target-specific
+implementation of the <tt class="docutils literal"><span class="pre">XXXSubtarget</span></tt> method should follow this pseudocode:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">XXXSubtarget</span><span class="o">::</span><span class="n">XXXSubtarget</span><span class="p">(</span><span class="k">const</span> <span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">,</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">FS</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Set the default features</span>
+ <span class="c1">// Determine default and user specified characteristics of the CPU</span>
+ <span class="c1">// Call ParseSubtargetFeatures(FS, CPU) to parse the features string</span>
+ <span class="c1">// Perform any additional operations</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="jit-support">
+<h2><a class="toc-backref" href="#id28">JIT Support</a><a class="headerlink" href="#jit-support" title="Permalink to this headline">¶</a></h2>
+<p>The implementation of a target machine optionally includes a Just-In-Time (JIT)
+code generator that emits machine code and auxiliary structures as binary
+output that can be written directly to memory. To do this, implement JIT code
+generation by performing the following steps:</p>
+<ul class="simple">
+<li>Write an <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt> file that contains a machine function pass
+that transforms target-machine instructions into relocatable machine
+code.</li>
+<li>Write an <tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> file that implements the JIT interfaces for
+target-specific code-generation activities, such as emitting machine code and
+stubs.</li>
+<li>Modify <tt class="docutils literal"><span class="pre">XXXTargetMachine</span></tt> so that it provides a <tt class="docutils literal"><span class="pre">TargetJITInfo</span></tt> object
+through its <tt class="docutils literal"><span class="pre">getJITInfo</span></tt> method.</li>
+</ul>
+<p>There are several different approaches to writing the JIT support code. For
+instance, TableGen and target descriptor files may be used for creating a JIT
+code generator, but are not mandatory. For the Alpha and PowerPC target
+machines, TableGen is used to generate <tt class="docutils literal"><span class="pre">XXXGenCodeEmitter.inc</span></tt>, which
+contains the binary coding of machine instructions and the
+<tt class="docutils literal"><span class="pre">getBinaryCodeForInstr</span></tt> method to access those codes. Other JIT
+implementations do not.</p>
+<p>Both <tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> and <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt> must include the
+<tt class="docutils literal"><span class="pre">llvm/CodeGen/MachineCodeEmitter.h</span></tt> header file that defines the
+<tt class="docutils literal"><span class="pre">MachineCodeEmitter</span></tt> class containing code for several callback functions
+that write data (in bytes, words, strings, etc.) to the output stream.</p>
+<div class="section" id="machine-code-emitter">
+<h3><a class="toc-backref" href="#id29">Machine Code Emitter</a><a class="headerlink" href="#machine-code-emitter" title="Permalink to this headline">¶</a></h3>
+<p>In <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt>, a target-specific of the <tt class="docutils literal"><span class="pre">Emitter</span></tt> class is
+implemented as a function pass (subclass of <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>). The
+target-specific implementation of <tt class="docutils literal"><span class="pre">runOnMachineFunction</span></tt> (invoked by
+<tt class="docutils literal"><span class="pre">runOnFunction</span></tt> in <tt class="docutils literal"><span class="pre">MachineFunctionPass</span></tt>) iterates through the
+<tt class="docutils literal"><span class="pre">MachineBasicBlock</span></tt> calls <tt class="docutils literal"><span class="pre">emitInstruction</span></tt> to process each instruction and
+emit binary code. <tt class="docutils literal"><span class="pre">emitInstruction</span></tt> is largely implemented with case
+statements on the instruction types defined in <tt class="docutils literal"><span class="pre">XXXInstrInfo.h</span></tt>. For
+example, in <tt class="docutils literal"><span class="pre">X86CodeEmitter.cpp</span></tt>, the <tt class="docutils literal"><span class="pre">emitInstruction</span></tt> method is built
+around the following <tt class="docutils literal"><span class="pre">switch</span></tt>/<tt class="docutils literal"><span class="pre">case</span></tt> statements:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">switch</span> <span class="p">(</span><span class="n">Desc</span><span class="o">-></span><span class="n">TSFlags</span> <span class="o">&</span> <span class="n">X86</span><span class="o">::</span><span class="n">FormMask</span><span class="p">)</span> <span class="p">{</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">Pseudo</span><span class="o">:</span> <span class="c1">// for not yet implemented instructions</span>
+ <span class="p">...</span> <span class="c1">// or pseudo-instructions</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">RawFrm</span><span class="o">:</span> <span class="c1">// for instructions with a fixed opcode value</span>
+ <span class="p">...</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">AddRegFrm</span><span class="o">:</span> <span class="c1">// for instructions that have one register operand</span>
+ <span class="p">...</span> <span class="c1">// added to their opcode</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMDestReg</span><span class="o">:</span><span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a destination (register)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMDestMem</span><span class="o">:</span><span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a destination (memory)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMSrcReg</span><span class="o">:</span> <span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a source (register)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMSrcMem</span><span class="o">:</span> <span class="c1">// for instructions that use the Mod/RM byte</span>
+ <span class="p">...</span> <span class="c1">// to specify a source (memory)</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM0r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM1r</span><span class="o">:</span> <span class="c1">// for instructions that operate on</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM2r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM3r</span><span class="o">:</span> <span class="c1">// a REGISTER r/m operand and</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM4r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM5r</span><span class="o">:</span> <span class="c1">// use the Mod/RM byte and a field</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM6r</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM7r</span><span class="o">:</span> <span class="c1">// to hold extended opcode data</span>
+ <span class="p">...</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM0m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM1m</span><span class="o">:</span> <span class="c1">// for instructions that operate on</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM2m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM3m</span><span class="o">:</span> <span class="c1">// a MEMORY r/m operand and</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM4m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM5m</span><span class="o">:</span> <span class="c1">// use the Mod/RM byte and a field</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM6m</span><span class="o">:</span> <span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRM7m</span><span class="o">:</span> <span class="c1">// to hold extended opcode data</span>
+ <span class="p">...</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">MRMInitReg</span><span class="o">:</span> <span class="c1">// for instructions whose source and</span>
+ <span class="p">...</span> <span class="c1">// destination are the same register</span>
+ <span class="k">break</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The implementations of these case statements often first emit the opcode and
+then get the operand(s). Then depending upon the operand, helper methods may
+be called to process the operand(s). For example, in <tt class="docutils literal"><span class="pre">X86CodeEmitter.cpp</span></tt>,
+for the <tt class="docutils literal"><span class="pre">X86II::AddRegFrm</span></tt> case, the first data emitted (by <tt class="docutils literal"><span class="pre">emitByte</span></tt>) is
+the opcode added to the register operand. Then an object representing the
+machine operand, <tt class="docutils literal"><span class="pre">MO1</span></tt>, is extracted. The helper methods such as
+<tt class="docutils literal"><span class="pre">isImmediate</span></tt>, <tt class="docutils literal"><span class="pre">isGlobalAddress</span></tt>, <tt class="docutils literal"><span class="pre">isExternalSymbol</span></tt>,
+<tt class="docutils literal"><span class="pre">isConstantPoolIndex</span></tt>, and <tt class="docutils literal"><span class="pre">isJumpTableIndex</span></tt> determine the operand type.
+(<tt class="docutils literal"><span class="pre">X86CodeEmitter.cpp</span></tt> also has private methods such as <tt class="docutils literal"><span class="pre">emitConstant</span></tt>,
+<tt class="docutils literal"><span class="pre">emitGlobalAddress</span></tt>, <tt class="docutils literal"><span class="pre">emitExternalSymbolAddress</span></tt>, <tt class="docutils literal"><span class="pre">emitConstPoolAddress</span></tt>,
+and <tt class="docutils literal"><span class="pre">emitJumpTableAddress</span></tt> that emit the data into the output stream.)</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">case</span> <span class="n">X86II</span>:<span class="o">:</span><span class="n">AddRegFrm</span><span class="o">:</span>
+ <span class="n">MCE</span><span class="p">.</span><span class="n">emitByte</span><span class="p">(</span><span class="n">BaseOpcode</span> <span class="o">+</span> <span class="n">getX86RegNum</span><span class="p">(</span><span class="n">MI</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="n">CurOp</span><span class="o">++</span><span class="p">).</span><span class="n">getReg</span><span class="p">()));</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">CurOp</span> <span class="o">!=</span> <span class="n">NumOps</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="n">MachineOperand</span> <span class="o">&</span><span class="n">MO1</span> <span class="o">=</span> <span class="n">MI</span><span class="p">.</span><span class="n">getOperand</span><span class="p">(</span><span class="n">CurOp</span><span class="o">++</span><span class="p">);</span>
+ <span class="kt">unsigned</span> <span class="n">Size</span> <span class="o">=</span> <span class="n">X86InstrInfo</span><span class="o">::</span><span class="n">sizeOfImm</span><span class="p">(</span><span class="n">Desc</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isImmediate</span><span class="p">())</span>
+ <span class="n">emitConstant</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getImm</span><span class="p">(),</span> <span class="n">Size</span><span class="p">);</span>
+ <span class="k">else</span> <span class="p">{</span>
+ <span class="kt">unsigned</span> <span class="n">rt</span> <span class="o">=</span> <span class="n">Is64BitMode</span> <span class="o">?</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_pcrel_word</span>
+ <span class="o">:</span> <span class="p">(</span><span class="n">IsPIC</span> <span class="o">?</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_picrel_word</span> <span class="o">:</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_absolute_word</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Opcode</span> <span class="o">==</span> <span class="n">X86</span><span class="o">::</span><span class="n">MOV64ri</span><span class="p">)</span>
+ <span class="n">rt</span> <span class="o">=</span> <span class="n">X86</span><span class="o">::</span><span class="n">reloc_absolute_dword</span><span class="p">;</span> <span class="c1">// FIXME: add X86II flag?</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isGlobalAddress</span><span class="p">())</span> <span class="p">{</span>
+ <span class="kt">bool</span> <span class="n">NeedStub</span> <span class="o">=</span> <span class="n">isa</span><span class="o"><</span><span class="n">Function</span><span class="o">></span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getGlobal</span><span class="p">());</span>
+ <span class="kt">bool</span> <span class="n">isLazy</span> <span class="o">=</span> <span class="n">gvNeedsLazyPtr</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getGlobal</span><span class="p">());</span>
+ <span class="n">emitGlobalAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getGlobal</span><span class="p">(),</span> <span class="n">rt</span><span class="p">,</span> <span class="n">MO1</span><span class="p">.</span><span class="n">getOffset</span><span class="p">(),</span> <span class="mi">0</span><span class="p">,</span>
+ <span class="n">NeedStub</span><span class="p">,</span> <span class="n">isLazy</span><span class="p">);</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="k">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isExternalSymbol</span><span class="p">())</span>
+ <span class="n">emitExternalSymbolAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getSymbolName</span><span class="p">(),</span> <span class="n">rt</span><span class="p">);</span>
+ <span class="k">else</span> <span class="nf">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isConstantPoolIndex</span><span class="p">())</span>
+ <span class="n">emitConstPoolAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getIndex</span><span class="p">(),</span> <span class="n">rt</span><span class="p">);</span>
+ <span class="k">else</span> <span class="nf">if</span> <span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">isJumpTableIndex</span><span class="p">())</span>
+ <span class="n">emitJumpTableAddress</span><span class="p">(</span><span class="n">MO1</span><span class="p">.</span><span class="n">getIndex</span><span class="p">(),</span> <span class="n">rt</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+ <span class="k">break</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>In the previous example, <tt class="docutils literal"><span class="pre">XXXCodeEmitter.cpp</span></tt> uses the variable <tt class="docutils literal"><span class="pre">rt</span></tt>, which
+is a <tt class="docutils literal"><span class="pre">RelocationType</span></tt> enum that may be used to relocate addresses (for
+example, a global address with a PIC base offset). The <tt class="docutils literal"><span class="pre">RelocationType</span></tt> enum
+for that target is defined in the short target-specific <tt class="docutils literal"><span class="pre">XXXRelocations.h</span></tt>
+file. The <tt class="docutils literal"><span class="pre">RelocationType</span></tt> is used by the <tt class="docutils literal"><span class="pre">relocate</span></tt> method defined in
+<tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> to rewrite addresses for referenced global symbols.</p>
+<p>For example, <tt class="docutils literal"><span class="pre">X86Relocations.h</span></tt> specifies the following relocation types for
+the X86 addresses. In all four cases, the relocated value is added to the
+value already in memory. For <tt class="docutils literal"><span class="pre">reloc_pcrel_word</span></tt> and <tt class="docutils literal"><span class="pre">reloc_picrel_word</span></tt>,
+there is an additional initial adjustment.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">RelocationType</span> <span class="p">{</span>
+ <span class="n">reloc_pcrel_word</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// add reloc value after adjusting for the PC loc</span>
+ <span class="n">reloc_picrel_word</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// add reloc value after adjusting for the PIC base</span>
+ <span class="n">reloc_absolute_word</span> <span class="o">=</span> <span class="mi">2</span><span class="p">,</span> <span class="c1">// absolute relocation; no additional adjustment</span>
+ <span class="n">reloc_absolute_dword</span> <span class="o">=</span> <span class="mi">3</span> <span class="c1">// absolute relocation; no additional adjustment</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="target-jit-info">
+<h3><a class="toc-backref" href="#id30">Target JIT Info</a><a class="headerlink" href="#target-jit-info" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">XXXJITInfo.cpp</span></tt> implements the JIT interfaces for target-specific
+code-generation activities, such as emitting machine code and stubs. At
+minimum, a target-specific version of <tt class="docutils literal"><span class="pre">XXXJITInfo</span></tt> implements the following:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> — Initializes the JIT, gives the target a
+function that is used for compilation.</li>
+<li><tt class="docutils literal"><span class="pre">emitFunctionStub</span></tt> — Returns a native function with a specified address
+for a callback function.</li>
+<li><tt class="docutils literal"><span class="pre">relocate</span></tt> — Changes the addresses of referenced globals, based on
+relocation types.</li>
+<li>Callback function that are wrappers to a function stub that is used when the
+real target is not initially known.</li>
+</ul>
+<p><tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> is generally trivial to implement. It makes the
+incoming parameter as the global <tt class="docutils literal"><span class="pre">JITCompilerFunction</span></tt> and returns the
+callback function that will be used a function wrapper. For the Alpha target
+(in <tt class="docutils literal"><span class="pre">AlphaJITInfo.cpp</span></tt>), the <tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> implementation is
+simply:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">TargetJITInfo</span><span class="o">::</span><span class="n">LazyResolverFn</span> <span class="n">AlphaJITInfo</span><span class="o">::</span><span class="n">getLazyResolverFunction</span><span class="p">(</span>
+ <span class="n">JITCompilerFn</span> <span class="n">F</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">JITCompilerFunction</span> <span class="o">=</span> <span class="n">F</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">AlphaCompilationCallback</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>For the X86 target, the <tt class="docutils literal"><span class="pre">getLazyResolverFunction</span></tt> implementation is a little
+more complicated, because it returns a different callback function for
+processors with SSE instructions and XMM registers.</p>
+<p>The callback function initially saves and later restores the callee register
+values, incoming arguments, and frame and return address. The callback
+function needs low-level access to the registers or stack, so it is typically
+implemented with assembler.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Vectorizers.html" title="Auto-Vectorization in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2013, LLVM Project.
+ Last updated on 2013-06-17.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2b1.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list