[www-releases] r230777 - Upload 3.6.0

Hans Wennborg hans at hanshq.net
Fri Feb 27 10:44:12 PST 2015


Added: www-releases/trunk/3.6.0/docs/MergeFunctions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/MergeFunctions.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/MergeFunctions.html (added)
+++ www-releases/trunk/3.6.0/docs/MergeFunctions.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,819 @@
+
+<!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>MergeFunctions pass, how it works — LLVM 3.6 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.6',
+        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.6 documentation" href="index.html" />
+    <link rel="next" title="LLVM Developer Policy" href="DeveloperPolicy.html" />
+    <link rel="prev" title="Garbage Collection Safepoints in LLVM" href="Statepoints.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="DeveloperPolicy.html" title="LLVM Developer Policy"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="Statepoints.html" title="Garbage Collection Safepoints 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="mergefunctions-pass-how-it-works">
+<h1>MergeFunctions pass, how it works<a class="headerlink" href="#mergefunctions-pass-how-it-works" 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="id1">Introduction</a><ul>
+<li><a class="reference internal" href="#why-would-i-want-to-read-this-document" id="id2">Why would I want to read this document?</a></li>
+<li><a class="reference internal" href="#what-should-i-know-to-be-able-to-follow-along-with-this-document" id="id3">What should I know to be able to follow along with this document?</a></li>
+<li><a class="reference internal" href="#what-i-gain-by-reading-this-document" id="id4">What I gain by reading this document?</a></li>
+<li><a class="reference internal" href="#narrative-structure" id="id5">Narrative structure</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#basics" id="id6">Basics</a><ul>
+<li><a class="reference internal" href="#how-to-do-it" id="id7">How to do it?</a><ul>
+<li><a class="reference internal" href="#possible-solutions" id="id8">Possible solutions</a><ul>
+<li><a class="reference internal" href="#random-access" id="id9">Random-access</a></li>
+<li><a class="reference internal" href="#logarithmical-search" id="id10">Logarithmical search</a></li>
+<li><a class="reference internal" href="#present-state" id="id11">Present state</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#mergefunctions-main-fields-and-runonmodule" id="id12">MergeFunctions, main fields and runOnModule</a><ul>
+<li><a class="reference internal" href="#runonmodule" id="id13">runOnModule</a></li>
+<li><a class="reference internal" href="#comparison-and-logarithmical-search" id="id14">Comparison and logarithmical search</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#functions-comparison" id="id15">Functions comparison</a><ul>
+<li><a class="reference internal" href="#functioncomparator-compare-void" id="id16">FunctionComparator::compare(void)</a></li>
+<li><a class="reference internal" href="#functioncomparator-cmptype" id="id17">FunctionComparator::cmpType</a></li>
+<li><a class="reference internal" href="#cmpvalues-const-value-const-value" id="id18">cmpValues(const Value*, const Value*)</a><ul>
+<li><a class="reference internal" href="#what-we-assiciate-in-cmpvalues" id="id19">What we assiciate in cmpValues?</a></li>
+<li><a class="reference internal" href="#how-to-implement-cmpvalues" id="id20">How to implement cmpValues?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#cmpconstants" id="id21">cmpConstants</a></li>
+<li><a class="reference internal" href="#compare-const-basicblock-const-basicblock" id="id22">compare(const BasicBlock*, const BasicBlock*)</a></li>
+<li><a class="reference internal" href="#cmpgep" id="id23">cmpGEP</a></li>
+<li><a class="reference internal" href="#cmpoperation" id="id24">cmpOperation</a></li>
+<li><a class="reference internal" href="#o-log-n" id="id25">O(log(N))</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#merging-process-mergetwofunctions" id="id26">Merging process, mergeTwoFunctions</a><ul>
+<li><a class="reference internal" href="#if-f-may-be-overridden" id="id27">If “F” may be overridden</a><ul>
+<li><a class="reference internal" href="#hasglobalaliases-removeusers" id="id28">HasGlobalAliases, removeUsers</a></li>
+<li><a class="reference internal" href="#no-global-aliases-replacedirectcallers" id="id29">No global aliases, replaceDirectCallers</a><ul>
+<li><a class="reference internal" href="#if-f-could-not-be-overridden-fix-it" id="id30">If “F” could not be overridden, fix it!</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#that-s-it" id="id31">That’s it.</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Sometimes code contains equal functions, or functions that does exactly the same
+thing even though they are non-equal on the IR level (e.g.: multiplication on 2
+and ‘shl 1’). It could happen due to several reasons: mainly, the usage of
+templates and automatic code generators. Though, sometimes user itself could
+write the same thing twice :-)</p>
+<p>The main purpose of this pass is to recognize such functions and merge them.</p>
+<div class="section" id="why-would-i-want-to-read-this-document">
+<h3><a class="toc-backref" href="#id2">Why would I want to read this document?</a><a class="headerlink" href="#why-would-i-want-to-read-this-document" title="Permalink to this headline">¶</a></h3>
+<p>Document is the extension to pass comments and describes the pass logic. It
+describes algorithm that is used in order to compare functions, it also
+explains how we could combine equal functions correctly, keeping module valid.</p>
+<p>Material is brought in top-down form, so reader could start learn pass from
+ideas and end up with low-level algorithm details, thus preparing him for
+reading the sources.</p>
+<p>So main goal is do describe algorithm and logic here; the concept. This document
+is good for you, if you <em>don’t want</em> to read the source code, but want to
+understand pass algorithms. Author tried not to repeat the source-code and
+cover only common cases, and thus avoid cases when after minor code changes we
+need to update this document.</p>
+</div>
+<div class="section" id="what-should-i-know-to-be-able-to-follow-along-with-this-document">
+<h3><a class="toc-backref" href="#id3">What should I know to be able to follow along with this document?</a><a class="headerlink" href="#what-should-i-know-to-be-able-to-follow-along-with-this-document" title="Permalink to this headline">¶</a></h3>
+<p>Reader should be familiar with common compile-engineering principles and LLVM
+code fundamentals. In this article we suppose reader is familiar with
+<a class="reference external" href="http://en.wikipedia.org/wiki/Static_single_assignment_form">Single Static Assingment</a>
+concepts. Understanding of
+<a class="reference external" href="http://llvm.org/docs/LangRef.html#high-level-structure">IR structure</a> is
+also important.</p>
+<p>We will use such terms as
+“<a class="reference external" href="http://llvm.org/docs/LangRef.html#high-level-structure">module</a>”,
+“<a class="reference external" href="http://llvm.org/docs/ProgrammersManual.html#the-function-class">function</a>”,
+“<a class="reference external" href="http://en.wikipedia.org/wiki/Basic_block">basic block</a>”,
+“<a class="reference external" href="http://llvm.org/docs/ProgrammersManual.html#the-user-class">user</a>”,
+“<a class="reference external" href="http://llvm.org/docs/ProgrammersManual.html#the-value-class">value</a>”,
+“<a class="reference external" href="http://llvm.org/docs/ProgrammersManual.html#the-instruction-class">instruction</a>”.</p>
+<p>As a good start point, Kaleidoscope tutorial could be used:</p>
+<p><a class="reference internal" href="tutorial/index.html"><em>LLVM Tutorial: Table of Contents</em></a></p>
+<p>Especially it’s important to understand chapter 3 of tutorial:</p>
+<p><a class="reference internal" href="tutorial/LangImpl3.html"><em>Kaleidoscope: Code generation to LLVM IR</em></a></p>
+<p>Reader also should know how passes work in LLVM, he could use next article as a
+reference and start point here:</p>
+<p><a class="reference internal" href="WritingAnLLVMPass.html"><em>Writing an LLVM Pass</em></a></p>
+<p>What else? Well perhaps reader also should have some experience in LLVM pass
+debugging and bug-fixing.</p>
+</div>
+<div class="section" id="what-i-gain-by-reading-this-document">
+<h3><a class="toc-backref" href="#id4">What I gain by reading this document?</a><a class="headerlink" href="#what-i-gain-by-reading-this-document" title="Permalink to this headline">¶</a></h3>
+<p>Main purpose is to provide reader with comfortable form of algorithms
+description, namely the human reading text. Since it could be hard to
+understand algorithm straight from the source code: pass uses some principles
+that have to be explained first.</p>
+<p>Author wishes to everybody to avoid case, when you read code from top to bottom
+again and again, and yet you don’t understand why we implemented it that way.</p>
+<p>We hope that after this article reader could easily debug and improve
+MergeFunctions pass and thus help LLVM project.</p>
+</div>
+<div class="section" id="narrative-structure">
+<h3><a class="toc-backref" href="#id5">Narrative structure</a><a class="headerlink" href="#narrative-structure" title="Permalink to this headline">¶</a></h3>
+<p>Article consists of three parts. First part explains pass functionality on the
+top-level. Second part describes the comparison procedure itself. The third
+part describes the merging process.</p>
+<p>In every part author also tried to put the contents into the top-down form.
+First, the top-level methods will be described, while the terminal ones will be
+at the end, in the tail of each part. If reader will see the reference to the
+method that wasn’t described yet, he will find its description a bit below.</p>
+</div>
+</div>
+<div class="section" id="basics">
+<h2><a class="toc-backref" href="#id6">Basics</a><a class="headerlink" href="#basics" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="how-to-do-it">
+<h3><a class="toc-backref" href="#id7">How to do it?</a><a class="headerlink" href="#how-to-do-it" title="Permalink to this headline">¶</a></h3>
+<p>Do we need to merge functions? Obvious thing is: yes that’s a quite possible
+case, since usually we <em>do</em> have duplicates. And it would be good to get rid of
+them. But how to detect such a duplicates? The idea is next: we split functions
+onto small bricks (parts), then we compare “bricks” amount, and if it equal,
+compare “bricks” themselves, and then do our conclusions about functions
+themselves.</p>
+<p>What the difference it could be? For example, on machine with 64-bit pointers
+(let’s assume we have only one address space),  one function stores 64-bit
+integer, while another one stores a pointer. So if the target is a machine
+mentioned above, and if functions are identical, except the parameter type (we
+could consider it as a part of function type), then we can treat <tt class="docutils literal"><span class="pre">uint64_t</span></tt>
+and``void*`` as equal.</p>
+<p>It was just an example; possible details are described a bit below.</p>
+<p>As another example reader may imagine two more functions. First function
+performs multiplication on 2, while the second one performs arithmetic right
+shift on 1.</p>
+<div class="section" id="possible-solutions">
+<h4><a class="toc-backref" href="#id8">Possible solutions</a><a class="headerlink" href="#possible-solutions" title="Permalink to this headline">¶</a></h4>
+<p>Let’s briefly consider possible options about how and what we have to implement
+in order to create full-featured functions merging, and also what it would
+meant for us.</p>
+<p>Equal functions detection, obviously supposes “detector” method to be
+implemented, latter should answer the question “whether functions are equal”.
+This “detector” method consists of tiny “sub-detectors”, each of them answers
+exactly the same question, but for function parts.</p>
+<p>As the second step, we should merge equal functions. So it should be a “merger”
+method. “Merger” accepts two functions <em>F1</em> and <em>F2</em>, and produces <em>F1F2</em>
+function, the result of merging.</p>
+<p>Having such a routines in our hands, we can process whole module, and merge all
+equal functions.</p>
+<p>In this case, we have to compare every function with every another function. As
+reader could notice, this way seems to be quite expensive. Of course we could
+introduce hashing and other helpers, but it is still just an optimization, and
+thus the level of O(N*N) complexity.</p>
+<p>Can we reach another level? Could we introduce logarithmical search, or random
+access lookup? The answer is: “yes”.</p>
+<div class="section" id="random-access">
+<h5><a class="toc-backref" href="#id9">Random-access</a><a class="headerlink" href="#random-access" title="Permalink to this headline">¶</a></h5>
+<p>How it could be done? Just convert each function to number, and gather all of
+them in special hash-table. Functions with equal hash are equal. Good hashing
+means, that every function part must be taken into account. That means we have
+to convert every function part into some number, and then add it into hash.
+Lookup-up time would be small, but such approach adds some delay due to hashing
+routine.</p>
+</div>
+<div class="section" id="logarithmical-search">
+<h5><a class="toc-backref" href="#id10">Logarithmical search</a><a class="headerlink" href="#logarithmical-search" title="Permalink to this headline">¶</a></h5>
+<p>We could introduce total ordering among the functions set, once we had it we
+could then implement a logarithmical search. Lookup time still depends on N,
+but adds a little of delay (<em>log(N)</em>).</p>
+</div>
+<div class="section" id="present-state">
+<h5><a class="toc-backref" href="#id11">Present state</a><a class="headerlink" href="#present-state" title="Permalink to this headline">¶</a></h5>
+<p>Both of approaches (random-access and logarithmical) has been implemented and
+tested. And both of them gave a very good improvement. And what was most
+surprising, logarithmical search was faster; sometimes up to 15%. Hashing needs
+some extra CPU time, and it is the main reason why it works slower; in most of
+cases total “hashing” time was greater than total “logarithmical-search” time.</p>
+<p>So, preference has been granted to the “logarithmical search”.</p>
+<p>Though in the case of need, <em>logarithmical-search</em> (read “total-ordering”) could
+be used as a milestone on our way to the <em>random-access</em> implementation.</p>
+<p>Every comparison is based either on the numbers or on flags comparison. In
+<em>random-access</em> approach we could use the same comparison algorithm. During
+comparison we exit once we find the difference, but here we might have to scan
+whole function body every time (note, it could be slower). Like in
+“total-ordering”, we will track every numbers and flags, but instead of
+comparison, we should get numbers sequence and then create the hash number. So,
+once again, <em>total-ordering</em> could be considered as a milestone for even faster
+(in theory) random-access approach.</p>
+</div>
+</div>
+<div class="section" id="mergefunctions-main-fields-and-runonmodule">
+<h4><a class="toc-backref" href="#id12">MergeFunctions, main fields and runOnModule</a><a class="headerlink" href="#mergefunctions-main-fields-and-runonmodule" title="Permalink to this headline">¶</a></h4>
+<p>There are two most important fields in class:</p>
+<p><tt class="docutils literal"><span class="pre">FnTree</span></tt>  – the set of all unique functions. It keeps items that couldn’t be
+merged with each other. It is defined as:</p>
+<p><tt class="docutils literal"><span class="pre">std::set<FunctionNode></span> <span class="pre">FnTree;</span></tt></p>
+<p>Here <tt class="docutils literal"><span class="pre">FunctionNode</span></tt> is a wrapper for <tt class="docutils literal"><span class="pre">llvm::Function</span></tt> class, with
+implemented “<” operator among the functions set (below we explain how it works
+exactly; this is a key point in fast functions comparison).</p>
+<p><tt class="docutils literal"><span class="pre">Deferred</span></tt> – merging process can affect bodies of functions that are in
+<tt class="docutils literal"><span class="pre">FnTree</span></tt> already. Obviously such functions should be rechecked again. In this
+case we remove them from <tt class="docutils literal"><span class="pre">FnTree</span></tt>, and mark them as to be rescanned, namely
+put them into <tt class="docutils literal"><span class="pre">Deferred</span></tt> list.</p>
+<div class="section" id="runonmodule">
+<h5><a class="toc-backref" href="#id13">runOnModule</a><a class="headerlink" href="#runonmodule" title="Permalink to this headline">¶</a></h5>
+<p>The algorithm is pretty simple:</p>
+<ol class="arabic simple">
+<li>Put all module’s functions into the <em>worklist</em>.</li>
+</ol>
+<p>2. Scan <em>worklist</em>‘s functions twice: first enumerate only strong functions and
+then only weak ones:</p>
+<blockquote>
+<div>2.1. Loop body: take function from <em>worklist</em>  (call it <em>FCur</em>) and try to
+insert it into <em>FnTree</em>: check whether <em>FCur</em> is equal to one of functions
+in <em>FnTree</em>. If there <em>is</em> equal function in <em>FnTree</em> (call it <em>FExists</em>):
+merge function <em>FCur</em> with <em>FExists</em>. Otherwise add function from <em>worklist</em>
+to <em>FnTree</em>.</div></blockquote>
+<p>3. Once <em>worklist</em> scanning and merging operations is complete, check <em>Deferred</em>
+list. If it is not empty: refill <em>worklist</em> contents with <em>Deferred</em> list and
+do step 2 again, if <em>Deferred</em> is empty, then exit from method.</p>
+</div>
+<div class="section" id="comparison-and-logarithmical-search">
+<h5><a class="toc-backref" href="#id14">Comparison and logarithmical search</a><a class="headerlink" href="#comparison-and-logarithmical-search" title="Permalink to this headline">¶</a></h5>
+<p>Let’s recall our task: for every function <em>F</em> from module <em>M</em>, we have to find
+equal functions <em>F`</em> in shortest time, and merge them into the single function.</p>
+<p>Defining total ordering among the functions set allows to organize functions
+into the binary tree. The lookup procedure complexity would be estimated as
+O(log(N)) in this case. But how to define <em>total-ordering</em>?</p>
+<p>We have to introduce a single rule applicable to every pair of functions, and
+following this rule then evaluate which of them is greater. What kind of rule
+it could be? Let’s declare it as “compare” method, that returns one of 3
+possible values:</p>
+<p>-1, left is <em>less</em> than right,</p>
+<p>0, left and right are <em>equal</em>,</p>
+<p>1, left is <em>greater</em> than right.</p>
+<p>Of course it means, that we have to maintain
+<em>strict and non-strict order relation properties</em>:</p>
+<ul class="simple">
+<li>reflexivity (<tt class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">a</span></tt>, <tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">a</span></tt>, <tt class="docutils literal"><span class="pre">a</span> <span class="pre">>=</span> <span class="pre">a</span></tt>),</li>
+<li>antisymmetry (if <tt class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">b</span></tt> and <tt class="docutils literal"><span class="pre">b</span> <span class="pre"><=</span> <span class="pre">a</span></tt> then <tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt>),</li>
+<li>transitivity (<tt class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">b</span></tt> and <tt class="docutils literal"><span class="pre">b</span> <span class="pre"><=</span> <span class="pre">c</span></tt>, then <tt class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">c</span></tt>)</li>
+<li>asymmetry (if <tt class="docutils literal"><span class="pre">a</span> <span class="pre"><</span> <span class="pre">b</span></tt>, then <tt class="docutils literal"><span class="pre">a</span> <span class="pre">></span> <span class="pre">b</span></tt> or <tt class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></tt>).</li>
+</ul>
+<p>As it was mentioned before, comparison routine consists of
+“sub-comparison-routines”, each of them also consists
+“sub-comparison-routines”, and so on, finally it ends up with a primitives
+comparison.</p>
+<p>Below, we will use the next operations:</p>
+<ol class="arabic simple">
+<li><tt class="docutils literal"><span class="pre">cmpNumbers(number1,</span> <span class="pre">number2)</span></tt> is method that returns -1 if left is less
+than right; 0, if left and right are equal; and 1 otherwise.</li>
+<li><tt class="docutils literal"><span class="pre">cmpFlags(flag1,</span> <span class="pre">flag2)</span></tt> is hypothetical method that compares two flags.
+The logic is the same as in <tt class="docutils literal"><span class="pre">cmpNumbers</span></tt>, where <tt class="docutils literal"><span class="pre">true</span></tt> is 1, and
+<tt class="docutils literal"><span class="pre">false</span></tt> is 0.</li>
+</ol>
+<p>The rest of article is based on <em>MergeFunctions.cpp</em> source code
+(<em><llvm_dir>/lib/Transforms/IPO/MergeFunctions.cpp</em>). We would like to ask
+reader to keep this file open nearby, so we could use it as a reference for
+further explanations.</p>
+<p>Now we’re ready to proceed to the next chapter and see how it works.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="functions-comparison">
+<h2><a class="toc-backref" href="#id15">Functions comparison</a><a class="headerlink" href="#functions-comparison" title="Permalink to this headline">¶</a></h2>
+<p>At first, let’s define how exactly we compare complex objects.</p>
+<p>Complex objects comparison (function, basic-block, etc) is mostly based on its
+sub-objects comparison results. So it is similar to the next “tree” objects
+comparison:</p>
+<ol class="arabic simple">
+<li>For two trees <em>T1</em> and <em>T2</em> we perform <em>depth-first-traversal</em> and have
+two sequences as a product: “<em>T1Items</em>” and “<em>T2Items</em>”.</li>
+<li>Then compare chains “<em>T1Items</em>” and “<em>T2Items</em>” in
+most-significant-item-first order. Result of items comparison would be the
+result of <em>T1</em> and <em>T2</em> comparison itself.</li>
+</ol>
+<div class="section" id="functioncomparator-compare-void">
+<h3><a class="toc-backref" href="#id16">FunctionComparator::compare(void)</a><a class="headerlink" href="#functioncomparator-compare-void" title="Permalink to this headline">¶</a></h3>
+<p>Brief look at the source code tells us, that comparison starts in
+“<tt class="docutils literal"><span class="pre">int</span> <span class="pre">FunctionComparator::compare(void)</span></tt>” method.</p>
+<p>1. First parts to be compared are function’s attributes and some properties that
+outsides “attributes” term, but still could make function different without
+changing its body. This part of comparison is usually done within simple
+<em>cmpNumbers</em> or <em>cmpFlags</em> operations (e.g.
+<tt class="docutils literal"><span class="pre">cmpFlags(F1->hasGC(),</span> <span class="pre">F2->hasGC())</span></tt>). Below is full list of function’s
+properties to be compared on this stage:</p>
+<blockquote>
+<div><ul class="simple">
+<li><em>Attributes</em> (those are returned by <tt class="docutils literal"><span class="pre">Function::getAttributes()</span></tt>
+method).</li>
+<li><em>GC</em>, for equivalence, <em>RHS</em> and <em>LHS</em> should be both either without
+<em>GC</em> or with the same one.</li>
+<li><em>Section</em>, just like a <em>GC</em>: <em>RHS</em> and <em>LHS</em> should be defined in the
+same section.</li>
+<li><em>Variable arguments</em>. <em>LHS</em> and <em>RHS</em> should be both either with or
+without <em>var-args</em>.</li>
+<li><em>Calling convention</em> should be the same.</li>
+</ul>
+</div></blockquote>
+<p>2. Function type. Checked by <tt class="docutils literal"><span class="pre">FunctionComparator::cmpType(Type*,</span> <span class="pre">Type*)</span></tt>
+method. It checks return type and parameters type; the method itself will be
+described later.</p>
+<p>3. Associate function formal parameters with each other. Then comparing function
+bodies, if we see the usage of <em>LHS</em>‘s <em>i</em>-th argument in <em>LHS</em>‘s body, then,
+we want to see usage of <em>RHS</em>‘s <em>i</em>-th argument at the same place in <em>RHS</em>‘s
+body, otherwise functions are different. On this stage we grant the preference
+to those we met later in function body (value we met first would be <em>less</em>).
+This is done by “<tt class="docutils literal"><span class="pre">FunctionComparator::cmpValues(const</span> <span class="pre">Value*,</span> <span class="pre">const</span> <span class="pre">Value*)</span></tt>”
+method (will be described a bit later).</p>
+<ol class="arabic simple" start="4">
+<li>Function body comparison. As it written in method comments:</li>
+</ol>
+<p>“We do a CFG-ordered walk since the actual ordering of the blocks in the linked
+list is immaterial. Our walk starts at the entry block for both functions, then
+takes each block from each terminator in order. As an artifact, this also means
+that unreachable blocks are ignored.”</p>
+<p>So, using this walk we get BBs from <em>left</em> and <em>right</em> in the same order, and
+compare them by “<tt class="docutils literal"><span class="pre">FunctionComparator::compare(const</span> <span class="pre">BasicBlock*,</span> <span class="pre">const</span>
+<span class="pre">BasicBlock*)</span></tt>” method.</p>
+<p>We also associate BBs with each other, like we did it with function formal
+arguments (see <tt class="docutils literal"><span class="pre">cmpValues</span></tt> method below).</p>
+</div>
+<div class="section" id="functioncomparator-cmptype">
+<h3><a class="toc-backref" href="#id17">FunctionComparator::cmpType</a><a class="headerlink" href="#functioncomparator-cmptype" title="Permalink to this headline">¶</a></h3>
+<p>Consider how types comparison works.</p>
+<p>1. Coerce pointer to integer. If left type is a pointer, try to coerce it to the
+integer type. It could be done if its address space is 0, or if address spaces
+are ignored at all. Do the same thing for the right type.</p>
+<p>2. If left and right types are equal, return 0. Otherwise we need to give
+preference to one of them. So proceed to the next step.</p>
+<p>3. If types are of different kind (different type IDs). Return result of type
+IDs comparison, treating them as a numbers (use <tt class="docutils literal"><span class="pre">cmpNumbers</span></tt> operation).</p>
+<p>4. If types are vectors or integers, return result of their pointers comparison,
+comparing them as numbers.</p>
+<ol class="arabic" start="5">
+<li><p class="first">Check whether type ID belongs to the next group (call it equivalent-group):</p>
+<ul class="simple">
+<li>Void</li>
+<li>Float</li>
+<li>Double</li>
+<li>X86_FP80</li>
+<li>FP128</li>
+<li>PPC_FP128</li>
+<li>Label</li>
+<li>Metadata.</li>
+</ul>
+<p>If ID belongs to group above, return 0. Since it’s enough to see that
+types has the same <tt class="docutils literal"><span class="pre">TypeID</span></tt>. No additional information is required.</p>
+</li>
+</ol>
+<p>6. Left and right are pointers. Return result of address space comparison
+(numbers comparison).</p>
+<p>7. Complex types (structures, arrays, etc.). Follow complex objects comparison
+technique (see the very first paragraph of this chapter). Both <em>left</em> and
+<em>right</em> are to be expanded and their element types will be checked the same
+way. If we get -1 or 1 on some stage, return it. Otherwise return 0.</p>
+<p>8. Steps 1-6 describe all the possible cases, if we passed steps 1-6 and didn’t
+get any conclusions, then invoke <tt class="docutils literal"><span class="pre">llvm_unreachable</span></tt>, since it’s quite
+unexpectable case.</p>
+</div>
+<div class="section" id="cmpvalues-const-value-const-value">
+<h3><a class="toc-backref" href="#id18">cmpValues(const Value*, const Value*)</a><a class="headerlink" href="#cmpvalues-const-value-const-value" title="Permalink to this headline">¶</a></h3>
+<p>Method that compares local values.</p>
+<p>This method gives us an answer on a very curious quesion: whether we could treat
+local values as equal, and which value is greater otherwise. It’s better to
+start from example:</p>
+<p>Consider situation when we’re looking at the same place in left function “<em>FL</em>”
+and in right function “<em>FR</em>”. And every part of <em>left</em> place is equal to the
+corresponding part of <em>right</em> place, and (!) both parts use <em>Value</em> instances,
+for example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>instr0 i32 %LV   ; left side, function FL
+instr0 i32 %RV   ; right side, function FR
+</pre></div>
+</div>
+<p>So, now our conclusion depends on <em>Value</em> instances comparison.</p>
+<p>Main purpose of this method is to determine relation between such values.</p>
+<p>What we expect from equal functions? At the same place, in functions “<em>FL</em>” and
+“<em>FR</em>” we expect to see <em>equal</em> values, or values <em>defined</em> at the same place
+in “<em>FL</em>” and “<em>FR</em>”.</p>
+<p>Consider small example here:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>define void %f(i32 %pf0, i32 %pf1) {
+  instr0 i32 %pf0 instr1 i32 %pf1 instr2 i32 123
+}
+</pre></div>
+</div>
+<div class="highlight-llvm"><div class="highlight"><pre>define void %g(i32 %pg0, i32 %pg1) {
+  instr0 i32 %pg0 instr1 i32 %pg0 instr2 i32 123
+}
+</pre></div>
+</div>
+<p>In this example, <em>pf0</em> is associated with <em>pg0</em>, <em>pf1</em> is associated with <em>pg1</em>,
+and we also declare that <em>pf0</em> < <em>pf1</em>, and thus <em>pg0</em> < <em>pf1</em>.</p>
+<p>Instructions with opcode “<em>instr0</em>” would be <em>equal</em>, since their types and
+opcodes are equal, and values are <em>associated</em>.</p>
+<p>Instruction with opcode “<em>instr1</em>” from <em>f</em> is <em>greater</em> than instruction with
+opcode “<em>instr1</em>” from <em>g</em>; here we have equal types and opcodes, but “<em>pf1</em> is
+greater than “<em>pg0</em>”.</p>
+<p>And instructions with opcode “<em>instr2</em>” are equal, because their opcodes and
+types are equal, and the same constant is used as a value.</p>
+<div class="section" id="what-we-assiciate-in-cmpvalues">
+<h4><a class="toc-backref" href="#id19">What we assiciate in cmpValues?</a><a class="headerlink" href="#what-we-assiciate-in-cmpvalues" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li>Function arguments. <em>i</em>-th argument from left function associated with
+<em>i</em>-th argument from right function.</li>
+<li>BasicBlock instances. In basic-block enumeration loop we associate <em>i</em>-th
+BasicBlock from the left function with <em>i</em>-th BasicBlock from the right
+function.</li>
+<li>Instructions.</li>
+<li>Instruction operands. Note, we can meet <em>Value</em> here we have never seen
+before. In this case it is not a function argument, nor <em>BasicBlock</em>, nor
+<em>Instruction</em>. It is global value. It is constant, since its the only
+supposed global here. Method also compares:</li>
+<li>Constants that are of the same type.</li>
+<li>If right constant could be losslessly bit-casted to the left one, then we
+also compare them.</li>
+</ul>
+</div>
+<div class="section" id="how-to-implement-cmpvalues">
+<h4><a class="toc-backref" href="#id20">How to implement cmpValues?</a><a class="headerlink" href="#how-to-implement-cmpvalues" title="Permalink to this headline">¶</a></h4>
+<p><em>Association</em> is a case of equality for us. We just treat such values as equal.
+But, in general, we need to implement antisymmetric relation. As it was
+mentioned above, to understand what is <em>less</em>, we can use order in which we
+meet values. If both of values has the same order in function (met at the same
+time), then treat values as <em>associated</em>. Otherwise – it depends on who was
+first.</p>
+<p>Every time we run top-level compare method, we initialize two identical maps
+(one for the left side, another one for the right side):</p>
+<p><tt class="docutils literal"><span class="pre">map<Value,</span> <span class="pre">int></span> <span class="pre">sn_mapL,</span> <span class="pre">sn_mapR;</span></tt></p>
+<p>The key of the map is the <em>Value</em> itself, the <em>value</em> – is its order (call it
+<em>serial number</em>).</p>
+<p>To add value <em>V</em> we need to perform the next procedure:</p>
+<p><tt class="docutils literal"><span class="pre">sn_map.insert(std::make_pair(V,</span> <span class="pre">sn_map.size()));</span></tt></p>
+<p>For the first <em>Value</em>, map will return <em>0</em>, for second <em>Value</em> map will return
+<em>1</em>, and so on.</p>
+<p>Then we can check whether left and right values met at the same time with simple
+comparison:</p>
+<p><tt class="docutils literal"><span class="pre">cmpNumbers(sn_mapL[Left],</span> <span class="pre">sn_mapR[Right]);</span></tt></p>
+<p>Of course, we can combine insertion and comparison:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">pair</span><span class="o"><</span><span class="n">iterator</span><span class="p">,</span> <span class="kt">bool</span><span class="o">></span>
+  <span class="n">LeftRes</span> <span class="o">=</span> <span class="n">sn_mapL</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_pair</span><span class="p">(</span><span class="n">Left</span><span class="p">,</span> <span class="n">sn_mapL</span><span class="p">.</span><span class="n">size</span><span class="p">())),</span> <span class="n">RightRes</span>
+  <span class="o">=</span> <span class="n">sn_mapR</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_pair</span><span class="p">(</span><span class="n">Right</span><span class="p">,</span> <span class="n">sn_mapR</span><span class="p">.</span><span class="n">size</span><span class="p">()));</span>
+<span class="k">return</span> <span class="nf">cmpNumbers</span><span class="p">(</span><span class="n">LeftRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span><span class="p">,</span> <span class="n">RightRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Let’s look, how whole method could be implemented.</p>
+<p>1. we have to start from the bad news. Consider function self and
+cross-referencing cases:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// self-reference unsigned fact0(unsigned n) { return n > 1 ? n</span>
+<span class="o">*</span> <span class="n">fact0</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="mi">1</span><span class="p">;</span> <span class="p">}</span> <span class="kt">unsigned</span> <span class="n">fact1</span><span class="p">(</span><span class="kt">unsigned</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">n</span> <span class="o">></span> <span class="mi">1</span> <span class="o">?</span> <span class="n">n</span> <span class="o">*</span>
+<span class="n">fact1</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="mi">1</span><span class="p">;</span> <span class="p">}</span>
+
+<span class="c1">// cross-reference unsigned ping(unsigned n) { return n!= 0 ? pong(n-1) : 0;</span>
+<span class="p">}</span> <span class="kt">unsigned</span> <span class="n">pong</span><span class="p">(</span><span class="kt">unsigned</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">n</span><span class="o">!=</span> <span class="mi">0</span> <span class="o">?</span> <span class="n">ping</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="mi">0</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<blockquote>
+<div>This comparison has been implemented in initial <em>MergeFunctions</em> pass
+version. But, unfortunately, it is not transitive. And this is the only case
+we can’t convert to less-equal-greater comparison. It is a seldom case, 4-5
+functions of 10000 (checked on test-suite), and, we hope, reader would
+forgive us for such a sacrifice in order to get the O(log(N)) pass time.</div></blockquote>
+<p>2. If left/right <em>Value</em> is a constant, we have to compare them. Return 0 if it
+is the same constant, or use <tt class="docutils literal"><span class="pre">cmpConstants</span></tt> method otherwise.</p>
+<p>3. If left/right is <em>InlineAsm</em> instance. Return result of <em>Value</em> pointers
+comparison.</p>
+<p>4. Explicit association of <em>L</em> (left value) and <em>R</em>  (right value). We need to
+find out whether values met at the same time, and thus are <em>associated</em>. Or we
+need to put the rule: when we treat <em>L</em> < <em>R</em>. Now it is easy: just return
+result of numbers comparison:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">std</span><span class="o">::</span><span class="n">pair</span><span class="o"><</span><span class="n">iterator</span><span class="p">,</span> <span class="kt">bool</span><span class="o">></span>
+  <span class="n">LeftRes</span> <span class="o">=</span> <span class="n">sn_mapL</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_pair</span><span class="p">(</span><span class="n">Left</span><span class="p">,</span> <span class="n">sn_mapL</span><span class="p">.</span><span class="n">size</span><span class="p">())),</span>
+  <span class="n">RightRes</span> <span class="o">=</span> <span class="n">sn_mapR</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_pair</span><span class="p">(</span><span class="n">Right</span><span class="p">,</span> <span class="n">sn_mapR</span><span class="p">.</span><span class="n">size</span><span class="p">()));</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">LeftRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span> <span class="o">==</span> <span class="n">RightRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span><span class="p">)</span> <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">LeftRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span> <span class="o"><</span> <span class="n">RightRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span><span class="p">)</span> <span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
+<span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Now when <em>cmpValues</em> returns 0, we can proceed comparison procedure. Otherwise,
+if we get (-1 or 1), we need to pass this result to the top level, and finish
+comparison procedure.</p>
+</div>
+</div>
+<div class="section" id="cmpconstants">
+<h3><a class="toc-backref" href="#id21">cmpConstants</a><a class="headerlink" href="#cmpconstants" title="Permalink to this headline">¶</a></h3>
+<p>Performs constants comparison as follows:</p>
+<p>1. Compare constant types using <tt class="docutils literal"><span class="pre">cmpType</span></tt> method. If result is -1 or 1, goto
+step 2, otherwise proceed to step 3.</p>
+<p>2. If types are different, we still can check whether constants could be
+losslessly bitcasted to each other. The further explanation is modification of
+<tt class="docutils literal"><span class="pre">canLosslesslyBitCastTo</span></tt> method.</p>
+<blockquote>
+<div><p>2.1 Check whether constants are of the first class types
+(<tt class="docutils literal"><span class="pre">isFirstClassType</span></tt> check):</p>
+<p>2.1.1. If both constants are <em>not</em> of the first class type: return result
+of <tt class="docutils literal"><span class="pre">cmpType</span></tt>.</p>
+<p>2.1.2. Otherwise, if left type is not of the first class, return -1. If
+right type is not of the first class, return 1.</p>
+<p>2.1.3. If both types are of the first class type, proceed to the next step
+(2.1.3.1).</p>
+<p>2.1.3.1. If types are vectors, compare their bitwidth using the
+<em>cmpNumbers</em>. If result is not 0, return it.</p>
+<p>2.1.3.2. Different types, but not a vectors:</p>
+<ul class="simple">
+<li>if both of them are pointers, good for us, we can proceed to step 3.</li>
+<li>if one of types is pointer, return result of <em>isPointer</em> flags
+comparison (<em>cmpFlags</em> operation).</li>
+<li>otherwise we have no methods to prove bitcastability, and thus return
+result of types comparison (-1 or 1).</li>
+</ul>
+</div></blockquote>
+<p>Steps below are for the case when types are equal, or case when constants are
+bitcastable:</p>
+<p>3. One of constants is a “<em>null</em>” value. Return the result of
+<tt class="docutils literal"><span class="pre">cmpFlags(L->isNullValue,</span> <span class="pre">R->isNullValue)</span></tt> comparison.</p>
+<ol class="arabic simple" start="4">
+<li>Compare value IDs, and return result if it is not 0:</li>
+</ol>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="kt">int</span> <span class="n">Res</span> <span class="o">=</span> <span class="n">cmpNumbers</span><span class="p">(</span><span class="n">L</span><span class="o">-></span><span class="n">getValueID</span><span class="p">(),</span> <span class="n">R</span><span class="o">-></span><span class="n">getValueID</span><span class="p">()))</span>
+  <span class="k">return</span> <span class="n">Res</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>5. Compare the contents of constants. The comparison depends on kind of
+constants, but on this stage it is just a lexicographical comparison. Just see
+how it was described in the beginning of “<em>Functions comparison</em>” paragraph.
+Mathematically it is equal to the next case: we encode left constant and right
+constant (with similar way <em>bitcode-writer</em> does). Then compare left code
+sequence and right code sequence.</p>
+</div>
+<div class="section" id="compare-const-basicblock-const-basicblock">
+<h3><a class="toc-backref" href="#id22">compare(const BasicBlock*, const BasicBlock*)</a><a class="headerlink" href="#compare-const-basicblock-const-basicblock" title="Permalink to this headline">¶</a></h3>
+<p>Compares two <em>BasicBlock</em> instances.</p>
+<p>It enumerates instructions from left <em>BB</em> and right <em>BB</em>.</p>
+<p>1. It assigns serial numbers to the left and right instructions, using
+<tt class="docutils literal"><span class="pre">cmpValues</span></tt> method.</p>
+<p>2. If one of left or right is <em>GEP</em> (<tt class="docutils literal"><span class="pre">GetElementPtr</span></tt>), then treat <em>GEP</em> as
+greater than other instructions, if both instructions are <em>GEPs</em> use <tt class="docutils literal"><span class="pre">cmpGEP</span></tt>
+method for comparison. If result is -1 or 1, pass it to the top-level
+comparison (return it).</p>
+<blockquote>
+<div><p>3.1. Compare operations. Call <tt class="docutils literal"><span class="pre">cmpOperation</span></tt> method. If result is -1 or
+1, return it.</p>
+<p>3.2. Compare number of operands, if result is -1 or 1, return it.</p>
+<p>3.3. Compare operands themselves, use <tt class="docutils literal"><span class="pre">cmpValues</span></tt> method. Return result
+if it is -1 or 1.</p>
+<p>3.4. Compare type of operands, using <tt class="docutils literal"><span class="pre">cmpType</span></tt> method. Return result if
+it is -1 or 1.</p>
+<p>3.5. Proceed to the next instruction.</p>
+</div></blockquote>
+<ol class="arabic" start="4">
+<li><p class="first">We can finish instruction enumeration in 3 cases:</p>
+<p>4.1. We reached the end of both left and right basic-blocks. We didn’t
+exit on steps 1-3, so contents is equal, return 0.</p>
+<p>4.2. We have reached the end of the left basic-block. Return -1.</p>
+<p>4.3. Return 1 (the end of the right basic block).</p>
+</li>
+</ol>
+</div>
+<div class="section" id="cmpgep">
+<h3><a class="toc-backref" href="#id23">cmpGEP</a><a class="headerlink" href="#cmpgep" title="Permalink to this headline">¶</a></h3>
+<p>Compares two GEPs (<tt class="docutils literal"><span class="pre">getelementptr</span></tt> instructions).</p>
+<p>It differs from regular operations comparison with the only thing: possibility
+to use <tt class="docutils literal"><span class="pre">accumulateConstantOffset</span></tt> method.</p>
+<p>So, if we get constant offset for both left and right <em>GEPs</em>, then compare it as
+numbers, and return comparison result.</p>
+<p>Otherwise treat it like a regular operation (see previous paragraph).</p>
+</div>
+<div class="section" id="cmpoperation">
+<h3><a class="toc-backref" href="#id24">cmpOperation</a><a class="headerlink" href="#cmpoperation" title="Permalink to this headline">¶</a></h3>
+<p>Compares instruction opcodes and some important operation properties.</p>
+<ol class="arabic simple">
+<li>Compare opcodes, if it differs return the result.</li>
+<li>Compare number of operands. If it differs – return the result.</li>
+</ol>
+<p>3. Compare operation types, use <em>cmpType</em>. All the same – if types are
+different, return result.</p>
+<p>4. Compare <em>subclassOptionalData</em>, get it with <tt class="docutils literal"><span class="pre">getRawSubclassOptionalData</span></tt>
+method, and compare it like a numbers.</p>
+<ol class="arabic simple" start="5">
+<li>Compare operand types.</li>
+</ol>
+<p>6. For some particular instructions check equivalence (relation in our case) of
+some significant attributes. For example we have to compare alignment for
+<tt class="docutils literal"><span class="pre">load</span></tt> instructions.</p>
+</div>
+<div class="section" id="o-log-n">
+<h3><a class="toc-backref" href="#id25">O(log(N))</a><a class="headerlink" href="#o-log-n" title="Permalink to this headline">¶</a></h3>
+<p>Methods described above implement order relationship. And latter, could be used
+for nodes comparison in a binary tree. So we can organize functions set into
+the binary tree and reduce the cost of lookup procedure from
+O(N*N) to O(log(N)).</p>
+</div>
+</div>
+<div class="section" id="merging-process-mergetwofunctions">
+<h2><a class="toc-backref" href="#id26">Merging process, mergeTwoFunctions</a><a class="headerlink" href="#merging-process-mergetwofunctions" title="Permalink to this headline">¶</a></h2>
+<p>Once <em>MergeFunctions</em> detected that current function (<em>G</em>) is equal to one that
+were analyzed before (function <em>F</em>) it calls <tt class="docutils literal"><span class="pre">mergeTwoFunctions(Function*,</span>
+<span class="pre">Function*)</span></tt>.</p>
+<p>Operation affects <tt class="docutils literal"><span class="pre">FnTree</span></tt> contents with next way: <em>F</em> will stay in
+<tt class="docutils literal"><span class="pre">FnTree</span></tt>. <em>G</em> being equal to <em>F</em> will not be added to <tt class="docutils literal"><span class="pre">FnTree</span></tt>. Calls of
+<em>G</em> would be replaced with something else. It changes bodies of callers. So,
+functions that calls <em>G</em> would be put into <tt class="docutils literal"><span class="pre">Deferred</span></tt> set and removed from
+<tt class="docutils literal"><span class="pre">FnTree</span></tt>, and analyzed again.</p>
+<p>The approach is next:</p>
+<p>1. Most wished case: when we can use alias and both of <em>F</em> and <em>G</em> are weak. We
+make both of them with aliases to the third strong function <em>H</em>. Actually <em>H</em>
+is <em>F</em>. See below how it’s made (but it’s better to look straight into the
+source code). Well, this is a case when we can just replace <em>G</em> with <em>F</em>
+everywhere, we use <tt class="docutils literal"><span class="pre">replaceAllUsesWith</span></tt> operation here (<em>RAUW</em>).</p>
+<p>2. <em>F</em> could not be overridden, while <em>G</em> could. It would be good to do the
+next: after merging the places where overridable function were used, still use
+overridable stub. So try to make <em>G</em> alias to <em>F</em>, or create overridable tail
+call wrapper around <em>F</em> and replace <em>G</em> with that call.</p>
+<p>3. Neither <em>F</em> nor <em>G</em> could be overridden. We can’t use <em>RAUW</em>. We can just
+change the callers: call <em>F</em> instead of <em>G</em>.  That’s what
+<tt class="docutils literal"><span class="pre">replaceDirectCallers</span></tt> does.</p>
+<p>Below is detailed body description.</p>
+<div class="section" id="if-f-may-be-overridden">
+<h3><a class="toc-backref" href="#id27">If “F” may be overridden</a><a class="headerlink" href="#if-f-may-be-overridden" title="Permalink to this headline">¶</a></h3>
+<p>As follows from <tt class="docutils literal"><span class="pre">mayBeOverridden</span></tt> comments: “whether the definition of this
+global may be replaced by something non-equivalent at link time”. If so, thats
+ok: we can use alias to <em>F</em> instead of <em>G</em> or change call instructions itself.</p>
+<div class="section" id="hasglobalaliases-removeusers">
+<h4><a class="toc-backref" href="#id28">HasGlobalAliases, removeUsers</a><a class="headerlink" href="#hasglobalaliases-removeusers" title="Permalink to this headline">¶</a></h4>
+<p>First consider the case when we have global aliases of one function name to
+another. Our purpose is  make both of them with aliases to the third strong
+function. Though if we keep <em>F</em> alive and without major changes we can leave it
+in <tt class="docutils literal"><span class="pre">FnTree</span></tt>. Try to combine these two goals.</p>
+<p>Do stub replacement of <em>F</em> itself with an alias to <em>F</em>.</p>
+<p>1. Create stub function <em>H</em>, with the same name and attributes like function
+<em>F</em>. It takes maximum alignment of <em>F</em> and <em>G</em>.</p>
+<p>2. Replace all uses of function <em>F</em> with uses of function <em>H</em>. It is the two
+steps procedure instead. First of all, we must take into account, all functions
+from whom <em>F</em> is called would be changed: since we change the call argument
+(from <em>F</em> to <em>H</em>). If so we must to review these caller functions again after
+this procedure. We remove callers from <tt class="docutils literal"><span class="pre">FnTree</span></tt>, method with name
+<tt class="docutils literal"><span class="pre">removeUsers(F)</span></tt> does that (don’t confuse with <tt class="docutils literal"><span class="pre">replaceAllUsesWith</span></tt>):</p>
+<blockquote>
+<div><p>2.1. <tt class="docutils literal"><span class="pre">Inside</span> <span class="pre">removeUsers(Value*</span>
+<span class="pre">V)</span></tt> we go through the all values that use value <em>V</em> (or <em>F</em> in our context).
+If value is instruction, we go to function that holds this instruction and
+mark it as to-be-analyzed-again (put to <tt class="docutils literal"><span class="pre">Deferred</span></tt> set), we also remove
+caller from <tt class="docutils literal"><span class="pre">FnTree</span></tt>.</p>
+<p>2.2. Now we can do the replacement: call <tt class="docutils literal"><span class="pre">F->replaceAllUsesWith(H)</span></tt>.</p>
+</div></blockquote>
+<p>3. <em>H</em> (that now “officially” plays <em>F</em>‘s role) is replaced with alias to <em>F</em>.
+Do the same with <em>G</em>: replace it with alias to <em>F</em>. So finally everywhere <em>F</em>
+was used, we use <em>H</em> and it is alias to <em>F</em>, and everywhere <em>G</em> was used we
+also have alias to <em>F</em>.</p>
+<ol class="arabic simple" start="4">
+<li>Set <em>F</em> linkage to private. Make it strong :-)</li>
+</ol>
+</div>
+<div class="section" id="no-global-aliases-replacedirectcallers">
+<h4><a class="toc-backref" href="#id29">No global aliases, replaceDirectCallers</a><a class="headerlink" href="#no-global-aliases-replacedirectcallers" title="Permalink to this headline">¶</a></h4>
+<p>If global aliases are not supported. We call <tt class="docutils literal"><span class="pre">replaceDirectCallers</span></tt> then. Just
+go through all calls of <em>G</em> and replace it with calls of <em>F</em>. If you look into
+method you will see that it scans all uses of <em>G</em> too, and if use is callee (if
+user is call instruction and <em>G</em> is used as what to be called), we replace it
+with use of <em>F</em>.</p>
+<div class="section" id="if-f-could-not-be-overridden-fix-it">
+<h5><a class="toc-backref" href="#id30">If “F” could not be overridden, fix it!</a><a class="headerlink" href="#if-f-could-not-be-overridden-fix-it" title="Permalink to this headline">¶</a></h5>
+<p>We call <tt class="docutils literal"><span class="pre">writeThunkOrAlias(Function</span> <span class="pre">*F,</span> <span class="pre">Function</span> <span class="pre">*G)</span></tt>. Here we try to replace
+<em>G</em> with alias to <em>F</em> first. Next conditions are essential:</p>
+<ul class="simple">
+<li>target should support global aliases,</li>
+<li>the address itself of  <em>G</em> should be not significant, not named and not
+referenced anywhere,</li>
+<li>function should come with external, local or weak linkage.</li>
+</ul>
+<p>Otherwise we write thunk: some wrapper that has <em>G’s</em> interface and calls <em>F</em>,
+so <em>G</em> could be replaced with this wrapper.</p>
+<p><em>writeAlias</em></p>
+<p>As follows from <em>llvm</em> reference:</p>
+<p>“Aliases act as <em>second name</em> for the aliasee value”. So we just want to create
+second name for <em>F</em> and use it instead of <em>G</em>:</p>
+<ol class="arabic">
+<li><p class="first">create global alias itself (<em>GA</em>),</p>
+</li>
+<li><p class="first">adjust alignment of <em>F</em> so it must be maximum of current and <em>G’s</em> alignment;</p>
+</li>
+<li><p class="first">replace uses of <em>G</em>:</p>
+<p>3.1. first mark all callers of <em>G</em> as to-be-analyzed-again, using
+<tt class="docutils literal"><span class="pre">removeUsers</span></tt> method (see chapter above),</p>
+<p>3.2. call <tt class="docutils literal"><span class="pre">G->replaceAllUsesWith(GA)</span></tt>.</p>
+</li>
+<li><p class="first">Get rid of <em>G</em>.</p>
+</li>
+</ol>
+<p><em>writeThunk</em></p>
+<p>As it written in method comments:</p>
+<p>“Replace G with a simple tail call to bitcast(F). Also replace direct uses of G
+with bitcast(F). Deletes G.”</p>
+<p>In general it does the same as usual when we want to replace callee, except the
+first point:</p>
+<p>1. We generate tail call wrapper around <em>F</em>, but with interface that allows use
+it instead of <em>G</em>.</p>
+<ol class="arabic simple" start="2">
+<li>“As-usual”: <tt class="docutils literal"><span class="pre">removeUsers</span></tt> and <tt class="docutils literal"><span class="pre">replaceAllUsesWith</span></tt> then.</li>
+<li>Get rid of <em>G</em>.</li>
+</ol>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="that-s-it">
+<h2><a class="toc-backref" href="#id31">That’s it.</a><a class="headerlink" href="#that-s-it" title="Permalink to this headline">¶</a></h2>
+<p>We have described how to detect equal functions, and how to merge them, and in
+first chapter we have described how it works all-together. Author hopes, reader
+have some picture from now, and it helps him improve and debug ­this pass.</p>
+<p>Reader is welcomed to send us any questions and proposals ;-)</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="DeveloperPolicy.html" title="LLVM Developer Policy"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="Statepoints.html" title="Garbage Collection Safepoints 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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/NVPTXUsage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/NVPTXUsage.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/NVPTXUsage.html (added)
+++ www-releases/trunk/3.6.0/docs/NVPTXUsage.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,1064 @@
+
+<!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>User Guide for NVPTX Back-end — LLVM 3.6 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.6',
+        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.6 documentation" href="index.html" />
+    <link rel="next" title="User Guide for R600 Back-end" href="R600Usage.html" />
+    <link rel="prev" title="How To Use Attributes" href="HowToUseAttributes.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="R600Usage.html" title="User Guide for R600 Back-end"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="HowToUseAttributes.html" title="How To Use Attributes"
+             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="user-guide-for-nvptx-back-end">
+<h1>User Guide for NVPTX Back-end<a class="headerlink" href="#user-guide-for-nvptx-back-end" 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="id11">Introduction</a></li>
+<li><a class="reference internal" href="#conventions" id="id12">Conventions</a><ul>
+<li><a class="reference internal" href="#marking-functions-as-kernels" id="id13">Marking Functions as Kernels</a></li>
+<li><a class="reference internal" href="#address-spaces" id="id14">Address Spaces</a></li>
+<li><a class="reference internal" href="#triples" id="id15">Triples</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#nvptx-intrinsics" id="id16">NVPTX Intrinsics</a><ul>
+<li><a class="reference internal" href="#address-space-conversion" id="id17">Address Space Conversion</a><ul>
+<li><a class="reference internal" href="#llvm-nvvm-ptr-to-gen-intrinsics" id="id18">‘<tt class="docutils literal"><span class="pre">llvm.nvvm.ptr.*.to.gen</span></tt>‘ Intrinsics</a></li>
+<li><a class="reference internal" href="#llvm-nvvm-ptr-gen-to-intrinsics" id="id19">‘<tt class="docutils literal"><span class="pre">llvm.nvvm.ptr.gen.to.*</span></tt>‘ Intrinsics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reading-ptx-special-registers" id="id20">Reading PTX Special Registers</a><ul>
+<li><a class="reference internal" href="#llvm-nvvm-read-ptx-sreg" id="id21">‘<tt class="docutils literal"><span class="pre">llvm.nvvm.read.ptx.sreg.*</span></tt>‘</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#barriers" id="id22">Barriers</a><ul>
+<li><a class="reference internal" href="#llvm-nvvm-barrier0" id="id23">‘<tt class="docutils literal"><span class="pre">llvm.nvvm.barrier0</span></tt>‘</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-intrinsics" id="id24">Other Intrinsics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#linking-with-libdevice" id="id25">Linking with Libdevice</a><ul>
+<li><a class="reference internal" href="#reflection-parameters" id="id26">Reflection Parameters</a></li>
+<li><a class="reference internal" href="#invoking-nvvmreflect" id="id27">Invoking NVVMReflect</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#executing-ptx" id="id28">Executing PTX</a></li>
+<li><a class="reference internal" href="#common-issues" id="id29">Common Issues</a><ul>
+<li><a class="reference internal" href="#ptxas-complains-of-undefined-function-nvvm-reflect" id="id30">ptxas complains of undefined function: __nvvm_reflect</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tutorial-a-simple-compute-kernel" id="id31">Tutorial: A Simple Compute Kernel</a><ul>
+<li><a class="reference internal" href="#the-kernel" id="id32">The Kernel</a></li>
+<li><a class="reference internal" href="#dissecting-the-kernel" id="id33">Dissecting the Kernel</a><ul>
+<li><a class="reference internal" href="#data-layout" id="id34">Data Layout</a></li>
+<li><a class="reference internal" href="#target-intrinsics" id="id35">Target Intrinsics</a></li>
+<li><a class="reference internal" href="#id10" id="id36">Address Spaces</a></li>
+<li><a class="reference internal" href="#kernel-metadata" id="id37">Kernel Metadata</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#running-the-kernel" id="id38">Running the Kernel</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tutorial-linking-with-libdevice" id="id39">Tutorial: Linking with Libdevice</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id11">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>To support GPU programming, the NVPTX back-end supports a subset of LLVM IR
+along with a defined set of conventions used to represent GPU programming
+concepts. This document provides an overview of the general usage of the back-
+end, including a description of the conventions used and the set of accepted
+LLVM IR.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This document assumes a basic familiarity with CUDA and the PTX
+assembly language. Information about the CUDA Driver API and the PTX assembly
+language can be found in the <a class="reference external" href="http://docs.nvidia.com/cuda/index.html">CUDA documentation</a>.</p>
+</div>
+</div>
+<div class="section" id="conventions">
+<h2><a class="toc-backref" href="#id12">Conventions</a><a class="headerlink" href="#conventions" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="marking-functions-as-kernels">
+<h3><a class="toc-backref" href="#id13">Marking Functions as Kernels</a><a class="headerlink" href="#marking-functions-as-kernels" title="Permalink to this headline">¶</a></h3>
+<p>In PTX, there are two types of functions: <em>device functions</em>, which are only
+callable by device code, and <em>kernel functions</em>, which are callable by host
+code. By default, the back-end will emit device functions. Metadata is used to
+declare a function as a kernel function. This metadata is attached to the
+<tt class="docutils literal"><span class="pre">nvvm.annotations</span></tt> named metadata object, and has the following format:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>!0 = metadata !{<function-ref>, metadata !"kernel", i32 1}
+</pre></div>
+</div>
+<p>The first parameter is a reference to the kernel function. The following
+example shows a kernel function calling a device function in LLVM IR. The
+function <tt class="docutils literal"><span class="pre">@my_kernel</span></tt> is callable from host code, but <tt class="docutils literal"><span class="pre">@my_fmad</span></tt> is not.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">float</span> <span class="vg">@my_fmad</span><span class="p">(</span><span class="kt">float</span> <span class="nv">%x</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%y</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%z</span><span class="p">)</span> <span class="p">{</span>
+  <span class="nv">%mul</span> <span class="p">=</span> <span class="k">fmul</span> <span class="kt">float</span> <span class="nv">%x</span><span class="p">,</span> <span class="nv">%y</span>
+  <span class="nv">%add</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">float</span> <span class="nv">%mul</span><span class="p">,</span> <span class="nv">%z</span>
+  <span class="k">ret</span> <span class="kt">float</span> <span class="nv">%add</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@my_kernel</span><span class="p">(</span><span class="kt">float</span><span class="p">*</span> <span class="nv">%ptr</span><span class="p">)</span> <span class="p">{</span>
+  <span class="nv">%val</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span><span class="p">*</span> <span class="nv">%ptr</span>
+  <span class="nv">%ret</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">float</span> <span class="vg">@my_fmad</span><span class="p">(</span><span class="kt">float</span> <span class="nv">%val</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%val</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%val</span><span class="p">)</span>
+  <span class="k">store</span> <span class="kt">float</span> <span class="nv">%ret</span><span class="p">,</span> <span class="kt">float</span><span class="p">*</span> <span class="nv">%ptr</span>
+  <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="nv">!nvvm.annotations</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!1</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="kt">void</span> <span class="p">(</span><span class="kt">float</span><span class="p">*)*</span> <span class="vg">@my_kernel</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"kernel"</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>When compiled, the PTX kernel functions are callable by host-side code.</p>
+</div>
+<div class="section" id="address-spaces">
+<span id="id1"></span><h3><a class="toc-backref" href="#id14">Address Spaces</a><a class="headerlink" href="#address-spaces" title="Permalink to this headline">¶</a></h3>
+<p>The NVPTX back-end uses the following address space mapping:</p>
+<blockquote>
+<div><table border="1" class="docutils">
+<colgroup>
+<col width="37%" />
+<col width="63%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Address Space</th>
+<th class="head">Memory Space</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>0</td>
+<td>Generic</td>
+</tr>
+<tr class="row-odd"><td>1</td>
+<td>Global</td>
+</tr>
+<tr class="row-even"><td>2</td>
+<td>Internal Use</td>
+</tr>
+<tr class="row-odd"><td>3</td>
+<td>Shared</td>
+</tr>
+<tr class="row-even"><td>4</td>
+<td>Constant</td>
+</tr>
+<tr class="row-odd"><td>5</td>
+<td>Local</td>
+</tr>
+</tbody>
+</table>
+</div></blockquote>
+<p>Every global variable and pointer type is assigned to one of these address
+spaces, with 0 being the default address space. Intrinsics are provided which
+can be used to convert pointers between the generic and non-generic address
+spaces.</p>
+<p>As an example, the following IR will define an array <tt class="docutils literal"><span class="pre">@g</span></tt> that resides in
+global device memory.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@g</span> <span class="p">=</span> <span class="k">internal</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)</span> <span class="k">global</span> <span class="p">[</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</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">1</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>
+</pre></div>
+</div>
+<p>LLVM IR functions can read and write to this array, and host-side code can
+copy data to it by name with the CUDA Driver API.</p>
+<p>Note that since address space 0 is the generic space, it is illegal to have
+global variables in address space 0.  Address space 0 is the default address
+space in LLVM, so the <tt class="docutils literal"><span class="pre">addrspace(N)</span></tt> annotation is <em>required</em> for global
+variables.</p>
+</div>
+<div class="section" id="triples">
+<h3><a class="toc-backref" href="#id15">Triples</a><a class="headerlink" href="#triples" title="Permalink to this headline">¶</a></h3>
+<p>The NVPTX target uses the module triple to select between 32/64-bit code
+generation and the driver-compiler interface to use. The triple architecture
+can be one of <tt class="docutils literal"><span class="pre">nvptx</span></tt> (32-bit PTX) or <tt class="docutils literal"><span class="pre">nvptx64</span></tt> (64-bit PTX). The
+operating system should be one of <tt class="docutils literal"><span class="pre">cuda</span></tt> or <tt class="docutils literal"><span class="pre">nvcl</span></tt>, which determines the
+interface used by the generated code to communicate with the driver.  Most
+users will want to use <tt class="docutils literal"><span class="pre">cuda</span></tt> as the operating system, which makes the
+generated PTX compatible with the CUDA Driver API.</p>
+<p>Example: 32-bit PTX for CUDA Driver API: <tt class="docutils literal"><span class="pre">nvptx-nvidia-cuda</span></tt></p>
+<p>Example: 64-bit PTX for CUDA Driver API: <tt class="docutils literal"><span class="pre">nvptx64-nvidia-cuda</span></tt></p>
+</div>
+</div>
+<div class="section" id="nvptx-intrinsics">
+<span id="id2"></span><h2><a class="toc-backref" href="#id16">NVPTX Intrinsics</a><a class="headerlink" href="#nvptx-intrinsics" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="address-space-conversion">
+<h3><a class="toc-backref" href="#id17">Address Space Conversion</a><a class="headerlink" href="#address-space-conversion" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="llvm-nvvm-ptr-to-gen-intrinsics">
+<h4><a class="toc-backref" href="#id18">‘<tt class="docutils literal"><span class="pre">llvm.nvvm.ptr.*.to.gen</span></tt>‘ Intrinsics</a><a class="headerlink" href="#llvm-nvvm-ptr-to-gen-intrinsics" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="syntax">
+<h5>Syntax:<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h5>
+<p>These are overloaded intrinsics.  You can use these on any pointer types.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.global.to.gen.p0i8.p1i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*)</span>
+<span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.shared.to.gen.p0i8.p3i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">3</span><span class="p">)*)</span>
+<span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.constant.to.gen.p0i8.p4i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">4</span><span class="p">)*)</span>
+<span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.local.to.gen.p0i8.p5i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">5</span><span class="p">)*)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="overview">
+<h5>Overview:<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.nvvm.ptr.*.to.gen</span></tt>‘ intrinsics convert a pointer in a non-generic
+address space to a generic address space pointer.</p>
+</div>
+<div class="section" id="semantics">
+<h5>Semantics:<a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h5>
+<p>These intrinsics modify the pointer value to be a valid generic address space
+pointer.</p>
+</div>
+</div>
+<div class="section" id="llvm-nvvm-ptr-gen-to-intrinsics">
+<h4><a class="toc-backref" href="#id19">‘<tt class="docutils literal"><span class="pre">llvm.nvvm.ptr.gen.to.*</span></tt>‘ Intrinsics</a><a class="headerlink" href="#llvm-nvvm-ptr-gen-to-intrinsics" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="id3">
+<h5>Syntax:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h5>
+<p>These are overloaded intrinsics.  You can use these on any pointer types.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.gen.to.global.p1i8.p0i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*)</span>
+<span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.gen.to.shared.p3i8.p0i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">3</span><span class="p">)*)</span>
+<span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.gen.to.constant.p4i8.p0i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">4</span><span class="p">)*)</span>
+<span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.gen.to.local.p5i8.p0i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">5</span><span class="p">)*)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="id4">
+<h5>Overview:<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.nvvm.ptr.gen.to.*</span></tt>‘ intrinsics convert a pointer in the generic
+address space to a pointer in the target address space.  Note that these
+intrinsics are only useful if the address space of the target address space of
+the pointer is known.  It is not legal to use address space conversion
+intrinsics to convert a pointer from one non-generic address space to another
+non-generic address space.</p>
+</div>
+<div class="section" id="id5">
+<h5>Semantics:<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h5>
+<p>These intrinsics modify the pointer value to be a valid pointer in the target
+non-generic address space.</p>
+</div>
+</div>
+</div>
+<div class="section" id="reading-ptx-special-registers">
+<h3><a class="toc-backref" href="#id20">Reading PTX Special Registers</a><a class="headerlink" href="#reading-ptx-special-registers" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="llvm-nvvm-read-ptx-sreg">
+<h4><a class="toc-backref" href="#id21">‘<tt class="docutils literal"><span class="pre">llvm.nvvm.read.ptx.sreg.*</span></tt>‘</a><a class="headerlink" href="#llvm-nvvm-read-ptx-sreg" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="id6">
+<h5>Syntax:<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.y</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.z</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ntid.x</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ntid.y</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ntid.z</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ctaid.x</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ctaid.y</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ctaid.z</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.nctaid.x</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.nctaid.y</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.nctaid.z</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.warpsize</span><span class="p">()</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="id7">
+<h5>Overview:<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.*</span></tt>‘ intrinsics provide access to the PTX
+special registers, in particular the kernel launch bounds.  These registers
+map in the following way to CUDA builtins:</p>
+<blockquote>
+<div><table border="1" class="docutils">
+<colgroup>
+<col width="24%" />
+<col width="76%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">CUDA Builtin</th>
+<th class="head">PTX Special Register Intrinsic</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">threadId</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.tid.*</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">blockIdx</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.ctaid.*</span></tt></td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">blockDim</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.ntid.*</span></tt></td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">gridDim</span></tt></td>
+<td><tt class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.nctaid.*</span></tt></td>
+</tr>
+</tbody>
+</table>
+</div></blockquote>
+</div>
+</div>
+</div>
+<div class="section" id="barriers">
+<h3><a class="toc-backref" href="#id22">Barriers</a><a class="headerlink" href="#barriers" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="llvm-nvvm-barrier0">
+<h4><a class="toc-backref" href="#id23">‘<tt class="docutils literal"><span class="pre">llvm.nvvm.barrier0</span></tt>‘</a><a class="headerlink" href="#llvm-nvvm-barrier0" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="id8">
+<h5>Syntax:<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">declare</span> <span class="kt">void</span> <span class="vg">@llvm.nvvm.barrier0</span><span class="p">()</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="id9">
+<h5>Overview:<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">@llvm.nvvm.barrier0()</span></tt>‘ intrinsic emits a PTX <tt class="docutils literal"><span class="pre">bar.sync</span> <span class="pre">0</span></tt>
+instruction, equivalent to the <tt class="docutils literal"><span class="pre">__syncthreads()</span></tt> call in CUDA.</p>
+</div>
+</div>
+</div>
+<div class="section" id="other-intrinsics">
+<h3><a class="toc-backref" href="#id24">Other Intrinsics</a><a class="headerlink" href="#other-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>For the full set of NVPTX intrinsics, please see the
+<tt class="docutils literal"><span class="pre">include/llvm/IR/IntrinsicsNVVM.td</span></tt> file in the LLVM source tree.</p>
+</div>
+</div>
+<div class="section" id="linking-with-libdevice">
+<span id="libdevice"></span><h2><a class="toc-backref" href="#id25">Linking with Libdevice</a><a class="headerlink" href="#linking-with-libdevice" title="Permalink to this headline">¶</a></h2>
+<p>The CUDA Toolkit comes with an LLVM bitcode library called <tt class="docutils literal"><span class="pre">libdevice</span></tt> that
+implements many common mathematical functions. This library can be used as a
+high-performance math library for any compilers using the LLVM NVPTX target.
+The library can be found under <tt class="docutils literal"><span class="pre">nvvm/libdevice/</span></tt> in the CUDA Toolkit and
+there is a separate version for each compute architecture.</p>
+<p>For a list of all math functions implemented in libdevice, see
+<a class="reference external" href="http://docs.nvidia.com/cuda/libdevice-users-guide/index.html">libdevice Users Guide</a>.</p>
+<p>To accommodate various math-related compiler flags that can affect code
+generation of libdevice code, the library code depends on a special LLVM IR
+pass (<tt class="docutils literal"><span class="pre">NVVMReflect</span></tt>) to handle conditional compilation within LLVM IR. This
+pass looks for calls to the <tt class="docutils literal"><span class="pre">@__nvvm_reflect</span></tt> function and replaces them
+with constants based on the defined reflection parameters. Such conditional
+code often follows a pattern:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">float</span> <span class="nf">my_function</span><span class="p">(</span><span class="kt">float</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">__nvvm_reflect</span><span class="p">(</span><span class="s">"FASTMATH"</span><span class="p">))</span>
+    <span class="k">return</span> <span class="n">my_function_fast</span><span class="p">(</span><span class="n">a</span><span class="p">);</span>
+  <span class="k">else</span>
+    <span class="k">return</span> <span class="n">my_function_precise</span><span class="p">(</span><span class="n">a</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The default value for all unspecified reflection parameters is zero.</p>
+<p>The <tt class="docutils literal"><span class="pre">NVVMReflect</span></tt> pass should be executed early in the optimization
+pipeline, immediately after the link stage. The <tt class="docutils literal"><span class="pre">internalize</span></tt> pass is also
+recommended to remove unused math functions from the resulting PTX. For an
+input IR module <tt class="docutils literal"><span class="pre">module.bc</span></tt>, the following compilation flow is recommended:</p>
+<ol class="arabic simple">
+<li>Save list of external functions in <tt class="docutils literal"><span class="pre">module.bc</span></tt></li>
+<li>Link <tt class="docutils literal"><span class="pre">module.bc</span></tt> with <tt class="docutils literal"><span class="pre">libdevice.compute_XX.YY.bc</span></tt></li>
+<li>Internalize all functions not in list from (1)</li>
+<li>Eliminate all unused internal functions</li>
+<li>Run <tt class="docutils literal"><span class="pre">NVVMReflect</span></tt> pass</li>
+<li>Run standard optimization pipeline</li>
+</ol>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last"><tt class="docutils literal"><span class="pre">linkonce</span></tt> and <tt class="docutils literal"><span class="pre">linkonce_odr</span></tt> linkage types are not suitable for the
+libdevice functions. It is possible to link two IR modules that have been
+linked against libdevice using different reflection variables.</p>
+</div>
+<p>Since the <tt class="docutils literal"><span class="pre">NVVMReflect</span></tt> pass replaces conditionals with constants, it will
+often leave behind dead code of the form:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nl">entry:</span>
+  <span class="p">..</span>
+  <span class="k">br</span> <span class="k">i1</span> <span class="k">true</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%foo</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%bar</span>
+<span class="nl">foo:</span>
+  <span class="p">..</span>
+<span class="nl">bar:</span>
+  <span class="c">; Dead code</span>
+  <span class="p">..</span>
+</pre></div>
+</div>
+<p>Therefore, it is recommended that <tt class="docutils literal"><span class="pre">NVVMReflect</span></tt> is executed early in the
+optimization pipeline before dead-code elimination.</p>
+<div class="section" id="reflection-parameters">
+<h3><a class="toc-backref" href="#id26">Reflection Parameters</a><a class="headerlink" href="#reflection-parameters" title="Permalink to this headline">¶</a></h3>
+<p>The libdevice library currently uses the following reflection parameters to
+control code generation:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="27%" />
+<col width="73%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Flag</th>
+<th class="head">Description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">__CUDA_FTZ=[0,1]</span></tt></td>
+<td>Use optimized code paths that flush subnormals to zero</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="invoking-nvvmreflect">
+<h3><a class="toc-backref" href="#id27">Invoking NVVMReflect</a><a class="headerlink" href="#invoking-nvvmreflect" title="Permalink to this headline">¶</a></h3>
+<p>To ensure that all dead code caused by the reflection pass is eliminated, it
+is recommended that the reflection pass is executed early in the LLVM IR
+optimization pipeline. The pass takes an optional mapping of reflection
+parameter name to an integer value. This mapping can be specified as either a
+command-line option to <tt class="docutils literal"><span class="pre">opt</span></tt> or as an LLVM <tt class="docutils literal"><span class="pre">StringMap<int></span></tt> object when
+programmatically creating a pass pipeline.</p>
+<p>With <tt class="docutils literal"><span class="pre">opt</span></tt>:</p>
+<div class="highlight-text"><div class="highlight"><pre># opt -nvvm-reflect -nvvm-reflect-list=<var>=<value>,<var>=<value> module.bc -o module.reflect.bc
+</pre></div>
+</div>
+<p>With programmatic pass pipeline:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">extern</span> <span class="n">ModulePass</span> <span class="o">*</span><span class="n">llvm</span><span class="o">::</span><span class="n">createNVVMReflectPass</span><span class="p">(</span><span class="k">const</span> <span class="n">StringMap</span><span class="o"><</span><span class="kt">int</span><span class="o">>&</span> <span class="n">Mapping</span><span class="p">);</span>
+
+<span class="n">StringMap</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">ReflectParams</span><span class="p">;</span>
+<span class="n">ReflectParams</span><span class="p">[</span><span class="s">"__CUDA_FTZ"</span><span class="p">]</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+<span class="n">Passes</span><span class="p">.</span><span class="n">add</span><span class="p">(</span><span class="n">createNVVMReflectPass</span><span class="p">(</span><span class="n">ReflectParams</span><span class="p">));</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="executing-ptx">
+<h2><a class="toc-backref" href="#id28">Executing PTX</a><a class="headerlink" href="#executing-ptx" title="Permalink to this headline">¶</a></h2>
+<p>The most common way to execute PTX assembly on a GPU device is to use the CUDA
+Driver API. This API is a low-level interface to the GPU driver and allows for
+JIT compilation of PTX code to native GPU machine code.</p>
+<p>Initializing the Driver API:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">CUdevice</span> <span class="n">device</span><span class="p">;</span>
+<span class="n">CUcontext</span> <span class="n">context</span><span class="p">;</span>
+
+<span class="c1">// Initialize the driver API</span>
+<span class="n">cuInit</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+<span class="c1">// Get a handle to the first compute device</span>
+<span class="n">cuDeviceGet</span><span class="p">(</span><span class="o">&</span><span class="n">device</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+<span class="c1">// Create a compute device context</span>
+<span class="n">cuCtxCreate</span><span class="p">(</span><span class="o">&</span><span class="n">context</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">device</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>JIT compiling a PTX string to a device binary:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">CUmodule</span> <span class="n">module</span><span class="p">;</span>
+<span class="n">CUfunction</span> <span class="n">funcion</span><span class="p">;</span>
+
+<span class="c1">// JIT compile a null-terminated PTX string</span>
+<span class="n">cuModuleLoadData</span><span class="p">(</span><span class="o">&</span><span class="n">module</span><span class="p">,</span> <span class="p">(</span><span class="kt">void</span><span class="o">*</span><span class="p">)</span><span class="n">PTXString</span><span class="p">);</span>
+
+<span class="c1">// Get a handle to the "myfunction" kernel function</span>
+<span class="n">cuModuleGetFunction</span><span class="p">(</span><span class="o">&</span><span class="n">function</span><span class="p">,</span> <span class="n">module</span><span class="p">,</span> <span class="s">"myfunction"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>For full examples of executing PTX assembly, please see the <a class="reference external" href="https://developer.nvidia.com/cuda-downloads">CUDA Samples</a> distribution.</p>
+</div>
+<div class="section" id="common-issues">
+<h2><a class="toc-backref" href="#id29">Common Issues</a><a class="headerlink" href="#common-issues" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="ptxas-complains-of-undefined-function-nvvm-reflect">
+<h3><a class="toc-backref" href="#id30">ptxas complains of undefined function: __nvvm_reflect</a><a class="headerlink" href="#ptxas-complains-of-undefined-function-nvvm-reflect" title="Permalink to this headline">¶</a></h3>
+<p>When linking with libdevice, the <tt class="docutils literal"><span class="pre">NVVMReflect</span></tt> pass must be used. See
+<a class="reference internal" href="#libdevice"><em>Linking with Libdevice</em></a> for more information.</p>
+</div>
+</div>
+<div class="section" id="tutorial-a-simple-compute-kernel">
+<h2><a class="toc-backref" href="#id31">Tutorial: A Simple Compute Kernel</a><a class="headerlink" href="#tutorial-a-simple-compute-kernel" title="Permalink to this headline">¶</a></h2>
+<p>To start, let us take a look at a simple compute kernel written directly in
+LLVM IR. The kernel implements vector addition, where each thread computes one
+element of the output vector C from the input vectors A and B.  To make this
+easier, we also assume that only a single CTA (thread block) will be launched,
+and that it will be one dimensional.</p>
+<div class="section" id="the-kernel">
+<h3><a class="toc-backref" href="#id32">The Kernel</a><a class="headerlink" href="#the-kernel" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">target</span> <span class="k">datalayout</span> <span class="p">=</span> <span class="s">"e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"</span>
+<span class="k">target</span> <span class="k">triple</span> <span class="p">=</span> <span class="s">"nvptx64-nvidia-cuda"</span>
+
+<span class="c">; Intrinsic to read X component of thread ID</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span> <span class="k">readnone</span> <span class="k">nounwind</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@kernel</span><span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%A</span><span class="p">,</span>
+                    <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%B</span><span class="p">,</span>
+                    <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%C</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="c">; What is my ID?</span>
+  <span class="nv">%id</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span> <span class="k">readnone</span> <span class="k">nounwind</span>
+
+  <span class="c">; Compute pointers into A, B, and C</span>
+  <span class="nv">%ptrA</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%A</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+  <span class="nv">%ptrB</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%B</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+  <span class="nv">%ptrC</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%C</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+
+  <span class="c">; Read A, B</span>
+  <span class="nv">%valA</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrA</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+  <span class="nv">%valB</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrB</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+
+  <span class="c">; Compute C = A + B</span>
+  <span class="nv">%valC</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">float</span> <span class="nv">%valA</span><span class="p">,</span> <span class="nv">%valB</span>
+
+  <span class="c">; Store back to C</span>
+  <span class="k">store</span> <span class="kt">float</span> <span class="nv">%valC</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrC</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+
+  <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="nv">!nvvm.annotations</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">void</span> <span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+                      <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+                      <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*)*</span> <span class="vg">@kernel</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"kernel"</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>We can use the LLVM <tt class="docutils literal"><span class="pre">llc</span></tt> tool to directly run the NVPTX code generator:</p>
+<div class="highlight-text"><div class="highlight"><pre># llc -mcpu=sm_20 kernel.ll -o kernel.ptx
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">If you want to generate 32-bit code, change <tt class="docutils literal"><span class="pre">p:64:64:64</span></tt> to <tt class="docutils literal"><span class="pre">p:32:32:32</span></tt>
+in the module data layout string and use <tt class="docutils literal"><span class="pre">nvptx-nvidia-cuda</span></tt> as the
+target triple.</p>
+</div>
+<p>The output we get from <tt class="docutils literal"><span class="pre">llc</span></tt> (as of LLVM 3.4):</p>
+<div class="highlight-text"><div class="highlight"><pre>//
+// Generated by LLVM NVPTX Back-End
+//
+
+.version 3.1
+.target sm_20
+.address_size 64
+
+  // .globl kernel
+                                        // @kernel
+.visible .entry kernel(
+  .param .u64 kernel_param_0,
+  .param .u64 kernel_param_1,
+  .param .u64 kernel_param_2
+)
+{
+  .reg .f32   %f<4>;
+  .reg .s32   %r<2>;
+  .reg .s64   %rl<8>;
+
+// BB#0:                                // %entry
+  ld.param.u64    %rl1, [kernel_param_0];
+  mov.u32         %r1, %tid.x;
+  mul.wide.s32    %rl2, %r1, 4;
+  add.s64         %rl3, %rl1, %rl2;
+  ld.param.u64    %rl4, [kernel_param_1];
+  add.s64         %rl5, %rl4, %rl2;
+  ld.param.u64    %rl6, [kernel_param_2];
+  add.s64         %rl7, %rl6, %rl2;
+  ld.global.f32   %f1, [%rl3];
+  ld.global.f32   %f2, [%rl5];
+  add.f32         %f3, %f1, %f2;
+  st.global.f32   [%rl7], %f3;
+  ret;
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="dissecting-the-kernel">
+<h3><a class="toc-backref" href="#id33">Dissecting the Kernel</a><a class="headerlink" href="#dissecting-the-kernel" title="Permalink to this headline">¶</a></h3>
+<p>Now let us dissect the LLVM IR that makes up this kernel.</p>
+<div class="section" id="data-layout">
+<h4><a class="toc-backref" href="#id34">Data Layout</a><a class="headerlink" href="#data-layout" title="Permalink to this headline">¶</a></h4>
+<p>The data layout string determines the size in bits of common data types, their
+ABI alignment, and their storage size.  For NVPTX, you should use one of the
+following:</p>
+<p>32-bit PTX:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">target</span> <span class="k">datalayout</span> <span class="p">=</span> <span class="s">"e-p:32:32:32-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"</span>
+</pre></div>
+</div>
+<p>64-bit PTX:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">target</span> <span class="k">datalayout</span> <span class="p">=</span> <span class="s">"e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="target-intrinsics">
+<h4><a class="toc-backref" href="#id35">Target Intrinsics</a><a class="headerlink" href="#target-intrinsics" title="Permalink to this headline">¶</a></h4>
+<p>In this example, we use the <tt class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.tid.x</span></tt> intrinsic to
+read the X component of the current thread’s ID, which corresponds to a read
+of register <tt class="docutils literal"><span class="pre">%tid.x</span></tt> in PTX. The NVPTX back-end supports a large set of
+intrinsics.  A short list is shown below; please see
+<tt class="docutils literal"><span class="pre">include/llvm/IR/IntrinsicsNVVM.td</span></tt> for the full list.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="71%" />
+<col width="29%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Intrinsic</th>
+<th class="head">CUDA Equivalent</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">i32</span> <span class="pre">@llvm.nvvm.read.ptx.sreg.tid.{x,y,z}</span></tt></td>
+<td>threadIdx.{x,y,z}</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">i32</span> <span class="pre">@llvm.nvvm.read.ptx.sreg.ctaid.{x,y,z}</span></tt></td>
+<td>blockIdx.{x,y,z}</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">i32</span> <span class="pre">@llvm.nvvm.read.ptx.sreg.ntid.{x,y,z}</span></tt></td>
+<td>blockDim.{x,y,z}</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">i32</span> <span class="pre">@llvm.nvvm.read.ptx.sreg.nctaid.{x,y,z}</span></tt></td>
+<td>gridDim.{x,y,z}</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">void</span> <span class="pre">@llvm.cuda.syncthreads()</span></tt></td>
+<td>__syncthreads()</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="id10">
+<h4><a class="toc-backref" href="#id36">Address Spaces</a><a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h4>
+<p>You may have noticed that all of the pointer types in the LLVM IR example had
+an explicit address space specifier. What is address space 1? NVIDIA GPU
+devices (generally) have four types of memory:</p>
+<ul class="simple">
+<li>Global: Large, off-chip memory</li>
+<li>Shared: Small, on-chip memory shared among all threads in a CTA</li>
+<li>Local: Per-thread, private memory</li>
+<li>Constant: Read-only memory shared across all threads</li>
+</ul>
+<p>These different types of memory are represented in LLVM IR as address spaces.
+There is also a fifth address space used by the NVPTX code generator that
+corresponds to the “generic” address space.  This address space can represent
+addresses in any other address space (with a few exceptions).  This allows
+users to write IR functions that can load/store memory using the same
+instructions. Intrinsics are provided to convert pointers between the generic
+and non-generic address spaces.</p>
+<p>See <a class="reference internal" href="#address-spaces"><em>Address Spaces</em></a> and <a class="reference internal" href="#nvptx-intrinsics"><em>NVPTX Intrinsics</em></a> for more information.</p>
+</div>
+<div class="section" id="kernel-metadata">
+<h4><a class="toc-backref" href="#id37">Kernel Metadata</a><a class="headerlink" href="#kernel-metadata" title="Permalink to this headline">¶</a></h4>
+<p>In PTX, a function can be either a <cite>kernel</cite> function (callable from the host
+program), or a <cite>device</cite> function (callable only from GPU code). You can think
+of <cite>kernel</cite> functions as entry-points in the GPU program. To mark an LLVM IR
+function as a <cite>kernel</cite> function, we make use of special LLVM metadata. The
+NVPTX back-end will look for a named metadata node called
+<tt class="docutils literal"><span class="pre">nvvm.annotations</span></tt>. This named metadata must contain a list of metadata that
+describe the IR. For our purposes, we need to declare a metadata node that
+assigns the “kernel” attribute to the LLVM IR function that should be emitted
+as a PTX <cite>kernel</cite> function. These metadata nodes take the form:</p>
+<div class="highlight-text"><div class="highlight"><pre>metadata !{<function ref>, metadata !"kernel", i32 1}
+</pre></div>
+</div>
+<p>For the previous example, we have:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">!nvvm.annotations</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">void</span> <span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+                      <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+                      <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*)*</span> <span class="vg">@kernel</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"kernel"</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>Here, we have a single metadata declaration in <tt class="docutils literal"><span class="pre">nvvm.annotations</span></tt>. This
+metadata annotates our <tt class="docutils literal"><span class="pre">@kernel</span></tt> function with the <tt class="docutils literal"><span class="pre">kernel</span></tt> attribute.</p>
+</div>
+</div>
+<div class="section" id="running-the-kernel">
+<h3><a class="toc-backref" href="#id38">Running the Kernel</a><a class="headerlink" href="#running-the-kernel" title="Permalink to this headline">¶</a></h3>
+<p>Generating PTX from LLVM IR is all well and good, but how do we execute it on
+a real GPU device? The CUDA Driver API provides a convenient mechanism for
+loading and JIT compiling PTX to a native GPU device, and launching a kernel.
+The API is similar to OpenCL.  A simple example showing how to load and
+execute our vector addition code is shown below. Note that for brevity this
+code does not perform much error checking!</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">You can also use the <tt class="docutils literal"><span class="pre">ptxas</span></tt> tool provided by the CUDA Toolkit to offline
+compile PTX to machine code (SASS) for a specific GPU architecture. Such
+binaries can be loaded by the CUDA Driver API in the same way as PTX. This
+can be useful for reducing startup time by precompiling the PTX kernels.</p>
+</div>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <iostream></span>
+<span class="cp">#include <fstream></span>
+<span class="cp">#include <cassert></span>
+<span class="cp">#include "cuda.h"</span>
+
+
+<span class="kt">void</span> <span class="nf">checkCudaErrors</span><span class="p">(</span><span class="n">CUresult</span> <span class="n">err</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">assert</span><span class="p">(</span><span class="n">err</span> <span class="o">==</span> <span class="n">CUDA_SUCCESS</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="c1">/// main - Program entry point</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="n">CUdevice</span>    <span class="n">device</span><span class="p">;</span>
+  <span class="n">CUmodule</span>    <span class="n">cudaModule</span><span class="p">;</span>
+  <span class="n">CUcontext</span>   <span class="n">context</span><span class="p">;</span>
+  <span class="n">CUfunction</span>  <span class="n">function</span><span class="p">;</span>
+  <span class="n">CUlinkState</span> <span class="n">linker</span><span class="p">;</span>
+  <span class="kt">int</span>         <span class="n">devCount</span><span class="p">;</span>
+
+  <span class="c1">// CUDA initialization</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuInit</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuDeviceGetCount</span><span class="p">(</span><span class="o">&</span><span class="n">devCount</span><span class="p">));</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuDeviceGet</span><span class="p">(</span><span class="o">&</span><span class="n">device</span><span class="p">,</span> <span class="mi">0</span><span class="p">));</span>
+
+  <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="mi">128</span><span class="p">];</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuDeviceGetName</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="mi">128</span><span class="p">,</span> <span class="n">device</span><span class="p">));</span>
+  <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Using CUDA Device [0]: "</span> <span class="o"><<</span> <span class="n">name</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+
+  <span class="kt">int</span> <span class="n">devMajor</span><span class="p">,</span> <span class="n">devMinor</span><span class="p">;</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuDeviceComputeCapability</span><span class="p">(</span><span class="o">&</span><span class="n">devMajor</span><span class="p">,</span> <span class="o">&</span><span class="n">devMinor</span><span class="p">,</span> <span class="n">device</span><span class="p">));</span>
+  <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Device Compute Capability: "</span>
+            <span class="o"><<</span> <span class="n">devMajor</span> <span class="o"><<</span> <span class="s">"."</span> <span class="o"><<</span> <span class="n">devMinor</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">devMajor</span> <span class="o"><</span> <span class="mi">2</span><span class="p">)</span> <span class="p">{</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"ERROR: Device 0 is not SM 2.0 or greater</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+    <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+  <span class="p">}</span>
+
+  <span class="n">std</span><span class="o">::</span><span class="n">ifstream</span> <span class="n">t</span><span class="p">(</span><span class="s">"kernel.ptx"</span><span class="p">);</span>
+  <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">t</span><span class="p">.</span><span class="n">is_open</span><span class="p">())</span> <span class="p">{</span>
+    <span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"kernel.ptx not found</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+    <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+  <span class="p">}</span>
+  <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">str</span><span class="p">((</span><span class="n">std</span><span class="o">::</span><span class="n">istreambuf_iterator</span><span class="o"><</span><span class="kt">char</span><span class="o">></span><span class="p">(</span><span class="n">t</span><span class="p">)),</span>
+                    <span class="n">std</span><span class="o">::</span><span class="n">istreambuf_iterator</span><span class="o"><</span><span class="kt">char</span><span class="o">></span><span class="p">());</span>
+
+  <span class="c1">// Create driver context</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuCtxCreate</span><span class="p">(</span><span class="o">&</span><span class="n">context</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">device</span><span class="p">));</span>
+
+  <span class="c1">// Create module for object</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuModuleLoadDataEx</span><span class="p">(</span><span class="o">&</span><span class="n">cudaModule</span><span class="p">,</span> <span class="n">str</span><span class="p">.</span><span class="n">c_str</span><span class="p">(),</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">));</span>
+
+  <span class="c1">// Get kernel function</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuModuleGetFunction</span><span class="p">(</span><span class="o">&</span><span class="n">function</span><span class="p">,</span> <span class="n">cudaModule</span><span class="p">,</span> <span class="s">"kernel"</span><span class="p">));</span>
+
+  <span class="c1">// Device data</span>
+  <span class="n">CUdeviceptr</span> <span class="n">devBufferA</span><span class="p">;</span>
+  <span class="n">CUdeviceptr</span> <span class="n">devBufferB</span><span class="p">;</span>
+  <span class="n">CUdeviceptr</span> <span class="n">devBufferC</span><span class="p">;</span>
+
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemAlloc</span><span class="p">(</span><span class="o">&</span><span class="n">devBufferA</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemAlloc</span><span class="p">(</span><span class="o">&</span><span class="n">devBufferB</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemAlloc</span><span class="p">(</span><span class="o">&</span><span class="n">devBufferC</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+
+  <span class="kt">float</span><span class="o">*</span> <span class="n">hostA</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">float</span><span class="p">[</span><span class="mi">16</span><span class="p">];</span>
+  <span class="kt">float</span><span class="o">*</span> <span class="n">hostB</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">float</span><span class="p">[</span><span class="mi">16</span><span class="p">];</span>
+  <span class="kt">float</span><span class="o">*</span> <span class="n">hostC</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">float</span><span class="p">[</span><span class="mi">16</span><span class="p">];</span>
+
+  <span class="c1">// Populate input</span>
+  <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</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">16</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">hostA</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="n">i</span><span class="p">;</span>
+    <span class="n">hostB</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="kt">float</span><span class="p">)(</span><span class="mi">2</span><span class="o">*</span><span class="n">i</span><span class="p">);</span>
+    <span class="n">hostC</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mf">0.0f</span><span class="p">;</span>
+  <span class="p">}</span>
+
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemcpyHtoD</span><span class="p">(</span><span class="n">devBufferA</span><span class="p">,</span> <span class="o">&</span><span class="n">hostA</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemcpyHtoD</span><span class="p">(</span><span class="n">devBufferB</span><span class="p">,</span> <span class="o">&</span><span class="n">hostB</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+
+
+  <span class="kt">unsigned</span> <span class="n">blockSizeX</span> <span class="o">=</span> <span class="mi">16</span><span class="p">;</span>
+  <span class="kt">unsigned</span> <span class="n">blockSizeY</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+  <span class="kt">unsigned</span> <span class="n">blockSizeZ</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+  <span class="kt">unsigned</span> <span class="n">gridSizeX</span>  <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+  <span class="kt">unsigned</span> <span class="n">gridSizeY</span>  <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+  <span class="kt">unsigned</span> <span class="n">gridSizeZ</span>  <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+
+  <span class="c1">// Kernel parameters</span>
+  <span class="kt">void</span> <span class="o">*</span><span class="n">KernelParams</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="o">&</span><span class="n">devBufferA</span><span class="p">,</span> <span class="o">&</span><span class="n">devBufferB</span><span class="p">,</span> <span class="o">&</span><span class="n">devBufferC</span> <span class="p">};</span>
+
+  <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Launching kernel</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+
+  <span class="c1">// Kernel launch</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuLaunchKernel</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">gridSizeX</span><span class="p">,</span> <span class="n">gridSizeY</span><span class="p">,</span> <span class="n">gridSizeZ</span><span class="p">,</span>
+                                 <span class="n">blockSizeX</span><span class="p">,</span> <span class="n">blockSizeY</span><span class="p">,</span> <span class="n">blockSizeZ</span><span class="p">,</span>
+                                 <span class="mi">0</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> <span class="n">KernelParams</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">));</span>
+
+  <span class="c1">// Retrieve device data</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemcpyDtoH</span><span class="p">(</span><span class="o">&</span><span class="n">hostC</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">devBufferC</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+
+
+  <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Results:</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+  <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</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">16</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">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">hostA</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o"><<</span> <span class="s">" + "</span> <span class="o"><<</span> <span class="n">hostB</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o"><<</span> <span class="s">" = "</span> <span class="o"><<</span> <span class="n">hostC</span><span class="p">[</span><span class="n">i</span><span class="p">]</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>
+
+
+  <span class="c1">// Clean up after ourselves</span>
+  <span class="k">delete</span> <span class="p">[]</span> <span class="n">hostA</span><span class="p">;</span>
+  <span class="k">delete</span> <span class="p">[]</span> <span class="n">hostB</span><span class="p">;</span>
+  <span class="k">delete</span> <span class="p">[]</span> <span class="n">hostC</span><span class="p">;</span>
+
+  <span class="c1">// Clean-up</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemFree</span><span class="p">(</span><span class="n">devBufferA</span><span class="p">));</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemFree</span><span class="p">(</span><span class="n">devBufferB</span><span class="p">));</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemFree</span><span class="p">(</span><span class="n">devBufferC</span><span class="p">));</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuModuleUnload</span><span class="p">(</span><span class="n">cudaModule</span><span class="p">));</span>
+  <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuCtxDestroy</span><span class="p">(</span><span class="n">context</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>You will need to link with the CUDA driver and specify the path to cuda.h.</p>
+<div class="highlight-text"><div class="highlight"><pre># clang++ sample.cpp -o sample -O2 -g -I/usr/local/cuda-5.5/include -lcuda
+</pre></div>
+</div>
+<p>We don’t need to specify a path to <tt class="docutils literal"><span class="pre">libcuda.so</span></tt> since this is installed in a
+system location by the driver, not the CUDA toolkit.</p>
+<p>If everything goes as planned, you should see the following output when
+running the compiled program:</p>
+<div class="highlight-text"><div class="highlight"><pre>Using CUDA Device [0]: GeForce GTX 680
+Device Compute Capability: 3.0
+Launching kernel
+Results:
+0 + 0 = 0
+1 + 2 = 3
+2 + 4 = 6
+3 + 6 = 9
+4 + 8 = 12
+5 + 10 = 15
+6 + 12 = 18
+7 + 14 = 21
+8 + 16 = 24
+9 + 18 = 27
+10 + 20 = 30
+11 + 22 = 33
+12 + 24 = 36
+13 + 26 = 39
+14 + 28 = 42
+15 + 30 = 45
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">You will likely see a different device identifier based on your hardware</p>
+</div>
+</div>
+</div>
+<div class="section" id="tutorial-linking-with-libdevice">
+<h2><a class="toc-backref" href="#id39">Tutorial: Linking with Libdevice</a><a class="headerlink" href="#tutorial-linking-with-libdevice" title="Permalink to this headline">¶</a></h2>
+<p>In this tutorial, we show a simple example of linking LLVM IR with the
+libdevice library. We will use the same kernel as the previous tutorial,
+except that we will compute <tt class="docutils literal"><span class="pre">C</span> <span class="pre">=</span> <span class="pre">pow(A,</span> <span class="pre">B)</span></tt> instead of <tt class="docutils literal"><span class="pre">C</span> <span class="pre">=</span> <span class="pre">A</span> <span class="pre">+</span> <span class="pre">B</span></tt>.
+Libdevice provides an <tt class="docutils literal"><span class="pre">__nv_powf</span></tt> function that we will use.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">target</span> <span class="k">datalayout</span> <span class="p">=</span> <span class="s">"e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"</span>
+<span class="k">target</span> <span class="k">triple</span> <span class="p">=</span> <span class="s">"nvptx64-nvidia-cuda"</span>
+
+<span class="c">; Intrinsic to read X component of thread ID</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span> <span class="k">readnone</span> <span class="k">nounwind</span>
+<span class="c">; libdevice function</span>
+<span class="k">declare</span> <span class="kt">float</span> <span class="vg">@__nv_powf</span><span class="p">(</span><span class="kt">float</span><span class="p">,</span> <span class="kt">float</span><span class="p">)</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@kernel</span><span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%A</span><span class="p">,</span>
+                    <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%B</span><span class="p">,</span>
+                    <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%C</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="c">; What is my ID?</span>
+  <span class="nv">%id</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span> <span class="k">readnone</span> <span class="k">nounwind</span>
+
+  <span class="c">; Compute pointers into A, B, and C</span>
+  <span class="nv">%ptrA</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%A</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+  <span class="nv">%ptrB</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%B</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+  <span class="nv">%ptrC</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%C</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+
+  <span class="c">; Read A, B</span>
+  <span class="nv">%valA</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrA</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+  <span class="nv">%valB</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrB</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+
+  <span class="c">; Compute C = pow(A, B)</span>
+  <span class="nv">%valC</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">float</span> <span class="vg">@__nv_powf</span><span class="p">(</span><span class="kt">float</span> <span class="nv">%valA</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%valB</span><span class="p">)</span>
+
+  <span class="c">; Store back to C</span>
+  <span class="k">store</span> <span class="kt">float</span> <span class="nv">%valC</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrC</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+
+  <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="nv">!nvvm.annotations</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span><span class="kt">void</span> <span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+                      <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+                      <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*)*</span> <span class="vg">@kernel</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"kernel"</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>To compile this kernel, we perform the following steps:</p>
+<ol class="arabic simple">
+<li>Link with libdevice</li>
+<li>Internalize all but the public kernel function</li>
+<li>Run <tt class="docutils literal"><span class="pre">NVVMReflect</span></tt> and set <tt class="docutils literal"><span class="pre">__CUDA_FTZ</span></tt> to 0</li>
+<li>Optimize the linked module</li>
+<li>Codegen the module</li>
+</ol>
+<p>These steps can be performed by the LLVM <tt class="docutils literal"><span class="pre">llvm-link</span></tt>, <tt class="docutils literal"><span class="pre">opt</span></tt>, and <tt class="docutils literal"><span class="pre">llc</span></tt>
+tools. In a complete compiler, these steps can also be performed entirely
+programmatically by setting up an appropriate pass configuration (see
+<a class="reference internal" href="#libdevice"><em>Linking with Libdevice</em></a>).</p>
+<div class="highlight-text"><div class="highlight"><pre># llvm-link t2.bc libdevice.compute_20.10.bc -o t2.linked.bc
+# opt -internalize -internalize-public-api-list=kernel -nvvm-reflect-list=__CUDA_FTZ=0 -nvvm-reflect -O3 t2.linked.bc -o t2.opt.bc
+# llc -mcpu=sm_20 t2.opt.bc -o t2.ptx
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The <tt class="docutils literal"><span class="pre">-nvvm-reflect-list=_CUDA_FTZ=0</span></tt> is not strictly required, as any
+undefined variables will default to zero. It is shown here for evaluation
+purposes.</p>
+</div>
+<p>This gives us the following PTX (excerpt):</p>
+<div class="highlight-text"><div class="highlight"><pre>//
+// Generated by LLVM NVPTX Back-End
+//
+
+.version 3.1
+.target sm_20
+.address_size 64
+
+  // .globl kernel
+                                        // @kernel
+.visible .entry kernel(
+  .param .u64 kernel_param_0,
+  .param .u64 kernel_param_1,
+  .param .u64 kernel_param_2
+)
+{
+  .reg .pred  %p<30>;
+  .reg .f32   %f<111>;
+  .reg .s32   %r<21>;
+  .reg .s64   %rl<8>;
+
+// BB#0:                                // %entry
+  ld.param.u64  %rl2, [kernel_param_0];
+  mov.u32   %r3, %tid.x;
+  ld.param.u64  %rl3, [kernel_param_1];
+  mul.wide.s32  %rl4, %r3, 4;
+  add.s64   %rl5, %rl2, %rl4;
+  ld.param.u64  %rl6, [kernel_param_2];
+  add.s64   %rl7, %rl3, %rl4;
+  add.s64   %rl1, %rl6, %rl4;
+  ld.global.f32   %f1, [%rl5];
+  ld.global.f32   %f2, [%rl7];
+  setp.eq.f32 %p1, %f1, 0f3F800000;
+  setp.eq.f32 %p2, %f2, 0f00000000;
+  or.pred   %p3, %p1, %p2;
+  @%p3 bra  BB0_1;
+  bra.uni   BB0_2;
+BB0_1:
+  mov.f32   %f110, 0f3F800000;
+  st.global.f32   [%rl1], %f110;
+  ret;
+BB0_2:                                  // %__nv_isnanf.exit.i
+  abs.f32   %f4, %f1;
+  setp.gtu.f32  %p4, %f4, 0f7F800000;
+  @%p4 bra  BB0_4;
+// BB#3:                                // %__nv_isnanf.exit5.i
+  abs.f32   %f5, %f2;
+  setp.le.f32 %p5, %f5, 0f7F800000;
+  @%p5 bra  BB0_5;
+BB0_4:                                  // %.critedge1.i
+  add.f32   %f110, %f1, %f2;
+  st.global.f32   [%rl1], %f110;
+  ret;
+BB0_5:                                  // %__nv_isinff.exit.i
+
+  ...
+
+BB0_26:                                 // %__nv_truncf.exit.i.i.i.i.i
+  mul.f32   %f90, %f107, 0f3FB8AA3B;
+  cvt.rzi.f32.f32 %f91, %f90;
+  mov.f32   %f92, 0fBF317200;
+  fma.rn.f32  %f93, %f91, %f92, %f107;
+  mov.f32   %f94, 0fB5BFBE8E;
+  fma.rn.f32  %f95, %f91, %f94, %f93;
+  mul.f32   %f89, %f95, 0f3FB8AA3B;
+  // inline asm
+  ex2.approx.ftz.f32 %f88,%f89;
+  // inline asm
+  add.f32   %f96, %f91, 0f00000000;
+  ex2.approx.f32  %f97, %f96;
+  mul.f32   %f98, %f88, %f97;
+  setp.lt.f32 %p15, %f107, 0fC2D20000;
+  selp.f32  %f99, 0f00000000, %f98, %p15;
+  setp.gt.f32 %p16, %f107, 0f42D20000;
+  selp.f32  %f110, 0f7F800000, %f99, %p16;
+  setp.eq.f32 %p17, %f110, 0f7F800000;
+  @%p17 bra   BB0_28;
+// BB#27:
+  fma.rn.f32  %f110, %f110, %f108, %f110;
+BB0_28:                                 // %__internal_accurate_powf.exit.i
+  setp.lt.f32 %p18, %f1, 0f00000000;
+  setp.eq.f32 %p19, %f3, 0f3F800000;
+  and.pred    %p20, %p18, %p19;
+  @!%p20 bra  BB0_30;
+  bra.uni   BB0_29;
+BB0_29:
+  mov.b32    %r9, %f110;
+  xor.b32   %r10, %r9, -2147483648;
+  mov.b32    %f110, %r10;
+BB0_30:                                 // %__nv_powf.exit
+  st.global.f32   [%rl1], %f110;
+  ret;
+}
+</pre></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="R600Usage.html" title="User Guide for R600 Back-end"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="HowToUseAttributes.html" title="How To Use Attributes"
+             >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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/Packaging.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/Packaging.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/Packaging.html (added)
+++ www-releases/trunk/3.6.0/docs/Packaging.html Fri Feb 27 12:44:09 2015
@@ -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>Advice on Packaging LLVM — LLVM 3.6 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.6',
+        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.6 documentation" href="index.html" />
+    <link rel="next" title="How To Validate a New Release" href="ReleaseProcess.html" />
+    <link rel="prev" title="How To Release LLVM To The Public" href="HowToReleaseLLVM.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="ReleaseProcess.html" title="How To Validate a New Release"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="HowToReleaseLLVM.html" title="How To Release LLVM To The Public"
+             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="advice-on-packaging-llvm">
+<h1>Advice on Packaging LLVM<a class="headerlink" href="#advice-on-packaging-llvm" 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="#compile-flags" id="id2">Compile Flags</a></li>
+<li><a class="reference internal" href="#c-features" id="id3">C++ Features</a></li>
+<li><a class="reference internal" href="#shared-library" id="id4">Shared Library</a></li>
+<li><a class="reference internal" href="#dependencies" id="id5">Dependencies</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>LLVM sets certain default configure options to make sure our developers don’t
+break things for constrained platforms.  These settings are not optimal for most
+desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts,
+etc.) will tweak them.  This document lists settings we suggest you tweak.</p>
+<p>LLVM’s API changes with each release, so users are likely to want, for example,
+both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps developed
+against each.</p>
+</div>
+<div class="section" id="compile-flags">
+<h2><a class="toc-backref" href="#id2">Compile Flags</a><a class="headerlink" href="#compile-flags" title="Permalink to this headline">¶</a></h2>
+<p>LLVM runs much more quickly when it’s optimized and assertions are removed.
+However, such a build is currently incompatible with users who build without
+defining <tt class="docutils literal"><span class="pre">NDEBUG</span></tt>, and the lack of assertions makes it hard to debug problems
+in user code.  We recommend allowing users to install both optimized and debug
+versions of LLVM in parallel.  The following configure flags are relevant:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">--disable-assertions</span></tt></dt>
+<dd>Builds LLVM with <tt class="docutils literal"><span class="pre">NDEBUG</span></tt> defined.  Changes the LLVM ABI.  Also available
+by setting <tt class="docutils literal"><span class="pre">DISABLE_ASSERTIONS=0|1</span></tt> in <tt class="docutils literal"><span class="pre">make</span></tt>‘s environment.  This
+defaults to enabled regardless of the optimization setting, but it slows
+things down.</dd>
+<dt><tt class="docutils literal"><span class="pre">--enable-debug-symbols</span></tt></dt>
+<dd>Builds LLVM with <tt class="docutils literal"><span class="pre">-g</span></tt>.  Also available by setting <tt class="docutils literal"><span class="pre">DEBUG_SYMBOLS=0|1</span></tt> in
+<tt class="docutils literal"><span class="pre">make</span></tt>‘s environment.  This defaults to disabled when optimizing, so you
+should turn it back on to let users debug their programs.</dd>
+<dt><tt class="docutils literal"><span class="pre">--enable-optimized</span></tt></dt>
+<dd>(For svn checkouts) Builds LLVM with <tt class="docutils literal"><span class="pre">-O2</span></tt> and, by default, turns off
+debug symbols.  Also available by setting <tt class="docutils literal"><span class="pre">ENABLE_OPTIMIZED=0|1</span></tt> in
+<tt class="docutils literal"><span class="pre">make</span></tt>‘s environment.  This defaults to enabled when not in a
+checkout.</dd>
+</dl>
+</div>
+<div class="section" id="c-features">
+<h2><a class="toc-backref" href="#id3">C++ Features</a><a class="headerlink" href="#c-features" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt>RTTI</dt>
+<dd>LLVM disables RTTI by default.  Add <tt class="docutils literal"><span class="pre">REQUIRES_RTTI=1</span></tt> to your environment
+while running <tt class="docutils literal"><span class="pre">make</span></tt> to re-enable it.  This will allow users to build with
+RTTI enabled and still inherit from LLVM classes.</dd>
+</dl>
+</div>
+<div class="section" id="shared-library">
+<h2><a class="toc-backref" href="#id4">Shared Library</a><a class="headerlink" href="#shared-library" title="Permalink to this headline">¶</a></h2>
+<p>Configure with <tt class="docutils literal"><span class="pre">--enable-shared</span></tt> to build
+<tt class="docutils literal"><span class="pre">libLLVM-<major>.<minor>.(so|dylib)</span></tt> and link the tools against it.  This
+saves lots of binary size at the cost of some startup time.</p>
+</div>
+<div class="section" id="dependencies">
+<h2><a class="toc-backref" href="#id5">Dependencies</a><a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">--enable-libffi</span></tt></dt>
+<dd>Depend on <a class="reference external" href="http://sources.redhat.com/libffi/">libffi</a> to allow the LLVM
+interpreter to call external functions.</dd>
+</dl>
+<p><tt class="docutils literal"><span class="pre">--with-oprofile</span></tt></p>
+<blockquote>
+<div>Depend on <a class="reference external" href="http://oprofile.sourceforge.net/doc/devel/index.html">libopagent</a> (>=version 0.9.4)
+to let the LLVM JIT tell oprofile about function addresses and line
+numbers.</div></blockquote>
+</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="ReleaseProcess.html" title="How To Validate a New Release"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="HowToReleaseLLVM.html" title="How To Release LLVM To The Public"
+             >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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/Passes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/Passes.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/Passes.html (added)
+++ www-releases/trunk/3.6.0/docs/Passes.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,1190 @@
+
+<!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’s Analysis and Transform Passes — LLVM 3.6 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.6',
+        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.6 documentation" href="index.html" />
+    <link rel="next" title="YAML I/O" href="YamlIO.html" />
+    <link rel="prev" title="LLVM 3.6 Release Notes" href="ReleaseNotes.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="YamlIO.html" title="YAML I/O"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="ReleaseNotes.html" title="LLVM 3.6 Release Notes"
+             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-s-analysis-and-transform-passes">
+<h1>LLVM’s Analysis and Transform Passes<a class="headerlink" href="#llvm-s-analysis-and-transform-passes" 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="id1">Introduction</a></li>
+<li><a class="reference internal" href="#analysis-passes" id="id2">Analysis Passes</a><ul>
+<li><a class="reference internal" href="#aa-eval-exhaustive-alias-analysis-precision-evaluator" id="id3"><tt class="docutils literal"><span class="pre">-aa-eval</span></tt>: Exhaustive Alias Analysis Precision Evaluator</a></li>
+<li><a class="reference internal" href="#basicaa-basic-alias-analysis-stateless-aa-impl" id="id4"><tt class="docutils literal"><span class="pre">-basicaa</span></tt>: Basic Alias Analysis (stateless AA impl)</a></li>
+<li><a class="reference internal" href="#basiccg-basic-callgraph-construction" id="id5"><tt class="docutils literal"><span class="pre">-basiccg</span></tt>: Basic CallGraph Construction</a></li>
+<li><a class="reference internal" href="#count-aa-count-alias-analysis-query-responses" id="id6"><tt class="docutils literal"><span class="pre">-count-aa</span></tt>: Count Alias Analysis Query Responses</a></li>
+<li><a class="reference internal" href="#da-dependence-analysis" id="id7"><tt class="docutils literal"><span class="pre">-da</span></tt>: Dependence Analysis</a></li>
+<li><a class="reference internal" href="#debug-aa-aa-use-debugger" id="id8"><tt class="docutils literal"><span class="pre">-debug-aa</span></tt>: AA use debugger</a></li>
+<li><a class="reference internal" href="#domfrontier-dominance-frontier-construction" id="id9"><tt class="docutils literal"><span class="pre">-domfrontier</span></tt>: Dominance Frontier Construction</a></li>
+<li><a class="reference internal" href="#domtree-dominator-tree-construction" id="id10"><tt class="docutils literal"><span class="pre">-domtree</span></tt>: Dominator Tree Construction</a></li>
+<li><a class="reference internal" href="#dot-callgraph-print-call-graph-to-dot-file" id="id11"><tt class="docutils literal"><span class="pre">-dot-callgraph</span></tt>: Print Call Graph to “dot” file</a></li>
+<li><a class="reference internal" href="#dot-cfg-print-cfg-of-function-to-dot-file" id="id12"><tt class="docutils literal"><span class="pre">-dot-cfg</span></tt>: Print CFG of function to “dot” file</a></li>
+<li><a class="reference internal" href="#dot-cfg-only-print-cfg-of-function-to-dot-file-with-no-function-bodies" id="id13"><tt class="docutils literal"><span class="pre">-dot-cfg-only</span></tt>: Print CFG of function to “dot” file (with no function bodies)</a></li>
+<li><a class="reference internal" href="#dot-dom-print-dominance-tree-of-function-to-dot-file" id="id14"><tt class="docutils literal"><span class="pre">-dot-dom</span></tt>: Print dominance tree of function to “dot” file</a></li>
+<li><a class="reference internal" href="#dot-dom-only-print-dominance-tree-of-function-to-dot-file-with-no-function-bodies" id="id15"><tt class="docutils literal"><span class="pre">-dot-dom-only</span></tt>: Print dominance tree of function to “dot” file (with no function bodies)</a></li>
+<li><a class="reference internal" href="#dot-postdom-print-postdominance-tree-of-function-to-dot-file" id="id16"><tt class="docutils literal"><span class="pre">-dot-postdom</span></tt>: Print postdominance tree of function to “dot” file</a></li>
+<li><a class="reference internal" href="#dot-postdom-only-print-postdominance-tree-of-function-to-dot-file-with-no-function-bodies" id="id17"><tt class="docutils literal"><span class="pre">-dot-postdom-only</span></tt>: Print postdominance tree of function to “dot” file (with no function bodies)</a></li>
+<li><a class="reference internal" href="#globalsmodref-aa-simple-mod-ref-analysis-for-globals" id="id18"><tt class="docutils literal"><span class="pre">-globalsmodref-aa</span></tt>: Simple mod/ref analysis for globals</a></li>
+<li><a class="reference internal" href="#instcount-counts-the-various-types-of-instructions" id="id19"><tt class="docutils literal"><span class="pre">-instcount</span></tt>: Counts the various types of <tt class="docutils literal"><span class="pre">Instruction</span></tt>s</a></li>
+<li><a class="reference internal" href="#intervals-interval-partition-construction" id="id20"><tt class="docutils literal"><span class="pre">-intervals</span></tt>: Interval Partition Construction</a></li>
+<li><a class="reference internal" href="#iv-users-induction-variable-users" id="id21"><tt class="docutils literal"><span class="pre">-iv-users</span></tt>: Induction Variable Users</a></li>
+<li><a class="reference internal" href="#lazy-value-info-lazy-value-information-analysis" id="id22"><tt class="docutils literal"><span class="pre">-lazy-value-info</span></tt>: Lazy Value Information Analysis</a></li>
+<li><a class="reference internal" href="#libcall-aa-libcall-alias-analysis" id="id23"><tt class="docutils literal"><span class="pre">-libcall-aa</span></tt>: LibCall Alias Analysis</a></li>
+<li><a class="reference internal" href="#lint-statically-lint-checks-llvm-ir" id="id24"><tt class="docutils literal"><span class="pre">-lint</span></tt>: Statically lint-checks LLVM IR</a></li>
+<li><a class="reference internal" href="#loops-natural-loop-information" id="id25"><tt class="docutils literal"><span class="pre">-loops</span></tt>: Natural Loop Information</a></li>
+<li><a class="reference internal" href="#memdep-memory-dependence-analysis" id="id26"><tt class="docutils literal"><span class="pre">-memdep</span></tt>: Memory Dependence Analysis</a></li>
+<li><a class="reference internal" href="#module-debuginfo-decodes-module-level-debug-info" id="id27"><tt class="docutils literal"><span class="pre">-module-debuginfo</span></tt>: Decodes module-level debug info</a></li>
+<li><a class="reference internal" href="#no-aa-no-alias-analysis-always-returns-may-alias" id="id28"><tt class="docutils literal"><span class="pre">-no-aa</span></tt>: No Alias Analysis (always returns ‘may’ alias)</a></li>
+<li><a class="reference internal" href="#postdomfrontier-post-dominance-frontier-construction" id="id29"><tt class="docutils literal"><span class="pre">-postdomfrontier</span></tt>: Post-Dominance Frontier Construction</a></li>
+<li><a class="reference internal" href="#postdomtree-post-dominator-tree-construction" id="id30"><tt class="docutils literal"><span class="pre">-postdomtree</span></tt>: Post-Dominator Tree Construction</a></li>
+<li><a class="reference internal" href="#print-alias-sets-alias-set-printer" id="id31"><tt class="docutils literal"><span class="pre">-print-alias-sets</span></tt>: Alias Set Printer</a></li>
+<li><a class="reference internal" href="#print-callgraph-print-a-call-graph" id="id32"><tt class="docutils literal"><span class="pre">-print-callgraph</span></tt>: Print a call graph</a></li>
+<li><a class="reference internal" href="#print-callgraph-sccs-print-sccs-of-the-call-graph" id="id33"><tt class="docutils literal"><span class="pre">-print-callgraph-sccs</span></tt>: Print SCCs of the Call Graph</a></li>
+<li><a class="reference internal" href="#print-cfg-sccs-print-sccs-of-each-function-cfg" id="id34"><tt class="docutils literal"><span class="pre">-print-cfg-sccs</span></tt>: Print SCCs of each function CFG</a></li>
+<li><a class="reference internal" href="#print-dom-info-dominator-info-printer" id="id35"><tt class="docutils literal"><span class="pre">-print-dom-info</span></tt>: Dominator Info Printer</a></li>
+<li><a class="reference internal" href="#print-externalfnconstants-print-external-fn-callsites-passed-constants" id="id36"><tt class="docutils literal"><span class="pre">-print-externalfnconstants</span></tt>: Print external fn callsites passed constants</a></li>
+<li><a class="reference internal" href="#print-function-print-function-to-stderr" id="id37"><tt class="docutils literal"><span class="pre">-print-function</span></tt>: Print function to stderr</a></li>
+<li><a class="reference internal" href="#print-module-print-module-to-stderr" id="id38"><tt class="docutils literal"><span class="pre">-print-module</span></tt>: Print module to stderr</a></li>
+<li><a class="reference internal" href="#print-used-types-find-used-types" id="id39"><tt class="docutils literal"><span class="pre">-print-used-types</span></tt>: Find Used Types</a></li>
+<li><a class="reference internal" href="#regions-detect-single-entry-single-exit-regions" id="id40"><tt class="docutils literal"><span class="pre">-regions</span></tt>: Detect single entry single exit regions</a></li>
+<li><a class="reference internal" href="#scalar-evolution-scalar-evolution-analysis" id="id41"><tt class="docutils literal"><span class="pre">-scalar-evolution</span></tt>: Scalar Evolution Analysis</a></li>
+<li><a class="reference internal" href="#scev-aa-scalarevolution-based-alias-analysis" id="id42"><tt class="docutils literal"><span class="pre">-scev-aa</span></tt>: ScalarEvolution-based Alias Analysis</a></li>
+<li><a class="reference internal" href="#targetdata-target-data-layout" id="id43"><tt class="docutils literal"><span class="pre">-targetdata</span></tt>: Target Data Layout</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#transform-passes" id="id44">Transform Passes</a><ul>
+<li><a class="reference internal" href="#adce-aggressive-dead-code-elimination" id="id45"><tt class="docutils literal"><span class="pre">-adce</span></tt>: Aggressive Dead Code Elimination</a></li>
+<li><a class="reference internal" href="#always-inline-inliner-for-always-inline-functions" id="id46"><tt class="docutils literal"><span class="pre">-always-inline</span></tt>: Inliner for <tt class="docutils literal"><span class="pre">always_inline</span></tt> functions</a></li>
+<li><a class="reference internal" href="#argpromotion-promote-by-reference-arguments-to-scalars" id="id47"><tt class="docutils literal"><span class="pre">-argpromotion</span></tt>: Promote ‘by reference’ arguments to scalars</a></li>
+<li><a class="reference internal" href="#bb-vectorize-basic-block-vectorization" id="id48"><tt class="docutils literal"><span class="pre">-bb-vectorize</span></tt>: Basic-Block Vectorization</a></li>
+<li><a class="reference internal" href="#block-placement-profile-guided-basic-block-placement" id="id49"><tt class="docutils literal"><span class="pre">-block-placement</span></tt>: Profile Guided Basic Block Placement</a></li>
+<li><a class="reference internal" href="#break-crit-edges-break-critical-edges-in-cfg" id="id50"><tt class="docutils literal"><span class="pre">-break-crit-edges</span></tt>: Break critical edges in CFG</a></li>
+<li><a class="reference internal" href="#codegenprepare-optimize-for-code-generation" id="id51"><tt class="docutils literal"><span class="pre">-codegenprepare</span></tt>: Optimize for code generation</a></li>
+<li><a class="reference internal" href="#constmerge-merge-duplicate-global-constants" id="id52"><tt class="docutils literal"><span class="pre">-constmerge</span></tt>: Merge Duplicate Global Constants</a></li>
+<li><a class="reference internal" href="#constprop-simple-constant-propagation" id="id53"><tt class="docutils literal"><span class="pre">-constprop</span></tt>: Simple constant propagation</a></li>
+<li><a class="reference internal" href="#dce-dead-code-elimination" id="id54"><tt class="docutils literal"><span class="pre">-dce</span></tt>: Dead Code Elimination</a></li>
+<li><a class="reference internal" href="#deadargelim-dead-argument-elimination" id="id55"><tt class="docutils literal"><span class="pre">-deadargelim</span></tt>: Dead Argument Elimination</a></li>
+<li><a class="reference internal" href="#deadtypeelim-dead-type-elimination" id="id56"><tt class="docutils literal"><span class="pre">-deadtypeelim</span></tt>: Dead Type Elimination</a></li>
+<li><a class="reference internal" href="#die-dead-instruction-elimination" id="id57"><tt class="docutils literal"><span class="pre">-die</span></tt>: Dead Instruction Elimination</a></li>
+<li><a class="reference internal" href="#dse-dead-store-elimination" id="id58"><tt class="docutils literal"><span class="pre">-dse</span></tt>: Dead Store Elimination</a></li>
+<li><a class="reference internal" href="#functionattrs-deduce-function-attributes" id="id59"><tt class="docutils literal"><span class="pre">-functionattrs</span></tt>: Deduce function attributes</a></li>
+<li><a class="reference internal" href="#globaldce-dead-global-elimination" id="id60"><tt class="docutils literal"><span class="pre">-globaldce</span></tt>: Dead Global Elimination</a></li>
+<li><a class="reference internal" href="#globalopt-global-variable-optimizer" id="id61"><tt class="docutils literal"><span class="pre">-globalopt</span></tt>: Global Variable Optimizer</a></li>
+<li><a class="reference internal" href="#gvn-global-value-numbering" id="id62"><tt class="docutils literal"><span class="pre">-gvn</span></tt>: Global Value Numbering</a></li>
+<li><a class="reference internal" href="#indvars-canonicalize-induction-variables" id="id63"><tt class="docutils literal"><span class="pre">-indvars</span></tt>: Canonicalize Induction Variables</a></li>
+<li><a class="reference internal" href="#inline-function-integration-inlining" id="id64"><tt class="docutils literal"><span class="pre">-inline</span></tt>: Function Integration/Inlining</a></li>
+<li><a class="reference internal" href="#instcombine-combine-redundant-instructions" id="id65"><tt class="docutils literal"><span class="pre">-instcombine</span></tt>: Combine redundant instructions</a></li>
+<li><a class="reference internal" href="#internalize-internalize-global-symbols" id="id66"><tt class="docutils literal"><span class="pre">-internalize</span></tt>: Internalize Global Symbols</a></li>
+<li><a class="reference internal" href="#ipconstprop-interprocedural-constant-propagation" id="id67"><tt class="docutils literal"><span class="pre">-ipconstprop</span></tt>: Interprocedural constant propagation</a></li>
+<li><a class="reference internal" href="#ipsccp-interprocedural-sparse-conditional-constant-propagation" id="id68"><tt class="docutils literal"><span class="pre">-ipsccp</span></tt>: Interprocedural Sparse Conditional Constant Propagation</a></li>
+<li><a class="reference internal" href="#jump-threading-jump-threading" id="id69"><tt class="docutils literal"><span class="pre">-jump-threading</span></tt>: Jump Threading</a></li>
+<li><a class="reference internal" href="#lcssa-loop-closed-ssa-form-pass" id="id70"><tt class="docutils literal"><span class="pre">-lcssa</span></tt>: Loop-Closed SSA Form Pass</a></li>
+<li><a class="reference internal" href="#licm-loop-invariant-code-motion" id="id71"><tt class="docutils literal"><span class="pre">-licm</span></tt>: Loop Invariant Code Motion</a></li>
+<li><a class="reference internal" href="#loop-deletion-delete-dead-loops" id="id72"><tt class="docutils literal"><span class="pre">-loop-deletion</span></tt>: Delete dead loops</a></li>
+<li><a class="reference internal" href="#loop-extract-extract-loops-into-new-functions" id="id73"><tt class="docutils literal"><span class="pre">-loop-extract</span></tt>: Extract loops into new functions</a></li>
+<li><a class="reference internal" href="#loop-extract-single-extract-at-most-one-loop-into-a-new-function" id="id74"><tt class="docutils literal"><span class="pre">-loop-extract-single</span></tt>: Extract at most one loop into a new function</a></li>
+<li><a class="reference internal" href="#loop-reduce-loop-strength-reduction" id="id75"><tt class="docutils literal"><span class="pre">-loop-reduce</span></tt>: Loop Strength Reduction</a></li>
+<li><a class="reference internal" href="#loop-rotate-rotate-loops" id="id76"><tt class="docutils literal"><span class="pre">-loop-rotate</span></tt>: Rotate Loops</a></li>
+<li><a class="reference internal" href="#loop-simplify-canonicalize-natural-loops" id="id77"><tt class="docutils literal"><span class="pre">-loop-simplify</span></tt>: Canonicalize natural loops</a></li>
+<li><a class="reference internal" href="#loop-unroll-unroll-loops" id="id78"><tt class="docutils literal"><span class="pre">-loop-unroll</span></tt>: Unroll loops</a></li>
+<li><a class="reference internal" href="#loop-unswitch-unswitch-loops" id="id79"><tt class="docutils literal"><span class="pre">-loop-unswitch</span></tt>: Unswitch loops</a></li>
+<li><a class="reference internal" href="#loweratomic-lower-atomic-intrinsics-to-non-atomic-form" id="id80"><tt class="docutils literal"><span class="pre">-loweratomic</span></tt>: Lower atomic intrinsics to non-atomic form</a></li>
+<li><a class="reference internal" href="#lowerinvoke-lower-invokes-to-calls-for-unwindless-code-generators" id="id81"><tt class="docutils literal"><span class="pre">-lowerinvoke</span></tt>: Lower invokes to calls, for unwindless code generators</a></li>
+<li><a class="reference internal" href="#lowerswitch-lower-switchinsts-to-branches" id="id82"><tt class="docutils literal"><span class="pre">-lowerswitch</span></tt>: Lower <tt class="docutils literal"><span class="pre">SwitchInst</span></tt>s to branches</a></li>
+<li><a class="reference internal" href="#mem2reg-promote-memory-to-register" id="id83"><tt class="docutils literal"><span class="pre">-mem2reg</span></tt>: Promote Memory to Register</a></li>
+<li><a class="reference internal" href="#memcpyopt-memcpy-optimization" id="id84"><tt class="docutils literal"><span class="pre">-memcpyopt</span></tt>: MemCpy Optimization</a></li>
+<li><a class="reference internal" href="#mergefunc-merge-functions" id="id85"><tt class="docutils literal"><span class="pre">-mergefunc</span></tt>: Merge Functions</a></li>
+<li><a class="reference internal" href="#mergereturn-unify-function-exit-nodes" id="id86"><tt class="docutils literal"><span class="pre">-mergereturn</span></tt>: Unify function exit nodes</a></li>
+<li><a class="reference internal" href="#partial-inliner-partial-inliner" id="id87"><tt class="docutils literal"><span class="pre">-partial-inliner</span></tt>: Partial Inliner</a></li>
+<li><a class="reference internal" href="#prune-eh-remove-unused-exception-handling-info" id="id88"><tt class="docutils literal"><span class="pre">-prune-eh</span></tt>: Remove unused exception handling info</a></li>
+<li><a class="reference internal" href="#reassociate-reassociate-expressions" id="id89"><tt class="docutils literal"><span class="pre">-reassociate</span></tt>: Reassociate expressions</a></li>
+<li><a class="reference internal" href="#reg2mem-demote-all-values-to-stack-slots" id="id90"><tt class="docutils literal"><span class="pre">-reg2mem</span></tt>: Demote all values to stack slots</a></li>
+<li><a class="reference internal" href="#scalarrepl-scalar-replacement-of-aggregates-dt" id="id91"><tt class="docutils literal"><span class="pre">-scalarrepl</span></tt>: Scalar Replacement of Aggregates (DT)</a></li>
+<li><a class="reference internal" href="#sccp-sparse-conditional-constant-propagation" id="id92"><tt class="docutils literal"><span class="pre">-sccp</span></tt>: Sparse Conditional Constant Propagation</a></li>
+<li><a class="reference internal" href="#simplifycfg-simplify-the-cfg" id="id93"><tt class="docutils literal"><span class="pre">-simplifycfg</span></tt>: Simplify the CFG</a></li>
+<li><a class="reference internal" href="#sink-code-sinking" id="id94"><tt class="docutils literal"><span class="pre">-sink</span></tt>: Code sinking</a></li>
+<li><a class="reference internal" href="#strip-strip-all-symbols-from-a-module" id="id95"><tt class="docutils literal"><span class="pre">-strip</span></tt>: Strip all symbols from a module</a></li>
+<li><a class="reference internal" href="#strip-dead-debug-info-strip-debug-info-for-unused-symbols" id="id96"><tt class="docutils literal"><span class="pre">-strip-dead-debug-info</span></tt>: Strip debug info for unused symbols</a></li>
+<li><a class="reference internal" href="#strip-dead-prototypes-strip-unused-function-prototypes" id="id97"><tt class="docutils literal"><span class="pre">-strip-dead-prototypes</span></tt>: Strip Unused Function Prototypes</a></li>
+<li><a class="reference internal" href="#strip-debug-declare-strip-all-llvm-dbg-declare-intrinsics" id="id98"><tt class="docutils literal"><span class="pre">-strip-debug-declare</span></tt>: Strip all <tt class="docutils literal"><span class="pre">llvm.dbg.declare</span></tt> intrinsics</a></li>
+<li><a class="reference internal" href="#strip-nondebug-strip-all-symbols-except-dbg-symbols-from-a-module" id="id99"><tt class="docutils literal"><span class="pre">-strip-nondebug</span></tt>: Strip all symbols, except dbg symbols, from a module</a></li>
+<li><a class="reference internal" href="#tailcallelim-tail-call-elimination" id="id100"><tt class="docutils literal"><span class="pre">-tailcallelim</span></tt>: Tail Call Elimination</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#utility-passes" id="id101">Utility Passes</a><ul>
+<li><a class="reference internal" href="#deadarghax0r-dead-argument-hacking-bugpoint-use-only-do-not-use" id="id102"><tt class="docutils literal"><span class="pre">-deadarghaX0r</span></tt>: Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)</a></li>
+<li><a class="reference internal" href="#extract-blocks-extract-basic-blocks-from-module-for-bugpoint-use" id="id103"><tt class="docutils literal"><span class="pre">-extract-blocks</span></tt>: Extract Basic Blocks From Module (for bugpoint use)</a></li>
+<li><a class="reference internal" href="#instnamer-assign-names-to-anonymous-instructions" id="id104"><tt class="docutils literal"><span class="pre">-instnamer</span></tt>: Assign names to anonymous instructions</a></li>
+<li><a class="reference internal" href="#preverify-preliminary-module-verification" id="id105"><tt class="docutils literal"><span class="pre">-preverify</span></tt>: Preliminary module verification</a></li>
+<li><a class="reference internal" href="#verify-module-verifier" id="id106"><tt class="docutils literal"><span class="pre">-verify</span></tt>: Module Verifier</a></li>
+<li><a class="reference internal" href="#view-cfg-view-cfg-of-function" id="id107"><tt class="docutils literal"><span class="pre">-view-cfg</span></tt>: View CFG of function</a></li>
+<li><a class="reference internal" href="#view-cfg-only-view-cfg-of-function-with-no-function-bodies" id="id108"><tt class="docutils literal"><span class="pre">-view-cfg-only</span></tt>: View CFG of function (with no function bodies)</a></li>
+<li><a class="reference internal" href="#view-dom-view-dominance-tree-of-function" id="id109"><tt class="docutils literal"><span class="pre">-view-dom</span></tt>: View dominance tree of function</a></li>
+<li><a class="reference internal" href="#view-dom-only-view-dominance-tree-of-function-with-no-function-bodies" id="id110"><tt class="docutils literal"><span class="pre">-view-dom-only</span></tt>: View dominance tree of function (with no function bodies)</a></li>
+<li><a class="reference internal" href="#view-postdom-view-postdominance-tree-of-function" id="id111"><tt class="docutils literal"><span class="pre">-view-postdom</span></tt>: View postdominance tree of function</a></li>
+<li><a class="reference internal" href="#view-postdom-only-view-postdominance-tree-of-function-with-no-function-bodies" id="id112"><tt class="docutils literal"><span class="pre">-view-postdom-only</span></tt>: View postdominance tree of function (with no function bodies)</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document serves as a high level summary of the optimization features that
+LLVM provides.  Optimizations are implemented as Passes that traverse some
+portion of a program to either collect information or transform the program.
+The table below divides the passes that LLVM provides into three categories.
+Analysis passes compute information that other passes can use or for debugging
+or program visualization purposes.  Transform passes can use (or invalidate)
+the analysis passes.  Transform passes all mutate the program in some way.
+Utility passes provides some utility but don’t otherwise fit categorization.
+For example passes to extract functions to bitcode or write a module to bitcode
+are neither analysis nor transform passes.  The table of contents above
+provides a quick summary of each pass and links to the more complete pass
+description later in the document.</p>
+</div>
+<div class="section" id="analysis-passes">
+<h2><a class="toc-backref" href="#id2">Analysis Passes</a><a class="headerlink" href="#analysis-passes" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the LLVM Analysis Passes.</p>
+<div class="section" id="aa-eval-exhaustive-alias-analysis-precision-evaluator">
+<h3><a class="toc-backref" href="#id3"><tt class="docutils literal"><span class="pre">-aa-eval</span></tt>: Exhaustive Alias Analysis Precision Evaluator</a><a class="headerlink" href="#aa-eval-exhaustive-alias-analysis-precision-evaluator" title="Permalink to this headline">¶</a></h3>
+<p>This is a simple N^2 alias analysis accuracy evaluator.  Basically, for each
+function in the program, it simply queries to see how the alias analysis
+implementation answers alias queries between each pair of pointers in the
+function.</p>
+<p>This is inspired and adapted from code by: Naveen Neelakantam, Francesco
+Spadini, and Wojciech Stryjewski.</p>
+</div>
+<div class="section" id="basicaa-basic-alias-analysis-stateless-aa-impl">
+<h3><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">-basicaa</span></tt>: Basic Alias Analysis (stateless AA impl)</a><a class="headerlink" href="#basicaa-basic-alias-analysis-stateless-aa-impl" title="Permalink to this headline">¶</a></h3>
+<p>A basic alias analysis pass that implements identities (two different globals
+cannot alias, etc), but does no stateful analysis.</p>
+</div>
+<div class="section" id="basiccg-basic-callgraph-construction">
+<h3><a class="toc-backref" href="#id5"><tt class="docutils literal"><span class="pre">-basiccg</span></tt>: Basic CallGraph Construction</a><a class="headerlink" href="#basiccg-basic-callgraph-construction" title="Permalink to this headline">¶</a></h3>
+<p>Yet to be written.</p>
+</div>
+<div class="section" id="count-aa-count-alias-analysis-query-responses">
+<h3><a class="toc-backref" href="#id6"><tt class="docutils literal"><span class="pre">-count-aa</span></tt>: Count Alias Analysis Query Responses</a><a class="headerlink" href="#count-aa-count-alias-analysis-query-responses" title="Permalink to this headline">¶</a></h3>
+<p>A pass which can be used to count how many alias queries are being made and how
+the alias analysis implementation being used responds.</p>
+</div>
+<div class="section" id="da-dependence-analysis">
+<h3><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre">-da</span></tt>: Dependence Analysis</a><a class="headerlink" href="#da-dependence-analysis" title="Permalink to this headline">¶</a></h3>
+<p>Dependence analysis framework, which is used to detect dependences in memory
+accesses.</p>
+</div>
+<div class="section" id="debug-aa-aa-use-debugger">
+<h3><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">-debug-aa</span></tt>: AA use debugger</a><a class="headerlink" href="#debug-aa-aa-use-debugger" title="Permalink to this headline">¶</a></h3>
+<p>This simple pass checks alias analysis users to ensure that if they create a
+new value, they do not query AA without informing it of the value.  It acts as
+a shim over any other AA pass you want.</p>
+<p>Yes keeping track of every value in the program is expensive, but this is a
+debugging pass.</p>
+</div>
+<div class="section" id="domfrontier-dominance-frontier-construction">
+<h3><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">-domfrontier</span></tt>: Dominance Frontier Construction</a><a class="headerlink" href="#domfrontier-dominance-frontier-construction" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a simple dominator construction algorithm for finding forward
+dominator frontiers.</p>
+</div>
+<div class="section" id="domtree-dominator-tree-construction">
+<h3><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">-domtree</span></tt>: Dominator Tree Construction</a><a class="headerlink" href="#domtree-dominator-tree-construction" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a simple dominator construction algorithm for finding forward
+dominators.</p>
+</div>
+<div class="section" id="dot-callgraph-print-call-graph-to-dot-file">
+<h3><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">-dot-callgraph</span></tt>: Print Call Graph to “dot” file</a><a class="headerlink" href="#dot-callgraph-print-call-graph-to-dot-file" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints the call graph into a <tt class="docutils literal"><span class="pre">.dot</span></tt>
+graph.  This graph can then be processed with the “dot” tool to convert it to
+postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-cfg-print-cfg-of-function-to-dot-file">
+<h3><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">-dot-cfg</span></tt>: Print CFG of function to “dot” file</a><a class="headerlink" href="#dot-cfg-print-cfg-of-function-to-dot-file" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints the control flow graph into a
+<tt class="docutils literal"><span class="pre">.dot</span></tt> graph.  This graph can then be processed with the <strong class="program">dot</strong> tool
+to convert it to postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-cfg-only-print-cfg-of-function-to-dot-file-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">-dot-cfg-only</span></tt>: Print CFG of function to “dot” file (with no function bodies)</a><a class="headerlink" href="#dot-cfg-only-print-cfg-of-function-to-dot-file-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints the control flow graph into a
+<tt class="docutils literal"><span class="pre">.dot</span></tt> graph, omitting the function bodies.  This graph can then be processed
+with the <strong class="program">dot</strong> tool to convert it to postscript or some other suitable
+format.</p>
+</div>
+<div class="section" id="dot-dom-print-dominance-tree-of-function-to-dot-file">
+<h3><a class="toc-backref" href="#id14"><tt class="docutils literal"><span class="pre">-dot-dom</span></tt>: Print dominance tree of function to “dot” file</a><a class="headerlink" href="#dot-dom-print-dominance-tree-of-function-to-dot-file" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints the dominator tree into a <tt class="docutils literal"><span class="pre">.dot</span></tt>
+graph.  This graph can then be processed with the <strong class="program">dot</strong> tool to
+convert it to postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-dom-only-print-dominance-tree-of-function-to-dot-file-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id15"><tt class="docutils literal"><span class="pre">-dot-dom-only</span></tt>: Print dominance tree of function to “dot” file (with no function bodies)</a><a class="headerlink" href="#dot-dom-only-print-dominance-tree-of-function-to-dot-file-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints the dominator tree into a <tt class="docutils literal"><span class="pre">.dot</span></tt>
+graph, omitting the function bodies.  This graph can then be processed with the
+<strong class="program">dot</strong> tool to convert it to postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-postdom-print-postdominance-tree-of-function-to-dot-file">
+<h3><a class="toc-backref" href="#id16"><tt class="docutils literal"><span class="pre">-dot-postdom</span></tt>: Print postdominance tree of function to “dot” file</a><a class="headerlink" href="#dot-postdom-print-postdominance-tree-of-function-to-dot-file" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints the post dominator tree into a
+<tt class="docutils literal"><span class="pre">.dot</span></tt> graph.  This graph can then be processed with the <strong class="program">dot</strong> tool
+to convert it to postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-postdom-only-print-postdominance-tree-of-function-to-dot-file-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id17"><tt class="docutils literal"><span class="pre">-dot-postdom-only</span></tt>: Print postdominance tree of function to “dot” file (with no function bodies)</a><a class="headerlink" href="#dot-postdom-only-print-postdominance-tree-of-function-to-dot-file-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints the post dominator tree into a
+<tt class="docutils literal"><span class="pre">.dot</span></tt> graph, omitting the function bodies.  This graph can then be processed
+with the <strong class="program">dot</strong> tool to convert it to postscript or some other suitable
+format.</p>
+</div>
+<div class="section" id="globalsmodref-aa-simple-mod-ref-analysis-for-globals">
+<h3><a class="toc-backref" href="#id18"><tt class="docutils literal"><span class="pre">-globalsmodref-aa</span></tt>: Simple mod/ref analysis for globals</a><a class="headerlink" href="#globalsmodref-aa-simple-mod-ref-analysis-for-globals" title="Permalink to this headline">¶</a></h3>
+<p>This simple pass provides alias and mod/ref information for global values that
+do not have their address taken, and keeps track of whether functions read or
+write memory (are “pure”).  For this simple (but very common) case, we can
+provide pretty accurate and useful information.</p>
+</div>
+<div class="section" id="instcount-counts-the-various-types-of-instructions">
+<h3><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">-instcount</span></tt>: Counts the various types of <tt class="docutils literal"><span class="pre">Instruction</span></tt>s</a><a class="headerlink" href="#instcount-counts-the-various-types-of-instructions" title="Permalink to this headline">¶</a></h3>
+<p>This pass collects the count of all instructions and reports them.</p>
+</div>
+<div class="section" id="intervals-interval-partition-construction">
+<h3><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">-intervals</span></tt>: Interval Partition Construction</a><a class="headerlink" href="#intervals-interval-partition-construction" title="Permalink to this headline">¶</a></h3>
+<p>This analysis calculates and represents the interval partition of a function,
+or a preexisting interval partition.</p>
+<p>In this way, the interval partition may be used to reduce a flow graph down to
+its degenerate single node interval partition (unless it is irreducible).</p>
+</div>
+<div class="section" id="iv-users-induction-variable-users">
+<h3><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">-iv-users</span></tt>: Induction Variable Users</a><a class="headerlink" href="#iv-users-induction-variable-users" title="Permalink to this headline">¶</a></h3>
+<p>Bookkeeping for “interesting” users of expressions computed from induction
+variables.</p>
+</div>
+<div class="section" id="lazy-value-info-lazy-value-information-analysis">
+<h3><a class="toc-backref" href="#id22"><tt class="docutils literal"><span class="pre">-lazy-value-info</span></tt>: Lazy Value Information Analysis</a><a class="headerlink" href="#lazy-value-info-lazy-value-information-analysis" title="Permalink to this headline">¶</a></h3>
+<p>Interface for lazy computation of value constraint information.</p>
+</div>
+<div class="section" id="libcall-aa-libcall-alias-analysis">
+<h3><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">-libcall-aa</span></tt>: LibCall Alias Analysis</a><a class="headerlink" href="#libcall-aa-libcall-alias-analysis" title="Permalink to this headline">¶</a></h3>
+<p>LibCall Alias Analysis.</p>
+</div>
+<div class="section" id="lint-statically-lint-checks-llvm-ir">
+<h3><a class="toc-backref" href="#id24"><tt class="docutils literal"><span class="pre">-lint</span></tt>: Statically lint-checks LLVM IR</a><a class="headerlink" href="#lint-statically-lint-checks-llvm-ir" title="Permalink to this headline">¶</a></h3>
+<p>This pass statically checks for common and easily-identified constructs which
+produce undefined or likely unintended behavior in LLVM IR.</p>
+<p>It is not a guarantee of correctness, in two ways.  First, it isn’t
+comprehensive.  There are checks which could be done statically which are not
+yet implemented.  Some of these are indicated by TODO comments, but those
+aren’t comprehensive either.  Second, many conditions cannot be checked
+statically.  This pass does no dynamic instrumentation, so it can’t check for
+all possible problems.</p>
+<p>Another limitation is that it assumes all code will be executed.  A store
+through a null pointer in a basic block which is never reached is harmless, but
+this pass will warn about it anyway.</p>
+<p>Optimization passes may make conditions that this pass checks for more or less
+obvious.  If an optimization pass appears to be introducing a warning, it may
+be that the optimization pass is merely exposing an existing condition in the
+code.</p>
+<p>This code may be run before <a class="reference internal" href="#passes-instcombine"><em>instcombine</em></a>.  In many
+cases, instcombine checks for the same kinds of things and turns instructions
+with undefined behavior into unreachable (or equivalent).  Because of this,
+this pass makes some effort to look through bitcasts and so on.</p>
+</div>
+<div class="section" id="loops-natural-loop-information">
+<h3><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">-loops</span></tt>: Natural Loop Information</a><a class="headerlink" href="#loops-natural-loop-information" title="Permalink to this headline">¶</a></h3>
+<p>This analysis is used to identify natural loops and determine the loop depth of
+various nodes of the CFG.  Note that the loops identified may actually be
+several natural loops that share the same header node... not just a single
+natural loop.</p>
+</div>
+<div class="section" id="memdep-memory-dependence-analysis">
+<h3><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">-memdep</span></tt>: Memory Dependence Analysis</a><a class="headerlink" href="#memdep-memory-dependence-analysis" title="Permalink to this headline">¶</a></h3>
+<p>An analysis that determines, for a given memory operation, what preceding
+memory operations it depends on.  It builds on alias analysis information, and
+tries to provide a lazy, caching interface to a common kind of alias
+information query.</p>
+</div>
+<div class="section" id="module-debuginfo-decodes-module-level-debug-info">
+<h3><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">-module-debuginfo</span></tt>: Decodes module-level debug info</a><a class="headerlink" href="#module-debuginfo-decodes-module-level-debug-info" title="Permalink to this headline">¶</a></h3>
+<p>This pass decodes the debug info metadata in a module and prints in a
+(sufficiently-prepared-) human-readable form.</p>
+<p>For example, run this pass from <tt class="docutils literal"><span class="pre">opt</span></tt> along with the <tt class="docutils literal"><span class="pre">-analyze</span></tt> option, and
+it’ll print to standard output.</p>
+</div>
+<div class="section" id="no-aa-no-alias-analysis-always-returns-may-alias">
+<h3><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">-no-aa</span></tt>: No Alias Analysis (always returns ‘may’ alias)</a><a class="headerlink" href="#no-aa-no-alias-analysis-always-returns-may-alias" title="Permalink to this headline">¶</a></h3>
+<p>This is the default implementation of the Alias Analysis interface.  It always
+returns “I don’t know” for alias queries.  NoAA is unlike other alias analysis
+implementations, in that it does not chain to a previous analysis.  As such it
+doesn’t follow many of the rules that other alias analyses must.</p>
+</div>
+<div class="section" id="postdomfrontier-post-dominance-frontier-construction">
+<h3><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">-postdomfrontier</span></tt>: Post-Dominance Frontier Construction</a><a class="headerlink" href="#postdomfrontier-post-dominance-frontier-construction" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a simple post-dominator construction algorithm for finding
+post-dominator frontiers.</p>
+</div>
+<div class="section" id="postdomtree-post-dominator-tree-construction">
+<h3><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">-postdomtree</span></tt>: Post-Dominator Tree Construction</a><a class="headerlink" href="#postdomtree-post-dominator-tree-construction" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a simple post-dominator construction algorithm for finding
+post-dominators.</p>
+</div>
+<div class="section" id="print-alias-sets-alias-set-printer">
+<h3><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">-print-alias-sets</span></tt>: Alias Set Printer</a><a class="headerlink" href="#print-alias-sets-alias-set-printer" title="Permalink to this headline">¶</a></h3>
+<p>Yet to be written.</p>
+</div>
+<div class="section" id="print-callgraph-print-a-call-graph">
+<h3><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">-print-callgraph</span></tt>: Print a call graph</a><a class="headerlink" href="#print-callgraph-print-a-call-graph" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints the call graph to standard error
+in a human-readable form.</p>
+</div>
+<div class="section" id="print-callgraph-sccs-print-sccs-of-the-call-graph">
+<h3><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">-print-callgraph-sccs</span></tt>: Print SCCs of the Call Graph</a><a class="headerlink" href="#print-callgraph-sccs-print-sccs-of-the-call-graph" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints the SCCs of the call graph to
+standard error in a human-readable form.</p>
+</div>
+<div class="section" id="print-cfg-sccs-print-sccs-of-each-function-cfg">
+<h3><a class="toc-backref" href="#id34"><tt class="docutils literal"><span class="pre">-print-cfg-sccs</span></tt>: Print SCCs of each function CFG</a><a class="headerlink" href="#print-cfg-sccs-print-sccs-of-each-function-cfg" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, printsthe SCCs of each function CFG to
+standard error in a human-readable fom.</p>
+</div>
+<div class="section" id="print-dom-info-dominator-info-printer">
+<h3><a class="toc-backref" href="#id35"><tt class="docutils literal"><span class="pre">-print-dom-info</span></tt>: Dominator Info Printer</a><a class="headerlink" href="#print-dom-info-dominator-info-printer" title="Permalink to this headline">¶</a></h3>
+<p>Dominator Info Printer.</p>
+</div>
+<div class="section" id="print-externalfnconstants-print-external-fn-callsites-passed-constants">
+<h3><a class="toc-backref" href="#id36"><tt class="docutils literal"><span class="pre">-print-externalfnconstants</span></tt>: Print external fn callsites passed constants</a><a class="headerlink" href="#print-externalfnconstants-print-external-fn-callsites-passed-constants" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <tt class="docutils literal"><span class="pre">opt</span></tt>, prints out call sites to external
+functions that are called with constant arguments.  This can be useful when
+looking for standard library functions we should constant fold or handle in
+alias analyses.</p>
+</div>
+<div class="section" id="print-function-print-function-to-stderr">
+<h3><a class="toc-backref" href="#id37"><tt class="docutils literal"><span class="pre">-print-function</span></tt>: Print function to stderr</a><a class="headerlink" href="#print-function-print-function-to-stderr" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">PrintFunctionPass</span></tt> class is designed to be pipelined with other
+<tt class="docutils literal"><span class="pre">FunctionPasses</span></tt>, and prints out the functions of the module as they are
+processed.</p>
+</div>
+<div class="section" id="print-module-print-module-to-stderr">
+<h3><a class="toc-backref" href="#id38"><tt class="docutils literal"><span class="pre">-print-module</span></tt>: Print module to stderr</a><a class="headerlink" href="#print-module-print-module-to-stderr" title="Permalink to this headline">¶</a></h3>
+<p>This pass simply prints out the entire module when it is executed.</p>
+</div>
+<div class="section" id="print-used-types-find-used-types">
+<span id="passes-print-used-types"></span><h3><a class="toc-backref" href="#id39"><tt class="docutils literal"><span class="pre">-print-used-types</span></tt>: Find Used Types</a><a class="headerlink" href="#print-used-types-find-used-types" title="Permalink to this headline">¶</a></h3>
+<p>This pass is used to seek out all of the types in use by the program.  Note
+that this analysis explicitly does not include types only used by the symbol
+table.</p>
+</div>
+<div class="section" id="regions-detect-single-entry-single-exit-regions">
+<h3><a class="toc-backref" href="#id40"><tt class="docutils literal"><span class="pre">-regions</span></tt>: Detect single entry single exit regions</a><a class="headerlink" href="#regions-detect-single-entry-single-exit-regions" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">RegionInfo</span></tt> pass detects single entry single exit regions in a function,
+where a region is defined as any subgraph that is connected to the remaining
+graph at only two spots.  Furthermore, an hierarchical region tree is built.</p>
+</div>
+<div class="section" id="scalar-evolution-scalar-evolution-analysis">
+<h3><a class="toc-backref" href="#id41"><tt class="docutils literal"><span class="pre">-scalar-evolution</span></tt>: Scalar Evolution Analysis</a><a class="headerlink" href="#scalar-evolution-scalar-evolution-analysis" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">ScalarEvolution</span></tt> analysis can be used to analyze and catagorize scalar
+expressions in loops.  It specializes in recognizing general induction
+variables, representing them with the abstract and opaque <tt class="docutils literal"><span class="pre">SCEV</span></tt> class.
+Given this analysis, trip counts of loops and other important properties can be
+obtained.</p>
+<p>This analysis is primarily useful for induction variable substitution and
+strength reduction.</p>
+</div>
+<div class="section" id="scev-aa-scalarevolution-based-alias-analysis">
+<h3><a class="toc-backref" href="#id42"><tt class="docutils literal"><span class="pre">-scev-aa</span></tt>: ScalarEvolution-based Alias Analysis</a><a class="headerlink" href="#scev-aa-scalarevolution-based-alias-analysis" title="Permalink to this headline">¶</a></h3>
+<p>Simple alias analysis implemented in terms of <tt class="docutils literal"><span class="pre">ScalarEvolution</span></tt> queries.</p>
+<p>This differs from traditional loop dependence analysis in that it tests for
+dependencies within a single iteration of a loop, rather than dependencies
+between different iterations.</p>
+<p><tt class="docutils literal"><span class="pre">ScalarEvolution</span></tt> has a more complete understanding of pointer arithmetic
+than <tt class="docutils literal"><span class="pre">BasicAliasAnalysis</span></tt>‘ collection of ad-hoc analyses.</p>
+</div>
+<div class="section" id="targetdata-target-data-layout">
+<h3><a class="toc-backref" href="#id43"><tt class="docutils literal"><span class="pre">-targetdata</span></tt>: Target Data Layout</a><a class="headerlink" href="#targetdata-target-data-layout" title="Permalink to this headline">¶</a></h3>
+<p>Provides other passes access to information on how the size and alignment
+required by the target ABI for various data types.</p>
+</div>
+</div>
+<div class="section" id="transform-passes">
+<h2><a class="toc-backref" href="#id44">Transform Passes</a><a class="headerlink" href="#transform-passes" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the LLVM Transform Passes.</p>
+<div class="section" id="adce-aggressive-dead-code-elimination">
+<h3><a class="toc-backref" href="#id45"><tt class="docutils literal"><span class="pre">-adce</span></tt>: Aggressive Dead Code Elimination</a><a class="headerlink" href="#adce-aggressive-dead-code-elimination" title="Permalink to this headline">¶</a></h3>
+<p>ADCE aggressively tries to eliminate code.  This pass is similar to <a class="reference internal" href="#passes-dce"><em>DCE</em></a> but it assumes that values are dead until proven otherwise.  This
+is similar to <a class="reference internal" href="#passes-sccp"><em>SCCP</em></a>, except applied to the liveness of
+values.</p>
+</div>
+<div class="section" id="always-inline-inliner-for-always-inline-functions">
+<h3><a class="toc-backref" href="#id46"><tt class="docutils literal"><span class="pre">-always-inline</span></tt>: Inliner for <tt class="docutils literal"><span class="pre">always_inline</span></tt> functions</a><a class="headerlink" href="#always-inline-inliner-for-always-inline-functions" title="Permalink to this headline">¶</a></h3>
+<p>A custom inliner that handles only functions that are marked as “always
+inline”.</p>
+</div>
+<div class="section" id="argpromotion-promote-by-reference-arguments-to-scalars">
+<h3><a class="toc-backref" href="#id47"><tt class="docutils literal"><span class="pre">-argpromotion</span></tt>: Promote ‘by reference’ arguments to scalars</a><a class="headerlink" href="#argpromotion-promote-by-reference-arguments-to-scalars" title="Permalink to this headline">¶</a></h3>
+<p>This pass promotes “by reference” arguments to be “by value” arguments.  In
+practice, this means looking for internal functions that have pointer
+arguments.  If it can prove, through the use of alias analysis, that an
+argument is <em>only</em> loaded, then it can pass the value into the function instead
+of the address of the value.  This can cause recursive simplification of code
+and lead to the elimination of allocas (especially in C++ template code like
+the STL).</p>
+<p>This pass also handles aggregate arguments that are passed into a function,
+scalarizing them if the elements of the aggregate are only loaded.  Note that
+it refuses to scalarize aggregates which would require passing in more than
+three operands to the function, because passing thousands of operands for a
+large array or structure is unprofitable!</p>
+<p>Note that this transformation could also be done for arguments that are only
+stored to (returning the value instead), but does not currently.  This case
+would be best handled when and if LLVM starts supporting multiple return values
+from functions.</p>
+</div>
+<div class="section" id="bb-vectorize-basic-block-vectorization">
+<h3><a class="toc-backref" href="#id48"><tt class="docutils literal"><span class="pre">-bb-vectorize</span></tt>: Basic-Block Vectorization</a><a class="headerlink" href="#bb-vectorize-basic-block-vectorization" title="Permalink to this headline">¶</a></h3>
+<p>This pass combines instructions inside basic blocks to form vector
+instructions.  It iterates over each basic block, attempting to pair compatible
+instructions, repeating this process until no additional pairs are selected for
+vectorization.  When the outputs of some pair of compatible instructions are
+used as inputs by some other pair of compatible instructions, those pairs are
+part of a potential vectorization chain.  Instruction pairs are only fused into
+vector instructions when they are part of a chain longer than some threshold
+length.  Moreover, the pass attempts to find the best possible chain for each
+pair of compatible instructions.  These heuristics are intended to prevent
+vectorization in cases where it would not yield a performance increase of the
+resulting code.</p>
+</div>
+<div class="section" id="block-placement-profile-guided-basic-block-placement">
+<h3><a class="toc-backref" href="#id49"><tt class="docutils literal"><span class="pre">-block-placement</span></tt>: Profile Guided Basic Block Placement</a><a class="headerlink" href="#block-placement-profile-guided-basic-block-placement" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a very simple profile guided basic block placement algorithm.  The
+idea is to put frequently executed blocks together at the start of the function
+and hopefully increase the number of fall-through conditional branches.  If
+there is no profile information for a particular function, this pass basically
+orders blocks in depth-first order.</p>
+</div>
+<div class="section" id="break-crit-edges-break-critical-edges-in-cfg">
+<h3><a class="toc-backref" href="#id50"><tt class="docutils literal"><span class="pre">-break-crit-edges</span></tt>: Break critical edges in CFG</a><a class="headerlink" href="#break-crit-edges-break-critical-edges-in-cfg" title="Permalink to this headline">¶</a></h3>
+<p>Break all of the critical edges in the CFG by inserting a dummy basic block.
+It may be “required” by passes that cannot deal with critical edges.  This
+transformation obviously invalidates the CFG, but can update forward dominator
+(set, immediate dominators, tree, and frontier) information.</p>
+</div>
+<div class="section" id="codegenprepare-optimize-for-code-generation">
+<h3><a class="toc-backref" href="#id51"><tt class="docutils literal"><span class="pre">-codegenprepare</span></tt>: Optimize for code generation</a><a class="headerlink" href="#codegenprepare-optimize-for-code-generation" title="Permalink to this headline">¶</a></h3>
+<p>This pass munges the code in the input function to better prepare it for
+SelectionDAG-based code generation.  This works around limitations in its
+basic-block-at-a-time approach.  It should eventually be removed.</p>
+</div>
+<div class="section" id="constmerge-merge-duplicate-global-constants">
+<h3><a class="toc-backref" href="#id52"><tt class="docutils literal"><span class="pre">-constmerge</span></tt>: Merge Duplicate Global Constants</a><a class="headerlink" href="#constmerge-merge-duplicate-global-constants" title="Permalink to this headline">¶</a></h3>
+<p>Merges duplicate global constants together into a single constant that is
+shared.  This is useful because some passes (i.e., TraceValues) insert a lot of
+string constants into the program, regardless of whether or not an existing
+string is available.</p>
+</div>
+<div class="section" id="constprop-simple-constant-propagation">
+<h3><a class="toc-backref" href="#id53"><tt class="docutils literal"><span class="pre">-constprop</span></tt>: Simple constant propagation</a><a class="headerlink" href="#constprop-simple-constant-propagation" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements constant propagation and merging.  It looks for
+instructions involving only constant operands and replaces them with a constant
+value instead of an instruction.  For example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><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>becomes</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i32</span> <span class="m">3</span>
+</pre></div>
+</div>
+<p>NOTE: this pass has a habit of making definitions be dead.  It is a good idea
+to run a <a class="reference internal" href="#passes-die"><em>Dead Instruction Elimination</em></a> pass sometime after
+running this pass.</p>
+</div>
+<div class="section" id="dce-dead-code-elimination">
+<span id="passes-dce"></span><h3><a class="toc-backref" href="#id54"><tt class="docutils literal"><span class="pre">-dce</span></tt>: Dead Code Elimination</a><a class="headerlink" href="#dce-dead-code-elimination" title="Permalink to this headline">¶</a></h3>
+<p>Dead code elimination is similar to <a class="reference internal" href="#passes-die"><em>dead instruction elimination</em></a>, but it rechecks instructions that were used by removed
+instructions to see if they are newly dead.</p>
+</div>
+<div class="section" id="deadargelim-dead-argument-elimination">
+<h3><a class="toc-backref" href="#id55"><tt class="docutils literal"><span class="pre">-deadargelim</span></tt>: Dead Argument Elimination</a><a class="headerlink" href="#deadargelim-dead-argument-elimination" title="Permalink to this headline">¶</a></h3>
+<p>This pass deletes dead arguments from internal functions.  Dead argument
+elimination removes arguments which are directly dead, as well as arguments
+only passed into function calls as dead arguments of other functions.  This
+pass also deletes dead arguments in a similar way.</p>
+<p>This pass is often useful as a cleanup pass to run after aggressive
+interprocedural passes, which add possibly-dead arguments.</p>
+</div>
+<div class="section" id="deadtypeelim-dead-type-elimination">
+<h3><a class="toc-backref" href="#id56"><tt class="docutils literal"><span class="pre">-deadtypeelim</span></tt>: Dead Type Elimination</a><a class="headerlink" href="#deadtypeelim-dead-type-elimination" title="Permalink to this headline">¶</a></h3>
+<p>This pass is used to cleanup the output of GCC.  It eliminate names for types
+that are unused in the entire translation unit, using the <a class="reference internal" href="#passes-print-used-types"><em>find used types</em></a> pass.</p>
+</div>
+<div class="section" id="die-dead-instruction-elimination">
+<span id="passes-die"></span><h3><a class="toc-backref" href="#id57"><tt class="docutils literal"><span class="pre">-die</span></tt>: Dead Instruction Elimination</a><a class="headerlink" href="#die-dead-instruction-elimination" title="Permalink to this headline">¶</a></h3>
+<p>Dead instruction elimination performs a single pass over the function, removing
+instructions that are obviously dead.</p>
+</div>
+<div class="section" id="dse-dead-store-elimination">
+<h3><a class="toc-backref" href="#id58"><tt class="docutils literal"><span class="pre">-dse</span></tt>: Dead Store Elimination</a><a class="headerlink" href="#dse-dead-store-elimination" title="Permalink to this headline">¶</a></h3>
+<p>A trivial dead store elimination that only considers basic-block local
+redundant stores.</p>
+</div>
+<div class="section" id="functionattrs-deduce-function-attributes">
+<span id="passes-functionattrs"></span><h3><a class="toc-backref" href="#id59"><tt class="docutils literal"><span class="pre">-functionattrs</span></tt>: Deduce function attributes</a><a class="headerlink" href="#functionattrs-deduce-function-attributes" title="Permalink to this headline">¶</a></h3>
+<p>A simple interprocedural pass which walks the call-graph, looking for functions
+which do not access or only read non-local memory, and marking them
+<tt class="docutils literal"><span class="pre">readnone</span></tt>/<tt class="docutils literal"><span class="pre">readonly</span></tt>.  In addition, it marks function arguments (of
+pointer type) “<tt class="docutils literal"><span class="pre">nocapture</span></tt>” if a call to the function does not create any
+copies of the pointer value that outlive the call.  This more or less means
+that the pointer is only dereferenced, and not returned from the function or
+stored in a global.  This pass is implemented as a bottom-up traversal of the
+call-graph.</p>
+</div>
+<div class="section" id="globaldce-dead-global-elimination">
+<h3><a class="toc-backref" href="#id60"><tt class="docutils literal"><span class="pre">-globaldce</span></tt>: Dead Global Elimination</a><a class="headerlink" href="#globaldce-dead-global-elimination" title="Permalink to this headline">¶</a></h3>
+<p>This transform is designed to eliminate unreachable internal globals from the
+program.  It uses an aggressive algorithm, searching out globals that are known
+to be alive.  After it finds all of the globals which are needed, it deletes
+whatever is left over.  This allows it to delete recursive chunks of the
+program which are unreachable.</p>
+</div>
+<div class="section" id="globalopt-global-variable-optimizer">
+<h3><a class="toc-backref" href="#id61"><tt class="docutils literal"><span class="pre">-globalopt</span></tt>: Global Variable Optimizer</a><a class="headerlink" href="#globalopt-global-variable-optimizer" title="Permalink to this headline">¶</a></h3>
+<p>This pass transforms simple global variables that never have their address
+taken.  If obviously true, it marks read/write globals as constant, deletes
+variables only stored to, etc.</p>
+</div>
+<div class="section" id="gvn-global-value-numbering">
+<h3><a class="toc-backref" href="#id62"><tt class="docutils literal"><span class="pre">-gvn</span></tt>: Global Value Numbering</a><a class="headerlink" href="#gvn-global-value-numbering" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs global value numbering to eliminate fully and partially
+redundant instructions.  It also performs redundant load elimination.</p>
+</div>
+<div class="section" id="indvars-canonicalize-induction-variables">
+<span id="passes-indvars"></span><h3><a class="toc-backref" href="#id63"><tt class="docutils literal"><span class="pre">-indvars</span></tt>: Canonicalize Induction Variables</a><a class="headerlink" href="#indvars-canonicalize-induction-variables" title="Permalink to this headline">¶</a></h3>
+<p>This transformation analyzes and transforms the induction variables (and
+computations derived from them) into simpler forms suitable for subsequent
+analysis and transformation.</p>
+<p>This transformation makes the following changes to each loop with an
+identifiable induction variable:</p>
+<ul class="simple">
+<li>All loops are transformed to have a <em>single</em> canonical induction variable
+which starts at zero and steps by one.</li>
+<li>The canonical induction variable is guaranteed to be the first PHI node in
+the loop header block.</li>
+<li>Any pointer arithmetic recurrences are raised to use array subscripts.</li>
+</ul>
+<p>If the trip count of a loop is computable, this pass also makes the following
+changes:</p>
+<ul>
+<li><p class="first">The exit condition for the loop is canonicalized to compare the induction
+value against the exit value.  This turns loops like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</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="n">i</span><span class="o">*</span><span class="n">i</span> <span class="o"><</span> <span class="mi">1000</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+
+<span class="n">into</span>
+</pre></div>
+</div>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</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="n">i</span> <span class="o">!=</span> <span class="mi">25</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Any use outside of the loop of an expression derived from the indvar is
+changed to compute the derived value outside of the loop, eliminating the
+dependence on the exit value of the induction variable.  If the only purpose
+of the loop is to compute the exit value of some derived expression, this
+transformation will make the loop dead.</p>
+</li>
+</ul>
+<p>This transformation should be followed by strength reduction after all of the
+desired loop transformations have been performed.  Additionally, on targets
+where it is profitable, the loop could be transformed to count down to zero
+(the “do loop” optimization).</p>
+</div>
+<div class="section" id="inline-function-integration-inlining">
+<h3><a class="toc-backref" href="#id64"><tt class="docutils literal"><span class="pre">-inline</span></tt>: Function Integration/Inlining</a><a class="headerlink" href="#inline-function-integration-inlining" title="Permalink to this headline">¶</a></h3>
+<p>Bottom-up inlining of functions into callees.</p>
+</div>
+<div class="section" id="instcombine-combine-redundant-instructions">
+<span id="passes-instcombine"></span><h3><a class="toc-backref" href="#id65"><tt class="docutils literal"><span class="pre">-instcombine</span></tt>: Combine redundant instructions</a><a class="headerlink" href="#instcombine-combine-redundant-instructions" title="Permalink to this headline">¶</a></h3>
+<p>Combine instructions to form fewer, simple instructions.  This pass does not
+modify the CFG. This pass is where algebraic simplification happens.</p>
+<p>This pass combines things like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%Y</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%X</span><span class="p">,</span> <span class="m">1</span>
+<span class="nv">%Z</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%Y</span><span class="p">,</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>into:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%Z</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%X</span><span class="p">,</span> <span class="m">2</span>
+</pre></div>
+</div>
+<p>This is a simple worklist driven algorithm.</p>
+<p>This pass guarantees that the following canonicalizations are performed on the
+program:</p>
+<ol class="arabic simple">
+<li>If a binary operator has a constant operand, it is moved to the right-hand
+side.</li>
+<li>Bitwise operators with constant operands are always grouped so that shifts
+are performed first, then <tt class="docutils literal"><span class="pre">or</span></tt>s, then <tt class="docutils literal"><span class="pre">and</span></tt>s, then <tt class="docutils literal"><span class="pre">xor</span></tt>s.</li>
+<li>Compare instructions are converted from <tt class="docutils literal"><span class="pre"><</span></tt>, <tt class="docutils literal"><span class="pre">></span></tt>, <tt class="docutils literal"><span class="pre">≤</span></tt>, or <tt class="docutils literal"><span class="pre">≥</span></tt> to
+<tt class="docutils literal"><span class="pre">=</span></tt> or <tt class="docutils literal"><span class="pre">≠</span></tt> if possible.</li>
+<li>All <tt class="docutils literal"><span class="pre">cmp</span></tt> instructions on boolean values are replaced with logical
+operations.</li>
+<li><tt class="docutils literal"><span class="pre">add</span> <span class="pre">X,</span> <span class="pre">X</span></tt> is represented as <tt class="docutils literal"><span class="pre">mul</span> <span class="pre">X,</span> <span class="pre">2</span></tt> ⇒ <tt class="docutils literal"><span class="pre">shl</span> <span class="pre">X,</span> <span class="pre">1</span></tt></li>
+<li>Multiplies with a constant power-of-two argument are transformed into
+shifts.</li>
+<li>… etc.</li>
+</ol>
+<p>This pass can also simplify calls to specific well-known function calls (e.g.
+runtime library functions).  For example, a call <tt class="docutils literal"><span class="pre">exit(3)</span></tt> that occurs within
+the <tt class="docutils literal"><span class="pre">main()</span></tt> function can be transformed into simply <tt class="docutils literal"><span class="pre">return</span> <span class="pre">3</span></tt>. Whether or
+not library calls are simplified is controlled by the
+<a class="reference internal" href="#passes-functionattrs"><em>-functionattrs</em></a> pass and LLVM’s knowledge of
+library calls on different targets.</p>
+</div>
+<div class="section" id="internalize-internalize-global-symbols">
+<h3><a class="toc-backref" href="#id66"><tt class="docutils literal"><span class="pre">-internalize</span></tt>: Internalize Global Symbols</a><a class="headerlink" href="#internalize-internalize-global-symbols" title="Permalink to this headline">¶</a></h3>
+<p>This pass loops over all of the functions in the input module, looking for a
+main function.  If a main function is found, all other functions and all global
+variables with initializers are marked as internal.</p>
+</div>
+<div class="section" id="ipconstprop-interprocedural-constant-propagation">
+<h3><a class="toc-backref" href="#id67"><tt class="docutils literal"><span class="pre">-ipconstprop</span></tt>: Interprocedural constant propagation</a><a class="headerlink" href="#ipconstprop-interprocedural-constant-propagation" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements an <em>extremely</em> simple interprocedural constant propagation
+pass.  It could certainly be improved in many different ways, like using a
+worklist.  This pass makes arguments dead, but does not remove them.  The
+existing dead argument elimination pass should be run after this to clean up
+the mess.</p>
+</div>
+<div class="section" id="ipsccp-interprocedural-sparse-conditional-constant-propagation">
+<h3><a class="toc-backref" href="#id68"><tt class="docutils literal"><span class="pre">-ipsccp</span></tt>: Interprocedural Sparse Conditional Constant Propagation</a><a class="headerlink" href="#ipsccp-interprocedural-sparse-conditional-constant-propagation" title="Permalink to this headline">¶</a></h3>
+<p>An interprocedural variant of <a class="reference internal" href="#passes-sccp"><em>Sparse Conditional Constant Propagation</em></a>.</p>
+</div>
+<div class="section" id="jump-threading-jump-threading">
+<h3><a class="toc-backref" href="#id69"><tt class="docutils literal"><span class="pre">-jump-threading</span></tt>: Jump Threading</a><a class="headerlink" href="#jump-threading-jump-threading" title="Permalink to this headline">¶</a></h3>
+<p>Jump threading tries to find distinct threads of control flow running through a
+basic block.  This pass looks at blocks that have multiple predecessors and
+multiple successors.  If one or more of the predecessors of the block can be
+proven to always cause a jump to one of the successors, we forward the edge
+from the predecessor to the successor by duplicating the contents of this
+block.</p>
+<p>An example of when this can occur is code like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">()</span> <span class="p">{</span> <span class="p">...</span>
+  <span class="n">X</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">X</span> <span class="o"><</span> <span class="mi">3</span><span class="p">)</span> <span class="p">{</span>
+</pre></div>
+</div>
+<p>In this case, the unconditional branch at the end of the first if can be
+revectored to the false side of the second if.</p>
+</div>
+<div class="section" id="lcssa-loop-closed-ssa-form-pass">
+<h3><a class="toc-backref" href="#id70"><tt class="docutils literal"><span class="pre">-lcssa</span></tt>: Loop-Closed SSA Form Pass</a><a class="headerlink" href="#lcssa-loop-closed-ssa-form-pass" title="Permalink to this headline">¶</a></h3>
+<p>This pass transforms loops by placing phi nodes at the end of the loops for all
+values that are live across the loop boundary.  For example, it turns the left
+into the right code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(...)</span>                <span class="k">for</span> <span class="p">(...)</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">c</span><span class="p">)</span>                   <span class="k">if</span> <span class="p">(</span><span class="n">c</span><span class="p">)</span>
+        <span class="n">X1</span> <span class="o">=</span> <span class="p">...</span>                 <span class="n">X1</span> <span class="o">=</span> <span class="p">...</span>
+    <span class="k">else</span>                     <span class="k">else</span>
+        <span class="n">X2</span> <span class="o">=</span> <span class="p">...</span>                 <span class="n">X2</span> <span class="o">=</span> <span class="p">...</span>
+    <span class="n">X3</span> <span class="o">=</span> <span class="n">phi</span><span class="p">(</span><span class="n">X1</span><span class="p">,</span> <span class="n">X2</span><span class="p">)</span>         <span class="n">X3</span> <span class="o">=</span> <span class="n">phi</span><span class="p">(</span><span class="n">X1</span><span class="p">,</span> <span class="n">X2</span><span class="p">)</span>
+<span class="p">...</span> <span class="o">=</span> <span class="n">X3</span> <span class="o">+</span> <span class="mi">4</span>              <span class="n">X4</span> <span class="o">=</span> <span class="n">phi</span><span class="p">(</span><span class="n">X3</span><span class="p">)</span>
+                            <span class="p">...</span> <span class="o">=</span> <span class="n">X4</span> <span class="o">+</span> <span class="mi">4</span>
+</pre></div>
+</div>
+<p>This is still valid LLVM; the extra phi nodes are purely redundant, and will be
+trivially eliminated by <tt class="docutils literal"><span class="pre">InstCombine</span></tt>.  The major benefit of this
+transformation is that it makes many other loop optimizations, such as
+<tt class="docutils literal"><span class="pre">LoopUnswitch</span></tt>ing, simpler.</p>
+</div>
+<div class="section" id="licm-loop-invariant-code-motion">
+<span id="passes-licm"></span><h3><a class="toc-backref" href="#id71"><tt class="docutils literal"><span class="pre">-licm</span></tt>: Loop Invariant Code Motion</a><a class="headerlink" href="#licm-loop-invariant-code-motion" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs loop invariant code motion, attempting to remove as much
+code from the body of a loop as possible.  It does this by either hoisting code
+into the preheader block, or by sinking code to the exit blocks if it is safe.
+This pass also promotes must-aliased memory locations in the loop to live in
+registers, thus hoisting and sinking “invariant” loads and stores.</p>
+<p>This pass uses alias analysis for two purposes:</p>
+<ol class="arabic">
+<li><p class="first">Moving loop invariant loads and calls out of loops.  If we can determine
+that a load or call inside of a loop never aliases anything stored to, we
+can hoist it or sink it like any other instruction.</p>
+</li>
+<li><p class="first">Scalar Promotion of Memory.  If there is a store instruction inside of the
+loop, we try to move the store to happen AFTER the loop instead of inside of
+the loop.  This can only happen if a few conditions are true:</p>
+<ol class="arabic simple">
+<li>The pointer stored through is loop invariant.</li>
+<li>There are no stores or loads in the loop which <em>may</em> alias the pointer.
+There are no calls in the loop which mod/ref the pointer.</li>
+</ol>
+<p>If these conditions are true, we can promote the loads and stores in the
+loop of the pointer to use a temporary alloca’d variable.  We then use the
+<a class="reference internal" href="#passes-mem2reg"><em>mem2reg</em></a> functionality to construct the appropriate
+SSA form for the variable.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="loop-deletion-delete-dead-loops">
+<h3><a class="toc-backref" href="#id72"><tt class="docutils literal"><span class="pre">-loop-deletion</span></tt>: Delete dead loops</a><a class="headerlink" href="#loop-deletion-delete-dead-loops" title="Permalink to this headline">¶</a></h3>
+<p>This file implements the Dead Loop Deletion Pass.  This pass is responsible for
+eliminating loops with non-infinite computable trip counts that have no side
+effects or volatile instructions, and do not contribute to the computation of
+the function’s return value.</p>
+</div>
+<div class="section" id="loop-extract-extract-loops-into-new-functions">
+<span id="passes-loop-extract"></span><h3><a class="toc-backref" href="#id73"><tt class="docutils literal"><span class="pre">-loop-extract</span></tt>: Extract loops into new functions</a><a class="headerlink" href="#loop-extract-extract-loops-into-new-functions" title="Permalink to this headline">¶</a></h3>
+<p>A pass wrapper around the <tt class="docutils literal"><span class="pre">ExtractLoop()</span></tt> scalar transformation to extract
+each top-level loop into its own new function.  If the loop is the <em>only</em> loop
+in a given function, it is not touched.  This is a pass most useful for
+debugging via bugpoint.</p>
+</div>
+<div class="section" id="loop-extract-single-extract-at-most-one-loop-into-a-new-function">
+<h3><a class="toc-backref" href="#id74"><tt class="docutils literal"><span class="pre">-loop-extract-single</span></tt>: Extract at most one loop into a new function</a><a class="headerlink" href="#loop-extract-single-extract-at-most-one-loop-into-a-new-function" title="Permalink to this headline">¶</a></h3>
+<p>Similar to <a class="reference internal" href="#passes-loop-extract"><em>Extract loops into new functions</em></a>, this
+pass extracts one natural loop from the program into a function if it can.
+This is used by <strong class="program">bugpoint</strong>.</p>
+</div>
+<div class="section" id="loop-reduce-loop-strength-reduction">
+<h3><a class="toc-backref" href="#id75"><tt class="docutils literal"><span class="pre">-loop-reduce</span></tt>: Loop Strength Reduction</a><a class="headerlink" href="#loop-reduce-loop-strength-reduction" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs a strength reduction on array references inside loops that
+have as one or more of their components the loop induction variable.  This is
+accomplished by creating a new value to hold the initial value of the array
+access for the first iteration, and then creating a new GEP instruction in the
+loop to increment the value by the appropriate amount.</p>
+</div>
+<div class="section" id="loop-rotate-rotate-loops">
+<h3><a class="toc-backref" href="#id76"><tt class="docutils literal"><span class="pre">-loop-rotate</span></tt>: Rotate Loops</a><a class="headerlink" href="#loop-rotate-rotate-loops" title="Permalink to this headline">¶</a></h3>
+<p>A simple loop rotation transformation.</p>
+</div>
+<div class="section" id="loop-simplify-canonicalize-natural-loops">
+<h3><a class="toc-backref" href="#id77"><tt class="docutils literal"><span class="pre">-loop-simplify</span></tt>: Canonicalize natural loops</a><a class="headerlink" href="#loop-simplify-canonicalize-natural-loops" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs several transformations to transform natural loops into a
+simpler form, which makes subsequent analyses and transformations simpler and
+more effective.</p>
+<p>Loop pre-header insertion guarantees that there is a single, non-critical entry
+edge from outside of the loop to the loop header.  This simplifies a number of
+analyses and transformations, such as <a class="reference internal" href="#passes-licm"><em>LICM</em></a>.</p>
+<p>Loop exit-block insertion guarantees that all exit blocks from the loop (blocks
+which are outside of the loop that have predecessors inside of the loop) only
+have predecessors from inside of the loop (and are thus dominated by the loop
+header).  This simplifies transformations such as store-sinking that are built
+into LICM.</p>
+<p>This pass also guarantees that loops will have exactly one backedge.</p>
+<p>Note that the <a class="reference internal" href="#passes-simplifycfg"><em>simplifycfg</em></a> pass will clean up blocks
+which are split out but end up being unnecessary, so usage of this pass should
+not pessimize generated code.</p>
+<p>This pass obviously modifies the CFG, but updates loop information and
+dominator information.</p>
+</div>
+<div class="section" id="loop-unroll-unroll-loops">
+<h3><a class="toc-backref" href="#id78"><tt class="docutils literal"><span class="pre">-loop-unroll</span></tt>: Unroll loops</a><a class="headerlink" href="#loop-unroll-unroll-loops" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements a simple loop unroller.  It works best when loops have
+been canonicalized by the <a class="reference internal" href="#passes-indvars"><em>indvars</em></a> pass, allowing it to
+determine the trip counts of loops easily.</p>
+</div>
+<div class="section" id="loop-unswitch-unswitch-loops">
+<h3><a class="toc-backref" href="#id79"><tt class="docutils literal"><span class="pre">-loop-unswitch</span></tt>: Unswitch loops</a><a class="headerlink" href="#loop-unswitch-unswitch-loops" title="Permalink to this headline">¶</a></h3>
+<p>This pass transforms loops that contain branches on loop-invariant conditions
+to have multiple loops.  For example, it turns the left into the right code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(...)</span>                  <span class="k">if</span> <span class="p">(</span><span class="n">lic</span><span class="p">)</span>
+    <span class="n">A</span>                          <span class="k">for</span> <span class="p">(...)</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">lic</span><span class="p">)</span>                       <span class="n">A</span><span class="p">;</span> <span class="n">B</span><span class="p">;</span> <span class="n">C</span>
+        <span class="n">B</span>                  <span class="k">else</span>
+    <span class="n">C</span>                          <span class="k">for</span> <span class="p">(...)</span>
+                                   <span class="n">A</span><span class="p">;</span> <span class="n">C</span>
+</pre></div>
+</div>
+<p>This can increase the size of the code exponentially (doubling it every time a
+loop is unswitched) so we only unswitch if the resultant code will be smaller
+than a threshold.</p>
+<p>This pass expects <a class="reference internal" href="#passes-licm"><em>LICM</em></a> to be run before it to hoist
+invariant conditions out of the loop, to make the unswitching opportunity
+obvious.</p>
+</div>
+<div class="section" id="loweratomic-lower-atomic-intrinsics-to-non-atomic-form">
+<h3><a class="toc-backref" href="#id80"><tt class="docutils literal"><span class="pre">-loweratomic</span></tt>: Lower atomic intrinsics to non-atomic form</a><a class="headerlink" href="#loweratomic-lower-atomic-intrinsics-to-non-atomic-form" title="Permalink to this headline">¶</a></h3>
+<p>This pass lowers atomic intrinsics to non-atomic form for use in a known
+non-preemptible environment.</p>
+<p>The pass does not verify that the environment is non-preemptible (in general
+this would require knowledge of the entire call graph of the program including
+any libraries which may not be available in bitcode form); it simply lowers
+every atomic intrinsic.</p>
+</div>
+<div class="section" id="lowerinvoke-lower-invokes-to-calls-for-unwindless-code-generators">
+<h3><a class="toc-backref" href="#id81"><tt class="docutils literal"><span class="pre">-lowerinvoke</span></tt>: Lower invokes to calls, for unwindless code generators</a><a class="headerlink" href="#lowerinvoke-lower-invokes-to-calls-for-unwindless-code-generators" title="Permalink to this headline">¶</a></h3>
+<p>This transformation is designed for use by code generators which do not yet
+support stack unwinding.  This pass converts <tt class="docutils literal"><span class="pre">invoke</span></tt> instructions to
+<tt class="docutils literal"><span class="pre">call</span></tt> instructions, so that any exception-handling <tt class="docutils literal"><span class="pre">landingpad</span></tt> blocks
+become dead code (which can be removed by running the <tt class="docutils literal"><span class="pre">-simplifycfg</span></tt> pass
+afterwards).</p>
+</div>
+<div class="section" id="lowerswitch-lower-switchinsts-to-branches">
+<h3><a class="toc-backref" href="#id82"><tt class="docutils literal"><span class="pre">-lowerswitch</span></tt>: Lower <tt class="docutils literal"><span class="pre">SwitchInst</span></tt>s to branches</a><a class="headerlink" href="#lowerswitch-lower-switchinsts-to-branches" title="Permalink to this headline">¶</a></h3>
+<p>Rewrites switch instructions with a sequence of branches, which allows targets
+to get away with not implementing the switch instruction until it is
+convenient.</p>
+</div>
+<div class="section" id="mem2reg-promote-memory-to-register">
+<span id="passes-mem2reg"></span><h3><a class="toc-backref" href="#id83"><tt class="docutils literal"><span class="pre">-mem2reg</span></tt>: Promote Memory to Register</a><a class="headerlink" href="#mem2reg-promote-memory-to-register" title="Permalink to this headline">¶</a></h3>
+<p>This file promotes memory references to be register references.  It promotes
+alloca instructions which only have loads and stores as uses.  An <tt class="docutils literal"><span class="pre">alloca</span></tt> is
+transformed by using dominator frontiers to place phi nodes, then traversing
+the function in depth-first order to rewrite loads and stores as appropriate.
+This is just the standard SSA construction algorithm to construct “pruned” SSA
+form.</p>
+</div>
+<div class="section" id="memcpyopt-memcpy-optimization">
+<h3><a class="toc-backref" href="#id84"><tt class="docutils literal"><span class="pre">-memcpyopt</span></tt>: MemCpy Optimization</a><a class="headerlink" href="#memcpyopt-memcpy-optimization" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs various transformations related to eliminating <tt class="docutils literal"><span class="pre">memcpy</span></tt>
+calls, or transforming sets of stores into <tt class="docutils literal"><span class="pre">memset</span></tt>s.</p>
+</div>
+<div class="section" id="mergefunc-merge-functions">
+<h3><a class="toc-backref" href="#id85"><tt class="docutils literal"><span class="pre">-mergefunc</span></tt>: Merge Functions</a><a class="headerlink" href="#mergefunc-merge-functions" title="Permalink to this headline">¶</a></h3>
+<p>This pass looks for equivalent functions that are mergable and folds them.</p>
+<p>Total-ordering is introduced among the functions set: we define comparison
+that answers for every two functions which of them is greater. It allows to
+arrange functions into the binary tree.</p>
+<p>For every new function we check for equivalent in tree.</p>
+<p>If equivalent exists we fold such functions. If both functions are overridable,
+we move the functionality into a new internal function and leave two
+overridable thunks to it.</p>
+<p>If there is no equivalent, then we add this function to tree.</p>
+<p>Lookup routine has O(log(n)) complexity, while whole merging process has
+complexity of O(n*log(n)).</p>
+<p>Read
+<a class="reference internal" href="MergeFunctions.html"><em>this</em></a>
+article for more details.</p>
+</div>
+<div class="section" id="mergereturn-unify-function-exit-nodes">
+<h3><a class="toc-backref" href="#id86"><tt class="docutils literal"><span class="pre">-mergereturn</span></tt>: Unify function exit nodes</a><a class="headerlink" href="#mergereturn-unify-function-exit-nodes" title="Permalink to this headline">¶</a></h3>
+<p>Ensure that functions have at most one <tt class="docutils literal"><span class="pre">ret</span></tt> instruction in them.
+Additionally, it keeps track of which node is the new exit node of the CFG.</p>
+</div>
+<div class="section" id="partial-inliner-partial-inliner">
+<h3><a class="toc-backref" href="#id87"><tt class="docutils literal"><span class="pre">-partial-inliner</span></tt>: Partial Inliner</a><a class="headerlink" href="#partial-inliner-partial-inliner" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs partial inlining, typically by inlining an <tt class="docutils literal"><span class="pre">if</span></tt> statement
+that surrounds the body of the function.</p>
+</div>
+<div class="section" id="prune-eh-remove-unused-exception-handling-info">
+<h3><a class="toc-backref" href="#id88"><tt class="docutils literal"><span class="pre">-prune-eh</span></tt>: Remove unused exception handling info</a><a class="headerlink" href="#prune-eh-remove-unused-exception-handling-info" title="Permalink to this headline">¶</a></h3>
+<p>This file implements a simple interprocedural pass which walks the call-graph,
+turning invoke instructions into call instructions if and only if the callee
+cannot throw an exception.  It implements this as a bottom-up traversal of the
+call-graph.</p>
+</div>
+<div class="section" id="reassociate-reassociate-expressions">
+<h3><a class="toc-backref" href="#id89"><tt class="docutils literal"><span class="pre">-reassociate</span></tt>: Reassociate expressions</a><a class="headerlink" href="#reassociate-reassociate-expressions" title="Permalink to this headline">¶</a></h3>
+<p>This pass reassociates commutative expressions in an order that is designed to
+promote better constant propagation, GCSE, <a class="reference internal" href="#passes-licm"><em>LICM</em></a>, PRE, etc.</p>
+<p>For example: 4 + (x + 5) ⇒ x + (4 + 5)</p>
+<p>In the implementation of this algorithm, constants are assigned rank = 0,
+function arguments are rank = 1, and other values are assigned ranks
+corresponding to the reverse post order traversal of current function (starting
+at 2), which effectively gives values in deep loops higher rank than values not
+in loops.</p>
+</div>
+<div class="section" id="reg2mem-demote-all-values-to-stack-slots">
+<h3><a class="toc-backref" href="#id90"><tt class="docutils literal"><span class="pre">-reg2mem</span></tt>: Demote all values to stack slots</a><a class="headerlink" href="#reg2mem-demote-all-values-to-stack-slots" title="Permalink to this headline">¶</a></h3>
+<p>This file demotes all registers to memory references.  It is intended to be the
+inverse of <a class="reference internal" href="#passes-mem2reg"><em>mem2reg</em></a>.  By converting to <tt class="docutils literal"><span class="pre">load</span></tt>
+instructions, the only values live across basic blocks are <tt class="docutils literal"><span class="pre">alloca</span></tt>
+instructions and <tt class="docutils literal"><span class="pre">load</span></tt> instructions before <tt class="docutils literal"><span class="pre">phi</span></tt> nodes.  It is intended
+that this should make CFG hacking much easier.  To make later hacking easier,
+the entry block is split into two, such that all introduced <tt class="docutils literal"><span class="pre">alloca</span></tt>
+instructions (and nothing else) are in the entry block.</p>
+</div>
+<div class="section" id="scalarrepl-scalar-replacement-of-aggregates-dt">
+<h3><a class="toc-backref" href="#id91"><tt class="docutils literal"><span class="pre">-scalarrepl</span></tt>: Scalar Replacement of Aggregates (DT)</a><a class="headerlink" href="#scalarrepl-scalar-replacement-of-aggregates-dt" title="Permalink to this headline">¶</a></h3>
+<p>The well-known scalar replacement of aggregates transformation.  This transform
+breaks up <tt class="docutils literal"><span class="pre">alloca</span></tt> instructions of aggregate type (structure or array) into
+individual <tt class="docutils literal"><span class="pre">alloca</span></tt> instructions for each member if possible.  Then, if
+possible, it transforms the individual <tt class="docutils literal"><span class="pre">alloca</span></tt> instructions into nice clean
+scalar SSA form.</p>
+<p>This combines a simple scalar replacement of aggregates algorithm with the
+<a class="reference internal" href="#passes-mem2reg"><em>mem2reg</em></a> algorithm because they often interact,
+especially for C++ programs.  As such, iterating between <tt class="docutils literal"><span class="pre">scalarrepl</span></tt>, then
+<a class="reference internal" href="#passes-mem2reg"><em>mem2reg</em></a> until we run out of things to promote works
+well.</p>
+</div>
+<div class="section" id="sccp-sparse-conditional-constant-propagation">
+<span id="passes-sccp"></span><h3><a class="toc-backref" href="#id92"><tt class="docutils literal"><span class="pre">-sccp</span></tt>: Sparse Conditional Constant Propagation</a><a class="headerlink" href="#sccp-sparse-conditional-constant-propagation" title="Permalink to this headline">¶</a></h3>
+<p>Sparse conditional constant propagation and merging, which can be summarized
+as:</p>
+<ul class="simple">
+<li>Assumes values are constant unless proven otherwise</li>
+<li>Assumes BasicBlocks are dead unless proven otherwise</li>
+<li>Proves values to be constant, and replaces them with constants</li>
+<li>Proves conditional branches to be unconditional</li>
+</ul>
+<p>Note that this pass has a habit of making definitions be dead.  It is a good
+idea to run a <a class="reference internal" href="#passes-dce"><em>DCE</em></a> pass sometime after running this pass.</p>
+</div>
+<div class="section" id="simplifycfg-simplify-the-cfg">
+<span id="passes-simplifycfg"></span><h3><a class="toc-backref" href="#id93"><tt class="docutils literal"><span class="pre">-simplifycfg</span></tt>: Simplify the CFG</a><a class="headerlink" href="#simplifycfg-simplify-the-cfg" title="Permalink to this headline">¶</a></h3>
+<p>Performs dead code elimination and basic block merging.  Specifically:</p>
+<ul class="simple">
+<li>Removes basic blocks with no predecessors.</li>
+<li>Merges a basic block into its predecessor if there is only one and the
+predecessor only has one successor.</li>
+<li>Eliminates PHI nodes for basic blocks with a single predecessor.</li>
+<li>Eliminates a basic block that only contains an unconditional branch.</li>
+</ul>
+</div>
+<div class="section" id="sink-code-sinking">
+<h3><a class="toc-backref" href="#id94"><tt class="docutils literal"><span class="pre">-sink</span></tt>: Code sinking</a><a class="headerlink" href="#sink-code-sinking" title="Permalink to this headline">¶</a></h3>
+<p>This pass moves instructions into successor blocks, when possible, so that they
+aren’t executed on paths where their results aren’t needed.</p>
+</div>
+<div class="section" id="strip-strip-all-symbols-from-a-module">
+<h3><a class="toc-backref" href="#id95"><tt class="docutils literal"><span class="pre">-strip</span></tt>: Strip all symbols from a module</a><a class="headerlink" href="#strip-strip-all-symbols-from-a-module" title="Permalink to this headline">¶</a></h3>
+<p>Performs code stripping.  This transformation can delete:</p>
+<ul class="simple">
+<li>names for virtual registers</li>
+<li>symbols for internal globals and functions</li>
+<li>debug information</li>
+</ul>
+<p>Note that this transformation makes code much less readable, so it should only
+be used in situations where the strip utility would be used, such as reducing
+code size or making it harder to reverse engineer code.</p>
+</div>
+<div class="section" id="strip-dead-debug-info-strip-debug-info-for-unused-symbols">
+<h3><a class="toc-backref" href="#id96"><tt class="docutils literal"><span class="pre">-strip-dead-debug-info</span></tt>: Strip debug info for unused symbols</a><a class="headerlink" href="#strip-dead-debug-info-strip-debug-info-for-unused-symbols" title="Permalink to this headline">¶</a></h3>
+<p>performs code stripping. this transformation can delete:</p>
+<ul class="simple">
+<li>names for virtual registers</li>
+<li>symbols for internal globals and functions</li>
+<li>debug information</li>
+</ul>
+<p>note that this transformation makes code much less readable, so it should only
+be used in situations where the strip utility would be used, such as reducing
+code size or making it harder to reverse engineer code.</p>
+</div>
+<div class="section" id="strip-dead-prototypes-strip-unused-function-prototypes">
+<h3><a class="toc-backref" href="#id97"><tt class="docutils literal"><span class="pre">-strip-dead-prototypes</span></tt>: Strip Unused Function Prototypes</a><a class="headerlink" href="#strip-dead-prototypes-strip-unused-function-prototypes" title="Permalink to this headline">¶</a></h3>
+<p>This pass loops over all of the functions in the input module, looking for dead
+declarations and removes them.  Dead declarations are declarations of functions
+for which no implementation is available (i.e., declarations for unused library
+functions).</p>
+</div>
+<div class="section" id="strip-debug-declare-strip-all-llvm-dbg-declare-intrinsics">
+<h3><a class="toc-backref" href="#id98"><tt class="docutils literal"><span class="pre">-strip-debug-declare</span></tt>: Strip all <tt class="docutils literal"><span class="pre">llvm.dbg.declare</span></tt> intrinsics</a><a class="headerlink" href="#strip-debug-declare-strip-all-llvm-dbg-declare-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements code stripping.  Specifically, it can delete:</p>
+<ol class="arabic simple">
+<li>names for virtual registers</li>
+<li>symbols for internal globals and functions</li>
+<li>debug information</li>
+</ol>
+<p>Note that this transformation makes code much less readable, so it should only
+be used in situations where the ‘strip’ utility would be used, such as reducing
+code size or making it harder to reverse engineer code.</p>
+</div>
+<div class="section" id="strip-nondebug-strip-all-symbols-except-dbg-symbols-from-a-module">
+<h3><a class="toc-backref" href="#id99"><tt class="docutils literal"><span class="pre">-strip-nondebug</span></tt>: Strip all symbols, except dbg symbols, from a module</a><a class="headerlink" href="#strip-nondebug-strip-all-symbols-except-dbg-symbols-from-a-module" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements code stripping.  Specifically, it can delete:</p>
+<ol class="arabic simple">
+<li>names for virtual registers</li>
+<li>symbols for internal globals and functions</li>
+<li>debug information</li>
+</ol>
+<p>Note that this transformation makes code much less readable, so it should only
+be used in situations where the ‘strip’ utility would be used, such as reducing
+code size or making it harder to reverse engineer code.</p>
+</div>
+<div class="section" id="tailcallelim-tail-call-elimination">
+<h3><a class="toc-backref" href="#id100"><tt class="docutils literal"><span class="pre">-tailcallelim</span></tt>: Tail Call Elimination</a><a class="headerlink" href="#tailcallelim-tail-call-elimination" title="Permalink to this headline">¶</a></h3>
+<p>This file transforms calls of the current function (self recursion) followed by
+a return instruction with a branch to the entry of the function, creating a
+loop.  This pass also implements the following extensions to the basic
+algorithm:</p>
+<ol class="arabic simple">
+<li>Trivial instructions between the call and return do not prevent the
+transformation from taking place, though currently the analysis cannot
+support moving any really useful instructions (only dead ones).</li>
+<li>This pass transforms functions that are prevented from being tail recursive
+by an associative expression to use an accumulator variable, thus compiling
+the typical naive factorial or fib implementation into efficient code.</li>
+<li>TRE is performed if the function returns void, if the return returns the
+result returned by the call, or if the function returns a run-time constant
+on all exits from the function.  It is possible, though unlikely, that the
+return returns something else (like constant 0), and can still be TRE’d.  It
+can be TRE’d if <em>all other</em> return instructions in the function return the
+exact same value.</li>
+<li>If it can prove that callees do not access theier caller stack frame, they
+are marked as eligible for tail call elimination (by the code generator).</li>
+</ol>
+</div>
+</div>
+<div class="section" id="utility-passes">
+<h2><a class="toc-backref" href="#id101">Utility Passes</a><a class="headerlink" href="#utility-passes" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the LLVM Utility Passes.</p>
+<div class="section" id="deadarghax0r-dead-argument-hacking-bugpoint-use-only-do-not-use">
+<h3><a class="toc-backref" href="#id102"><tt class="docutils literal"><span class="pre">-deadarghaX0r</span></tt>: Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)</a><a class="headerlink" href="#deadarghax0r-dead-argument-hacking-bugpoint-use-only-do-not-use" title="Permalink to this headline">¶</a></h3>
+<p>Same as dead argument elimination, but deletes arguments to functions which are
+external.  This is only for use by <a class="reference internal" href="Bugpoint.html"><em>bugpoint</em></a>.</p>
+</div>
+<div class="section" id="extract-blocks-extract-basic-blocks-from-module-for-bugpoint-use">
+<h3><a class="toc-backref" href="#id103"><tt class="docutils literal"><span class="pre">-extract-blocks</span></tt>: Extract Basic Blocks From Module (for bugpoint use)</a><a class="headerlink" href="#extract-blocks-extract-basic-blocks-from-module-for-bugpoint-use" title="Permalink to this headline">¶</a></h3>
+<p>This pass is used by bugpoint to extract all blocks from the module into their
+own functions.</p>
+</div>
+<div class="section" id="instnamer-assign-names-to-anonymous-instructions">
+<h3><a class="toc-backref" href="#id104"><tt class="docutils literal"><span class="pre">-instnamer</span></tt>: Assign names to anonymous instructions</a><a class="headerlink" href="#instnamer-assign-names-to-anonymous-instructions" title="Permalink to this headline">¶</a></h3>
+<p>This is a little utility pass that gives instructions names, this is mostly
+useful when diffing the effect of an optimization because deleting an unnamed
+instruction can change all other instruction numbering, making the diff very
+noisy.</p>
+</div>
+<div class="section" id="preverify-preliminary-module-verification">
+<h3><a class="toc-backref" href="#id105"><tt class="docutils literal"><span class="pre">-preverify</span></tt>: Preliminary module verification</a><a class="headerlink" href="#preverify-preliminary-module-verification" title="Permalink to this headline">¶</a></h3>
+<p>Ensures that the module is in the form required by the <a class="reference internal" href="#passes-verify"><em>Module Verifier</em></a> pass.  Running the verifier runs this pass automatically, so
+there should be no need to use it directly.</p>
+</div>
+<div class="section" id="verify-module-verifier">
+<span id="passes-verify"></span><h3><a class="toc-backref" href="#id106"><tt class="docutils literal"><span class="pre">-verify</span></tt>: Module Verifier</a><a class="headerlink" href="#verify-module-verifier" title="Permalink to this headline">¶</a></h3>
+<p>Verifies an LLVM IR code.  This is useful to run after an optimization which is
+undergoing testing.  Note that llvm-as verifies its input before emitting
+bitcode, and also that malformed bitcode is likely to make LLVM crash.  All
+language front-ends are therefore encouraged to verify their output before
+performing optimizing transformations.</p>
+<ol class="arabic simple">
+<li>Both of a binary operator’s parameters are of the same type.</li>
+<li>Verify that the indices of mem access instructions match other operands.</li>
+<li>Verify that arithmetic and other things are only performed on first-class
+types.  Verify that shifts and logicals only happen on integrals f.e.</li>
+<li>All of the constants in a switch statement are of the correct type.</li>
+<li>The code is in valid SSA form.</li>
+<li>It is illegal to put a label into any other type (like a structure) or to
+return one.</li>
+<li>Only phi nodes can be self referential: <tt class="docutils literal"><span class="pre">%x</span> <span class="pre">=</span> <span class="pre">add</span> <span class="pre">i32</span> <span class="pre">%x</span></tt>, <tt class="docutils literal"><span class="pre">%x</span></tt> is
+invalid.</li>
+<li>PHI nodes must have an entry for each predecessor, with no extras.</li>
+<li>PHI nodes must be the first thing in a basic block, all grouped together.</li>
+<li>PHI nodes must have at least one entry.</li>
+<li>All basic blocks should only end with terminator insts, not contain them.</li>
+<li>The entry node to a function must not have predecessors.</li>
+<li>All Instructions must be embedded into a basic block.</li>
+<li>Functions cannot take a void-typed parameter.</li>
+<li>Verify that a function’s argument list agrees with its declared type.</li>
+<li>It is illegal to specify a name for a void value.</li>
+<li>It is illegal to have an internal global value with no initializer.</li>
+<li>It is illegal to have a <tt class="docutils literal"><span class="pre">ret</span></tt> instruction that returns a value that does
+not agree with the function return value type.</li>
+<li>Function call argument types match the function prototype.</li>
+<li>All other things that are tested by asserts spread about the code.</li>
+</ol>
+<p>Note that this does not provide full security verification (like Java), but
+instead just tries to ensure that code is well-formed.</p>
+</div>
+<div class="section" id="view-cfg-view-cfg-of-function">
+<h3><a class="toc-backref" href="#id107"><tt class="docutils literal"><span class="pre">-view-cfg</span></tt>: View CFG of function</a><a class="headerlink" href="#view-cfg-view-cfg-of-function" title="Permalink to this headline">¶</a></h3>
+<p>Displays the control flow graph using the GraphViz tool.</p>
+</div>
+<div class="section" id="view-cfg-only-view-cfg-of-function-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id108"><tt class="docutils literal"><span class="pre">-view-cfg-only</span></tt>: View CFG of function (with no function bodies)</a><a class="headerlink" href="#view-cfg-only-view-cfg-of-function-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>Displays the control flow graph using the GraphViz tool, but omitting function
+bodies.</p>
+</div>
+<div class="section" id="view-dom-view-dominance-tree-of-function">
+<h3><a class="toc-backref" href="#id109"><tt class="docutils literal"><span class="pre">-view-dom</span></tt>: View dominance tree of function</a><a class="headerlink" href="#view-dom-view-dominance-tree-of-function" title="Permalink to this headline">¶</a></h3>
+<p>Displays the dominator tree using the GraphViz tool.</p>
+</div>
+<div class="section" id="view-dom-only-view-dominance-tree-of-function-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id110"><tt class="docutils literal"><span class="pre">-view-dom-only</span></tt>: View dominance tree of function (with no function bodies)</a><a class="headerlink" href="#view-dom-only-view-dominance-tree-of-function-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>Displays the dominator tree using the GraphViz tool, but omitting function
+bodies.</p>
+</div>
+<div class="section" id="view-postdom-view-postdominance-tree-of-function">
+<h3><a class="toc-backref" href="#id111"><tt class="docutils literal"><span class="pre">-view-postdom</span></tt>: View postdominance tree of function</a><a class="headerlink" href="#view-postdom-view-postdominance-tree-of-function" title="Permalink to this headline">¶</a></h3>
+<p>Displays the post dominator tree using the GraphViz tool.</p>
+</div>
+<div class="section" id="view-postdom-only-view-postdominance-tree-of-function-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id112"><tt class="docutils literal"><span class="pre">-view-postdom-only</span></tt>: View postdominance tree of function (with no function bodies)</a><a class="headerlink" href="#view-postdom-only-view-postdominance-tree-of-function-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>Displays the post dominator tree using the GraphViz tool, but omitting function
+bodies.</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="YamlIO.html" title="YAML I/O"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="ReleaseNotes.html" title="LLVM 3.6 Release Notes"
+             >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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/Phabricator.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/Phabricator.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/Phabricator.html (added)
+++ www-releases/trunk/3.6.0/docs/Phabricator.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,207 @@
+
+<!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>Code Reviews with Phabricator — LLVM 3.6 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.6',
+        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.6 documentation" href="index.html" />
+    <link rel="prev" title="How To Validate a New Release" href="ReleaseProcess.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="ReleaseProcess.html" title="How To Validate a New Release"
+             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="code-reviews-with-phabricator">
+<h1>Code Reviews with Phabricator<a class="headerlink" href="#code-reviews-with-phabricator" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#sign-up" id="id1">Sign up</a></li>
+<li><a class="reference internal" href="#requesting-a-review-via-the-command-line" id="id2">Requesting a review via the command line</a></li>
+<li><a class="reference internal" href="#requesting-a-review-via-the-web-interface" id="id3">Requesting a review via the web interface</a></li>
+<li><a class="reference internal" href="#reviewing-code-with-phabricator" id="id4">Reviewing code with Phabricator</a></li>
+<li><a class="reference internal" href="#committing-a-change" id="id5">Committing a change</a></li>
+<li><a class="reference internal" href="#status" id="id6">Status</a></li>
+</ul>
+</div>
+<p>If you prefer to use a web user interface for code reviews, you can now submit
+your patches for Clang and LLVM at <a class="reference external" href="http://reviews.llvm.org">LLVM’s Phabricator</a> instance.</p>
+<p>While Phabricator is a useful tool for some, the relevant -commits mailing list
+is the system of record for all LLVM code review. The mailing list should be
+added as a subscriber on all reviews, and Phabricator users should be prepared
+to respond to free-form comments in mail sent to the commits list.</p>
+<div class="section" id="sign-up">
+<h2><a class="toc-backref" href="#id1">Sign up</a><a class="headerlink" href="#sign-up" title="Permalink to this headline">¶</a></h2>
+<p>To get started with Phabricator, navigate to <a class="reference external" href="http://reviews.llvm.org">http://reviews.llvm.org</a> and
+click the power icon in the top right. You can register with a GitHub account,
+a Google account, or you can create your own profile.</p>
+<p>Make <em>sure</em> that the email address registered with Phabricator is subscribed
+to the relevant -commits mailing list. If your are not subscribed to the commit
+list, all mail sent by Phabricator on your behalf will be held for moderation.</p>
+<p>Note that if you use your Subversion user name as Phabricator user name,
+Phabricator will automatically connect your submits to your Phabricator user in
+the <a class="reference external" href="http://reviews.llvm.org/diffusion/">Code Repository Browser</a>.</p>
+</div>
+<div class="section" id="requesting-a-review-via-the-command-line">
+<h2><a class="toc-backref" href="#id2">Requesting a review via the command line</a><a class="headerlink" href="#requesting-a-review-via-the-command-line" title="Permalink to this headline">¶</a></h2>
+<p>Phabricator has a tool called <em>Arcanist</em> to upload patches from
+the command line. To get you set up, follow the
+<a class="reference external" href="http://www.phabricator.com/docs/phabricator/article/Arcanist_Quick_Start.html">Arcanist Quick Start</a> instructions.</p>
+<p>You can learn more about how to use arc to interact with
+Phabricator in the <a class="reference external" href="http://www.phabricator.com/docs/phabricator/article/Arcanist_User_Guide.html">Arcanist User Guide</a>.</p>
+</div>
+<div class="section" id="requesting-a-review-via-the-web-interface">
+<h2><a class="toc-backref" href="#id3">Requesting a review via the web interface</a><a class="headerlink" href="#requesting-a-review-via-the-web-interface" title="Permalink to this headline">¶</a></h2>
+<p>The tool to create and review patches in Phabricator is called
+<em>Differential</em>.</p>
+<p>Note that you can upload patches created through various diff tools,
+including git and svn. To make reviews easier, please always include
+<strong>as much context as possible</strong> with your diff! Don’t worry, Phabricator
+will automatically send a diff with a smaller context in the review
+email, but having the full file in the web interface will help the
+reviewer understand your code.</p>
+<p>To get a full diff, use one of the following commands (or just use Arcanist
+to upload your patch):</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">git</span> <span class="pre">diff</span> <span class="pre">-U999999</span> <span class="pre">other-branch</span></tt></li>
+<li><tt class="docutils literal"><span class="pre">svn</span> <span class="pre">diff</span> <span class="pre">--diff-cmd=diff</span> <span class="pre">-x</span> <span class="pre">-U999999</span></tt></li>
+</ul>
+<p>To upload a new patch:</p>
+<ul class="simple">
+<li>Click <em>Differential</em>.</li>
+<li>Click <em>Create Diff</em>.</li>
+<li>Paste the text diff or upload the patch file.
+Note that TODO</li>
+<li>Leave the drop down on <em>Create a new Revision...</em> and click <em>Continue</em>.</li>
+<li>Enter a descriptive title and summary; add reviewers and mailing
+lists that you want to be included in the review. If your patch is
+for LLVM, add llvm-commits as a subscriber; if your patch is for Clang,
+add cfe-commits.</li>
+<li>Click <em>Save</em>.</li>
+</ul>
+<p>To submit an updated patch:</p>
+<ul class="simple">
+<li>Click <em>Differential</em>.</li>
+<li>Click <em>Create Diff</em>.</li>
+<li>Paste the updated diff.</li>
+<li>Select the review you want to from the <em>Attach To</em> dropdown and click
+<em>Continue</em>.</li>
+<li>Click <em>Save</em>.</li>
+</ul>
+</div>
+<div class="section" id="reviewing-code-with-phabricator">
+<h2><a class="toc-backref" href="#id4">Reviewing code with Phabricator</a><a class="headerlink" href="#reviewing-code-with-phabricator" title="Permalink to this headline">¶</a></h2>
+<p>Phabricator allows you to add inline comments as well as overall comments
+to a revision. To add an inline comment, select the lines of code you want
+to comment on by clicking and dragging the line numbers in the diff pane.</p>
+<p>You can add overall comments or submit your comments at the bottom of the page.</p>
+<p>Phabricator has many useful features, for example allowing you to select
+diffs between different versions of the patch as it was reviewed in the
+<em>Revision Update History</em>. Most features are self descriptive - explore, and
+if you have a question, drop by on #llvm in IRC to get help.</p>
+<p>Note that as e-mail is the system of reference for code reviews, and some
+people prefer it over a web interface, we do not generate automated mail
+when a review changes state, for example by clicking “Accept Revision” in
+the web interface. Thus, please type LGTM into the comment box to accept
+a change from Phabricator.</p>
+</div>
+<div class="section" id="committing-a-change">
+<h2><a class="toc-backref" href="#id5">Committing a change</a><a class="headerlink" href="#committing-a-change" title="Permalink to this headline">¶</a></h2>
+<p>Arcanist can manage the commit transparently. It will retrieve the description,
+reviewers, the <tt class="docutils literal"><span class="pre">Differential</span> <span class="pre">Revision</span></tt>, etc from the review and commit it to the repository.</p>
+<div class="highlight-python"><div class="highlight"><pre>arc patch D<Revision>
+arc commit --revision D<Revision>
+</pre></div>
+</div>
+<p>When committing an LLVM change that has been reviewed using
+Phabricator, the convention is for the commit message to end with the
+line:</p>
+<div class="highlight-python"><div class="highlight"><pre>Differential Revision: <URL>
+</pre></div>
+</div>
+<p>where <tt class="docutils literal"><span class="pre"><URL></span></tt> is the URL for the code review, starting with
+<tt class="docutils literal"><span class="pre">http://reviews.llvm.org/</span></tt>.</p>
+<p>Note that Arcanist will add this automatically.</p>
+<p>This allows people reading the version history to see the review for
+context.  This also allows Phabricator to detect the commit, close the
+review, and add a link from the review to the commit.</p>
+</div>
+<div class="section" id="status">
+<h2><a class="toc-backref" href="#id6">Status</a><a class="headerlink" href="#status" title="Permalink to this headline">¶</a></h2>
+<p>Please let us know whether you like it and what could be improved!</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="ReleaseProcess.html" title="How To Validate a New Release"
+             >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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/ProgrammersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/ProgrammersManual.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/ProgrammersManual.html (added)
+++ www-releases/trunk/3.6.0/docs/ProgrammersManual.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,2868 @@
+
+<!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.6 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.6',
+        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.6 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="#passing-functions-and-other-callable-objects" id="id15">Passing functions and other callable objects</a><ul>
+<li><a class="reference internal" href="#function-template" id="id16">Function template</a></li>
+<li><a class="reference internal" href="#the-function-ref-class-template" id="id17">The <tt class="docutils literal"><span class="pre">function_ref</span></tt> class template</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-debug-macro-and-debug-option" id="id18">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="id19">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="id20">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="id21">Viewing graphs while debugging code</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#picking-the-right-data-structure-for-a-task" id="id22">Picking the Right Data Structure for a Task</a><ul>
+<li><a class="reference internal" href="#sequential-containers-std-vector-std-list-etc" id="id23">Sequential Containers (std::vector, std::list, etc)</a><ul>
+<li><a class="reference internal" href="#llvm-adt-arrayref-h" id="id24">llvm/ADT/ArrayRef.h</a></li>
+<li><a class="reference internal" href="#fixed-size-arrays" id="id25">Fixed Size Arrays</a></li>
+<li><a class="reference internal" href="#heap-allocated-arrays" id="id26">Heap Allocated Arrays</a></li>
+<li><a class="reference internal" href="#llvm-adt-tinyptrvector-h" id="id27">llvm/ADT/TinyPtrVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallvector-h" id="id28">llvm/ADT/SmallVector.h</a></li>
+<li><a class="reference internal" href="#vector" id="id29"><vector></a></li>
+<li><a class="reference internal" href="#deque" id="id30"><deque></a></li>
+<li><a class="reference internal" href="#list" id="id31"><list></a></li>
+<li><a class="reference internal" href="#llvm-adt-ilist-h" id="id32">llvm/ADT/ilist.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-packedvector-h" id="id33">llvm/ADT/PackedVector.h</a></li>
+<li><a class="reference internal" href="#ilist-traits" id="id34">ilist_traits</a></li>
+<li><a class="reference internal" href="#iplist" id="id35">iplist</a></li>
+<li><a class="reference internal" href="#llvm-adt-ilist-node-h" id="id36">llvm/ADT/ilist_node.h</a></li>
+<li><a class="reference internal" href="#sentinels" id="id37">Sentinels</a></li>
+<li><a class="reference internal" href="#other-sequential-container-options" id="id38">Other Sequential Container options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#string-like-containers" id="id39">String-like containers</a><ul>
+<li><a class="reference internal" href="#llvm-adt-stringref-h" id="id40">llvm/ADT/StringRef.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-twine-h" id="id41">llvm/ADT/Twine.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallstring-h" id="id42">llvm/ADT/SmallString.h</a></li>
+<li><a class="reference internal" href="#std-string" id="id43">std::string</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#set-like-containers-std-set-smallset-setvector-etc" id="id44">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a><ul>
+<li><a class="reference internal" href="#a-sorted-vector" id="id45">A sorted ‘vector’</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallset-h" id="id46">llvm/ADT/SmallSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallptrset-h" id="id47">llvm/ADT/SmallPtrSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-denseset-h" id="id48">llvm/ADT/DenseSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-sparseset-h" id="id49">llvm/ADT/SparseSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-sparsemultiset-h" id="id50">llvm/ADT/SparseMultiSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-foldingset-h" id="id51">llvm/ADT/FoldingSet.h</a></li>
+<li><a class="reference internal" href="#set" id="id52"><set></a></li>
+<li><a class="reference internal" href="#llvm-adt-setvector-h" id="id53">llvm/ADT/SetVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-uniquevector-h" id="id54">llvm/ADT/UniqueVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-immutableset-h" id="id55">llvm/ADT/ImmutableSet.h</a></li>
+<li><a class="reference internal" href="#other-set-like-container-options" id="id56">Other Set-Like Container Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#map-like-containers-std-map-densemap-etc" id="id57">Map-Like Containers (std::map, DenseMap, etc)</a><ul>
+<li><a class="reference internal" href="#dss-sortedvectormap" id="id58">A sorted ‘vector’</a></li>
+<li><a class="reference internal" href="#llvm-adt-stringmap-h" id="id59">llvm/ADT/StringMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-indexedmap-h" id="id60">llvm/ADT/IndexedMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-densemap-h" id="id61">llvm/ADT/DenseMap.h</a></li>
+<li><a class="reference internal" href="#llvm-ir-valuemap-h" id="id62">llvm/IR/ValueMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-intervalmap-h" id="id63">llvm/ADT/IntervalMap.h</a></li>
+<li><a class="reference internal" href="#map" id="id64"><map></a></li>
+<li><a class="reference internal" href="#llvm-adt-mapvector-h" id="id65">llvm/ADT/MapVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-inteqclasses-h" id="id66">llvm/ADT/IntEqClasses.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-immutablemap-h" id="id67">llvm/ADT/ImmutableMap.h</a></li>
+<li><a class="reference internal" href="#other-map-like-container-options" id="id68">Other Map-Like Container Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#bit-storage-containers-bitvector-sparsebitvector" id="id69">Bit storage containers (BitVector, SparseBitVector)</a><ul>
+<li><a class="reference internal" href="#bitvector" id="id70">BitVector</a></li>
+<li><a class="reference internal" href="#smallbitvector" id="id71">SmallBitVector</a></li>
+<li><a class="reference internal" href="#sparsebitvector" id="id72">SparseBitVector</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#helpful-hints-for-common-operations" id="id73">Helpful Hints for Common Operations</a><ul>
+<li><a class="reference internal" href="#basic-inspection-and-traversal-routines" id="id74">Basic Inspection and Traversal Routines</a><ul>
+<li><a class="reference internal" href="#iterating-over-the-basicblock-in-a-function" id="id75">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="id76">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="id77">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="id78">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="id79">Finding call sites: a slightly more complex example</a></li>
+<li><a class="reference internal" href="#treating-calls-and-invokes-the-same-way" id="id80">Treating calls and invokes the same way</a></li>
+<li><a class="reference internal" href="#iterating-over-def-use-use-def-chains" id="id81">Iterating over def-use & use-def chains</a></li>
+<li><a class="reference internal" href="#iterating-over-predecessors-successors-of-blocks" id="id82">Iterating over predecessors & successors of blocks</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#making-simple-changes" id="id83">Making simple changes</a><ul>
+<li><a class="reference internal" href="#creating-and-inserting-new-instructions" id="id84">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="id85">Deleting Instructions</a></li>
+<li><a class="reference internal" href="#replacing-an-instruction-with-another-value" id="id86">Replacing an Instruction with another Value</a><ul>
+<li><a class="reference internal" href="#replacing-individual-instructions" id="id87">Replacing individual instructions</a></li>
+<li><a class="reference internal" href="#schanges-deleting-sub" id="id88">Deleting Instructions</a></li>
+<li><a class="reference internal" href="#replacing-multiple-uses-of-users-and-values" id="id89">Replacing multiple uses of Users and Values</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#deleting-globalvariables" id="id90">Deleting GlobalVariables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#how-to-create-types" id="id91">How to Create Types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#threads-and-llvm" id="id92">Threads and LLVM</a><ul>
+<li><a class="reference internal" href="#ending-execution-with-llvm-shutdown" id="id93">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="id94">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="id95">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="id96">Threads and the JIT</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#advanced-topics" id="id97">Advanced Topics</a><ul>
+<li><a class="reference internal" href="#the-valuesymboltable-class" id="id98">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="id99">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="id100">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="id101">The waymarking algorithm</a></li>
+<li><a class="reference internal" href="#reference-implementation" id="id102">Reference implementation</a></li>
+<li><a class="reference internal" href="#tagging-considerations" id="id103">Tagging considerations</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-core-llvm-class-hierarchy-reference" id="id104">The Core LLVM Class Hierarchy Reference</a><ul>
+<li><a class="reference internal" href="#the-type-class-and-derived-types" id="id105">The Type class and Derived Types</a><ul>
+<li><a class="reference internal" href="#important-public-methods" id="id106">Important Public Methods</a></li>
+<li><a class="reference internal" href="#important-derived-types" id="id107">Important Derived Types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-module-class" id="id108">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="id109">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="id110">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="id111">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="id112">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="id113">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="id114">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="id115">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="id116">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="id117">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="id118">Important Subclasses of Constant</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-globalvalue-class" id="id119">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="id120">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="id121">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="id122">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="id123">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="id124">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="id125">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="id126">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="id127">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="passing-functions-and-other-callable-objects">
+<span id="function-apis"></span><h3><a class="toc-backref" href="#id15">Passing functions and other callable objects</a><a class="headerlink" href="#passing-functions-and-other-callable-objects" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes you may want a function to be passed a callback object. In order to
+support lambda expressions and other function objects, you should not use the
+traditional C approach of taking a function pointer and an opaque cookie:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">takeCallback</span><span class="p">(</span><span class="kt">bool</span> <span class="p">(</span><span class="o">*</span><span class="n">Callback</span><span class="p">)(</span><span class="n">Function</span> <span class="o">*</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="p">),</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Cookie</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Instead, use one of the following approaches:</p>
+<div class="section" id="function-template">
+<h4><a class="toc-backref" href="#id16">Function template</a><a class="headerlink" href="#function-template" title="Permalink to this headline">¶</a></h4>
+<p>If you don’t mind putting the definition of your function into a header file,
+make it a function template that is templated on the callable type.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">template</span><span class="o"><</span><span class="k">typename</span> <span class="n">Callable</span><span class="o">></span>
+<span class="kt">void</span> <span class="n">takeCallback</span><span class="p">(</span><span class="n">Callable</span> <span class="n">Callback</span><span class="p">)</span> <span class="p">{</span>
+  <span class="n">Callback</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-function-ref-class-template">
+<h4><a class="toc-backref" href="#id17">The <tt class="docutils literal"><span class="pre">function_ref</span></tt> class template</a><a class="headerlink" href="#the-function-ref-class-template" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">function_ref</span></tt>
+(<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1function_ref.html">doxygen</a>) class
+template represents a reference to a callable object, templated over the type
+of the callable. This is a good choice for passing a callback to a function,
+if you don’t need to hold onto the callback after the function returns. In this
+way, <tt class="docutils literal"><span class="pre">function_ref</span></tt> is to <tt class="docutils literal"><span class="pre">std::function</span></tt> as <tt class="docutils literal"><span class="pre">StringRef</span></tt> is to
+<tt class="docutils literal"><span class="pre">std::string</span></tt>.</p>
+<p><tt class="docutils literal"><span class="pre">function_ref<Ret(Param1,</span> <span class="pre">Param2,</span> <span class="pre">...)></span></tt> can be implicitly constructed from
+any callable object that can be called with arguments of type <tt class="docutils literal"><span class="pre">Param1</span></tt>,
+<tt class="docutils literal"><span class="pre">Param2</span></tt>, ..., and returns a value that can be converted to type <tt class="docutils literal"><span class="pre">Ret</span></tt>.
+For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">visitBasicBlocks</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="n">function_ref</span><span class="o"><</span><span class="kt">bool</span> <span class="p">(</span><span class="n">BasicBlock</span><span class="o">*</span><span class="p">)</span><span class="o">></span> <span class="n">Callback</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">BB</span> <span class="o">:</span> <span class="o">*</span><span class="n">F</span><span class="p">)</span>
+    <span class="k">if</span> <span class="p">(</span><span class="n">Callback</span><span class="p">(</span><span class="o">&</span><span class="n">BB</span><span class="p">))</span>
+      <span class="k">return</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>can be called using:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">visitBasicBlocks</span><span class="p">(</span><span class="n">F</span><span class="p">,</span> <span class="p">[</span><span class="o">&</span><span class="p">](</span><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">BB</span><span class="p">)</span> <span class="p">{</span>
+  <span class="k">if</span> <span class="p">(</span><span class="n">process</span><span class="p">(</span><span class="n">BB</span><span class="p">))</span>
+    <span class="k">return</span> <span class="n">isEmpty</span><span class="p">(</span><span class="n">BB</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>Note that a <tt class="docutils literal"><span class="pre">function_ref</span></tt> object contains pointers to external memory, so it
+is not generally safe to store an instance of the class (unless you know that
+the external storage will not be freed). If you need this ability, consider
+using <tt class="docutils literal"><span class="pre">std::function</span></tt>. <tt class="docutils literal"><span class="pre">function_ref</span></tt> is small enough that it should always
+be passed by value.</p>
+</div>
+</div>
+<div class="section" id="the-debug-macro-and-debug-option">
+<span id="debug"></span><h3><a class="toc-backref" href="#id18">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="#id19">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
+can define the <tt class="docutils literal"><span class="pre">DEBUG_TYPE</span></tt> macro and use the <tt class="docutils literal"><span class="pre">-debug-only</span></tt> 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-only=InstrSched</span></tt>, even if
+the source lives in multiple files.</p>
+<p>For performance reasons, -debug-only is not available in optimized build
+(<tt class="docutils literal"><span class="pre">--enable-optimized</span></tt>) of LLVM.</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="#id20">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="#id21">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 setup.  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. The programs need not be present when configuring, building or
+running LLVM and can simply be installed when needed during an active debug
+session.</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="#id22">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="#id23">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="#id24">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="#id25">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="#id26">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="#id27">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="#id28">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="#id29"><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="#id30"><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="#id31"><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="#id32">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="#id33">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="#id34">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="#id35">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="#id36">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 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="#id37">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="#id38">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="#id39">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="#id40">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="#id41">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="#id42">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="#id43">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="#id44">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="#id45">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="#id46">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="#id47">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="#id48">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="#id49">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="#id50">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="#id51">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="#id52"><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="#id53">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 its “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="#id54">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="#id55">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="#id56">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="#id57">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="#id58">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="#id59">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="#id60">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="#id61">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-ir-valuemap-h">
+<span id="dss-valuemap"></span><h4><a class="toc-backref" href="#id62">llvm/IR/ValueMap.h</a><a class="headerlink" href="#llvm-ir-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="#id63">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="#id64"><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="#id65">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 removing elements takes linear time.  If it is
+necessary to remove elements, it’s best to remove them in bulk using
+<tt class="docutils literal"><span class="pre">remove_if()</span></tt>.</p>
+</div>
+<div class="section" id="llvm-adt-inteqclasses-h">
+<span id="dss-inteqclasses"></span><h4><a class="toc-backref" href="#id66">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="#id67">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="#id68">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="#id69">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="#id70">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="#id71">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="#id72">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="#id73">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="#id74">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="#id75">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="#id76">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="#id77">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/IR/InstIterator.h</span></tt> (<a class="reference external" href="http://llvm.org/doxygen/InstIterator_8h.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/IR/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="#id78">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="#id79">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="#id80">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="#id81">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">User</span> <span class="o">*</span><span class="n">U</span> <span class="o">:</span> <span class="n">GV</span><span class="o">-></span><span class="n">users</span><span class="p">())</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="n">U</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>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">Use</span> <span class="o">&</span><span class="n">U</span> <span class="o">:</span> <span class="n">pi</span><span class="o">-></span><span class="n">operands</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="n">U</span><span class="p">.</span><span class="n">get</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="#id82">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="#id83">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="#id84">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 three 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>
+<li><p class="first">Insertion using an instance of <tt class="docutils literal"><span class="pre">IRBuilder</span></tt></p>
+<p>Inserting several <tt class="docutils literal"><span class="pre">Instruction</span></tt>s can be quite laborious using the previous
+methods. The <tt class="docutils literal"><span class="pre">IRBuilder</span></tt> is a convenience class that can be used to add
+several instructions to the end of a <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> or before a particular
+<tt class="docutils literal"><span class="pre">Instruction</span></tt>. It also supports constant folding and renaming named
+registers (see <tt class="docutils literal"><span class="pre">IRBuilder</span></tt>‘s template arguments).</p>
+<p>The example below demonstrates a very simple use of the <tt class="docutils literal"><span class="pre">IRBuilder</span></tt> where
+three instructions are inserted before the instruction <tt class="docutils literal"><span class="pre">pi</span></tt>. The first two
+instructions are Call instructions and third instruction multiplies the return
+value of the two calls.</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">IRBuilder</span><span class="o"><></span> <span class="n">Builder</span><span class="p">(</span><span class="n">pi</span><span class="p">);</span>
+<span class="n">CallInst</span><span class="o">*</span> <span class="n">callOne</span> <span class="o">=</span> <span class="n">Builder</span><span class="p">.</span><span class="n">CreateCall</span><span class="p">(...);</span>
+<span class="n">CallInst</span><span class="o">*</span> <span class="n">callTwo</span> <span class="o">=</span> <span class="n">Builder</span><span class="p">.</span><span class="n">CreateCall</span><span class="p">(...);</span>
+<span class="n">Value</span><span class="o">*</span> <span class="n">result</span> <span class="o">=</span> <span class="n">Builder</span><span class="p">.</span><span class="n">CreateMul</span><span class="p">(</span><span class="n">callOne</span><span class="p">,</span> <span class="n">callTwo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The example below is similar to the above example except that the created
+<tt class="docutils literal"><span class="pre">IRBuilder</span></tt> inserts instructions at the end of the <tt class="docutils literal"><span class="pre">BasicBlock</span></tt> <tt class="docutils literal"><span class="pre">pb</span></tt>.</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">IRBuilder</span><span class="o"><></span> <span class="n">Builder</span><span class="p">(</span><span class="n">pb</span><span class="p">);</span>
+<span class="n">CallInst</span><span class="o">*</span> <span class="n">callOne</span> <span class="o">=</span> <span class="n">Builder</span><span class="p">.</span><span class="n">CreateCall</span><span class="p">(...);</span>
+<span class="n">CallInst</span><span class="o">*</span> <span class="n">callTwo</span> <span class="o">=</span> <span class="n">Builder</span><span class="p">.</span><span class="n">CreateCall</span><span class="p">(...);</span>
+<span class="n">Value</span><span class="o">*</span> <span class="n">result</span> <span class="o">=</span> <span class="n">Builder</span><span class="p">.</span><span class="n">CreateMul</span><span class="p">(</span><span class="n">callOne</span><span class="p">,</span> <span class="n">callTwo</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>See <a class="reference internal" href="tutorial/LangImpl3.html"><em>Kaleidoscope: Code generation to LLVM IR</em></a> for a practical use of the <tt class="docutils literal"><span class="pre">IRBuilder</span></tt>.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="deleting-instructions">
+<span id="schanges-deleting"></span><h4><a class="toc-backref" href="#id85">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="#id86">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="#id87">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="#id88">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="#id89">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="#id90">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="#id91">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="#id92">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="ending-execution-with-llvm-shutdown">
+<span id="shutdown"></span><h3><a class="toc-backref" href="#id93">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.</p>
+</div>
+<div class="section" id="lazy-initialization-with-managedstatic">
+<span id="managedstatic"></span><h3><a class="toc-backref" href="#id94">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.  In a
+single-threaded environment, it implements a simple lazy initialization scheme.
+When LLVM is compiled with support for multi-threading, however, it uses
+double-checked locking to implement thread-safe lazy initialization.</p>
+</div>
+<div class="section" id="achieving-isolation-with-llvmcontext">
+<span id="llvmcontext"></span><h3><a class="toc-backref" href="#id95">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="#id96">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="#id97">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="#id98">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="#id99">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="#id100">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="#id101">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="#id102">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"><div class="highlight"><pre>*Main> quickCheck identityProp
+OK, passed 100 tests.
+</pre></div>
+</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"><div class="highlight"><pre>*Main> deepCheck identityProp
+OK, passed 500 tests.
+</pre></div>
+</div>
+</div>
+<div class="section" id="tagging-considerations">
+<span id="tagging"></span><h4><a class="toc-backref" href="#id103">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="#id104">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/IR/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="#id105">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="#id106">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="#id107">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="#id108">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/IR/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="#id109">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="#id110">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/IR/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="#id111">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="#id112">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/IR/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="#id113">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="#id114">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/IR/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="#id115">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="#id116">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="#id117">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="#id118">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="#id119">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/IR/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="#id120">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="#id121">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/IR/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="#id122">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="#id123">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/IR/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="#id124">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="#id125">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/IR/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="#id126">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="#id127">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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/Projects.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/Projects.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/Projects.html (added)
+++ www-releases/trunk/3.6.0/docs/Projects.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,337 @@
+
+<!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.6 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.6',
+        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.6 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="#source-tree-layout" id="id2">Source Tree Layout</a></li>
+<li><a class="reference internal" href="#writing-llvm-style-makefiles" id="id3">Writing LLVM Style Makefiles</a><ul>
+<li><a class="reference internal" href="#required-variables" id="id4">Required Variables</a></li>
+<li><a class="reference internal" href="#variables-for-building-subdirectories" id="id5">Variables for Building Subdirectories</a></li>
+<li><a class="reference internal" href="#variables-for-building-libraries" id="id6">Variables for Building Libraries</a></li>
+<li><a class="reference internal" href="#variables-for-building-programs" id="id7">Variables for Building Programs</a></li>
+<li><a class="reference internal" href="#miscellaneous-variables" id="id8">Miscellaneous Variables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#placement-of-object-code" id="id9">Placement of Object Code</a></li>
+<li><a class="reference internal" href="#further-help" id="id10">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>If you want to devise your own build system, studying other projects 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="source-tree-layout">
+<h2><a class="toc-backref" href="#id2">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.</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="#id3">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="#id4">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="#id5">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="#id6">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="#id7">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="#id8">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="#id9">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="#id10">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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/R600Usage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/R600Usage.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/R600Usage.html (added)
+++ www-releases/trunk/3.6.0/docs/R600Usage.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,131 @@
+
+<!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>User Guide for R600 Back-end — LLVM 3.6 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.6',
+        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.6 documentation" href="index.html" />
+    <link rel="next" title="Stack maps and patch points in LLVM" href="StackMaps.html" />
+    <link rel="prev" title="User Guide for NVPTX Back-end" href="NVPTXUsage.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="StackMaps.html" title="Stack maps and patch points in LLVM"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
+             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="user-guide-for-r600-back-end">
+<h1>User Guide for R600 Back-end<a class="headerlink" href="#user-guide-for-r600-back-end" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction">
+<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The R600 back-end provides ISA code generation for AMD GPUs, starting with
+the R600 family up until the current Sea Islands (GCN Gen 2).</p>
+</div>
+<div class="section" id="assembler">
+<h2>Assembler<a class="headerlink" href="#assembler" title="Permalink to this headline">¶</a></h2>
+<p>The assembler is currently a work in progress and not yet complete.  Below
+are the currently supported features.</p>
+<div class="section" id="sopp-instructions">
+<h3>SOPP Instructions<a class="headerlink" href="#sopp-instructions" title="Permalink to this headline">¶</a></h3>
+<p>Unless otherwise mentioned, all SOPP instructions that with an operand
+accept a integer operand(s) only.  No verification is performed on the
+operands, so it is up to the programmer to be familiar with the range
+or acceptable values.</p>
+<div class="section" id="s-waitcnt">
+<h4>s_waitcnt<a class="headerlink" href="#s-waitcnt" title="Permalink to this headline">¶</a></h4>
+<p>s_waitcnt accepts named arguments to specify which memory counter(s) to
+wait for.</p>
+<div class="highlight-nasm"><div class="highlight"><pre>// Wait for all counters to be 0
+s_waitcnt 0
+
+// Equivalent to s_waitcnt 0.  Counter names can also be delimited by
+// '&' or ','.
+s_waitcnt vmcnt(0) expcnt(0) lgkcmt(0)
+
+// Wait for vmcnt counter to be 1.
+s_waitcnt vmcnt(1)
+</pre></div>
+</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="StackMaps.html" title="Stack maps and patch points in LLVM"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
+             >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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/ReleaseNotes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/ReleaseNotes.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/ReleaseNotes.html (added)
+++ www-releases/trunk/3.6.0/docs/ReleaseNotes.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,641 @@
+
+<!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.6 Release Notes — LLVM 3.6 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.6',
+        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.6 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-6-release-notes">
+<h1>LLVM 3.6 Release Notes<a class="headerlink" href="#llvm-3-6-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="#prefix-data-rework" id="id4">Prefix data rework</a></li>
+<li><a class="reference internal" href="#metadata-is-not-a-value" id="id5">Metadata is not a Value</a><ul>
+<li><a class="reference internal" href="#bridges-between-value-and-metadata" id="id6">Bridges between Value and Metadata</a></li>
+<li><a class="reference internal" href="#metadata-is-typeless" id="id7">Metadata is typeless</a></li>
+<li><a class="reference internal" href="#distinct-metadata-nodes" id="id8">Distinct metadata nodes</a></li>
+<li><a class="reference internal" href="#constructing-cyclic-graphs" id="id9">Constructing cyclic graphs</a></li>
+<li><a class="reference internal" href="#mdlocation-aka-debugloc-aka-dilocation" id="id10">MDLocation (aka DebugLoc aka DILocation)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#alias-syntax-change" id="id11">Alias syntax change</a></li>
+<li><a class="reference internal" href="#the-old-jit-has-been-removed" id="id12">The old JIT has been removed</a></li>
+<li><a class="reference internal" href="#object-binary-doesn-t-own-the-file-buffer" id="id13">object::Binary doesn’t own the file buffer</a></li>
+<li><a class="reference internal" href="#ir-in-object-files-is-now-supported" id="id14">IR in object files is now supported</a></li>
+<li><a class="reference internal" href="#the-gold-plugin-has-been-rewritten" id="id15">The gold plugin has been rewritten</a></li>
+<li><a class="reference internal" href="#change-in-the-representation-of-lazy-loaded-funcs" id="id16">Change in the representation of lazy loaded funcs</a></li>
+<li><a class="reference internal" href="#the-opt-option-std-compile-opts-was-removed" id="id17">The opt option -std-compile-opts was removed</a></li>
+<li><a class="reference internal" href="#python-2-7-is-now-required" id="id18">Python 2.7 is now required</a></li>
+<li><a class="reference internal" href="#the-leak-detector-has-been-removed" id="id19">The leak detector has been removed</a></li>
+<li><a class="reference internal" href="#new-comdat-syntax" id="id20">New comdat syntax</a></li>
+<li><a class="reference internal" href="#added-support-for-win64-unwind-information" id="id21">Added support for Win64 unwind information</a></li>
+<li><a class="reference internal" href="#diagnostic-infrastructure-used-by-lib-linker-and-lib-bitcode" id="id22">Diagnostic infrastructure used by lib/Linker and lib/Bitcode</a></li>
+<li><a class="reference internal" href="#the-preservesource-linker-mode-was-removed" id="id23">The PreserveSource linker mode was removed</a></li>
+<li><a class="reference internal" href="#garbage-collection" id="id24">Garbage Collection</a></li>
+<li><a class="reference internal" href="#changes-to-the-mips-target" id="id25">Changes to the MIPS Target</a><ul>
+<li><a class="reference internal" href="#abi" id="id26">ABI</a></li>
+<li><a class="reference internal" href="#llvmlinux" id="id27">LLVMLinux</a></li>
+<li><a class="reference internal" href="#miscellaneous" id="id28">Miscellaneous</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#changes-to-the-powerpc-target" id="id29">Changes to the PowerPC Target</a></li>
+<li><a class="reference internal" href="#changes-to-the-ocaml-bindings" id="id30">Changes to the OCaml bindings</a></li>
+<li><a class="reference internal" href="#go-bindings" id="id31">Go bindings</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#external-open-source-projects-using-llvm-3-6" id="id32">External Open Source Projects Using LLVM 3.6</a><ul>
+<li><a class="reference internal" href="#portable-computing-language-pocl" id="id33">Portable Computing Language (pocl)</a></li>
+<li><a class="reference internal" href="#tta-based-co-design-environment-tce" id="id34">TTA-based Co-design Environment (TCE)</a></li>
+<li><a class="reference internal" href="#likely" id="id35">Likely</a></li>
+<li><a class="reference internal" href="#ldc-the-llvm-based-d-compiler" id="id36">LDC - the LLVM-based D compiler</a></li>
+<li><a class="reference internal" href="#llvmsharp-clangsharp" id="id37">LLVMSharp & ClangSharp</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#additional-information" id="id38">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.6.  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>
+</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>Support for AuroraUX has been removed.</li>
+<li>Added support for a <a class="reference external" href="BitCodeFormat.html#native-object-file">native object file-based bitcode wrapper format</a>.</li>
+<li>Added support for MSVC’s <tt class="docutils literal"><span class="pre">__vectorcall</span></tt> calling convention as
+<tt class="docutils literal"><span class="pre">x86_vectorcallcc</span></tt>.</li>
+</ul>
+<div class="section" id="prefix-data-rework">
+<h3><a class="toc-backref" href="#id4">Prefix data rework</a><a class="headerlink" href="#prefix-data-rework" title="Permalink to this headline">¶</a></h3>
+<p>The semantics of the <tt class="docutils literal"><span class="pre">prefix</span></tt> attribute have been changed. Users
+that want the previous <tt class="docutils literal"><span class="pre">prefix</span></tt> semantics should instead use
+<tt class="docutils literal"><span class="pre">prologue</span></tt>.  To motivate this change, let’s examine the primary
+usecases that these attributes aim to serve,</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li>Code sanitization metadata (e.g. Clang’s undefined behavior
+sanitizer)</li>
+<li>Function hot-patching: Enable the user to insert <tt class="docutils literal"><span class="pre">nop</span></tt> operations
+at the beginning of the function which can later be safely replaced
+with a call to some instrumentation facility.</li>
+<li>Language runtime metadata: Allow a compiler to insert data for
+use by the runtime during execution. GHC is one example of a
+compiler that needs this functionality for its
+tables-next-to-code functionality.</li>
+</ol>
+</div></blockquote>
+<p>Previously <tt class="docutils literal"><span class="pre">prefix</span></tt> served cases (1) and (2) quite well by allowing the user
+to introduce arbitrary data at the entrypoint but before the function
+body. Case (3), however, was poorly handled by this approach as it
+required that prefix data was valid executable code.</p>
+<p>In this release the concept of prefix data has been redefined to be
+data which occurs immediately before the function entrypoint (i.e. the
+symbol address). Since prefix data now occurs before the function
+entrypoint, there is no need for the data to be valid code.</p>
+<p>The previous notion of prefix data now goes under the name “prologue
+data” to emphasize its duality with the function epilogue.</p>
+<p>The intention here is to handle cases (1) and (2) with prologue data and
+case (3) with prefix data. See the language reference for further details
+on the semantics of these attributes.</p>
+<p>This refactoring arose out of <a class="reference external" href="http://lists.cs.uiuc.edu/pipermail/llvmdev/2014-May/073235.html">discussions</a> with Reid Kleckner in
+response to a proposal to introduce the notion of symbol offsets to
+enable handling of case (3).</p>
+</div>
+<div class="section" id="metadata-is-not-a-value">
+<h3><a class="toc-backref" href="#id5">Metadata is not a Value</a><a class="headerlink" href="#metadata-is-not-a-value" title="Permalink to this headline">¶</a></h3>
+<p>Metadata nodes (<tt class="docutils literal"><span class="pre">!{...}</span></tt>) and strings (<tt class="docutils literal"><span class="pre">!"..."</span></tt>) are no longer values.
+They have no use-lists, no type, cannot RAUW, and cannot be function-local.</p>
+<div class="section" id="bridges-between-value-and-metadata">
+<h4><a class="toc-backref" href="#id6">Bridges between Value and Metadata</a><a class="headerlink" href="#bridges-between-value-and-metadata" title="Permalink to this headline">¶</a></h4>
+<p>LLVM intrinsics can reference metadata using the <tt class="docutils literal"><span class="pre">metadata</span></tt> type, and
+metadata nodes can reference constant values.</p>
+<p>Function-local metadata is limited to direct arguments to LLVM intrinsics.</p>
+</div>
+<div class="section" id="metadata-is-typeless">
+<h4><a class="toc-backref" href="#id7">Metadata is typeless</a><a class="headerlink" href="#metadata-is-typeless" title="Permalink to this headline">¶</a></h4>
+<p>The following old IR:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@g</span> <span class="p">=</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%v</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span> <span class="p">!{</span><span class="k">i32</span> <span class="nv">%v</span><span class="p">})</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</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="vg">@global</span><span class="p">})</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span> <span class="nv-Anonymous">!0</span><span class="p">)</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span> <span class="p">!{</span><span class="kt">metadata</span> <span class="nv">!"string"</span><span class="p">})</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</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="kt">metadata</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"string"</span><span class="p">}})</span>
+  <span class="k">ret</span> <span class="kt">void</span><span class="p">,</span> <span class="nv">!bar</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="nv">!baz</span> <span class="nv-Anonymous">!2</span>
+<span class="p">}</span>
+
+<span class="k">declare</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span><span class="p">)</span>
+
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</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-Anonymous">!2</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">!"some string"</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="kt">metadata</span> <span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="k">null</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv">!"other"</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@global</span><span class="p">,</span> <span class="k">i32</span> <span class="m">7</span><span class="p">}</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{}</span>
+</pre></div>
+</div>
+<p>should now be written as:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@g</span> <span class="p">=</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">0</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%v</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span> <span class="k">i32</span> <span class="nv">%v</span><span class="p">)</span> <span class="c">; The only legal place for function-local</span>
+                                      <span class="c">; metadata.</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@global</span><span class="p">)</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span> <span class="nv-Anonymous">!0</span><span class="p">)</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span> <span class="p">!{</span><span class="nv">!"string"</span><span class="p">})</span>
+  <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span> <span class="p">!{!{</span><span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="nv">!"string"</span><span class="p">}})</span>
+  <span class="k">ret</span> <span class="kt">void</span><span class="p">,</span> <span class="nv">!bar</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="nv">!baz</span> <span class="nv-Anonymous">!2</span>
+<span class="p">}</span>
+
+<span class="k">declare</span> <span class="kt">void</span> <span class="vg">@llvm.md</span><span class="p">(</span><span class="kt">metadata</span><span class="p">)</span>
+
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="nv">!"some string"</span><span class="p">}</span>
+<span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="k">null</span><span class="p">,</span> <span class="nv">!"other"</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@global</span><span class="p">,</span> <span class="k">i32</span> <span class="m">7</span><span class="p">}</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="p">!{}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="distinct-metadata-nodes">
+<h4><a class="toc-backref" href="#id8">Distinct metadata nodes</a><a class="headerlink" href="#distinct-metadata-nodes" title="Permalink to this headline">¶</a></h4>
+<p>Metadata nodes can opt-out of uniquing, using the keyword <tt class="docutils literal"><span class="pre">distinct</span></tt>.
+Distinct nodes are still owned by the context, but are stored in a side table,
+and not uniqued.</p>
+<p>In LLVM 3.5, metadata nodes would drop uniquing if an operand changed to
+<tt class="docutils literal"><span class="pre">null</span></tt> during optimizations.  This is no longer true.  However, if an operand
+change causes a uniquing collision, they become <tt class="docutils literal"><span class="pre">distinct</span></tt>.  Unlike LLVM 3.5,
+where serializing to assembly or bitcode would re-unique the nodes, they now
+remain <tt class="docutils literal"><span class="pre">distinct</span></tt>.</p>
+<p>The following IR:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>!named = !{!0, !1, !2, !3, !4, !5, !6, !7, !8}
+
+!0 = !{}
+!1 = !{}
+!2 = distinct !{}
+!3 = distinct !{}
+!4 = !{!0}
+!5 = distinct !{!0}
+!6 = !{!4, !{}, !5}
+!7 = !{!{!0}, !0, !5}
+!8 = distinct !{!{!0}, !0, !5}
+</pre></div>
+</div>
+<p>is equivalent to the following:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>!named = !{!0, !0, !1, !2, !3, !4, !5, !5, !6}
+
+!0 = !{}
+!1 = distinct !{}
+!2 = distinct !{}
+!3 = !{!0}
+!4 = distinct !{!0}
+!5 = !{!3, !0, !4}
+!6 = distinct !{!3, !0, !4}
+</pre></div>
+</div>
+</div>
+<div class="section" id="constructing-cyclic-graphs">
+<h4><a class="toc-backref" href="#id9">Constructing cyclic graphs</a><a class="headerlink" href="#constructing-cyclic-graphs" title="Permalink to this headline">¶</a></h4>
+<p>During graph construction, if a metadata node transitively references a forward
+declaration, the node itself is considered “unresolved” until the forward
+declaration resolves.  An unresolved node can RAUW itself to support uniquing.
+Nodes automatically resolve once all their operands have resolved.</p>
+<p>However, cyclic graphs prevent the nodes from resolving.  An API client that
+constructs a cyclic graph must call <tt class="docutils literal"><span class="pre">resolveCycles()</span></tt> to resolve nodes in the
+cycle.</p>
+<p>To save self-references from that burden, self-referencing nodes are implicitly
+<tt class="docutils literal"><span class="pre">distinct</span></tt>.  So the following IR:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">!named</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">,</span> <span class="nv-Anonymous">!1</span><span class="p">,</span> <span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="nv-Anonymous">!3</span><span class="p">,</span> <span class="nv-Anonymous">!4</span><span class="p">}</span>
+
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!1</span><span class="p">}</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="nv-Anonymous">!1</span><span class="p">}</span>
+<span class="nv-Anonymous">!3</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="nv-Anonymous">!1</span><span class="p">}</span>
+<span class="nv-Anonymous">!4</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="nv-Anonymous">!1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>is equivalent to:</p>
+<div class="highlight-llvm"><div class="highlight"><pre>!named = !{!0, !1, !2, !3, !3}
+
+!0 = distinct !{!0}
+!1 = distinct !{!1}
+!2 = distinct !{!2, !1}
+!3 = !{!2, !1}
+</pre></div>
+</div>
+</div>
+<div class="section" id="mdlocation-aka-debugloc-aka-dilocation">
+<h4><a class="toc-backref" href="#id10">MDLocation (aka DebugLoc aka DILocation)</a><a class="headerlink" href="#mdlocation-aka-debugloc-aka-dilocation" title="Permalink to this headline">¶</a></h4>
+<p>There’s a new first-class metadata construct called <tt class="docutils literal"><span class="pre">MDLocation</span></tt> (to be
+followed in subsequent releases by others).  It’s used for the locations
+referenced by <tt class="docutils literal"><span class="pre">!dbg</span></tt> metadata attachments.</p>
+<p>For example, if an old <tt class="docutils literal"><span class="pre">!dbg</span></tt> attachment looked like this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@foo</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%a</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%b</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv">%add</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%a</span><span class="p">,</span> <span class="nv">%b</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!0</span>
+  <span class="k">ret</span> <span class="nv">%add</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!1</span>
+<span class="p">}</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">10</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">!2</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!1</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">20</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">!3</span><span class="p">)</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{...}</span>
+<span class="nv-Anonymous">!3</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{...}</span>
+</pre></div>
+</div>
+<p>the new attachment looks like this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@foo</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%a</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%b</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+  <span class="nv">%add</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%a</span><span class="p">,</span> <span class="nv">%b</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!0</span>
+  <span class="k">ret</span> <span class="nv">%add</span><span class="p">,</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!1</span>
+<span class="p">}</span>
+
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="nv">!MDLocation</span><span class="p">(</span><span class="nl">line:</span> <span class="m">10</span><span class="p">,</span> <span class="nl">column:</span> <span class="m">3</span><span class="p">,</span> <span class="nl">scope:</span> <span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="nl">inlinedAt:</span> <span class="nv-Anonymous">!1</span><span class="p">)</span>
+<span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="nv">!MDLocation</span><span class="p">(</span><span class="nl">line:</span> <span class="m">20</span><span class="p">,</span> <span class="nl">column:</span> <span class="m">7</span><span class="p">,</span> <span class="nl">scope:</span> <span class="nv-Anonymous">!3</span><span class="p">)</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="p">!{...}</span>
+<span class="nv-Anonymous">!3</span> <span class="p">=</span> <span class="p">!{...}</span>
+</pre></div>
+</div>
+<p>The fields are named, can be reordered, and have sane defaults if left out
+(although <tt class="docutils literal"><span class="pre">scope:</span></tt> is required).</p>
+</div>
+</div>
+<div class="section" id="alias-syntax-change">
+<h3><a class="toc-backref" href="#id11">Alias syntax change</a><a class="headerlink" href="#alias-syntax-change" title="Permalink to this headline">¶</a></h3>
+<p>The syntax for aliases is now closer to what is used for global variables</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@a</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">global</span> <span class="p">...</span>
+<span class="vg">@b</span> <span class="p">=</span> <span class="k">weak</span> <span class="k">alias</span> <span class="p">...</span>
+</pre></div>
+</div>
+<p>The order of the <tt class="docutils literal"><span class="pre">alias</span></tt> keyword and the linkage was swapped before.</p>
+</div>
+<div class="section" id="the-old-jit-has-been-removed">
+<h3><a class="toc-backref" href="#id12">The old JIT has been removed</a><a class="headerlink" href="#the-old-jit-has-been-removed" title="Permalink to this headline">¶</a></h3>
+<p>All users should transition to MCJIT.</p>
+</div>
+<div class="section" id="object-binary-doesn-t-own-the-file-buffer">
+<h3><a class="toc-backref" href="#id13">object::Binary doesn’t own the file buffer</a><a class="headerlink" href="#object-binary-doesn-t-own-the-file-buffer" title="Permalink to this headline">¶</a></h3>
+<p>It is now just a wrapper, which simplifies using object::Binary with other
+users of the underlying file.</p>
+</div>
+<div class="section" id="ir-in-object-files-is-now-supported">
+<h3><a class="toc-backref" href="#id14">IR in object files is now supported</a><a class="headerlink" href="#ir-in-object-files-is-now-supported" title="Permalink to this headline">¶</a></h3>
+<p>Regular object files can contain IR in a section named <tt class="docutils literal"><span class="pre">.llvmbc</span></tt>.</p>
+</div>
+<div class="section" id="the-gold-plugin-has-been-rewritten">
+<h3><a class="toc-backref" href="#id15">The gold plugin has been rewritten</a><a class="headerlink" href="#the-gold-plugin-has-been-rewritten" title="Permalink to this headline">¶</a></h3>
+<p>It is now implemented directly on top of lib/Linker instead of <tt class="docutils literal"><span class="pre">lib/LTO</span></tt>.
+The API of <tt class="docutils literal"><span class="pre">lib/LTO</span></tt> is sufficiently different from gold’s view of the
+linking process that some cases could not be conveniently implemented.</p>
+<p>The new implementation is also lazier and has a <tt class="docutils literal"><span class="pre">save-temps</span></tt> option.</p>
+</div>
+<div class="section" id="change-in-the-representation-of-lazy-loaded-funcs">
+<h3><a class="toc-backref" href="#id16">Change in the representation of lazy loaded funcs</a><a class="headerlink" href="#change-in-the-representation-of-lazy-loaded-funcs" title="Permalink to this headline">¶</a></h3>
+<p>Lazy loaded functions are now represented in a way that <tt class="docutils literal"><span class="pre">isDeclaration</span></tt>
+returns the correct answer even before reading the body.</p>
+</div>
+<div class="section" id="the-opt-option-std-compile-opts-was-removed">
+<h3><a class="toc-backref" href="#id17">The opt option -std-compile-opts was removed</a><a class="headerlink" href="#the-opt-option-std-compile-opts-was-removed" title="Permalink to this headline">¶</a></h3>
+<p>It was effectively an alias of -O3.</p>
+</div>
+<div class="section" id="python-2-7-is-now-required">
+<h3><a class="toc-backref" href="#id18">Python 2.7 is now required</a><a class="headerlink" href="#python-2-7-is-now-required" title="Permalink to this headline">¶</a></h3>
+<p>This was done to simplify compatibility with python 3.</p>
+</div>
+<div class="section" id="the-leak-detector-has-been-removed">
+<h3><a class="toc-backref" href="#id19">The leak detector has been removed</a><a class="headerlink" href="#the-leak-detector-has-been-removed" title="Permalink to this headline">¶</a></h3>
+<p>In practice, tools like asan and valgrind were finding way more bugs than
+the old leak detector, so it was removed.</p>
+</div>
+<div class="section" id="new-comdat-syntax">
+<h3><a class="toc-backref" href="#id20">New comdat syntax</a><a class="headerlink" href="#new-comdat-syntax" title="Permalink to this headline">¶</a></h3>
+<p>The syntax of comdats was changed to</p>
+<div class="highlight-llvm"><div class="highlight"><pre>$c = comdat any
+ at g = global i32 0, comdat($c)
+ at c = global i32 0, comdat
+</pre></div>
+</div>
+<p>The version without the parentheses is a syntactic sugar for a comdat with
+the same name as the global.</p>
+</div>
+<div class="section" id="added-support-for-win64-unwind-information">
+<h3><a class="toc-backref" href="#id21">Added support for Win64 unwind information</a><a class="headerlink" href="#added-support-for-win64-unwind-information" title="Permalink to this headline">¶</a></h3>
+<p>LLVM now obeys the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/tawsa7cb.aspx">Win64 prologue and epilogue conventions</a> documented by
+Microsoft. Unwind information is also emitted into the .xdata section.</p>
+<p>As a result of the ABI-required prologue changes, it is now no longer possible
+to unwind the stack using a standard frame pointer walk on Win64. Instead,
+users should call <tt class="docutils literal"><span class="pre">CaptureStackBackTrace</span></tt>, or implement equivalent
+functionality by consulting the unwind tables present in the binary.</p>
+</div>
+<div class="section" id="diagnostic-infrastructure-used-by-lib-linker-and-lib-bitcode">
+<h3><a class="toc-backref" href="#id22">Diagnostic infrastructure used by lib/Linker and lib/Bitcode</a><a class="headerlink" href="#diagnostic-infrastructure-used-by-lib-linker-and-lib-bitcode" title="Permalink to this headline">¶</a></h3>
+<p>These libraries now use the diagnostic handler to print errors and warnings.
+This provides better error messages and simpler error handling.</p>
+</div>
+<div class="section" id="the-preservesource-linker-mode-was-removed">
+<h3><a class="toc-backref" href="#id23">The PreserveSource linker mode was removed</a><a class="headerlink" href="#the-preservesource-linker-mode-was-removed" title="Permalink to this headline">¶</a></h3>
+<p>It was fairly broken and was removed.</p>
+<p>The mode is currently still available in the C API for source
+compatibility, but it doesn’t have any effect.</p>
+</div>
+<div class="section" id="garbage-collection">
+<h3><a class="toc-backref" href="#id24">Garbage Collection</a><a class="headerlink" href="#garbage-collection" title="Permalink to this headline">¶</a></h3>
+<p>A new experimental mechanism for describing a garbage collection safepoint was
+added to LLVM.  The new mechanism was not complete at the point this release
+was branched so it is recommended that anyone interested in using this
+mechanism track the ongoing development work on tip of tree.  The hope is that
+these intrinsics will be ready for general use by 3.7.  Documentation can be
+found <a class="reference external" href="http://llvm.org/docs/Statepoints.html">here</a>.</p>
+<p>The existing gc.root implementation is still supported and as fully featured
+as it ever was.  However, two features from GCStrategy will likely be removed
+in the 3.7 release (performCustomLowering and findCustomSafePoints).  If you
+have a use case for either, please mention it on llvm-dev so that it can be
+considered for future development.</p>
+<p>We are expecting to migrate away from gc.root in the 3.8 time frame,
+but both mechanisms will be supported in 3.7.</p>
+</div>
+<div class="section" id="changes-to-the-mips-target">
+<h3><a class="toc-backref" href="#id25">Changes to the MIPS Target</a><a class="headerlink" href="#changes-to-the-mips-target" title="Permalink to this headline">¶</a></h3>
+<p>During this release the MIPS target has reached a few major milestones. The
+compiler has gained support for MIPS-II and MIPS-III; become ABI-compatible
+with GCC for big and little endian O32, N32, and N64; and is now able to
+compile the Linux kernel for 32-bit targets. Additionally, LLD now supports
+microMIPS for the O32 ABI on little endian targets, and code generation for
+microMIPS is almost completely passing the test-suite.</p>
+<div class="section" id="abi">
+<h4><a class="toc-backref" href="#id26">ABI</a><a class="headerlink" href="#abi" title="Permalink to this headline">¶</a></h4>
+<p>A large number of bugs have been fixed for big-endian MIPS targets using the
+N32 and N64 ABI’s as well as a small number of bugs affecting other ABI’s.
+Please note that some of these bugs will still affect LLVM-IR generated by
+LLVM 3.5 since correct code generation depends on appropriate usage of the
+<tt class="docutils literal"><span class="pre">inreg</span></tt>, <tt class="docutils literal"><span class="pre">signext</span></tt>, and <tt class="docutils literal"><span class="pre">zeroext</span></tt> attributes on all function arguments
+and returns.</p>
+<p>There are far too many corrections to provide a complete list but here are a
+few notable ones:</p>
+<ul class="simple">
+<li>Big-endian N32 and N64 now interlinks successfully with GCC compiled code.
+Previously this didn’t work for the majority of cases.</li>
+<li>The registers used to return a structure containing a single 128-bit floating
+point member on the N32/N64 ABI’s have been changed from those specified by
+the ABI documentation to match those used by GCC. The documentation specifies
+that <tt class="docutils literal"><span class="pre">$f0</span></tt> and <tt class="docutils literal"><span class="pre">$f2</span></tt> should be used but GCC has used <tt class="docutils literal"><span class="pre">$f0</span></tt> and <tt class="docutils literal"><span class="pre">$f1</span></tt>
+for many years.</li>
+<li>Returning a zero-byte struct no longer causes arguments to be read from the
+wrong registers when using the O32 ABI.</li>
+<li>The exception personality has been changed for 64-bit MIPS targets to
+eliminate warnings about relocations in a read-only section.</li>
+<li>Incorrect usage of odd-numbered single-precision floating point registers
+has been fixed when the fastcc calling convention is used with 64-bit FPU’s
+and -mno-odd-spreg.</li>
+</ul>
+</div>
+<div class="section" id="llvmlinux">
+<h4><a class="toc-backref" href="#id27">LLVMLinux</a><a class="headerlink" href="#llvmlinux" title="Permalink to this headline">¶</a></h4>
+<p>It is now possible to compile the Linux kernel. This currently requires a small
+number of kernel patches. See the <a class="reference external" href="http://llvm.linuxfoundation.org/index.php/Main_Page">LLVMLinux project</a> for details.</p>
+<ul class="simple">
+<li>Added -mabicalls and -mno-abicalls. The implementation may not be complete
+but works sufficiently well for the Linux kernel.</li>
+<li>Fixed multiple compatibility issues between LLVM’s inline assembly support
+and GCC’s.</li>
+<li>Added support for a number of directives used by Linux to the Integrated
+Assembler.</li>
+</ul>
+</div>
+<div class="section" id="miscellaneous">
+<h4><a class="toc-backref" href="#id28">Miscellaneous</a><a class="headerlink" href="#miscellaneous" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li>Attempting to disassemble l[wd]c[23], s[wd]c[23], cache, and pref no longer
+triggers an assertion.</li>
+<li>Added -muclibc and -mglibc to support toolchains that provide both uClibC and
+GLibC.</li>
+<li>__SIZEOF_INT128__ is no longer defined for 64-bit targets since 128-bit
+integers do not work at this time for this target.</li>
+<li>Using $t4-$t7 with the N32 and N64 ABI is deprecated when <tt class="docutils literal"><span class="pre">-fintegrated-as</span></tt>
+is in use and will be removed in LLVM 3.7. These names have never been
+supported by the GNU Assembler for these ABI’s.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="changes-to-the-powerpc-target">
+<h3><a class="toc-backref" href="#id29">Changes to the PowerPC Target</a><a class="headerlink" href="#changes-to-the-powerpc-target" title="Permalink to this headline">¶</a></h3>
+<p>There are numerous improvements to the PowerPC target in this release:</p>
+<ul class="simple">
+<li>LLVM now generates the Vector-Scalar eXtension (VSX) instructions from
+version 2.06 of the Power ISA, for both big- and little-endian targets.</li>
+<li>LLVM now has a POWER8 instruction scheduling description.</li>
+<li>AddressSanitizer (ASan) support is now fully functional.</li>
+<li>Performance of simple atomic accesses has been greatly improved.</li>
+<li>Atomic fences now use light-weight syncs where possible, again providing
+significant performance benefit.</li>
+<li>The PowerPC target now supports PIC levels (-fPIC vs. -fpic).</li>
+<li>PPC32 SVR4 now supports small-model PIC.</li>
+<li>Experimental support for the stackmap/patchpoint intrinsics has been added.</li>
+<li>There have been many smaller bug fixes and performance improvements.</li>
+</ul>
+</div>
+<div class="section" id="changes-to-the-ocaml-bindings">
+<h3><a class="toc-backref" href="#id30">Changes to the OCaml bindings</a><a class="headerlink" href="#changes-to-the-ocaml-bindings" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>The bindings now require OCaml >=4.00.0, ocamlfind,
+ctypes >=0.3.0 <0.4 and OUnit 2 if tests are enabled.</li>
+<li>The bindings can now be built using cmake as well as autoconf.</li>
+<li>LLVM 3.5 has, unfortunately, shipped a broken Llvm_executionengine
+implementation. In LLVM 3.6, the bindings now fully support MCJIT,
+however the interface is reworked from scratch using ctypes
+and is not backwards compatible.</li>
+<li>Llvm_linker.Mode was removed following the changes in LLVM.
+This breaks the interface of Llvm_linker.</li>
+<li>All combinations of ocamlc/ocamlc -custom/ocamlopt and shared/static
+builds of LLVM are now supported.</li>
+<li>Absolute paths are not embedded into the OCaml libraries anymore.
+Either OCaml >=4.02.2 must be used, which includes an rpath-like $ORIGIN
+mechanism, or META file must be updated for out-of-tree installations;
+see r221139.</li>
+<li>As usual, many more functions have been exposed to OCaml.</li>
+</ul>
+</div>
+<div class="section" id="go-bindings">
+<h3><a class="toc-backref" href="#id31">Go bindings</a><a class="headerlink" href="#go-bindings" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>A set of Go bindings based on <a class="reference external" href="https://github.com/go-llvm/llvm">gollvm</a>
+was introduced in this release.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="external-open-source-projects-using-llvm-3-6">
+<h2><a class="toc-backref" href="#id32">External Open Source Projects Using LLVM 3.6</a><a class="headerlink" href="#external-open-source-projects-using-llvm-3-6" 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.6.</p>
+<div class="section" id="portable-computing-language-pocl">
+<h3><a class="toc-backref" href="#id33">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://portablecl.org/">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="#id34">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 customized
+exposed datapath processors based on the Transport triggered
+architecture (TTA).</p>
+<p>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 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="likely">
+<h3><a class="toc-backref" href="#id35">Likely</a><a class="headerlink" href="#likely" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://www.liblikely.org">Likely</a> is an embeddable just-in-time Lisp for
+image recognition and heterogeneous computing. Algorithms are just-in-time
+compiled using LLVM’s MCJIT infrastructure to execute on single or
+multi-threaded CPUs and potentially OpenCL SPIR or CUDA enabled GPUs.
+Likely seeks to explore new optimizations for statistical learning
+algorithms by moving them from an offline model generation step to the
+compile-time evaluation of a function (the learning algorithm) with constant
+arguments (the training data).</p>
+</div>
+<div class="section" id="ldc-the-llvm-based-d-compiler">
+<h3><a class="toc-backref" href="#id36">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, FreeBSD and Windows and also Linux on
+PowerPC (32/64 bit). Ports to other architectures like ARM, AArch64 and MIPS64
+are underway.</p>
+</div>
+<div class="section" id="llvmsharp-clangsharp">
+<h3><a class="toc-backref" href="#id37">LLVMSharp & ClangSharp</a><a class="headerlink" href="#llvmsharp-clangsharp" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://www.llvmsharp.org">LLVMSharp</a> and
+<a class="reference external" href="http://www.clangsharp.org">ClangSharp</a> are type-safe C# bindings for
+Microsoft.NET and Mono that Platform Invoke into the native libraries.
+ClangSharp is self-hosted and is used to generated LLVMSharp using the
+LLVM-C API.</p>
+<p><a class="reference external" href="http://www.llvmsharp.org/Kaleidoscope/">LLVMSharp Kaleidoscope Tutorials</a>
+are instructive examples of writing a compiler in C#, with certain improvements
+like using the visitor pattern to generate LLVM IR.</p>
+<p><a class="reference external" href="http://www.clangsharp.org/PInvoke/">ClangSharp PInvoke Generator</a> is the
+self-hosting mechanism for LLVM/ClangSharp and is demonstrative of using
+LibClang to generate Platform Invoke (PInvoke) signatures for C APIs.</p>
+</div>
+</div>
+<div class="section" id="additional-information">
+<h2><a class="toc-backref" href="#id38">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-2014, LLVM Project.
+      Last updated on 2015-02-27.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/ReleaseProcess.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/ReleaseProcess.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/ReleaseProcess.html (added)
+++ www-releases/trunk/3.6.0/docs/ReleaseProcess.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,255 @@
+
+<!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>How To Validate a New Release — LLVM 3.6 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.6',
+        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.6 documentation" href="index.html" />
+    <link rel="next" title="Code Reviews with Phabricator" href="Phabricator.html" />
+    <link rel="prev" title="Advice on Packaging LLVM" href="Packaging.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="Packaging.html" title="Advice on Packaging 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="how-to-validate-a-new-release">
+<h1>How To Validate a New Release<a class="headerlink" href="#how-to-validate-a-new-release" 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="id9">Introduction</a></li>
+<li><a class="reference internal" href="#scripts" id="id10">Scripts</a></li>
+<li><a class="reference internal" href="#test-suite" id="id11">Test Suite</a></li>
+<li><a class="reference internal" href="#pre-release-process" id="id12">Pre-Release Process</a></li>
+<li><a class="reference internal" href="#release-process" id="id13">Release Process</a></li>
+<li><a class="reference internal" href="#bug-reporting-process" id="id14">Bug Reporting Process</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id9">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains information about testing the release candidates that will
+ultimately be the next LLVM release. For more information on how to manage the
+actual release, please refer to <a class="reference internal" href="HowToReleaseLLVM.html"><em>How To Release LLVM To The Public</em></a>.</p>
+<div class="section" id="overview-of-the-release-process">
+<h3>Overview of the Release Process<a class="headerlink" href="#overview-of-the-release-process" title="Permalink to this headline">¶</a></h3>
+<p>Once the release process starts, the Release Manager will ask for volunteers,
+and it’ll be the role of each volunteer to:</p>
+<ul class="simple">
+<li>Test and benchmark the previous release</li>
+<li>Test and benchmark each release candidate, comparing to the previous release and candidates</li>
+<li>Identify, reduce and report every regression found during tests and benchmarks</li>
+<li>Make sure the critical bugs get fixed and merged to the next release candidate</li>
+</ul>
+<p>Not all bugs or regressions are show-stoppers and it’s a bit of a grey area what
+should be fixed before the next candidate and what can wait until the next release.</p>
+<p>It’ll depend on:</p>
+<ul class="simple">
+<li>The severity of the bug, how many people it affects and if it’s a regression or a
+known bug. Known bugs are “unsupported features” and some bugs can be disabled if
+they have been implemented recently.</li>
+<li>The stage in the release. Less critical bugs should be considered to be fixed between
+RC1 and RC2, but not so much at the end of it.</li>
+<li>If it’s a correctness or a performance regression. Performance regression tends to be
+taken more lightly than correctness.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="scripts">
+<span id="id1"></span><h2><a class="toc-backref" href="#id10">Scripts</a><a class="headerlink" href="#scripts" title="Permalink to this headline">¶</a></h2>
+<p>The scripts are in the <tt class="docutils literal"><span class="pre">utils/release</span></tt> directory.</p>
+<div class="section" id="test-release-sh">
+<h3>test-release.sh<a class="headerlink" href="#test-release-sh" title="Permalink to this headline">¶</a></h3>
+<p>This script will check-out, configure and compile LLVM+Clang (+ most add-ons, like <tt class="docutils literal"><span class="pre">compiler-rt</span></tt>,
+<tt class="docutils literal"><span class="pre">libcxx</span></tt> and <tt class="docutils literal"><span class="pre">clang-extra-tools</span></tt>) in three stages, and will test the final stage.
+It’ll have installed the final binaries on the Phase3/Releasei(+Asserts) directory, and
+that’s the one you should use for the test-suite and other external tests.</p>
+<p>To run the script on a specific release candidate run:</p>
+<div class="highlight-python"><div class="highlight"><pre>./test-release.sh \
+     -release 3.3 \
+     -rc 1 \
+     -no-64bit \
+     -test-asserts \
+     -no-compare-files
+</pre></div>
+</div>
+<p>Each system will require different options. For instance, x86_64 will obviously not need
+<tt class="docutils literal"><span class="pre">-no-64bit</span></tt> while 32-bit systems will, or the script will fail.</p>
+<p>The important flags to get right are:</p>
+<ul class="simple">
+<li>On the pre-release, you should change <tt class="docutils literal"><span class="pre">-rc</span> <span class="pre">1</span></tt> to <tt class="docutils literal"><span class="pre">-final</span></tt>. On RC2, change it to <tt class="docutils literal"><span class="pre">-rc</span> <span class="pre">2</span></tt> and so on.</li>
+<li>On non-release testing, you can use <tt class="docutils literal"><span class="pre">-final</span></tt> in conjunction with <tt class="docutils literal"><span class="pre">-no-checkout</span></tt>, but you’ll have to
+create the <tt class="docutils literal"><span class="pre">final</span></tt> directory by hand and link the correct source dir to <tt class="docutils literal"><span class="pre">final/llvm.src</span></tt>.</li>
+<li>For release candidates, you need <tt class="docutils literal"><span class="pre">-test-asserts</span></tt>, or it won’t create a “Release+Asserts” directory,
+which is needed for release testing and benchmarking. This will take twice as long.</li>
+<li>On the final candidate you just need Release builds, and that’s the binary directory you’ll have to pack.</li>
+</ul>
+<p>This script builds three phases of Clang+LLVM twice each (Release and Release+Asserts), so use
+screen or nohup to avoid headaches, since it’ll take a long time.</p>
+<p>Use the <tt class="docutils literal"><span class="pre">--help</span></tt> option to see all the options and chose it according to your needs.</p>
+</div>
+<div class="section" id="findregressions-nightly-py">
+<h3>findRegressions-nightly.py<a class="headerlink" href="#findregressions-nightly-py" title="Permalink to this headline">¶</a></h3>
+<p>TODO</p>
+</div>
+</div>
+<div class="section" id="test-suite">
+<span id="id2"></span><h2><a class="toc-backref" href="#id11">Test Suite</a><a class="headerlink" href="#test-suite" title="Permalink to this headline">¶</a></h2>
+<p>Follow the <a class="reference external" href="http://llvm.org/docs/lnt/quickstart.html">LNT Quick Start Guide</a> link on how to set-up the test-suite</p>
+<p>The binary location you’ll have to use for testing is inside the <tt class="docutils literal"><span class="pre">rcN/Phase3/Release+Asserts/llvmCore-REL-RC.install</span></tt>.
+Link that directory to an easier location and run the test-suite.</p>
+<p>An example on the run command line, assuming you created a link from the correct
+install directory to <tt class="docutils literal"><span class="pre">~/devel/llvm/install</span></tt>:</p>
+<div class="highlight-python"><div class="highlight"><pre>./sandbox/bin/python sandbox/bin/lnt runtest \
+    nt \
+    -j4 \
+    --sandbox sandbox \
+    --test-suite ~/devel/llvm/test/test-suite \
+    --cc ~/devel/llvm/install/bin/clang \
+    --cxx ~/devel/llvm/install/bin/clang++
+</pre></div>
+</div>
+<p>It should have no new regressions, compared to the previous release or release candidate. You don’t need to fix
+all the bugs in the test-suite, since they’re not necessarily meant to pass on all architectures all the time. This is
+due to the nature of the result checking, which relies on direct comparison, and most of the time, the failures are
+related to bad output checking, rather than bad code generation.</p>
+<p>If the errors are in LLVM itself, please report every single regression found as blocker, and all the other bugs
+as important, but not necessarily blocking the release to proceed. They can be set as “known failures” and to be
+fix on a future date.</p>
+</div>
+<div class="section" id="pre-release-process">
+<span id="id4"></span><h2><a class="toc-backref" href="#id12">Pre-Release Process</a><a class="headerlink" href="#pre-release-process" title="Permalink to this headline">¶</a></h2>
+<p>When the release process is announced on the mailing list, you should prepare
+for the testing, by applying the same testing you’ll do on the release candidates,
+on the previous release.</p>
+<p>You should:</p>
+<ul class="simple">
+<li>Download the previous release sources from <a class="reference external" href="http://llvm.org/releases/download.html">http://llvm.org/releases/download.html</a>.</li>
+<li>Run the test-release.sh script on <tt class="docutils literal"><span class="pre">final</span></tt> mode (change <tt class="docutils literal"><span class="pre">-rc</span> <span class="pre">1</span></tt> to <tt class="docutils literal"><span class="pre">-final</span></tt>).</li>
+<li>Once all three stages are done, it’ll test the final stage.</li>
+<li>Using the <tt class="docutils literal"><span class="pre">Phase3/Release+Asserts/llvmCore-MAJ.MIN-final.install</span></tt> base, run the test-suite.</li>
+</ul>
+<p>If the final phase’s <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-all</span></tt> failed, it’s a good idea to also test the
+intermediate stages by going on the obj directory and running <tt class="docutils literal"><span class="pre">make</span> <span class="pre">check-all</span></tt> to find
+if there’s at least one stage that passes (helps when reducing the error for bug report
+purposes).</p>
+</div>
+<div class="section" id="release-process">
+<span id="id6"></span><h2><a class="toc-backref" href="#id13">Release Process</a><a class="headerlink" href="#release-process" title="Permalink to this headline">¶</a></h2>
+<p>When the Release Manager sends you the release candidate, download all sources,
+unzip on the same directory (there will be sym-links from the appropriate places
+to them), and run the release test as above.</p>
+<p>You should:</p>
+<ul class="simple">
+<li>Download the current candidate sources from where the release manager points you
+(ex. <a class="reference external" href="http://llvm.org/pre-releases/3.3/rc1/">http://llvm.org/pre-releases/3.3/rc1/</a>).</li>
+<li>Repeat the steps above with <tt class="docutils literal"><span class="pre">-rc</span> <span class="pre">1</span></tt>, <tt class="docutils literal"><span class="pre">-rc</span> <span class="pre">2</span></tt> etc modes and run the test-suite
+the same way.</li>
+<li>Compare the results, report all errors on Bugzilla and publish the binary blob
+where the release manager can grab it.</li>
+</ul>
+<p>Once the release manages announces that the latest candidate is the good one, you
+have to pack the <tt class="docutils literal"><span class="pre">Release</span></tt> (no Asserts) install directory on <tt class="docutils literal"><span class="pre">Phase3</span></tt> and that
+will be the official binary.</p>
+<ul class="simple">
+<li>Rename (or link) <tt class="docutils literal"><span class="pre">clang+llvm-REL-ARCH-ENV</span></tt> to the .install directory</li>
+<li>Tar that into the same name with <tt class="docutils literal"><span class="pre">.tar.gz</span></tt> extensioan from outside the directory</li>
+<li>Make it available for the release manager to download</li>
+</ul>
+</div>
+<div class="section" id="bug-reporting-process">
+<span id="bug-reporting"></span><h2><a class="toc-backref" href="#id14">Bug Reporting Process</a><a class="headerlink" href="#bug-reporting-process" title="Permalink to this headline">¶</a></h2>
+<p>If you found regressions or failures when comparing a release candidate with the
+previous release, follow the rules below:</p>
+<ul class="simple">
+<li>Critical bugs on compilation should be fixed as soon as possible, possibly before
+releasing the binary blobs.</li>
+<li>Check-all tests should be fixed before the next release candidate, but can wait
+until the test-suite run is finished.</li>
+<li>Bugs in the test suite or unimportant check-all tests can be fixed in between
+release candidates.</li>
+<li>New features or recent big changes, when close to the release, should have done
+in a way that it’s easy to disable. If they misbehave, prefer disabling them than
+releasing an unstable (but untested) binary package.</li>
+</ul>
+</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="Packaging.html" title="Advice on Packaging 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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/SegmentedStacks.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/SegmentedStacks.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/SegmentedStacks.html (added)
+++ www-releases/trunk/3.6.0/docs/SegmentedStacks.html Fri Feb 27 12:44:09 2015
@@ -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.6 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.6',
+        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.6 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. Segmented stacks are
+enabled with the <tt class="docutils literal"><span class="pre">"split-stack"</span></tt> attribute on LLVM functions.</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"><div class="highlight"><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>
+</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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/SourceLevelDebugging.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/SourceLevelDebugging.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/SourceLevelDebugging.html (added)
+++ www-releases/trunk/3.6.0/docs/SourceLevelDebugging.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,1878 @@
+
+<!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.6 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.6',
+        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.6 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="#complex-expressions" id="id22">Complex Expressions</a></li>
+<li><a class="reference internal" href="#debugger-intrinsic-functions" id="id23">Debugger intrinsic functions</a></li>
+<li><a class="reference internal" href="#llvm-dbg-declare" id="id24"><tt class="docutils literal"><span class="pre">llvm.dbg.declare</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-dbg-value" id="id25"><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="id26">Object lifetimes and scoping</a></li>
+<li><a class="reference internal" href="#c-c-front-end-specific-debug-information" id="id27">C/C++ front-end specific debug information</a><ul>
+<li><a class="reference internal" href="#c-c-source-file-information" id="id28">C/C++ source file information</a></li>
+<li><a class="reference internal" href="#c-c-global-variable-information" id="id29">C/C++ global variable information</a></li>
+<li><a class="reference internal" href="#c-c-function-information" id="id30">C/C++ function information</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id1" id="id31">Debugging information format</a><ul>
+<li><a class="reference internal" href="#debugging-information-extension-for-objective-c-properties" id="id32">Debugging Information Extension for Objective C Properties</a><ul>
+<li><a class="reference internal" href="#id2" id="id33">Introduction</a></li>
+<li><a class="reference internal" href="#proposal" id="id34">Proposal</a></li>
+<li><a class="reference internal" href="#new-dwarf-tags" id="id35">New DWARF Tags</a></li>
+<li><a class="reference internal" href="#new-dwarf-attributes" id="id36">New DWARF Attributes</a></li>
+<li><a class="reference internal" href="#new-dwarf-constants" id="id37">New DWARF Constants</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#name-accelerator-tables" id="id38">Name Accelerator Tables</a><ul>
+<li><a class="reference internal" href="#id3" id="id39">Introduction</a></li>
+<li><a class="reference internal" href="#hash-tables" id="id40">Hash Tables</a><ul>
+<li><a class="reference internal" href="#standard-hash-tables" id="id41">Standard Hash Tables</a></li>
+<li><a class="reference internal" href="#name-hash-tables" id="id42">Name Hash Tables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#details" id="id43">Details</a><ul>
+<li><a class="reference internal" href="#header-layout" id="id44">Header Layout</a></li>
+<li><a class="reference internal" href="#fixed-lookup" id="id45">Fixed Lookup</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id4" id="id46">Contents</a></li>
+<li><a class="reference internal" href="#language-extensions-and-file-format-changes" id="id47">Language Extensions and File Format Changes</a><ul>
+<li><a class="reference internal" href="#objective-c-extensions" id="id48">Objective-C Extensions</a></li>
+<li><a class="reference internal" href="#mach-o-changes" id="id49">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 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>Most of the string and integer fields in descriptors are packed into a single,
+null-separated <tt class="docutils literal"><span class="pre">mdstring</span></tt>.  The first field of the header is always an
+<tt class="docutils literal"><span class="pre">i32</span></tt> containing the DWARF tag value identifying the content of the
+descriptor.</p>
+<p>For clarity of definition in this document, these header fields are described
+below split inside an imaginary <tt class="docutils literal"><span class="pre">DIHeader</span></tt> construct.  This is invalid
+assembly syntax.  In valid IR, these fields are stringified and concatenated,
+separated by <tt class="docutils literal"><span class="pre">\00</span></tt>.</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>!0 = metadata !{
+  DIHeader(
+    i32,       ;; Tag = 17 (DW_TAG_compile_unit)
+    i32,       ;; DWARF language identifier (ex. DW_LANG_C89)
+    mdstring,  ;; Producer (ex. "4.0.1 LLVM (LLVM research group)")
+    i1,        ;; True if this is optimized.
+    mdstring,  ;; Flags
+    i32,       ;; Runtime version
+    mdstring,  ;; Split debug filename
+    i32        ;; Debug info emission kind (1 = Full Debug Info, 2 = Line Tables Only)
+  ),
+  metadata,  ;; Source directory (including trailing slash) & file pair
+  metadata,  ;; List of enums types
+  metadata,  ;; List of retained types
+  metadata,  ;; List of subprograms
+  metadata,  ;; List of global variables
+  metadata   ;; List of imported entities
+}
+</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), a reference to a metadata node containing a pair of
+strings for the source file name and the working directory, as well as an
+identifier string for the compiler that produced it.</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, type information, and imported
+entities (declarations and namespaces).</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>!0 = metadata !{
+  DIHeader(
+    i32       ;; Tag = 41 (DW_TAG_file_type)
+  ),
+  metadata  ;; Source directory (including trailing slash) & file pair
+}
+</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>!1 = metadata !{
+  DIHeader(
+    i32,      ;; Tag = 52 (DW_TAG_variable)
+    mdstring, ;; Name
+    mdstring, ;; Display name (fully qualified C++ name)
+    mdstring, ;; MIPS linkage name (for C++)
+    i32,      ;; Line number where defined
+    i1,       ;; True if the global is local to compile unit (static)
+    i1        ;; True if the global is defined in the compile unit (not extern)
+  ),
+  metadata, ;; Reference to context descriptor
+  metadata, ;; Reference to file where defined
+  metadata, ;; Reference to type descriptor
+  {}*,      ;; Reference to the global variable
+  metadata, ;; The static member declaration, if any
+}
+</pre></div>
+</div>
+<p>These descriptors provide debug information about global variables.  They
+provide details such as name, type and where the variable is defined.  All
+global variables are collected inside the named metadata <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"><div class="highlight"><pre>!2 = metadata !{
+  DIHeader(
+    i32,      ;; Tag = 46 (DW_TAG_subprogram)
+    mdstring, ;; Name
+    mdstring, ;; Display name (fully qualified C++ name)
+    mdstring, ;; MIPS linkage name (for C++)
+    i32,      ;; Line number where defined
+    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
+    i32,      ;; Flags - Artificial, Private, Protected, Explicit, Prototyped.
+    i1,       ;; isOptimized
+    i32       ;; Line number where the scope of the subprogram begins
+  ),
+  metadata, ;; Source directory (including trailing slash) & file pair
+  metadata, ;; Reference to context descriptor
+  metadata, ;; Reference to type descriptor
+  metadata, ;; indicates which base type contains the vtable pointer for the
+            ;; derived class
+  {}*,      ;; Reference to the LLVM function
+  metadata, ;; Lists function template parameters
+  metadata, ;; Function declaration descriptor
+  metadata  ;; List of function variables
+}
+</pre></div>
+</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>!3 = metadata !{
+  DIHeader(
+    i32,      ;; Tag = 11 (DW_TAG_lexical_block)
+    i32,      ;; Line number
+    i32,      ;; Column number
+    i32       ;; Unique ID to identify blocks from a template function
+  ),
+  metadata, ;; Source directory (including trailing slash) & file pair
+  metadata  ;; Reference to context descriptor
+}
+</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>!3 = metadata !{
+  DIHeader(
+    i32,      ;; Tag = 11 (DW_TAG_lexical_block)
+    i32       ;; DWARF path discriminator value
+  ),
+  metadata, ;; Source directory (including trailing slash) & file pair
+  metadata  ;; Reference to the scope we're annotating with a file change
+}
+</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>!4 = metadata !{
+  DIHeader(
+    i32,      ;; Tag = 36 (DW_TAG_base_type)
+    mdstring, ;; Name (may be "" for anonymous types)
+    i32,      ;; Line number where defined (may be 0)
+    i64,      ;; Size in bits
+    i64,      ;; Alignment in bits
+    i64,      ;; Offset in bits
+    i32,      ;; Flags
+    i32       ;; DWARF type encoding
+  ),
+  metadata, ;; Source directory (including trailing slash) & file pair (may be null)
+  metadata  ;; Reference to context
+}
+</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"><div class="highlight"><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>
+<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>!5 = metadata !{
+  DIHeader(
+    i32,      ;; Tag (see below)
+    mdstring, ;; Name (may be "" for anonymous types)
+    i32,      ;; Line number where defined (may be 0)
+    i64,      ;; Size in bits
+    i64,      ;; Alignment in bits
+    i64,      ;; Offset in bits
+    i32       ;; Flags to encode attributes, e.g. private
+  ),
+  metadata, ;; Source directory (including trailing slash) & file pair (may be null)
+  metadata, ;; Reference to context
+  metadata, ;; Reference to type derived from
+  metadata  ;; (optional) Objective C property node
+}
+</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"><div class="highlight"><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>
+</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>!6 = metadata !{
+  DIHeader(
+    i32,      ;; Tag (see below)
+    mdstring, ;; Name (may be "" for anonymous types)
+    i32,      ;; Line number where defined (may be 0)
+    i64,      ;; Size in bits
+    i64,      ;; Alignment in bits
+    i64,      ;; Offset in bits
+    i32,      ;; Flags
+    i32       ;; Runtime languages
+  ),
+  metadata, ;; Source directory (including trailing slash) & file pair (may be null)
+  metadata, ;; Reference to context
+  metadata, ;; Reference to type derived from
+  metadata, ;; Reference to array of member descriptors
+  metadata, ;; Base type containing the vtable pointer for this type
+  metadata, ;; Template parameters
+  mdstring  ;; A unique identifier for type uniquing purpose (may be null)
+}
+</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"><div class="highlight"><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>
+</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>!42 = metadata !{
+  DIHeader(
+    i32,      ;; Tag = 33 (DW_TAG_subrange_type)
+    i64,      ;; Low value
+    i64       ;; High value
+  )
+}
+</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>!6 = metadata !{
+  DIHeader(
+    i32,      ;; Tag = 40 (DW_TAG_enumerator)
+    mdstring, ;; Name
+    i64       ;; Value
+  )
+}
+</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>!7 = metadata !{
+  DIHeader(
+    i32,      ;; Tag (see below)
+    mdstring, ;; Name
+    i32,      ;; 24 bit - Line number where defined
+              ;; 8 bit - Argument number. 1 indicates 1st argument.
+    i32       ;; flags
+  ),
+  metadata, ;; Context
+  metadata, ;; Reference to file where defined
+  metadata, ;; Reference to the type descriptor
+  metadata  ;; (optional) Reference to inline location
+}
+</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"><div class="highlight"><pre>DW_TAG_auto_variable   = 256
+DW_TAG_arg_variable    = 257
+</pre></div>
+</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="complex-expressions">
+<h4><a class="toc-backref" href="#id22">Complex Expressions</a><a class="headerlink" href="#complex-expressions" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><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="p">,</span>      <span class="c">;; DW_TAG_expression</span>
+  <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Complex expressions describe variable storage locations in terms of
+prefix-notated DWARF expressions. Currently the only supported
+operators are <tt class="docutils literal"><span class="pre">DW_OP_plus</span></tt>, <tt class="docutils literal"><span class="pre">DW_OP_deref</span></tt>, and <tt class="docutils literal"><span class="pre">DW_OP_piece</span></tt>.</p>
+<p>The <tt class="docutils literal"><span class="pre">DW_OP_piece</span></tt> operator is used for (typically larger aggregate)
+variables that are fragmented across several locations. It takes two
+i32 arguments, an offset and a size in bytes to describe which piece
+of the variable is at this location.</p>
+</div>
+<div class="section" id="debugger-intrinsic-functions">
+<span id="format-common-intrinsics"></span><h4><a class="toc-backref" href="#id23">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="#id24"><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="#id25"><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="#id26">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>define void @foo() #0 {
+entry:
+ %X = alloca i32, align 4
+  %Y = alloca i32, align 4
+  %Z = alloca i32, align 4
+  call void @llvm.dbg.declare(metadata !{i32* %X}, metadata !10), !dbg !12
+    ; [debug line = 2:7] [debug variable = X]
+  store i32 21, i32* %X, align 4, !dbg !12
+  call void @llvm.dbg.declare(metadata !{i32* %Y}, metadata !13), !dbg !14
+    ; [debug line = 3:7] [debug variable = Y]
+  store i32 22, i32* %Y, align 4, !dbg !14
+  call void @llvm.dbg.declare(metadata !{i32* %Z}, metadata !15), !dbg !17
+    ; [debug line = 5:9] [debug variable = Z]
+  store i32 23, i32* %Z, align 4, !dbg !17
+  %0 = load i32* %X, align 4, !dbg !18
+    [debug line = 6:5]
+  store i32 %0, i32* %Z, align 4, !dbg !18
+  %1 = load i32* %Y, align 4, !dbg !19
+    [debug line = 8:3]
+  store i32 %1, i32* %X, align 4, !dbg !19
+  ret void, !dbg !20
+}
+
+; Function Attrs: nounwind readnone
+declare void @llvm.dbg.declare(metadata, metadata) #1
+
+attributes #0 = { nounwind ssp uwtable "less-precise-fpmad"="false"
+  "no-frame-pointer-elim"="true" "no-frame-pointer-elim-non-leaf"
+  "no-infs-fp-math"="false" "no-nans-fp-math"="false"
+  "stack-protector-buffer-size"="8" "unsafe-fp-math"="false"
+  "use-soft-float"="false" }
+attributes #1 = { nounwind readnone }
+
+!llvm.dbg.cu = !{!0}
+!llvm.module.flags = !{!8}
+!llvm.ident = !{!9}
+
+!0 = metadata !{i32 786449, metadata !1, i32 12,
+                metadata !"clang version 3.4 (trunk 193128) (llvm/trunk 193139)",
+                i1 false, metadata !"", i32 0, metadata !2, metadata !2, metadata !3,
+                metadata !2, metadata !2, metadata !""} ; [ DW_TAG_compile_unit ] \
+                  [/private/tmp/foo.c] \
+                  [DW_LANG_C99]
+!1 = metadata !{metadata !"t.c", metadata !"/private/tmp"}
+!2 = metadata !{i32 0}
+!3 = metadata !{metadata !4}
+!4 = metadata !{i32 786478, metadata !1, metadata !5, metadata !"foo",
+                metadata !"foo", metadata !"", i32 1, metadata !6,
+                i1 false, i1 true, i32 0, i32 0, null, i32 0, i1 false,
+                void ()* @foo, null, null, metadata !2, i32 1}
+                ; [ DW_TAG_subprogram ] [line 1] [def] [foo]
+!5 = metadata !{i32 786473, metadata !1}  ; [ DW_TAG_file_type ] \
+                  [/private/tmp/t.c]
+!6 = metadata !{i32 786453, i32 0, null, metadata !"", i32 0, i64 0, i64 0,
+                i64 0, i32 0, null, metadata !7, i32 0, null, null, null}
+                ; [ DW_TAG_subroutine_type ] \
+                  [line 0, size 0, align 0, offset 0] [from ]
+!7 = metadata !{null}
+!8 = metadata !{i32 2, metadata !"Dwarf Version", i32 2}
+!9 = metadata !{metadata !"clang version 3.4 (trunk 193128) (llvm/trunk 193139)"}
+!10 = metadata !{i32 786688, metadata !4, metadata !"X", metadata !5, i32 2,
+                 metadata !11, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [X] \
+                   [line 2]
+!11 = metadata !{i32 786468, null, null, metadata !"int", i32 0, i64 32,
+                 i64 32, i64 0, i32 0, i32 5} ; [ DW_TAG_base_type ] [int] \
+                   [line 0, size 32, align 32, offset 0, enc DW_ATE_signed]
+!12 = metadata !{i32 2, i32 0, metadata !4, null}
+!13 = metadata !{i32 786688, metadata !4, metadata !"Y", metadata !5, i32 3,
+                 metadata !11, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [Y] \
+                   [line 3]
+!14 = metadata !{i32 3, i32 0, metadata !4, null}
+!15 = metadata !{i32 786688, metadata !16, metadata !"Z", metadata !5, i32 5,
+                 metadata !11, i32 0, i32 0} ; [ DW_TAG_auto_variable ] [Z] \
+                   [line 5]
+!16 = metadata !{i32 786443, metadata !1, metadata !4, i32 4, i32 0, i32 0} \
+                 ; [ DW_TAG_lexical_block ] [/private/tmp/t.c]
+!17 = metadata !{i32 5, i32 0, metadata !16, null}
+!18 = metadata !{i32 6, i32 0, metadata !16, null}
+!19 = metadata !{i32 8, i32 0, metadata !4, null} ; [ DW_TAG_imported_declaration ]
+!20 = metadata !{i32 9, i32 0, metadata !4, null}
+</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="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">!10</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!12</span>
+  <span class="c">; [debug line = 2:7] [debug variable = X]</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">!12</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">!12</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">0</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!4</span><span class="p">,</span> <span class="k">null</span><span class="p">}</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">786478</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-Anonymous">!5</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">!""</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">!6</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="k">i32</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="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span>
+                <span class="kt">void</span> <span class="p">()*</span> <span class="vg">@foo</span><span class="p">,</span> <span class="k">null</span><span class="p">,</span> <span class="k">null</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+                  <span class="c">; [ DW_TAG_subprogram ] [line 1] [def] [foo]</span>
+</pre></div>
+</div>
+<p>Here <tt class="docutils literal"><span class="pre">!12</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">!4</span></tt>, 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="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">!15</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv-Anonymous">!17</span>
+  <span class="c">; [debug line = 5:9] [debug variable = Z]</span>
+</pre></div>
+</div>
+<p>The third 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">!17</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>!16 = metadata !{i32 786443, metadata !1, metadata !4, i32 4, i32 0, i32 0} \
+                 ; [ DW_TAG_lexical_block ] [/private/tmp/t.c]
+!17 = metadata !{i32 5, i32 0, metadata !16, null}
+</pre></div>
+</div>
+<p>Here <tt class="docutils literal"><span class="pre">!15</span></tt> indicates that <tt class="docutils literal"><span class="pre">Z</span></tt> is declared at line number 5 and
+column number 0 inside of lexical scope <tt class="docutils literal"><span class="pre">!16</span></tt>.  The lexical scope itself
+resides inside of subprogram <tt class="docutils literal"><span class="pre">!4</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="#id27">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 a few C/C++ constructs and the debug
+information that would best describe those constructs.  The canonical
+references are the <tt class="docutils literal"><span class="pre">DIDescriptor</span></tt> classes defined in
+<tt class="docutils literal"><span class="pre">include/llvm/IR/DebugInfo.h</span></tt> and the implementations of the helper functions
+in <tt class="docutils literal"><span class="pre">lib/IR/DIBuilder.cpp</span></tt>.</p>
+<div class="section" id="c-c-source-file-information">
+<h3><a class="toc-backref" href="#id28">C/C++ source file information</a><a class="headerlink" href="#c-c-source-file-information" title="Permalink to this headline">¶</a></h3>
+<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="#id29">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"><div class="highlight"><pre><span class="c">;;</span>
+<span class="c">;; Define the global itself.</span>
+<span class="c">;;</span>
+<span class="vg">@MyGlobal</span> <span class="p">=</span> <span class="k">global</span> <span class="k">i32</span> <span class="m">100</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+<span class="p">...</span>
+<span class="c">;;</span>
+<span class="c">;; List of debug info of globals</span>
+<span class="c">;;</span>
+<span class="nv">!llvm.dbg.cu</span> <span class="p">=</span> <span class="p">!{</span><span class="nv-Anonymous">!0</span><span class="p">}</span>
+
+<span class="c">;; Define the compile unit.</span>
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+  <span class="c">; Header(</span>
+  <span class="c">;   i32 17,                           ;; Tag</span>
+  <span class="c">;   i32 0,                            ;; Context</span>
+  <span class="c">;   i32 4,                            ;; Language</span>
+  <span class="c">;   metadata !"clang version 3.6.0 ", ;; Producer</span>
+  <span class="c">;   i1 false,                         ;; "isOptimized"?</span>
+  <span class="c">;   metadata !"",                     ;; Flags</span>
+  <span class="c">;   i32 0,                            ;; Runtime Version</span>
+  <span class="c">;   "",                               ;; Split debug filename</span>
+  <span class="c">;   1                                 ;; Full debug info</span>
+  <span class="c">; )</span>
+  <span class="kt">metadata</span> <span class="nv">!"0x11\0012\00clang version 3.6.0 \000\00\000\00\001"</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="kt">metadata</span> <span class="nv-Anonymous">!2</span><span class="p">,</span>                          <span class="c">;; Enum Types</span>
+  <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span><span class="p">,</span>                          <span class="c">;; Retained Types</span>
+  <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span><span class="p">,</span>                          <span class="c">;; Subprograms</span>
+  <span class="kt">metadata</span> <span class="nv-Anonymous">!3</span><span class="p">,</span>                          <span class="c">;; Global Variables</span>
+  <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span>                           <span class="c">;; Imported entities</span>
+<span class="p">}</span> <span class="c">; [ DW_TAG_compile_unit ]</span>
+
+<span class="c">;; The file/directory pair.</span>
+<span class="nv-Anonymous">!1</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{</span>
+  <span class="kt">metadata</span> <span class="nv">!"foo.c"</span><span class="p">,</span>                                 <span class="c">;; Filename</span>
+  <span class="kt">metadata</span> <span class="nv">!"/Users/dexonsmith/data/llvm/debug-info"</span> <span class="c">;; Directory</span>
+<span class="p">}</span>
+
+<span class="c">;; An empty array.</span>
+<span class="nv-Anonymous">!2</span> <span class="p">=</span> <span class="kt">metadata</span> <span class="p">!{}</span>
+
+<span class="c">;; The Array of Global Variables</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="c">;;</span>
+<span class="c">;; Define the global variable itself.</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="c">; Header(</span>
+  <span class="c">;   i32 52,                        ;; Tag</span>
+  <span class="c">;   metadata !"MyGlobal",          ;; Name</span>
+  <span class="c">;   metadata !"MyGlobal",          ;; Display Name</span>
+  <span class="c">;   metadata !"",                  ;; Linkage Name</span>
+  <span class="c">;   i32 1,                         ;; Line</span>
+  <span class="c">;   i32 0,                         ;; IsLocalToUnit</span>
+  <span class="c">;   i32 1                          ;; IsDefinition</span>
+  <span class="c">; )</span>
+  <span class="kt">metadata</span> <span class="nv">!"0x34\00MyGlobal\00MyGlobal\00\001\000\001"</span><span class="p">,</span>
+  <span class="k">null</span><span class="p">,</span>                              <span class="c">;; Unused</span>
+  <span class="kt">metadata</span> <span class="nv-Anonymous">!5</span><span class="p">,</span>                       <span class="c">;; File</span>
+  <span class="kt">metadata</span> <span class="nv-Anonymous">!6</span><span class="p">,</span>                       <span class="c">;; Type</span>
+  <span class="k">i32</span><span class="p">*</span> <span class="vg">@MyGlobal</span><span class="p">,</span>                    <span class="c">;; LLVM-IR Value</span>
+  <span class="k">null</span>                               <span class="c">;; Static member declaration</span>
+<span class="p">}</span> <span class="c">; [ DW_TAG_variable ]</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the file</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="c">; Header(</span>
+  <span class="c">;   i32 41             ;; Tag</span>
+  <span class="c">; )</span>
+  <span class="kt">metadata</span> <span class="nv">!"0x29"</span><span class="p">,</span>
+  <span class="kt">metadata</span> <span class="nv-Anonymous">!1</span>            <span class="c">;; File/directory pair</span>
+<span class="p">}</span> <span class="c">; [ DW_TAG_file_type ]</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the 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="c">; Header(</span>
+  <span class="c">;   i32 36,                       ;; Tag</span>
+  <span class="c">;   metadata !"int",              ;; Name</span>
+  <span class="c">;   i32 0,                        ;; Line</span>
+  <span class="c">;   i64 32,                       ;; Size in Bits</span>
+  <span class="c">;   i64 32,                       ;; Align in Bits</span>
+  <span class="c">;   i64 0,                        ;; Offset</span>
+  <span class="c">;   i32 0,                        ;; Flags</span>
+  <span class="c">;   i32 5                         ;; Encoding</span>
+  <span class="c">; )</span>
+  <span class="kt">metadata</span> <span class="nv">!"0x24\00int\000\0032\0032\000\000\005"</span><span class="p">,</span>
+  <span class="k">null</span><span class="p">,</span>                             <span class="c">;; Unused</span>
+  <span class="k">null</span>                              <span class="c">;; Unused</span>
+<span class="p">}</span> <span class="c">; [ DW_TAG_base_type ]</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="c-c-function-information">
+<h3><a class="toc-backref" href="#id30">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"><div class="highlight"><pre><span class="c">;;</span>
+<span class="c">;; Define the anchor for subprograms.</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="c">; Header(</span>
+  <span class="c">;   i32 46,             ;; Tag</span>
+  <span class="c">;   metadata !"main",   ;; Name</span>
+  <span class="c">;   metadata !"main",   ;; Display name</span>
+  <span class="c">;   metadata !"",       ;; Linkage name</span>
+  <span class="c">;   i32 1,              ;; Line number</span>
+  <span class="c">;   i1 false,           ;; Is local</span>
+  <span class="c">;   i1 true,            ;; Is definition</span>
+  <span class="c">;   i32 0,              ;; Virtuality attribute, e.g. pure virtual function</span>
+  <span class="c">;   i32 0,              ;; Index into virtual table for C++ methods</span>
+  <span class="c">;   i32 256,            ;; Flags</span>
+  <span class="c">;   i1 0,               ;; True if this function is optimized</span>
+  <span class="c">;   1                   ;; Line number of the opening '{' of the function</span>
+  <span class="c">; )</span>
+  <span class="kt">metadata</span> <span class="nv">!"0x2e\00main\00main\00\001\000\001\000\000\00256\000\001"</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="kt">metadata</span> <span class="nv-Anonymous">!5</span><span class="p">,</span>            <span class="c">;; Context</span>
+  <span class="kt">metadata</span> <span class="nv-Anonymous">!6</span><span class="p">,</span>            <span class="c">;; Type</span>
+  <span class="k">null</span><span class="p">,</span>                   <span class="c">;; Containing type</span>
+  <span class="k">i32</span> <span class="p">(</span><span class="k">i32</span><span class="p">,</span> <span class="k">i8</span><span class="p">**)*</span> <span class="vg">@main</span><span class="p">,</span> <span class="c">;; Pointer to llvm::Function</span>
+  <span class="k">null</span><span class="p">,</span>                   <span class="c">;; Function template parameters</span>
+  <span class="k">null</span><span class="p">,</span>                   <span class="c">;; Function declaration</span>
+  <span class="kt">metadata</span> <span class="nv-Anonymous">!2</span>             <span class="c">;; List of function variables (emitted when optimizing)</span>
+<span class="p">}</span>
+
+<span class="c">;;</span>
+<span class="c">;; Define the subprogram itself.</span>
+<span class="c">;;</span>
+<span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%argc</span><span class="p">,</span> <span class="k">i8</span><span class="p">**</span> <span class="nv">%argv</span><span class="p">)</span> <span class="p">{</span>
+<span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="id1">
+<h2><a class="toc-backref" href="#id31">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="#id32">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="#id33">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="#id34">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="#id35">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="#id36">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="#id37">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="73%" />
+<col width="11%" />
+<col width="16%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head" colspan="2">Name</th>
+<th class="head">Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td colspan="2">DW_APPLE_PROPERTY_readonly</td>
+<td>0x01</td>
+</tr>
+<tr class="row-odd"><td colspan="2">DW_APPLE_PROPERTY_getter</td>
+<td>0x02</td>
+</tr>
+<tr class="row-even"><td colspan="2">DW_APPLE_PROPERTY_assign</td>
+<td>0x04</td>
+</tr>
+<tr class="row-odd"><td colspan="2">DW_APPLE_PROPERTY_readwrite</td>
+<td>0x08</td>
+</tr>
+<tr class="row-even"><td colspan="2">DW_APPLE_PROPERTY_retain</td>
+<td>0x10</td>
+</tr>
+<tr class="row-odd"><td colspan="2">DW_APPLE_PROPERTY_copy</td>
+<td>0x20</td>
+</tr>
+<tr class="row-even"><td colspan="2">DW_APPLE_PROPERTY_nonatomic</td>
+<td>0x40</td>
+</tr>
+<tr class="row-odd"><td colspan="2">DW_APPLE_PROPERTY_setter</td>
+<td>0x80</td>
+</tr>
+<tr class="row-even"><td colspan="2">DW_APPLE_PROPERTY_atomic</td>
+<td>0x100</td>
+</tr>
+<tr class="row-odd"><td colspan="2">DW_APPLE_PROPERTY_weak</td>
+<td>0x200</td>
+</tr>
+<tr class="row-even"><td colspan="2">DW_APPLE_PROPERTY_strong</td>
+<td>0x400</td>
+</tr>
+<tr class="row-odd"><td colspan="2">DW_APPLE_PROPERTY_unsafe_unretained</td>
+<td>0x800</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="name-accelerator-tables">
+<h3><a class="toc-backref" href="#id38">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="#id39">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="#id40">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="#id41">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="#id42">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="#id43">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="#id44">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="#id45">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="#id46">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="#id47">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="#id48">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="#id49">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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/SphinxQuickstartTemplate.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/SphinxQuickstartTemplate.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/SphinxQuickstartTemplate.html (added)
+++ www-releases/trunk/3.6.0/docs/SphinxQuickstartTemplate.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,223 @@
+
+<!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.6 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.6',
+        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.6 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"><div class="highlight"><pre>                      .
+                       +:.
+                   ..:: ::
+                .++:+:: ::+:.:.
+               .:+           :
+        ::.::..::            .+.
+      ..:+    ::              :
+......+:.                    ..
+      :++.    ..              :
+        .+:::+::              :
+        ..   . .+            ::
+                 +.:      .::+.
+                  ...+. .: .
+                     .++:..
+                      ...
+</pre></div>
+</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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/StackMaps.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/StackMaps.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/StackMaps.html (added)
+++ www-releases/trunk/3.6.0/docs/StackMaps.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,575 @@
+
+<!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>Stack maps and patch points in LLVM — LLVM 3.6 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.6',
+        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.6 documentation" href="index.html" />
+    <link rel="next" title="Design and Usage of the InAlloca Attribute" href="InAlloca.html" />
+    <link rel="prev" title="User Guide for R600 Back-end" href="R600Usage.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="InAlloca.html" title="Design and Usage of the InAlloca Attribute"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="R600Usage.html" title="User Guide for R600 Back-end"
+             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="stack-maps-and-patch-points-in-llvm">
+<h1>Stack maps and patch points in LLVM<a class="headerlink" href="#stack-maps-and-patch-points-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="#definitions" id="id5">Definitions</a></li>
+<li><a class="reference internal" href="#motivation" id="id6">Motivation</a></li>
+<li><a class="reference internal" href="#intrinsics" id="id7">Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-experimental-stackmap-intrinsic" id="id8">‘<tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt>‘ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-experimental-patchpoint-intrinsic" id="id9">‘<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint.*</span></tt>‘ Intrinsic</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#stack-map-format" id="id10">Stack Map Format</a><ul>
+<li><a class="reference internal" href="#stack-map-section" id="id11">Stack Map Section</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#stack-map-usage" id="id12">Stack Map Usage</a><ul>
+<li><a class="reference internal" href="#direct-stack-map-entries" id="id13">Direct Stack Map Entries</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="definitions">
+<h2><a class="toc-backref" href="#id5">Definitions</a><a class="headerlink" href="#definitions" title="Permalink to this headline">¶</a></h2>
+<p>In this document we refer to the “runtime” collectively as all
+components that serve as the LLVM client, including the LLVM IR
+generator, object code consumer, and code patcher.</p>
+<p>A stack map records the location of <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> at a particular
+instruction address. These <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> do not refer to all the
+LLVM values live across the stack map. Instead, they are only the
+values that the runtime requires to be live at this point. For
+example, they may be the values the runtime will need to resume
+program execution at that point independent of the compiled function
+containing the stack map.</p>
+<p>LLVM emits stack map data into the object code within a designated
+<a class="reference internal" href="#stackmap-section"><em>Stack Map Section</em></a>. This stack map data contains a record for
+each stack map. The record stores the stack map’s instruction address
+and contains a entry for each mapped value. Each entry encodes a
+value’s location as a register, stack offset, or constant.</p>
+<p>A patch point is an instruction address at which space is reserved for
+patching a new instruction sequence at run time. Patch points look
+much like calls to LLVM. They take arguments that follow a calling
+convention and may return a value. They also imply stack map
+generation, which allows the runtime to locate the patchpoint and
+find the location of <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> at that point.</p>
+</div>
+<div class="section" id="motivation">
+<h2><a class="toc-backref" href="#id6">Motivation</a><a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2>
+<p>This functionality is currently experimental but is potentially useful
+in a variety of settings, the most obvious being a runtime (JIT)
+compiler. Example applications of the patchpoint intrinsics are
+implementing an inline call cache for polymorphic method dispatch or
+optimizing the retrieval of properties in dynamically typed languages
+such as JavaScript.</p>
+<p>The intrinsics documented here are currently used by the JavaScript
+compiler within the open source WebKit project, see the <a class="reference external" href="https://trac.webkit.org/wiki/FTLJIT">FTL JIT</a>, but they are designed to be
+used whenever stack maps or code patching are needed. Because the
+intrinsics have experimental status, compatibility across LLVM
+releases is not guaranteed.</p>
+<p>The stack map functionality described in this document is separate
+from the functionality described in
+<a class="reference internal" href="GarbageCollection.html#stack-map"><em>Computing stack maps</em></a>. <cite>GCFunctionMetadata</cite> provides the location of
+pointers into a collected heap captured by the <cite>GCRoot</cite> intrinsic,
+which can also be considered a “stack map”. Unlike the stack maps
+defined above, the <cite>GCFunctionMetadata</cite> stack map interface does not
+provide a way to associate live register values of arbitrary type with
+an instruction address, nor does it specify a format for the resulting
+stack map. The stack maps described here could potentially provide
+richer information to a garbage collecting runtime, but that usage
+will not be discussed in this document.</p>
+</div>
+<div class="section" id="intrinsics">
+<h2><a class="toc-backref" href="#id7">Intrinsics</a><a class="headerlink" href="#intrinsics" title="Permalink to this headline">¶</a></h2>
+<p>The following two kinds of intrinsics can be used to implement stack
+maps and patch points: <tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt> and
+<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt>. Both kinds of intrinsics generate a
+stack map record, and they both allow some form of code patching. They
+can be used independently (i.e. <tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt>
+implicitly generates a stack map without the need for an additional
+call to <tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt>). The choice of which to use
+depends on whether it is necessary to reserve space for code patching
+and whether any of the intrinsic arguments should be lowered according
+to calling conventions. <tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt> does not
+reserve any space, nor does it expect any call arguments. If the
+runtime patches code at the stack map’s address, it will destructively
+overwrite the program text. This is unlike
+<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt>, which reserves space for in-place
+patching without overwriting surrounding code. The
+<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt> intrinsic also lowers a specified
+number of arguments according to its calling convention. This allows
+patched code to make in-place function calls without marshaling.</p>
+<p>Each instance of one of these intrinsics generates a stack map record
+in the <a class="reference internal" href="#stackmap-section"><em>Stack Map Section</em></a>. The record includes an ID, allowing
+the runtime to uniquely identify the stack map, and the offset within
+the code from the beginning of the enclosing function.</p>
+<div class="section" id="llvm-experimental-stackmap-intrinsic">
+<h3><a class="toc-backref" href="#id8">‘<tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt>‘ Intrinsic</a><a class="headerlink" href="#llvm-experimental-stackmap-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="syntax">
+<h4>Syntax:<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare void
+  @llvm.experimental.stackmap(i64 <id>, i32 <numShadowBytes>, ...)
+</pre></div>
+</div>
+</div>
+<div class="section" id="overview">
+<h4>Overview:<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h4>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt>‘ intrinsic records the location of
+specified values in the stack map without generating any code.</p>
+</div>
+<div class="section" id="operands">
+<h4>Operands:<a class="headerlink" href="#operands" title="Permalink to this headline">¶</a></h4>
+<p>The first operand is an ID to be encoded within the stack map. The
+second operand is the number of shadow bytes following the
+intrinsic. The variable number of operands that follow are the <tt class="docutils literal"><span class="pre">live</span>
+<span class="pre">values</span></tt> for which locations will be recorded in the stack map.</p>
+<p>To use this intrinsic as a bare-bones stack map, with no code patching
+support, the number of shadow bytes can be set to zero.</p>
+</div>
+<div class="section" id="semantics">
+<h4>Semantics:<a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h4>
+<p>The stack map intrinsic generates no code in place, unless nops are
+needed to cover its shadow (see below). However, its offset from
+function entry is stored in the stack map. This is the relative
+instruction address immediately following the instructions that
+precede the stack map.</p>
+<p>The stack map ID allows a runtime to locate the desired stack map
+record. LLVM passes this ID through directly to the stack map
+record without checking uniqueness.</p>
+<p>LLVM guarantees a shadow of instructions following the stack map’s
+instruction offset during which neither the end of the basic block nor
+another call to <tt class="docutils literal"><span class="pre">llvm.experimental.stackmap</span></tt> or
+<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint</span></tt> may occur. This allows the runtime to
+patch the code at this point in response to an event triggered from
+outside the code. The code for instructions following the stack map
+may be emitted in the stack map’s shadow, and these instructions may
+be overwritten by destructive patching. Without shadow bytes, this
+destructive patching could overwrite program text or data outside the
+current function. We disallow overlapping stack map shadows so that
+the runtime does not need to consider this corner case.</p>
+<p>For example, a stack map with 8 byte shadow:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">call</span> <span class="kt">void</span> <span class="vg">@runtime</span><span class="p">()</span>
+<span class="k">call</span> <span class="kt">void</span> <span class="p">(</span><span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="p">...)*</span> <span class="vg">@llvm.experimental.stackmap</span><span class="p">(</span><span class="k">i64</span> <span class="m">77</span><span class="p">,</span> <span class="k">i32</span> <span class="m">8</span><span class="p">,</span>
+                                                       <span class="k">i64</span><span class="p">*</span> <span class="nv">%ptr</span><span class="p">)</span>
+<span class="nv">%val</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i64</span><span class="p">*</span> <span class="nv">%ptr</span>
+<span class="nv">%add</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i64</span> <span class="nv">%val</span><span class="p">,</span> <span class="m">3</span>
+<span class="k">ret</span> <span class="k">i64</span> <span class="nv">%add</span>
+</pre></div>
+</div>
+<p>May require one byte of nop-padding:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00 callq _runtime
+0x05 nop                <--- stack map address
+0x06 movq (%rdi), %rax
+0x07 addq $3, %rax
+0x0a popq %rdx
+0x0b ret                <---- end of 8-byte shadow
+</pre></div>
+</div>
+<p>Now, if the runtime needs to invalidate the compiled code, it may
+patch 8 bytes of code at the stack map’s address at follows:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00 callq _runtime
+0x05 movl  $0xffff, %rax <--- patched code at stack map address
+0x0a callq *%rax         <---- end of 8-byte shadow
+</pre></div>
+</div>
+<p>This way, after the normal call to the runtime returns, the code will
+execute a patched call to a special entry point that can rebuild a
+stack frame from the values located by the stack map.</p>
+</div>
+</div>
+<div class="section" id="llvm-experimental-patchpoint-intrinsic">
+<h3><a class="toc-backref" href="#id9">‘<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint.*</span></tt>‘ Intrinsic</a><a class="headerlink" href="#llvm-experimental-patchpoint-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id1">
+<h4>Syntax:<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare void
+  @llvm.experimental.patchpoint.void(i64 <id>, i32 <numBytes>,
+                                     i8* <target>, i32 <numArgs>, ...)
+declare i64
+  @llvm.experimental.patchpoint.i64(i64 <id>, i32 <numBytes>,
+                                    i8* <target>, i32 <numArgs>, ...)
+</pre></div>
+</div>
+</div>
+<div class="section" id="id2">
+<h4>Overview:<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.experimental.patchpoint.*</span></tt>‘ intrinsics creates a function
+call to the specified <tt class="docutils literal"><span class="pre"><target></span></tt> and records the location of specified
+values in the stack map.</p>
+</div>
+<div class="section" id="id3">
+<h4>Operands:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p>The first operand is an ID, the second operand is the number of bytes
+reserved for the patchable region, the third operand is the target
+address of a function (optionally null), and the fourth operand
+specifies how many of the following variable operands are considered
+function call arguments. The remaining variable number of operands are
+the <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> for which locations will be recorded in the stack
+map.</p>
+</div>
+<div class="section" id="id4">
+<h4>Semantics:<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<p>The patch point intrinsic generates a stack map. It also emits a
+function call to the address specified by <tt class="docutils literal"><span class="pre"><target></span></tt> if the address
+is not a constant null. The function call and its arguments are
+lowered according to the calling convention specified at the
+intrinsic’s callsite. Variants of the intrinsic with non-void return
+type also return a value according to calling convention.</p>
+<p>On PowerPC, note that the <tt class="docutils literal"><span class="pre"><target></span></tt> must be the actual intended target of
+the indirect call, not the function-descriptor address normally used as the
+C/C++ function-pointer representation. As a result, the call target must be
+local because no adjustment or restoration of the TOC pointer (in register r2)
+will be performed.</p>
+<p>Requesting zero patch point arguments is valid. In this case, all
+variable operands are handled just like
+<tt class="docutils literal"><span class="pre">llvm.experimental.stackmap.*</span></tt>. The difference is that space will
+still be reserved for patching, a call will be emitted, and a return
+value is allowed.</p>
+<p>The location of the arguments are not normally recorded in the stack
+map because they are already fixed by the calling convention. The
+remaining <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt> will have their location recorded, which
+could be a register, stack location, or constant. A special calling
+convention has been introduced for use with stack maps, anyregcc,
+which forces the arguments to be loaded into registers but allows
+those register to be dynamically allocated. These argument registers
+will have their register locations recorded in the stack map in
+addition to the remaining <tt class="docutils literal"><span class="pre">live</span> <span class="pre">values</span></tt>.</p>
+<p>The patch point also emits nops to cover at least <tt class="docutils literal"><span class="pre"><numBytes></span></tt> of
+instruction encoding space. Hence, the client must ensure that
+<tt class="docutils literal"><span class="pre"><numBytes></span></tt> is enough to encode a call to the target address on the
+supported targets. If the call target is constant null, then there is
+no minimum requirement. A zero-byte null target patchpoint is
+valid.</p>
+<p>The runtime may patch the code emitted for the patch point, including
+the call sequence and nops. However, the runtime may not assume
+anything about the code LLVM emits within the reserved space. Partial
+patching is not allowed. The runtime must patch all reserved bytes,
+padding with nops if necessary.</p>
+<p>This example shows a patch point reserving 15 bytes, with one argument
+in $rdi, and a return value in $rax per native calling convention:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%target</span> <span class="p">=</span> <span class="k">inttoptr</span> <span class="k">i64</span> <span class="m">-281474976710654</span> <span class="k">to</span> <span class="k">i8</span><span class="p">*</span>
+<span class="nv">%val</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i64</span> <span class="p">(</span><span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="p">...)*</span>
+         <span class="vg">@llvm.experimental.patchpoint.i64</span><span class="p">(</span><span class="k">i64</span> <span class="m">78</span><span class="p">,</span> <span class="k">i32</span> <span class="m">15</span><span class="p">,</span>
+                                           <span class="k">i8</span><span class="p">*</span> <span class="nv">%target</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="k">i64</span><span class="p">*</span> <span class="nv">%ptr</span><span class="p">)</span>
+<span class="nv">%add</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i64</span> <span class="nv">%val</span><span class="p">,</span> <span class="m">3</span>
+<span class="k">ret</span> <span class="k">i64</span> <span class="nv">%add</span>
+</pre></div>
+</div>
+<p>May generate:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00 movabsq $0xffff000000000002, %r11 <--- patch point address
+0x0a callq   *%r11
+0x0d nop
+0x0e nop                               <--- end of reserved 15-bytes
+0x0f addq    $0x3, %rax
+0x10 movl    %rax, 8(%rsp)
+</pre></div>
+</div>
+<p>Note that no stack map locations will be recorded. If the patched code
+sequence does not need arguments fixed to specific calling convention
+registers, then the <tt class="docutils literal"><span class="pre">anyregcc</span></tt> convention may be used:</p>
+<div class="highlight-none"><div class="highlight"><pre>%val = call anyregcc @llvm.experimental.patchpoint(i64 78, i32 15,
+                                                   i8* %target, i32 1,
+                                                   i64* %ptr)
+</pre></div>
+</div>
+<p>The stack map now indicates the location of the %ptr argument and
+return value:</p>
+<div class="highlight-none"><div class="highlight"><pre>Stack Map: ID=78, Loc0=%r9 Loc1=%r8
+</pre></div>
+</div>
+<p>The patch code sequence may now use the argument that happened to be
+allocated in %r8 and return a value allocated in %r9:</p>
+<div class="highlight-none"><div class="highlight"><pre>0x00 movslq 4(%r8) %r9              <--- patched code at patch point address
+0x03 nop
+...
+0x0e nop                            <--- end of reserved 15-bytes
+0x0f addq    $0x3, %r9
+0x10 movl    %r9, 8(%rsp)
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="stack-map-format">
+<span id="stackmap-format"></span><h2><a class="toc-backref" href="#id10">Stack Map Format</a><a class="headerlink" href="#stack-map-format" title="Permalink to this headline">¶</a></h2>
+<p>The existence of a stack map or patch point intrinsic within an LLVM
+Module forces code emission to create a <a class="reference internal" href="#stackmap-section"><em>Stack Map Section</em></a>. The
+format of this section follows:</p>
+<div class="highlight-none"><div class="highlight"><pre>Header {
+  uint8  : Stack Map Version (current version is 1)
+  uint8  : Reserved (expected to be 0)
+  uint16 : Reserved (expected to be 0)
+}
+uint32 : NumFunctions
+uint32 : NumConstants
+uint32 : NumRecords
+StkSizeRecord[NumFunctions] {
+  uint64 : Function Address
+  uint64 : Stack Size
+}
+Constants[NumConstants] {
+  uint64 : LargeConstant
+}
+StkMapRecord[NumRecords] {
+  uint64 : PatchPoint ID
+  uint32 : Instruction Offset
+  uint16 : Reserved (record flags)
+  uint16 : NumLocations
+  Location[NumLocations] {
+    uint8  : Register | Direct | Indirect | Constant | ConstantIndex
+    uint8  : Reserved (location flags)
+    uint16 : Dwarf RegNum
+    int32  : Offset or SmallConstant
+  }
+  uint16 : Padding
+  uint16 : NumLiveOuts
+  LiveOuts[NumLiveOuts]
+    uint16 : Dwarf RegNum
+    uint8  : Reserved
+    uint8  : Size in Bytes
+  }
+  uint32 : Padding (only if required to align to 8 byte)
+}
+</pre></div>
+</div>
+<p>The first byte of each location encodes a type that indicates how to
+interpret the <tt class="docutils literal"><span class="pre">RegNum</span></tt> and <tt class="docutils literal"><span class="pre">Offset</span></tt> fields as follows:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="13%" />
+<col width="16%" />
+<col width="30%" />
+<col width="42%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>Encoding</td>
+<td>Type</td>
+<td>Value</td>
+<td>Description</td>
+</tr>
+<tr class="row-even"><td>0x1</td>
+<td>Register</td>
+<td>Reg</td>
+<td>Value in a register</td>
+</tr>
+<tr class="row-odd"><td>0x2</td>
+<td>Direct</td>
+<td>Reg + Offset</td>
+<td>Frame index value</td>
+</tr>
+<tr class="row-even"><td>0x3</td>
+<td>Indirect</td>
+<td>[Reg + Offset]</td>
+<td>Spilled value</td>
+</tr>
+<tr class="row-odd"><td>0x4</td>
+<td>Constant</td>
+<td>Offset</td>
+<td>Small constant</td>
+</tr>
+<tr class="row-even"><td>0x5</td>
+<td>ConstIndex</td>
+<td>Constants[Offset]</td>
+<td>Large constant</td>
+</tr>
+</tbody>
+</table>
+<p>In the common case, a value is available in a register, and the
+<tt class="docutils literal"><span class="pre">Offset</span></tt> field will be zero. Values spilled to the stack are encoded
+as <tt class="docutils literal"><span class="pre">Indirect</span></tt> locations. The runtime must load those values from a
+stack address, typically in the form <tt class="docutils literal"><span class="pre">[BP</span> <span class="pre">+</span> <span class="pre">Offset]</span></tt>. If an
+<tt class="docutils literal"><span class="pre">alloca</span></tt> value is passed directly to a stack map intrinsic, then
+LLVM may fold the frame index into the stack map as an optimization to
+avoid allocating a register or stack slot. These frame indices will be
+encoded as <tt class="docutils literal"><span class="pre">Direct</span></tt> locations in the form <tt class="docutils literal"><span class="pre">BP</span> <span class="pre">+</span> <span class="pre">Offset</span></tt>. LLVM may
+also optimize constants by emitting them directly in the stack map,
+either in the <tt class="docutils literal"><span class="pre">Offset</span></tt> of a <tt class="docutils literal"><span class="pre">Constant</span></tt> location or in the constant
+pool, referred to by <tt class="docutils literal"><span class="pre">ConstantIndex</span></tt> locations.</p>
+<p>At each callsite, a “liveout” register list is also recorded. These
+are the registers that are live across the stackmap and therefore must
+be saved by the runtime. This is an important optimization when the
+patchpoint intrinsic is used with a calling convention that by default
+preserves most registers as callee-save.</p>
+<p>Each entry in the liveout register list contains a DWARF register
+number and size in bytes. The stackmap format deliberately omits
+specific subregister information. Instead the runtime must interpret
+this information conservatively. For example, if the stackmap reports
+one byte at <tt class="docutils literal"><span class="pre">%rax</span></tt>, then the value may be in either <tt class="docutils literal"><span class="pre">%al</span></tt> or
+<tt class="docutils literal"><span class="pre">%ah</span></tt>. It doesn’t matter in practice, because the runtime will
+simply save <tt class="docutils literal"><span class="pre">%rax</span></tt>. However, if the stackmap reports 16 bytes at
+<tt class="docutils literal"><span class="pre">%ymm0</span></tt>, then the runtime can safely optimize by saving only
+<tt class="docutils literal"><span class="pre">%xmm0</span></tt>.</p>
+<p>The stack map format is a contract between an LLVM SVN revision and
+the runtime. It is currently experimental and may change in the short
+term, but minimizing the need to update the runtime is
+important. Consequently, the stack map design is motivated by
+simplicity and extensibility. Compactness of the representation is
+secondary because the runtime is expected to parse the data
+immediately after compiling a module and encode the information in its
+own format. Since the runtime controls the allocation of sections, it
+can reuse the same stack map space for multiple modules.</p>
+<p>Stackmap support is currently only implemented for 64-bit
+platforms. However, a 32-bit implementation should be able to use the
+same format with an insignificant amount of wasted space.</p>
+<div class="section" id="stack-map-section">
+<span id="stackmap-section"></span><h3><a class="toc-backref" href="#id11">Stack Map Section</a><a class="headerlink" href="#stack-map-section" title="Permalink to this headline">¶</a></h3>
+<p>A JIT compiler can easily access this section by providing its own
+memory manager via the LLVM C API
+<tt class="docutils literal"><span class="pre">LLVMCreateSimpleMCJITMemoryManager()</span></tt>. When creating the memory
+manager, the JIT provides a callback:
+<tt class="docutils literal"><span class="pre">LLVMMemoryManagerAllocateDataSectionCallback()</span></tt>. When LLVM creates
+this section, it invokes the callback and passes the section name. The
+JIT can record the in-memory address of the section at this time and
+later parse it to recover the stack map data.</p>
+<p>On Darwin, the stack map section name is “__llvm_stackmaps”. The
+segment name is “__LLVM_STACKMAPS”.</p>
+</div>
+</div>
+<div class="section" id="stack-map-usage">
+<h2><a class="toc-backref" href="#id12">Stack Map Usage</a><a class="headerlink" href="#stack-map-usage" title="Permalink to this headline">¶</a></h2>
+<p>The stack map support described in this document can be used to
+precisely determine the location of values at a specific position in
+the code. LLVM does not maintain any mapping between those values and
+any higher-level entity. The runtime must be able to interpret the
+stack map record given only the ID, offset, and the order of the
+locations, which LLVM preserves.</p>
+<p>Note that this is quite different from the goal of debug information,
+which is a best-effort attempt to track the location of named
+variables at every instruction.</p>
+<p>An important motivation for this design is to allow a runtime to
+commandeer a stack frame when execution reaches an instruction address
+associated with a stack map. The runtime must be able to rebuild a
+stack frame and resume program execution using the information
+provided by the stack map. For example, execution may resume in an
+interpreter or a recompiled version of the same function.</p>
+<p>This usage restricts LLVM optimization. Clearly, LLVM must not move
+stores across a stack map. However, loads must also be handled
+conservatively. If the load may trigger an exception, hoisting it
+above a stack map could be invalid. For example, the runtime may
+determine that a load is safe to execute without a type check given
+the current state of the type system. If the type system changes while
+some activation of the load’s function exists on the stack, the load
+becomes unsafe. The runtime can prevent subsequent execution of that
+load by immediately patching any stack map location that lies between
+the current call site and the load (typically, the runtime would
+simply patch all stack map locations to invalidate the function). If
+the compiler had hoisted the load above the stack map, then the
+program could crash before the runtime could take back control.</p>
+<p>To enforce these semantics, stackmap and patchpoint intrinsics are
+considered to potentially read and write all memory. This may limit
+optimization more than some clients desire. This limitation may be
+avoided by marking the call site as “readonly”. In the future we may
+also allow meta-data to be added to the intrinsic call to express
+aliasing, thereby allowing optimizations to hoist certain loads above
+stack maps.</p>
+<div class="section" id="direct-stack-map-entries">
+<h3><a class="toc-backref" href="#id13">Direct Stack Map Entries</a><a class="headerlink" href="#direct-stack-map-entries" title="Permalink to this headline">¶</a></h3>
+<p>As shown in <a class="reference internal" href="#stackmap-section"><em>Stack Map Section</em></a>, a Direct stack map location
+records the address of frame index. This address is itself the value
+that the runtime requested. This differs from Indirect locations,
+which refer to a stack locations from which the requested values must
+be loaded. Direct locations can communicate the address if an alloca,
+while Indirect locations handle register spills.</p>
+<p>For example:</p>
+<div class="highlight-none"><div class="highlight"><pre>entry:
+  %a = alloca i64...
+  llvm.experimental.stackmap(i64 <ID>, i32 <shadowBytes>, i64* %a)
+</pre></div>
+</div>
+<p>The runtime can determine this alloca’s relative location on the
+stack immediately after compilation, or at any time thereafter. This
+differs from Register and Indirect locations, because the runtime can
+only read the values in those locations when execution reaches the
+instruction address of the stack map.</p>
+<p>This functionality requires LLVM to treat entry-block allocas
+specially when they are directly consumed by an intrinsics. (This is
+the same requirement imposed by the llvm.gcroot intrinsic.) LLVM
+transformations must not substitute the alloca with any intervening
+value. This can be verified by the runtime simply by checking that the
+stack map’s location is a Direct location type.</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="InAlloca.html" title="Design and Usage of the InAlloca Attribute"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="R600Usage.html" title="User Guide for R600 Back-end"
+             >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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/Statepoints.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/Statepoints.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/Statepoints.html (added)
+++ www-releases/trunk/3.6.0/docs/Statepoints.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,467 @@
+
+<!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>Garbage Collection Safepoints in LLVM — LLVM 3.6 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.6',
+        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.6 documentation" href="index.html" />
+    <link rel="next" title="MergeFunctions pass, how it works" href="MergeFunctions.html" />
+    <link rel="prev" title="LLVM Code Coverage Mapping Format" href="CoverageMappingFormat.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="MergeFunctions.html" title="MergeFunctions pass, how it works"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="CoverageMappingFormat.html" title="LLVM Code Coverage Mapping Format"
+             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="garbage-collection-safepoints-in-llvm">
+<h1>Garbage Collection Safepoints in LLVM<a class="headerlink" href="#garbage-collection-safepoints-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="#status" id="id10">Status</a></li>
+<li><a class="reference internal" href="#overview" id="id11">Overview</a></li>
+<li><a class="reference internal" href="#intrinsics" id="id12">Intrinsics</a><ul>
+<li><a class="reference internal" href="#gc-statepoint-intrinsic" id="id13">‘’‘gc.statepoint’‘’ Intrinsic</a></li>
+<li><a class="reference internal" href="#gc-result-intrinsic" id="id14">‘’‘gc.result’‘’ Intrinsic</a></li>
+<li><a class="reference internal" href="#gc-relocate-intrinsic" id="id15">‘’‘gc.relocate’‘’ Intrinsic</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#stack-map-format" id="id16">Stack Map Format</a></li>
+<li><a class="reference internal" href="#safepoint-semantics-verification" id="id17">Safepoint Semantics & Verification</a></li>
+<li><a class="reference internal" href="#bugs-and-enhancements" id="id18">Bugs and Enhancements</a></li>
+</ul>
+</div>
+<div class="section" id="status">
+<h2><a class="toc-backref" href="#id10">Status</a><a class="headerlink" href="#status" title="Permalink to this headline">¶</a></h2>
+<p>This document describes a set of experimental extensions to LLVM. Use
+with caution.  Because the intrinsics have experimental status,
+compatibility across LLVM releases is not guaranteed.</p>
+<p>LLVM currently supports an alternate mechanism for conservative
+garbage collection support using the gc_root intrinsic.  The mechanism
+described here shares little in common with the alternate
+implementation and it is hoped that this mechanism will eventually
+replace the gc_root mechanism.</p>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id11">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>To collect dead objects, garbage collectors must be able to identify
+any references to objects contained within executing code, and,
+depending on the collector, potentially update them.  The collector
+does not need this information at all points in code - that would make
+the problem much harder - but only at well-defined points in the
+execution known as ‘safepoints’ For most collectors, it is sufficient
+to track at least one copy of each unique pointer value.  However, for
+a collector which wishes to relocate objects directly reachable from
+running code, a higher standard is required.</p>
+<p>One additional challenge is that the compiler may compute intermediate
+results (“derived pointers”) which point outside of the allocation or
+even into the middle of another allocation.  The eventual use of this
+intermediate value must yield an address within the bounds of the
+allocation, but such “exterior derived pointers” may be visible to the
+collector.  Given this, a garbage collector can not safely rely on the
+runtime value of an address to indicate the object it is associated
+with.  If the garbage collector wishes to move any object, the
+compiler must provide a mapping, for each pointer, to an indication of
+its allocation.</p>
+<p>To simplify the interaction between a collector and the compiled code,
+most garbage collectors are organized in terms of three abstractions:
+load barriers, store barriers, and safepoints.</p>
+<ol class="arabic simple">
+<li>A load barrier is a bit of code executed immediately after the
+machine load instruction, but before any use of the value loaded.
+Depending on the collector, such a barrier may be needed for all
+loads, merely loads of a particular type (in the original source
+language), or none at all.</li>
+<li>Analogously, a store barrier is a code fragement that runs
+immediately before the machine store instruction, but after the
+computation of the value stored.  The most common use of a store
+barrier is to update a ‘card table’ in a generational garbage
+collector.</li>
+<li>A safepoint is a location at which pointers visible to the compiled
+code (i.e. currently in registers or on the stack) are allowed to
+change.  After the safepoint completes, the actual pointer value
+may differ, but the ‘object’ (as seen by the source language)
+pointed to will not.</li>
+</ol>
+<blockquote>
+<div>Note that the term ‘safepoint’ is somewhat overloaded.  It refers to
+both the location at which the machine state is parsable and the
+coordination protocol involved in bring application threads to a
+point at which the collector can safely use that information.  The
+term “statepoint” as used in this document refers exclusively to the
+former.</div></blockquote>
+<p>This document focuses on the last item - compiler support for
+safepoints in generated code.  We will assume that an outside
+mechanism has decided where to place safepoints.  From our
+perspective, all safepoints will be function calls.  To support
+relocation of objects directly reachable from values in compiled code,
+the collector must be able to:</p>
+<ol class="arabic simple">
+<li>identify every copy of a pointer (including copies introduced by
+the compiler itself) at the safepoint,</li>
+<li>identify which object each pointer relates to, and</li>
+<li>potentially update each of those copies.</li>
+</ol>
+<p>This document describes the mechanism by which an LLVM based compiler
+can provide this information to a language runtime/collector, and
+ensure that all pointers can be read and updated if desired.  The
+heart of the approach is to construct (or rewrite) the IR in a manner
+where the possible updates performed by the garbage collector are
+explicitly visible in the IR.  Doing so requires that we:</p>
+<ol class="arabic simple">
+<li>create a new SSA value for each potentially relocated pointer, and
+ensure that no uses of the original (non relocated) value is
+reachable after the safepoint,</li>
+<li>specify the relocation in a way which is opaque to the compiler to
+ensure that the optimizer can not introduce new uses of an
+unrelocated value after a statepoint. This prevents the optimizer
+from performing unsound optimizations.</li>
+<li>recording a mapping of live pointers (and the allocation they’re
+associated with) for each statepoint.</li>
+</ol>
+<p>At the most abstract level, inserting a safepoint can be thought of as
+replacing a call instruction with a call to a multiple return value
+function which both calls the original target of the call, returns
+it’s result, and returns updated values for any live pointers to
+garbage collected objects.</p>
+<blockquote>
+<div>Note that the task of identifying all live pointers to garbage
+collected values, transforming the IR to expose a pointer giving the
+base object for every such live pointer, and inserting all the
+intrinsics correctly is explicitly out of scope for this document.
+The recommended approach is described in the section of Late
+Safepoint Placement below.</div></blockquote>
+<p>This abstract function call is concretely represented by a sequence of
+intrinsic calls known as a ‘statepoint sequence’.</p>
+<dl class="docutils">
+<dt>Let’s consider a simple call in LLVM IR:</dt>
+<dd>todo</dd>
+</dl>
+<p>Depending on our language we may need to allow a safepoint during the
+execution of the function called from this site.  If so, we need to
+let the collector update local values in the current frame.</p>
+<p>Let’s say we need to relocate SSA values ‘a’, ‘b’, and ‘c’ at this
+safepoint.  To represent this, we would generate the statepoint
+sequence:</p>
+<blockquote>
+<div>todo</div></blockquote>
+<p>Ideally, this sequence would have been represented as a M argument, N
+return value function (where M is the number of values being
+relocated + the original call arguments and N is the original return
+value + each relocated value), but LLVM does not easily support such a
+representation.</p>
+<p>Instead, the statepoint intrinsic marks the actual site of the
+safepoint or statepoint.  The statepoint returns a token value (which
+exists only at compile time).  To get back the original return value
+of the call, we use the ‘gc.result’ intrinsic.  To get the relocation
+of each pointer in turn, we use the ‘gc.relocate’ intrinsic with the
+appropriate index.  Note that both the gc.relocate and gc.result are
+tied to the statepoint.  The combination forms a “statepoint sequence”
+and represents the entitety of a parseable call or ‘statepoint’.</p>
+<dl class="docutils">
+<dt>When lowered, this example would generate the following x86 assembly::</dt>
+<dd>put assembly here</dd>
+</dl>
+<p>Each of the potentially relocated values has been spilled to the
+stack, and a record of that location has been recorded to the
+<a class="reference internal" href="StackMaps.html#stackmap-section"><em>Stack Map section</em></a>.  If the garbage collector
+needs to update any of these pointers during the call, it knows
+exactly what to change.</p>
+</div>
+<div class="section" id="intrinsics">
+<h2><a class="toc-backref" href="#id12">Intrinsics</a><a class="headerlink" href="#intrinsics" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="gc-statepoint-intrinsic">
+<h3><a class="toc-backref" href="#id13">‘’‘gc.statepoint’‘’ Intrinsic</a><a class="headerlink" href="#gc-statepoint-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="syntax">
+<h4>Syntax:<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare i32
+  @gc.statepoint(func_type <target>, i64 <#call args>.
+                 i64 <unused>, ... (call parameters),
+                 i64 <# deopt args>, ... (deopt parameters),
+                 ... (gc parameters))
+</pre></div>
+</div>
+</div>
+<div class="section" id="id1">
+<h4>Overview:<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>The statepoint intrinsic represents a call which is parse-able by the
+runtime.</p>
+</div>
+<div class="section" id="operands">
+<h4>Operands:<a class="headerlink" href="#operands" title="Permalink to this headline">¶</a></h4>
+<p>The ‘target’ operand is the function actually being called.  The
+target can be specified as either a symbolic LLVM function, or as an
+arbitrary Value of appropriate function type.  Note that the function
+type must match the signature of the callee and the types of the ‘call
+parameters’ arguments.</p>
+<p>The ‘#call args’ operand is the number of arguments to the actual
+call.  It must exactly match the number of arguments passed in the
+‘call parameters’ variable length section.</p>
+<p>The ‘unused’ operand is unused and likely to be removed.  Please do
+not use.</p>
+<p>The ‘call parameters’ arguments are simply the arguments which need to
+be passed to the call target.  They will be lowered according to the
+specified calling convention and otherwise handled like a normal call
+instruction.  The number of arguments must exactly match what is
+specified in ‘# call args’.  The types must match the signature of
+‘target’.</p>
+<p>The ‘deopt parameters’ arguments contain an arbitrary list of Values
+which is meaningful to the runtime.  The runtime may read any of these
+values, but is assumed not to modify them.  If the garbage collector
+might need to modify one of these values, it must also be listed in
+the ‘gc pointer’ argument list.  The ‘# deopt args’ field indicates
+how many operands are to be interpreted as ‘deopt parameters’.</p>
+<p>The ‘gc parameters’ arguments contain every pointer to a garbage
+collector object which potentially needs to be updated by the garbage
+collector.  Note that the argument list must explicitly contain a base
+pointer for every derived pointer listed.  The order of arguments is
+unimportant.  Unlike the other variable length parameter sets, this
+list is not length prefixed.</p>
+</div>
+<div class="section" id="semantics">
+<h4>Semantics:<a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h4>
+<p>A statepoint is assumed to read and write all memory.  As a result,
+memory operations can not be reordered past a statepoint.  It is
+illegal to mark a statepoint as being either ‘readonly’ or ‘readnone’.</p>
+<p>Note that legal IR can not perform any memory operation on a ‘gc
+pointer’ argument of the statepoint in a location statically reachable
+from the statepoint.  Instead, the explicitly relocated value (from a
+‘’gc.relocate’‘) must be used.</p>
+</div>
+</div>
+<div class="section" id="gc-result-intrinsic">
+<h3><a class="toc-backref" href="#id14">‘’‘gc.result’‘’ Intrinsic</a><a class="headerlink" href="#gc-result-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id2">
+<h4>Syntax:<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare type*
+  @gc.result_ptr(i32 %statepoint_token)
+
+declare fX
+  @gc.result_float(i32 %statepoint_token)
+
+declare iX
+  @gc.result_int(i32 %statepoint_token)
+</pre></div>
+</div>
+</div>
+<div class="section" id="id3">
+<h4>Overview:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p>‘’‘gc.result’‘’ extracts the result of the original call instruction
+which was replaced by the ‘’‘gc.statepoint’‘’.  The ‘’‘gc.result’‘’
+intrinsic is actually a family of three intrinsics due to an
+implementation limitation.  Other than the type of the return value,
+the semantics are the same.</p>
+</div>
+<div class="section" id="id4">
+<h4>Operands:<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<p>The first and only argument is the ‘’‘gc.statepoint’‘’ which starts
+the safepoint sequence of which this ‘’‘gc.result’’ is a part.
+Despite the typing of this as a generic i32, <em>only</em> the value defined
+by a ‘’‘gc.statepoint’‘’ is legal here.</p>
+</div>
+<div class="section" id="id5">
+<h4>Semantics:<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h4>
+<p>The ‘’gc.result’’ represents the return value of the call target of
+the ‘’statepoint’‘.  The type of the ‘’gc.result’’ must exactly match
+the type of the target.  If the call target returns void, there will
+be no ‘’gc.result’‘.</p>
+<p>A ‘’gc.result’’ is modeled as a ‘readnone’ pure function.  It has no
+side effects since it is just a projection of the return value of the
+previous call represented by the ‘’gc.statepoint’‘.</p>
+</div>
+</div>
+<div class="section" id="gc-relocate-intrinsic">
+<h3><a class="toc-backref" href="#id15">‘’‘gc.relocate’‘’ Intrinsic</a><a class="headerlink" href="#gc-relocate-intrinsic" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id6">
+<h4>Syntax:<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><div class="highlight"><pre>declare <type> addrspace(1)*
+  @gc.relocate(i32 %statepoint_token, i32 %base_offset, i32 %pointer_offset)
+</pre></div>
+</div>
+</div>
+<div class="section" id="id7">
+<h4>Overview:<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h4>
+<p>A ‘’gc.relocate’’ returns the potentially relocated value of a pointer
+at the safepoint.</p>
+</div>
+<div class="section" id="id8">
+<h4>Operands:<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h4>
+<p>The first argument is the ‘’‘gc.statepoint’‘’ which starts the
+safepoint sequence of which this ‘’‘gc.relocation’’ is a part.
+Despite the typing of this as a generic i32, <em>only</em> the value defined
+by a ‘’‘gc.statepoint’‘’ is legal here.</p>
+<p>The second argument is an index into the statepoints list of arguments
+which specifies the base pointer for the pointer being relocated.
+This index must land within the ‘gc parameter’ section of the
+statepoint’s argument list.</p>
+<p>The third argument is an index into the statepoint’s list of arguments
+which specify the (potentially) derived pointer being relocated.  It
+is legal for this index to be the same as the second argument
+if-and-only-if a base pointer is being relocated. This index must land
+within the ‘gc parameter’ section of the statepoint’s argument list.</p>
+</div>
+<div class="section" id="id9">
+<h4>Semantics:<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h4>
+<p>The return value of ‘’gc.relocate’’ is the potentially relocated value
+of the pointer specified by it’s arguments.  It is unspecified how the
+value of the returned pointer relates to the argument to the
+‘’gc.statepoint’’ other than that a) it points to the same source
+language object with the same offset, and b) the ‘based-on’
+relationship of the newly relocated pointers is a projection of the
+unrelocated pointers.  In particular, the integer value of the pointer
+returned is unspecified.</p>
+<p>A ‘’gc.relocate’’ is modeled as a ‘readnone’ pure function.  It has no
+side effects since it is just a way to extract information about work
+done during the actual call modeled by the ‘’gc.statepoint’‘.</p>
+</div>
+</div>
+</div>
+<div class="section" id="stack-map-format">
+<h2><a class="toc-backref" href="#id16">Stack Map Format</a><a class="headerlink" href="#stack-map-format" title="Permalink to this headline">¶</a></h2>
+<p>Locations for each pointer value which may need read and/or updated by
+the runtime or collector are provided via the <a class="reference internal" href="StackMaps.html#stackmap-format"><em>Stack Map format</em></a> specified in the PatchPoint documentation.</p>
+<p>Each statepoint generates the following Locations:</p>
+<ul class="simple">
+<li>Constant which describes number of following deopt <em>Locations</em> (not
+operands)</li>
+<li>Variable number of Locations, one for each deopt parameter listed in
+the IR statepoint (same number as described by previous Constant)</li>
+<li>Variable number of Locations pairs, one pair for each unique pointer
+which needs relocated.  The first Location in each pair describes
+the base pointer for the object.  The second is the derived pointer
+actually being relocated.  It is guaranteed that the base pointer
+must also appear explicitly as a relocation pair if used after the
+statepoint. There may be fewer pairs then gc parameters in the IR
+statepoint. Each <em>unique</em> pair will occur at least once; duplicates
+are possible.</li>
+</ul>
+<p>Note that the Locations used in each section may describe the same
+physical location.  e.g. A stack slot may appear as a deopt location,
+a gc base pointer, and a gc derived pointer.</p>
+<p>The ID field of the ‘StkMapRecord’ for a statepoint is meaningless and
+it’s value is explicitly unspecified.</p>
+<p>The LiveOut section of the StkMapRecord will be empty for a statepoint
+record.</p>
+</div>
+<div class="section" id="safepoint-semantics-verification">
+<h2><a class="toc-backref" href="#id17">Safepoint Semantics & Verification</a><a class="headerlink" href="#safepoint-semantics-verification" title="Permalink to this headline">¶</a></h2>
+<p>The fundamental correctness property for the compiled code’s
+correctness w.r.t. the garbage collector is a dynamic one.  It must be
+the case that there is no dynamic trace such that a operation
+involving a potentially relocated pointer is observably-after a
+safepoint which could relocate it.  ‘observably-after’ is this usage
+means that an outside observer could observe this sequence of events
+in a way which precludes the operation being performed before the
+safepoint.</p>
+<p>To understand why this ‘observable-after’ property is required,
+consider a null comparison performed on the original copy of a
+relocated pointer.  Assuming that control flow follows the safepoint,
+there is no way to observe externally whether the null comparison is
+performed before or after the safepoint.  (Remember, the original
+Value is unmodified by the safepoint.)  The compiler is free to make
+either scheduling choice.</p>
+<p>The actual correctness property implemented is slightly stronger than
+this.  We require that there be no <em>static path</em> on which a
+potentially relocated pointer is ‘observably-after’ it may have been
+relocated.  This is slightly stronger than is strictly necessary (and
+thus may disallow some otherwise valid programs), but greatly
+simplifies reasoning about correctness of the compiled code.</p>
+<p>By construction, this property will be upheld by the optimizer if
+correctly established in the source IR.  This is a key invariant of
+the design.</p>
+<p>The existing IR Verifier pass has been extended to check most of the
+local restrictions on the intrinsics mentioned in their respective
+documentation.  The current implementation in LLVM does not check the
+key relocation invariant, but this is ongoing work on developing such
+a verifier.  Please ask on llvmdev if you’re interested in
+experimenting with the current version.</p>
+</div>
+<div class="section" id="bugs-and-enhancements">
+<h2><a class="toc-backref" href="#id18">Bugs and Enhancements</a><a class="headerlink" href="#bugs-and-enhancements" title="Permalink to this headline">¶</a></h2>
+<p>Currently known bugs and enhancements under consideration can be
+tracked by performing a <a class="reference external" href="http://llvm.org/bugs/buglist.cgi?cmdtype=runnamed&namedcmd=Statepoint%20Bugs&list_id=64342">bugzilla search</a>
+for [Statepoint] in the summary field. When filing new bugs, please
+use this tag so that interested parties see the newly filed bug.  As
+with most LLVM features, design discussions take place on <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev">llvmdev</a>, and patches
+should be sent to <a class="reference external" href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits">llvm-commits</a> for review.</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="MergeFunctions.html" title="MergeFunctions pass, how it works"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="CoverageMappingFormat.html" title="LLVM Code Coverage Mapping Format"
+             >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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/SystemLibrary.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/SystemLibrary.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/SystemLibrary.html (added)
+++ www-releases/trunk/3.6.0/docs/SystemLibrary.html Fri Feb 27 12:44:09 2015
@@ -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.6 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.6',
+        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.6 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-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/TableGen/BackEnds.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/TableGen/BackEnds.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/TableGen/BackEnds.html (added)
+++ www-releases/trunk/3.6.0/docs/TableGen/BackEnds.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,496 @@
+
+<!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 BackEnds — LLVM 3.6 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.6',
+        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.6 documentation" href="../index.html" />
+    <link rel="up" title="TableGen" href="index.html" />
+    <link rel="next" title="TableGen Language Reference" href="LangRef.html" />
+    <link rel="prev" title="TableGen" href="index.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="LangRef.html" title="TableGen Language Reference"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="index.html" title="TableGen"
+             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="index.html" accesskey="U">TableGen</a> »</li> 
+      </ul>
+    </div>
+
+
+    <div class="document">
+      <div class="documentwrapper">
+          <div class="body">
+            
+  <div class="section" id="tablegen-backends">
+<h1>TableGen BackEnds<a class="headerlink" href="#tablegen-backends" 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="id1">Introduction</a></li>
+<li><a class="reference internal" href="#llvm-backends" id="id2">LLVM BackEnds</a><ul>
+<li><a class="reference internal" href="#codeemitter" id="id3">CodeEmitter</a></li>
+<li><a class="reference internal" href="#registerinfo" id="id4">RegisterInfo</a></li>
+<li><a class="reference internal" href="#instrinfo" id="id5">InstrInfo</a></li>
+<li><a class="reference internal" href="#asmwriter" id="id6">AsmWriter</a></li>
+<li><a class="reference internal" href="#asmmatcher" id="id7">AsmMatcher</a></li>
+<li><a class="reference internal" href="#disassembler" id="id8">Disassembler</a></li>
+<li><a class="reference internal" href="#pseudolowering" id="id9">PseudoLowering</a></li>
+<li><a class="reference internal" href="#callingconv" id="id10">CallingConv</a></li>
+<li><a class="reference internal" href="#dagisel" id="id11">DAGISel</a></li>
+<li><a class="reference internal" href="#dfapacketizer" id="id12">DFAPacketizer</a></li>
+<li><a class="reference internal" href="#fastisel" id="id13">FastISel</a></li>
+<li><a class="reference internal" href="#subtarget" id="id14">Subtarget</a></li>
+<li><a class="reference internal" href="#intrinsic" id="id15">Intrinsic</a></li>
+<li><a class="reference internal" href="#optparserdefs" id="id16">OptParserDefs</a></li>
+<li><a class="reference internal" href="#ctags" id="id17">CTags</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#clang-backends" id="id18">Clang BackEnds</a><ul>
+<li><a class="reference internal" href="#clangattrclasses" id="id19">ClangAttrClasses</a></li>
+<li><a class="reference internal" href="#clangattrparserstringswitches" id="id20">ClangAttrParserStringSwitches</a></li>
+<li><a class="reference internal" href="#clangattrimpl" id="id21">ClangAttrImpl</a></li>
+<li><a class="reference internal" href="#clangattrlist" id="id22">ClangAttrList</a></li>
+<li><a class="reference internal" href="#clangattrpchread" id="id23">ClangAttrPCHRead</a></li>
+<li><a class="reference internal" href="#clangattrpchwrite" id="id24">ClangAttrPCHWrite</a></li>
+<li><a class="reference internal" href="#clangattrspellings" id="id25">ClangAttrSpellings</a></li>
+<li><a class="reference internal" href="#clangattrspellinglistindex" id="id26">ClangAttrSpellingListIndex</a></li>
+<li><a class="reference internal" href="#clangattrvisitor" id="id27">ClangAttrVisitor</a></li>
+<li><a class="reference internal" href="#clangattrtemplateinstantiate" id="id28">ClangAttrTemplateInstantiate</a></li>
+<li><a class="reference internal" href="#clangattrparsedattrlist" id="id29">ClangAttrParsedAttrList</a></li>
+<li><a class="reference internal" href="#clangattrparsedattrimpl" id="id30">ClangAttrParsedAttrImpl</a></li>
+<li><a class="reference internal" href="#clangattrparsedattrkinds" id="id31">ClangAttrParsedAttrKinds</a></li>
+<li><a class="reference internal" href="#clangattrdump" id="id32">ClangAttrDump</a></li>
+<li><a class="reference internal" href="#clangdiagsdefs" id="id33">ClangDiagsDefs</a></li>
+<li><a class="reference internal" href="#clangdiaggroups" id="id34">ClangDiagGroups</a></li>
+<li><a class="reference internal" href="#clangdiagsindexname" id="id35">ClangDiagsIndexName</a></li>
+<li><a class="reference internal" href="#clangcommentnodes" id="id36">ClangCommentNodes</a></li>
+<li><a class="reference internal" href="#clangdeclnodes" id="id37">ClangDeclNodes</a></li>
+<li><a class="reference internal" href="#clangstmtnodes" id="id38">ClangStmtNodes</a></li>
+<li><a class="reference internal" href="#clangsacheckers" id="id39">ClangSACheckers</a></li>
+<li><a class="reference internal" href="#clangcommenthtmltags" id="id40">ClangCommentHTMLTags</a></li>
+<li><a class="reference internal" href="#clangcommenthtmltagsproperties" id="id41">ClangCommentHTMLTagsProperties</a></li>
+<li><a class="reference internal" href="#clangcommenthtmlnamedcharacterreferences" id="id42">ClangCommentHTMLNamedCharacterReferences</a></li>
+<li><a class="reference internal" href="#clangcommentcommandinfo" id="id43">ClangCommentCommandInfo</a></li>
+<li><a class="reference internal" href="#clangcommentcommandlist" id="id44">ClangCommentCommandList</a></li>
+<li><a class="reference internal" href="#armneon" id="id45">ArmNeon</a></li>
+<li><a class="reference internal" href="#armneonsema" id="id46">ArmNeonSema</a></li>
+<li><a class="reference internal" href="#armneontest" id="id47">ArmNeonTest</a></li>
+<li><a class="reference internal" href="#attrdocs" id="id48">AttrDocs</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#how-to-write-a-back-end" id="id49">How to write a back-end</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>TableGen backends are at the core of TableGen’s functionality. The source files
+provide the semantics to a generated (in memory) structure, but it’s up to the
+backend to print this out in a way that is meaningful to the user (normally a
+C program including a file or a textual list of warnings, options and error
+messages).</p>
+<p>TableGen is used by both LLVM and Clang with very different goals. LLVM uses it
+as a way to automate the generation of massive amounts of information regarding
+instructions, schedules, cores and architecture features. Some backends generate
+output that is consumed by more than one source file, so they need to be created
+in a way that is easy to use pre-processor tricks. Some backends can also print
+C code structures, so that they can be directly included as-is.</p>
+<p>Clang, on the other hand, uses it mainly for diagnostic messages (errors,
+warnings, tips) and attributes, so more on the textual end of the scale.</p>
+</div>
+<div class="section" id="llvm-backends">
+<h2><a class="toc-backref" href="#id2">LLVM BackEnds</a><a class="headerlink" href="#llvm-backends" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This document is raw. Each section below needs three sub-sections: description
+of its purpose with a list of users, output generated from generic input, and
+finally why it needed a new backend (in case there’s something similar).</p>
+</div>
+<p>Overall, each backend will take the same TableGen file type and transform into
+similar output for different targets/uses. There is an implicit contract between
+the TableGen files, the back-ends and their users.</p>
+<p>For instance, a global contract is that each back-end produces macro-guarded
+sections. Based on whether the file is included by a header or a source file,
+or even in which context of each file the include is being used, you have
+todefine a macro just before including it, to get the right output:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_REGINFO_TARGET_DESC</span>
+<span class="cp">#include "ARMGenRegisterInfo.inc"</span>
+</pre></div>
+</div>
+<p>And just part of the generated file would be included. This is useful if
+you need the same information in multiple formats (instantiation, initialization,
+getter/setter functions, etc) from the same source TableGen file without having
+to re-compile the TableGen file multiple times.</p>
+<p>Sometimes, multiple macros might be defined before the same include file to
+output multiple blocks:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#define GET_REGISTER_MATCHER</span>
+<span class="cp">#define GET_SUBTARGET_FEATURE_NAME</span>
+<span class="cp">#define GET_MATCHER_IMPLEMENTATION</span>
+<span class="cp">#include "ARMGenAsmMatcher.inc"</span>
+</pre></div>
+</div>
+<p>The macros will be undef’d automatically as they’re used, in the include file.</p>
+<p>On all LLVM back-ends, the <tt class="docutils literal"><span class="pre">llvm-tblgen</span></tt> binary will be executed on the root
+TableGen file <tt class="docutils literal"><span class="pre"><Target>.td</span></tt>, which should include all others. This guarantees
+that all information needed is accessible, and that no duplication is needed
+in the TbleGen files.</p>
+<div class="section" id="codeemitter">
+<h3><a class="toc-backref" href="#id3">CodeEmitter</a><a class="headerlink" href="#codeemitter" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: CodeEmitterGen uses the descriptions of instructions and their fields to
+construct an automated code emitter: a function that, given a MachineInstr,
+returns the (currently, 32-bit unsigned) value of the instruction.</p>
+<p><strong>Output</strong>: C++ code, implementing the target’s CodeEmitter
+class by overriding the virtual functions as <tt class="docutils literal"><span class="pre"><Target>CodeEmitter::function()</span></tt>.</p>
+<p><strong>Usage</strong>: Used to include directly at the end of <tt class="docutils literal"><span class="pre"><Target>MCCodeEmitter.cpp</span></tt>.</p>
+</div>
+<div class="section" id="registerinfo">
+<h3><a class="toc-backref" href="#id4">RegisterInfo</a><a class="headerlink" href="#registerinfo" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend is responsible for emitting a description of a target
+register file for a code generator.  It uses instances of the Register,
+RegisterAliases, and RegisterClass classes to gather this information.</p>
+<p><strong>Output</strong>: C++ code with enums and structures representing the register mappings,
+properties, masks, etc.</p>
+<p><strong>Usage</strong>: Both on <tt class="docutils literal"><span class="pre"><Target>BaseRegisterInfo</span></tt> and <tt class="docutils literal"><span class="pre"><Target>MCTargetDesc</span></tt> (headers
+and source files) with macros defining in which they are for declaration vs.
+initialization issues.</p>
+</div>
+<div class="section" id="instrinfo">
+<h3><a class="toc-backref" href="#id5">InstrInfo</a><a class="headerlink" href="#instrinfo" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend is responsible for emitting a description of the target
+instruction set for the code generator. (what are the differences from CodeEmitter?)</p>
+<p><strong>Output</strong>: C++ code with enums and structures representing the register mappings,
+properties, masks, etc.</p>
+<p><strong>Usage</strong>: Both on <tt class="docutils literal"><span class="pre"><Target>BaseInstrInfo</span></tt> and <tt class="docutils literal"><span class="pre"><Target>MCTargetDesc</span></tt> (headers
+and source files) with macros defining in which they are for declaration vs.</p>
+</div>
+<div class="section" id="asmwriter">
+<h3><a class="toc-backref" href="#id6">AsmWriter</a><a class="headerlink" href="#asmwriter" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Emits an assembly printer for the current target.</p>
+<p><strong>Output</strong>: Implementation of <tt class="docutils literal"><span class="pre"><Target>InstPrinter::printInstruction()</span></tt>, among
+other things.</p>
+<p><strong>Usage</strong>: Included directly into <tt class="docutils literal"><span class="pre">InstPrinter/<Target>InstPrinter.cpp</span></tt>.</p>
+</div>
+<div class="section" id="asmmatcher">
+<h3><a class="toc-backref" href="#id7">AsmMatcher</a><a class="headerlink" href="#asmmatcher" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Emits a target specifier matcher for
+converting parsed assembly operands in the MCInst structures. It also
+emits a matcher for custom operand parsing. Extensive documentation is
+written on the <tt class="docutils literal"><span class="pre">AsmMatcherEmitter.cpp</span></tt> file.</p>
+<p><strong>Output</strong>: Assembler parsers’ matcher functions, declarations, etc.</p>
+<p><strong>Usage</strong>: Used in back-ends’ <tt class="docutils literal"><span class="pre">AsmParser/<Target>AsmParser.cpp</span></tt> for
+building the AsmParser class.</p>
+</div>
+<div class="section" id="disassembler">
+<h3><a class="toc-backref" href="#id8">Disassembler</a><a class="headerlink" href="#disassembler" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Contains disassembler table emitters for various
+architectures. Extensive documentation is written on the
+<tt class="docutils literal"><span class="pre">DisassemblerEmitter.cpp</span></tt> file.</p>
+<p><strong>Output</strong>: Decoding tables, static decoding functions, etc.</p>
+<p><strong>Usage</strong>: Directly included in <tt class="docutils literal"><span class="pre">Disassembler/<Target>Disassembler.cpp</span></tt>
+to cater for all default decodings, after all hand-made ones.</p>
+</div>
+<div class="section" id="pseudolowering">
+<h3><a class="toc-backref" href="#id9">PseudoLowering</a><a class="headerlink" href="#pseudolowering" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate pseudo instruction lowering.</p>
+<p><strong>Output</strong>: Implements <tt class="docutils literal"><span class="pre">ARMAsmPrinter::emitPseudoExpansionLowering()</span></tt>.</p>
+<p><strong>Usage</strong>: Included directly into <tt class="docutils literal"><span class="pre"><Target>AsmPrinter.cpp</span></tt>.</p>
+</div>
+<div class="section" id="callingconv">
+<h3><a class="toc-backref" href="#id10">CallingConv</a><a class="headerlink" href="#callingconv" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Responsible for emitting descriptions of the calling
+conventions supported by this target.</p>
+<p><strong>Output</strong>: Implement static functions to deal with calling conventions
+chained by matching styles, returning false on no match.</p>
+<p><strong>Usage</strong>: Used in ISelLowering and FastIsel as function pointers to
+implementation returned by a CC sellection function.</p>
+</div>
+<div class="section" id="dagisel">
+<h3><a class="toc-backref" href="#id11">DAGISel</a><a class="headerlink" href="#dagisel" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate a DAG instruction selector.</p>
+<p><strong>Output</strong>: Creates huge functions for automating DAG selection.</p>
+<p><strong>Usage</strong>: Included in <tt class="docutils literal"><span class="pre"><Target>ISelDAGToDAG.cpp</span></tt> inside the target’s
+implementation of <tt class="docutils literal"><span class="pre">SelectionDAGISel</span></tt>.</p>
+</div>
+<div class="section" id="dfapacketizer">
+<h3><a class="toc-backref" href="#id12">DFAPacketizer</a><a class="headerlink" href="#dfapacketizer" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This class parses the Schedule.td file and produces an API that
+can be used to reason about whether an instruction can be added to a packet
+on a VLIW architecture. The class internally generates a deterministic finite
+automaton (DFA) that models all possible mappings of machine instructions
+to functional units as instructions are added to a packet.</p>
+<p><strong>Output</strong>: Scheduling tables for GPU back-ends (Hexagon, AMD).</p>
+<p><strong>Usage</strong>: Included directly on <tt class="docutils literal"><span class="pre"><Target>InstrInfo.cpp</span></tt>.</p>
+</div>
+<div class="section" id="fastisel">
+<h3><a class="toc-backref" href="#id13">FastISel</a><a class="headerlink" href="#fastisel" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend emits code for use by the “fast”
+instruction selection algorithm. See the comments at the top of
+lib/CodeGen/SelectionDAG/FastISel.cpp for background. This file
+scans through the target’s tablegen instruction-info files
+and extracts instructions with obvious-looking patterns, and it emits
+code to look up these instructions by type and operator.</p>
+<p><strong>Output</strong>: Generates <tt class="docutils literal"><span class="pre">Predicate</span></tt> and <tt class="docutils literal"><span class="pre">FastEmit</span></tt> methods.</p>
+<p><strong>Usage</strong>: Implements private methods of the targets’ implementation
+of <tt class="docutils literal"><span class="pre">FastISel</span></tt> class.</p>
+</div>
+<div class="section" id="subtarget">
+<h3><a class="toc-backref" href="#id14">Subtarget</a><a class="headerlink" href="#subtarget" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate subtarget enumerations.</p>
+<p><strong>Output</strong>: Enums, globals, local tables for sub-target information.</p>
+<p><strong>Usage</strong>: Populates <tt class="docutils literal"><span class="pre"><Target>Subtarget</span></tt> and
+<tt class="docutils literal"><span class="pre">MCTargetDesc/<Target>MCTargetDesc</span></tt> files (both headers and source).</p>
+</div>
+<div class="section" id="intrinsic">
+<h3><a class="toc-backref" href="#id15">Intrinsic</a><a class="headerlink" href="#intrinsic" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Generate (target) intrinsic information.</p>
+</div>
+<div class="section" id="optparserdefs">
+<h3><a class="toc-backref" href="#id16">OptParserDefs</a><a class="headerlink" href="#optparserdefs" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Print enum values for a class.</p>
+</div>
+<div class="section" id="ctags">
+<h3><a class="toc-backref" href="#id17">CTags</a><a class="headerlink" href="#ctags" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: This tablegen backend emits an index of definitions in ctags(1)
+format. A helper script, utils/TableGen/tdtags, provides an easier-to-use
+interface; run ‘tdtags -H’ for documentation.</p>
+</div>
+</div>
+<div class="section" id="clang-backends">
+<h2><a class="toc-backref" href="#id18">Clang BackEnds</a><a class="headerlink" href="#clang-backends" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="clangattrclasses">
+<h3><a class="toc-backref" href="#id19">ClangAttrClasses</a><a class="headerlink" href="#clangattrclasses" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates Attrs.inc, which contains semantic attribute class
+declarations for any attribute in <tt class="docutils literal"><span class="pre">Attr.td</span></tt> that has not set <tt class="docutils literal"><span class="pre">ASTNode</span> <span class="pre">=</span> <span class="pre">0</span></tt>.
+This file is included as part of <tt class="docutils literal"><span class="pre">Attr.h</span></tt>.</p>
+</div>
+<div class="section" id="clangattrparserstringswitches">
+<h3><a class="toc-backref" href="#id20">ClangAttrParserStringSwitches</a><a class="headerlink" href="#clangattrparserstringswitches" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParserStringSwitches.inc, which contains
+StringSwitch::Case statements for parser-related string switches. Each switch
+is given its own macro (such as <tt class="docutils literal"><span class="pre">CLANG_ATTR_ARG_CONTEXT_LIST</span></tt>, or
+<tt class="docutils literal"><span class="pre">CLANG_ATTR_IDENTIFIER_ARG_LIST</span></tt>), which is expected to be defined before
+including AttrParserStringSwitches.inc, and undefined after.</p>
+</div>
+<div class="section" id="clangattrimpl">
+<h3><a class="toc-backref" href="#id21">ClangAttrImpl</a><a class="headerlink" href="#clangattrimpl" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrImpl.inc, which contains semantic attribute class
+definitions for any attribute in <tt class="docutils literal"><span class="pre">Attr.td</span></tt> that has not set <tt class="docutils literal"><span class="pre">ASTNode</span> <span class="pre">=</span> <span class="pre">0</span></tt>.
+This file is included as part of <tt class="docutils literal"><span class="pre">AttrImpl.cpp</span></tt>.</p>
+</div>
+<div class="section" id="clangattrlist">
+<h3><a class="toc-backref" href="#id22">ClangAttrList</a><a class="headerlink" href="#clangattrlist" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrList.inc, which is used when a list of semantic
+attribute identifiers is required. For instance, <tt class="docutils literal"><span class="pre">AttrKinds.h</span></tt> includes this
+file to generate the list of <tt class="docutils literal"><span class="pre">attr::Kind</span></tt> enumeration values. This list is
+separated out into multiple categories: attributes, inheritable attributes, and
+inheritable parameter attributes. This categorization happens automatically
+based on information in <tt class="docutils literal"><span class="pre">Attr.td</span></tt> and is used to implement the <tt class="docutils literal"><span class="pre">classof</span></tt>
+functionality required for <tt class="docutils literal"><span class="pre">dyn_cast</span></tt> and similar APIs.</p>
+</div>
+<div class="section" id="clangattrpchread">
+<h3><a class="toc-backref" href="#id23">ClangAttrPCHRead</a><a class="headerlink" href="#clangattrpchread" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrPCHRead.inc, which is used to deserialize attributes
+in the <tt class="docutils literal"><span class="pre">ASTReader::ReadAttributes</span></tt> function.</p>
+</div>
+<div class="section" id="clangattrpchwrite">
+<h3><a class="toc-backref" href="#id24">ClangAttrPCHWrite</a><a class="headerlink" href="#clangattrpchwrite" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrPCHWrite.inc, which is used to serialize attributes in
+the <tt class="docutils literal"><span class="pre">ASTWriter::WriteAttributes</span></tt> function.</p>
+</div>
+<div class="section" id="clangattrspellings">
+<h3><a class="toc-backref" href="#id25">ClangAttrSpellings</a><a class="headerlink" href="#clangattrspellings" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrSpellings.inc, which is used to implement the
+<tt class="docutils literal"><span class="pre">__has_attribute</span></tt> feature test macro.</p>
+</div>
+<div class="section" id="clangattrspellinglistindex">
+<h3><a class="toc-backref" href="#id26">ClangAttrSpellingListIndex</a><a class="headerlink" href="#clangattrspellinglistindex" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrSpellingListIndex.inc, which is used to map parsed
+attribute spellings (including which syntax or scope was used) to an attribute
+spelling list index. These spelling list index values are internal
+implementation details exposed via
+<tt class="docutils literal"><span class="pre">AttributeList::getAttributeSpellingListIndex</span></tt>.</p>
+</div>
+<div class="section" id="clangattrvisitor">
+<h3><a class="toc-backref" href="#id27">ClangAttrVisitor</a><a class="headerlink" href="#clangattrvisitor" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrVisitor.inc, which is used when implementing
+recursive AST visitors.</p>
+</div>
+<div class="section" id="clangattrtemplateinstantiate">
+<h3><a class="toc-backref" href="#id28">ClangAttrTemplateInstantiate</a><a class="headerlink" href="#clangattrtemplateinstantiate" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrTemplateInstantiate.inc, which implements the
+<tt class="docutils literal"><span class="pre">instantiateTemplateAttribute</span></tt> function, used when instantiating a template
+that requires an attribute to be cloned.</p>
+</div>
+<div class="section" id="clangattrparsedattrlist">
+<h3><a class="toc-backref" href="#id29">ClangAttrParsedAttrList</a><a class="headerlink" href="#clangattrparsedattrlist" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParsedAttrList.inc, which is used to generate the
+<tt class="docutils literal"><span class="pre">AttributeList::Kind</span></tt> parsed attribute enumeration.</p>
+</div>
+<div class="section" id="clangattrparsedattrimpl">
+<h3><a class="toc-backref" href="#id30">ClangAttrParsedAttrImpl</a><a class="headerlink" href="#clangattrparsedattrimpl" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParsedAttrImpl.inc, which is used by
+<tt class="docutils literal"><span class="pre">AttributeList.cpp</span></tt> to implement several functions on the <tt class="docutils literal"><span class="pre">AttributeList</span></tt>
+class. This functionality is implemented via the <tt class="docutils literal"><span class="pre">AttrInfoMap</span> <span class="pre">ParsedAttrInfo</span></tt>
+array, which contains one element per parsed attribute object.</p>
+</div>
+<div class="section" id="clangattrparsedattrkinds">
+<h3><a class="toc-backref" href="#id31">ClangAttrParsedAttrKinds</a><a class="headerlink" href="#clangattrparsedattrkinds" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrParsedAttrKinds.inc, which is used to implement the
+<tt class="docutils literal"><span class="pre">AttributeList::getKind</span></tt> function, mapping a string (and syntax) to a parsed
+attribute <tt class="docutils literal"><span class="pre">AttributeList::Kind</span></tt> enumeration.</p>
+</div>
+<div class="section" id="clangattrdump">
+<h3><a class="toc-backref" href="#id32">ClangAttrDump</a><a class="headerlink" href="#clangattrdump" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates AttrDump.inc, which dumps information about an attribute.
+It is used to implement <tt class="docutils literal"><span class="pre">ASTDumper::dumpAttr</span></tt>.</p>
+</div>
+<div class="section" id="clangdiagsdefs">
+<h3><a class="toc-backref" href="#id33">ClangDiagsDefs</a><a class="headerlink" href="#clangdiagsdefs" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang diagnostics definitions.</p>
+</div>
+<div class="section" id="clangdiaggroups">
+<h3><a class="toc-backref" href="#id34">ClangDiagGroups</a><a class="headerlink" href="#clangdiaggroups" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang diagnostic groups.</p>
+</div>
+<div class="section" id="clangdiagsindexname">
+<h3><a class="toc-backref" href="#id35">ClangDiagsIndexName</a><a class="headerlink" href="#clangdiagsindexname" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang diagnostic name index.</p>
+</div>
+<div class="section" id="clangcommentnodes">
+<h3><a class="toc-backref" href="#id36">ClangCommentNodes</a><a class="headerlink" href="#clangcommentnodes" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang AST comment nodes.</p>
+</div>
+<div class="section" id="clangdeclnodes">
+<h3><a class="toc-backref" href="#id37">ClangDeclNodes</a><a class="headerlink" href="#clangdeclnodes" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang AST declaration nodes.</p>
+</div>
+<div class="section" id="clangstmtnodes">
+<h3><a class="toc-backref" href="#id38">ClangStmtNodes</a><a class="headerlink" href="#clangstmtnodes" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang AST statement nodes.</p>
+</div>
+<div class="section" id="clangsacheckers">
+<h3><a class="toc-backref" href="#id39">ClangSACheckers</a><a class="headerlink" href="#clangsacheckers" title="Permalink to this headline">¶</a></h3>
+<p>Generate Clang Static Analyzer checkers.</p>
+</div>
+<div class="section" id="clangcommenthtmltags">
+<h3><a class="toc-backref" href="#id40">ClangCommentHTMLTags</a><a class="headerlink" href="#clangcommenthtmltags" title="Permalink to this headline">¶</a></h3>
+<p>Generate efficient matchers for HTML tag names that are used in documentation comments.</p>
+</div>
+<div class="section" id="clangcommenthtmltagsproperties">
+<h3><a class="toc-backref" href="#id41">ClangCommentHTMLTagsProperties</a><a class="headerlink" href="#clangcommenthtmltagsproperties" title="Permalink to this headline">¶</a></h3>
+<p>Generate efficient matchers for HTML tag properties.</p>
+</div>
+<div class="section" id="clangcommenthtmlnamedcharacterreferences">
+<h3><a class="toc-backref" href="#id42">ClangCommentHTMLNamedCharacterReferences</a><a class="headerlink" href="#clangcommenthtmlnamedcharacterreferences" title="Permalink to this headline">¶</a></h3>
+<p>Generate function to translate named character references to UTF-8 sequences.</p>
+</div>
+<div class="section" id="clangcommentcommandinfo">
+<h3><a class="toc-backref" href="#id43">ClangCommentCommandInfo</a><a class="headerlink" href="#clangcommentcommandinfo" title="Permalink to this headline">¶</a></h3>
+<p>Generate command properties for commands that are used in documentation comments.</p>
+</div>
+<div class="section" id="clangcommentcommandlist">
+<h3><a class="toc-backref" href="#id44">ClangCommentCommandList</a><a class="headerlink" href="#clangcommentcommandlist" title="Permalink to this headline">¶</a></h3>
+<p>Generate list of commands that are used in documentation comments.</p>
+</div>
+<div class="section" id="armneon">
+<h3><a class="toc-backref" href="#id45">ArmNeon</a><a class="headerlink" href="#armneon" title="Permalink to this headline">¶</a></h3>
+<p>Generate arm_neon.h for clang.</p>
+</div>
+<div class="section" id="armneonsema">
+<h3><a class="toc-backref" href="#id46">ArmNeonSema</a><a class="headerlink" href="#armneonsema" title="Permalink to this headline">¶</a></h3>
+<p>Generate ARM NEON sema support for clang.</p>
+</div>
+<div class="section" id="armneontest">
+<h3><a class="toc-backref" href="#id47">ArmNeonTest</a><a class="headerlink" href="#armneontest" title="Permalink to this headline">¶</a></h3>
+<p>Generate ARM NEON tests for clang.</p>
+</div>
+<div class="section" id="attrdocs">
+<h3><a class="toc-backref" href="#id48">AttrDocs</a><a class="headerlink" href="#attrdocs" title="Permalink to this headline">¶</a></h3>
+<p><strong>Purpose</strong>: Creates <tt class="docutils literal"><span class="pre">AttributeReference.rst</span></tt> from <tt class="docutils literal"><span class="pre">AttrDocs.td</span></tt>, and is
+used for documenting user-facing attributes.</p>
+</div>
+</div>
+<div class="section" id="how-to-write-a-back-end">
+<h2><a class="toc-backref" href="#id49">How to write a back-end</a><a class="headerlink" href="#how-to-write-a-back-end" title="Permalink to this headline">¶</a></h2>
+<p>TODO.</p>
+<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="LangRef.html" title="TableGen Language Reference"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="index.html" title="TableGen"
+             >previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="../index.html">Documentation</a>»</li>
+
+          <li><a href="index.html" >TableGen</a> »</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        © Copyright 2003-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/TableGen/Deficiencies.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/TableGen/Deficiencies.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/TableGen/Deficiencies.html (added)
+++ www-releases/trunk/3.6.0/docs/TableGen/Deficiencies.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,128 @@
+
+<!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 Deficiencies — LLVM 3.6 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.6',
+        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.6 documentation" href="../index.html" />
+    <link rel="up" title="TableGen" href="index.html" />
+    <link rel="next" title="Debugging JIT-ed Code With GDB" href="../DebuggingJITedCode.html" />
+    <link rel="prev" title="TableGen Language Introduction" href="LangIntro.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="LangIntro.html" title="TableGen Language Introduction"
+             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="index.html" accesskey="U">TableGen</a> »</li> 
+      </ul>
+    </div>
+
+
+    <div class="document">
+      <div class="documentwrapper">
+          <div class="body">
+            
+  <div class="section" id="tablegen-deficiencies">
+<h1>TableGen Deficiencies<a class="headerlink" href="#tablegen-deficiencies" 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="id1">Introduction</a></li>
+<li><a class="reference internal" href="#known-problems" id="id2">Known Problems</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Despite being very generic, TableGen has some deficiencies that have been
+pointed out numerous times. The common theme is that, while TableGen allows
+you to build Domain-Specific-Languages, the final languages that you create
+lack the power of other DSLs, which in turn increase considerably the size
+and complexity of TableGen files.</p>
+<p>At the same time, TableGen allows you to create virtually any meaning of
+the basic concepts via custom-made back-ends, which can pervert the original
+design and make it very hard for newcomers to understand it.</p>
+<p>There are some in favour of extending the semantics even more, but making sure
+back-ends adhere to strict rules. Others suggesting we should move to more
+powerful DSLs designed with specific purposes, or even re-using existing
+DSLs.</p>
+</div>
+<div class="section" id="known-problems">
+<h2><a class="toc-backref" href="#id2">Known Problems</a><a class="headerlink" href="#known-problems" title="Permalink to this headline">¶</a></h2>
+<p>TODO: Add here frequently asked questions about why TableGen doesn’t do
+what you want, how it might, and how we could extend/restrict it to
+be more use friendly.</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="LangIntro.html" title="TableGen Language Introduction"
+             >previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="../index.html">Documentation</a>»</li>
+
+          <li><a href="index.html" >TableGen</a> »</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        © Copyright 2003-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file

Added: www-releases/trunk/3.6.0/docs/TableGen/LangIntro.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/3.6.0/docs/TableGen/LangIntro.html?rev=230777&view=auto
==============================================================================
--- www-releases/trunk/3.6.0/docs/TableGen/LangIntro.html (added)
+++ www-releases/trunk/3.6.0/docs/TableGen/LangIntro.html Fri Feb 27 12:44:09 2015
@@ -0,0 +1,647 @@
+
+<!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 Introduction — LLVM 3.6 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.6',
+        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.6 documentation" href="../index.html" />
+    <link rel="up" title="TableGen" href="index.html" />
+    <link rel="next" title="TableGen Deficiencies" href="Deficiencies.html" />
+    <link rel="prev" title="TableGen Language Reference" href="LangRef.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="Deficiencies.html" title="TableGen Deficiencies"
+             accesskey="N">next</a> |</li>
+        <li class="right" >
+          <a href="LangRef.html" title="TableGen Language Reference"
+             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="index.html" accesskey="U">TableGen</a> »</li> 
+      </ul>
+    </div>
+
+
+    <div class="document">
+      <div class="documentwrapper">
+          <div class="body">
+            
+  <div class="section" id="tablegen-language-introduction">
+<h1>TableGen Language Introduction<a class="headerlink" href="#tablegen-language-introduction" 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="id4">Introduction</a></li>
+<li><a class="reference internal" href="#tablegen-syntax" id="id5">TableGen syntax</a><ul>
+<li><a class="reference internal" href="#tablegen-primitives" id="id6">TableGen primitives</a><ul>
+<li><a class="reference internal" href="#tablegen-comments" id="id7">TableGen comments</a></li>
+<li><a class="reference internal" href="#the-tablegen-type-system" id="id8">The TableGen type system</a></li>
+<li><a class="reference internal" href="#tablegen-values-and-expressions" id="id9">TableGen values and expressions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#classes-and-definitions" id="id10">Classes and definitions</a><ul>
+<li><a class="reference internal" href="#value-definitions" id="id11">Value definitions</a></li>
+<li><a class="reference internal" href="#let-expressions-within-a-record" id="id12">‘let’ expressions</a></li>
+<li><a class="reference internal" href="#class-template-arguments" id="id13">Class template arguments</a></li>
+<li><a class="reference internal" href="#multiclass-definitions-and-instances" id="id14">Multiclass definitions and instances</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#file-scope-entities" id="id15">File scope entities</a><ul>
+<li><a class="reference internal" href="#file-inclusion" id="id16">File inclusion</a></li>
+<li><a class="reference internal" href="#id3" id="id17">‘let’ expressions</a></li>
+<li><a class="reference internal" href="#looping" id="id18">Looping</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#code-generator-backend-info" id="id19">Code Generator backend info</a></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="#id4">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is not 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). For
+the formal language specification, see <a class="reference internal" href="LangRef.html"><em>TableGen Language Reference</em></a>.</p>
+</div>
+<div class="section" id="tablegen-syntax">
+<h2><a class="toc-backref" href="#id5">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="#id6">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="#id7">TableGen comments</a><a class="headerlink" href="#tablegen-comments" title="Permalink to this headline">¶</a></h4>
+<p>TableGen supports C++ 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="#id8">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>
+</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="#id9">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.
+Note that this is sized by the number of bits given and will not be
+silently extended/truncated.</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>usually called a “code fragment”, but is just a multiline string literal</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">0b10</span> <span class="pre">}</span></tt></dt>
+<dd>initializer for a “bits<4>” value.
+1-bit from “a”, 1-bit from “b”, 2-bits from 0b10.</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">!listconcat(a,</span> <span class="pre">b,</span> <span class="pre">...)</span></tt></dt>
+<dd>A list value that is the result of concatenating the ‘a’ and ‘b’ lists.
+The lists must have the same element type.
+More than two arguments are accepted with the result being the concatenation
+of all the lists given.</dd>
+<dt><tt class="docutils literal"><span class="pre">!strconcat(a,</span> <span class="pre">b,</span> <span class="pre">...)</span></tt></dt>
+<dd>A string value that is the result of concatenating the ‘a’ and ‘b’ strings.
+More than two arguments are accepted with the result being the concatenation
+of all the strings given.</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>
+<dt><tt class="docutils literal"><span class="pre">!shl(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!srl(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!sra(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!add(a,b)</span></tt> <tt class="docutils literal"><span class="pre">!and(a,b)</span></tt></dt>
+<dd>The usual binary and arithmetic operators.</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="#id10">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="index.html"><em>introduction</em></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"><div class="highlight"><pre>class C { bit V = 1; }
+def X : C;
+def Y : C {
+  string Greeting = "hello";
+}
+</pre></div>
+</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="#id11">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="#id12">‘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"><div class="highlight"><pre>class D : C { let V = 0; }
+def Z : D;
+</pre></div>
+</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="#id13">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"><div class="highlight"><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>
+</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"><div class="highlight"><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>
+</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"><div class="highlight"><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>
+</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="#id14">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"><div class="highlight"><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>
+</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"><div class="highlight"><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>
+</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 instantiations.</p>
+<div class="highlight-llvm"><div class="highlight"><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>
+</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"><div class="highlight"><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>
+<div class="section" id="file-scope-entities">
+<h3><a class="toc-backref" href="#id15">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="#id16">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"><div class="highlight"><pre>include "foo.td"
+</pre></div>
+</div>
+</div>
+<div class="section" id="id3">
+<h4><a class="toc-backref" href="#id17">‘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"><div class="highlight"><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>
+</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 instantiations. This also avoids the need of using “let”
+expressions within subsequent records inside a multiclass.</p>
+<div class="highlight-llvm"><div class="highlight"><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>
+<div class="section" id="looping">
+<h4><a class="toc-backref" href="#id18">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"><div class="highlight"><pre>foreach i = [0, 1, 2, 3] in {
+  def R#i : Register<...>;
+  def F#i : Register<...>;
+}
+</pre></div>
+</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"><div class="highlight"><pre>foreach i = [0, 1, 2, 3] in
+  def R#i : Register<...>;
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="code-generator-backend-info">
+<h2><a class="toc-backref" href="#id19">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>
+
+
+          </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="Deficiencies.html" title="TableGen Deficiencies"
+             >next</a> |</li>
+        <li class="right" >
+          <a href="LangRef.html" title="TableGen Language Reference"
+             >previous</a> |</li>
+  <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+  <li><a href="../index.html">Documentation</a>»</li>
+
+          <li><a href="index.html" >TableGen</a> »</li> 
+      </ul>
+    </div>
+    <div class="footer">
+        © Copyright 2003-2014, LLVM Project.
+      Last updated on 2015-01-21.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
+    </div>
+  </body>
+</html>
\ No newline at end of file






More information about the llvm-commits mailing list