[www-releases] r368037 - Add 8.0.1 LLVM docs
Tom Stellard via llvm-commits
llvm-commits at lists.llvm.org
Tue Aug 6 06:51:06 PDT 2019
Added: www-releases/trunk/8.0.1/docs/ProgrammersManual.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/ProgrammersManual.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/ProgrammersManual.html (added)
+++ www-releases/trunk/8.0.1/docs/ProgrammersManual.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,3586 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>LLVM Programmerâs Manual — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <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" role="main">
+
+ <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="id8">Introduction</a></li>
+<li><a class="reference internal" href="#general-information" id="id9">General Information</a><ul>
+<li><a class="reference internal" href="#the-c-standard-template-library" id="id10">The C++ Standard Template Library</a></li>
+<li><a class="reference internal" href="#other-useful-references" id="id11">Other useful references</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#important-and-useful-llvm-apis" id="id12">Important and useful LLVM APIs</a><ul>
+<li><a class="reference internal" href="#the-isa-cast-and-dyn-cast-templates" id="id13">The <code class="docutils literal notranslate"><span class="pre">isa<></span></code>, <code class="docutils literal notranslate"><span class="pre">cast<></span></code> and <code class="docutils literal notranslate"><span class="pre">dyn_cast<></span></code> templates</a></li>
+<li><a class="reference internal" href="#passing-strings-the-stringref-and-twine-classes" id="id14">Passing strings (the <code class="docutils literal notranslate"><span class="pre">StringRef</span></code> and <code class="docutils literal notranslate"><span class="pre">Twine</span></code> classes)</a><ul>
+<li><a class="reference internal" href="#the-stringref-class" id="id15">The <code class="docutils literal notranslate"><span class="pre">StringRef</span></code> class</a></li>
+<li><a class="reference internal" href="#the-twine-class" id="id16">The <code class="docutils literal notranslate"><span class="pre">Twine</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#formatting-strings-the-formatv-function" id="id17">Formatting strings (the <code class="docutils literal notranslate"><span class="pre">formatv</span></code> function)</a><ul>
+<li><a class="reference internal" href="#simple-formatting" id="id18">Simple formatting</a></li>
+<li><a class="reference internal" href="#custom-formatting" id="id19">Custom formatting</a></li>
+<li><a class="reference internal" href="#formatv-examples" id="id20"><code class="docutils literal notranslate"><span class="pre">formatv</span></code> Examples</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#error-handling" id="id21">Error handling</a><ul>
+<li><a class="reference internal" href="#programmatic-errors" id="id22">Programmatic Errors</a></li>
+<li><a class="reference internal" href="#recoverable-errors" id="id23">Recoverable Errors</a><ul>
+<li><a class="reference internal" href="#stringerror" id="id24">StringError</a></li>
+<li><a class="reference internal" href="#interoperability-with-std-error-code-and-erroror" id="id25">Interoperability with std::error_code and ErrorOr</a></li>
+<li><a class="reference internal" href="#returning-errors-from-error-handlers" id="id26">Returning Errors from error handlers</a></li>
+<li><a class="reference internal" href="#using-exitonerror-to-simplify-tool-code" id="id27">Using ExitOnError to simplify tool code</a></li>
+<li><a class="reference internal" href="#using-cantfail-to-simplify-safe-callsites" id="id28">Using cantFail to simplify safe callsites</a></li>
+<li><a class="reference internal" href="#fallible-constructors" id="id29">Fallible constructors</a></li>
+<li><a class="reference internal" href="#propagating-and-consuming-errors-based-on-types" id="id30">Propagating and consuming errors based on types</a></li>
+<li><a class="reference internal" href="#concatenating-errors-with-joinerrors" id="id31">Concatenating Errors with joinErrors</a></li>
+<li><a class="reference internal" href="#building-fallible-iterators-and-iterator-ranges" id="id32">Building fallible iterators and iterator ranges</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#passing-functions-and-other-callable-objects" id="id33">Passing functions and other callable objects</a><ul>
+<li><a class="reference internal" href="#function-template" id="id34">Function template</a></li>
+<li><a class="reference internal" href="#the-function-ref-class-template" id="id35">The <code class="docutils literal notranslate"><span class="pre">function_ref</span></code> class template</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-llvm-debug-macro-and-debug-option" id="id36">The <code class="docutils literal notranslate"><span class="pre">LLVM_DEBUG()</span></code> macro and <code class="docutils literal notranslate"><span class="pre">-debug</span></code> option</a><ul>
+<li><a class="reference internal" href="#fine-grained-debug-info-with-debug-type-and-the-debug-only-option" id="id37">Fine grained debug info with <code class="docutils literal notranslate"><span class="pre">DEBUG_TYPE</span></code> and the <code class="docutils literal notranslate"><span class="pre">-debug-only</span></code> option</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-statistic-class-stats-option" id="id38">The <code class="docutils literal notranslate"><span class="pre">Statistic</span></code> class & <code class="docutils literal notranslate"><span class="pre">-stats</span></code> option</a></li>
+<li><a class="reference internal" href="#adding-debug-counters-to-aid-in-debugging-your-code" id="id39">Adding debug counters to aid in debugging your code</a></li>
+<li><a class="reference internal" href="#viewing-graphs-while-debugging-code" id="id40">Viewing graphs while debugging code</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#picking-the-right-data-structure-for-a-task" id="id41">Picking the Right Data Structure for a Task</a><ul>
+<li><a class="reference internal" href="#sequential-containers-std-vector-std-list-etc" id="id42">Sequential Containers (std::vector, std::list, etc)</a><ul>
+<li><a class="reference internal" href="#llvm-adt-arrayref-h" id="id43">llvm/ADT/ArrayRef.h</a></li>
+<li><a class="reference internal" href="#fixed-size-arrays" id="id44">Fixed Size Arrays</a></li>
+<li><a class="reference internal" href="#heap-allocated-arrays" id="id45">Heap Allocated Arrays</a></li>
+<li><a class="reference internal" href="#llvm-adt-tinyptrvector-h" id="id46">llvm/ADT/TinyPtrVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallvector-h" id="id47">llvm/ADT/SmallVector.h</a></li>
+<li><a class="reference internal" href="#vector" id="id48"><vector></a></li>
+<li><a class="reference internal" href="#deque" id="id49"><deque></a></li>
+<li><a class="reference internal" href="#list" id="id50"><list></a></li>
+<li><a class="reference internal" href="#llvm-adt-ilist-h" id="id51">llvm/ADT/ilist.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-packedvector-h" id="id52">llvm/ADT/PackedVector.h</a></li>
+<li><a class="reference internal" href="#ilist-traits" id="id53">ilist_traits</a></li>
+<li><a class="reference internal" href="#iplist" id="id54">iplist</a></li>
+<li><a class="reference internal" href="#llvm-adt-ilist-node-h" id="id55">llvm/ADT/ilist_node.h</a></li>
+<li><a class="reference internal" href="#sentinels" id="id56">Sentinels</a></li>
+<li><a class="reference internal" href="#other-sequential-container-options" id="id57">Other Sequential Container options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#string-like-containers" id="id58">String-like containers</a><ul>
+<li><a class="reference internal" href="#llvm-adt-stringref-h" id="id59">llvm/ADT/StringRef.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-twine-h" id="id60">llvm/ADT/Twine.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallstring-h" id="id61">llvm/ADT/SmallString.h</a></li>
+<li><a class="reference internal" href="#std-string" id="id62">std::string</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#set-like-containers-std-set-smallset-setvector-etc" id="id63">Set-Like Containers (std::set, SmallSet, SetVector, etc)</a><ul>
+<li><a class="reference internal" href="#a-sorted-vector" id="id64">A sorted âvectorâ</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallset-h" id="id65">llvm/ADT/SmallSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-smallptrset-h" id="id66">llvm/ADT/SmallPtrSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-stringset-h" id="id67">llvm/ADT/StringSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-denseset-h" id="id68">llvm/ADT/DenseSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-sparseset-h" id="id69">llvm/ADT/SparseSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-sparsemultiset-h" id="id70">llvm/ADT/SparseMultiSet.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-foldingset-h" id="id71">llvm/ADT/FoldingSet.h</a></li>
+<li><a class="reference internal" href="#set" id="id72"><set></a></li>
+<li><a class="reference internal" href="#llvm-adt-setvector-h" id="id73">llvm/ADT/SetVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-uniquevector-h" id="id74">llvm/ADT/UniqueVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-immutableset-h" id="id75">llvm/ADT/ImmutableSet.h</a></li>
+<li><a class="reference internal" href="#other-set-like-container-options" id="id76">Other Set-Like Container Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#map-like-containers-std-map-densemap-etc" id="id77">Map-Like Containers (std::map, DenseMap, etc)</a><ul>
+<li><a class="reference internal" href="#dss-sortedvectormap" id="id78">A sorted âvectorâ</a></li>
+<li><a class="reference internal" href="#llvm-adt-stringmap-h" id="id79">llvm/ADT/StringMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-indexedmap-h" id="id80">llvm/ADT/IndexedMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-densemap-h" id="id81">llvm/ADT/DenseMap.h</a></li>
+<li><a class="reference internal" href="#llvm-ir-valuemap-h" id="id82">llvm/IR/ValueMap.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-intervalmap-h" id="id83">llvm/ADT/IntervalMap.h</a></li>
+<li><a class="reference internal" href="#map" id="id84"><map></a></li>
+<li><a class="reference internal" href="#llvm-adt-mapvector-h" id="id85">llvm/ADT/MapVector.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-inteqclasses-h" id="id86">llvm/ADT/IntEqClasses.h</a></li>
+<li><a class="reference internal" href="#llvm-adt-immutablemap-h" id="id87">llvm/ADT/ImmutableMap.h</a></li>
+<li><a class="reference internal" href="#other-map-like-container-options" id="id88">Other Map-Like Container Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#bit-storage-containers-bitvector-sparsebitvector" id="id89">Bit storage containers (BitVector, SparseBitVector)</a><ul>
+<li><a class="reference internal" href="#bitvector" id="id90">BitVector</a></li>
+<li><a class="reference internal" href="#smallbitvector" id="id91">SmallBitVector</a></li>
+<li><a class="reference internal" href="#sparsebitvector" id="id92">SparseBitVector</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#debugging" id="id93">Debugging</a></li>
+<li><a class="reference internal" href="#helpful-hints-for-common-operations" id="id94">Helpful Hints for Common Operations</a><ul>
+<li><a class="reference internal" href="#basic-inspection-and-traversal-routines" id="id95">Basic Inspection and Traversal Routines</a><ul>
+<li><a class="reference internal" href="#iterating-over-the-basicblock-in-a-function" id="id96">Iterating over the <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> in a <code class="docutils literal notranslate"><span class="pre">Function</span></code></a></li>
+<li><a class="reference internal" href="#iterating-over-the-instruction-in-a-basicblock" id="id97">Iterating over the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> in a <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code></a></li>
+<li><a class="reference internal" href="#iterating-over-the-instruction-in-a-function" id="id98">Iterating over the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> in a <code class="docutils literal notranslate"><span class="pre">Function</span></code></a></li>
+<li><a class="reference internal" href="#turning-an-iterator-into-a-class-pointer-and-vice-versa" id="id99">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="id100">Finding call sites: a slightly more complex example</a></li>
+<li><a class="reference internal" href="#treating-calls-and-invokes-the-same-way" id="id101">Treating calls and invokes the same way</a></li>
+<li><a class="reference internal" href="#iterating-over-def-use-use-def-chains" id="id102">Iterating over def-use & use-def chains</a></li>
+<li><a class="reference internal" href="#iterating-over-predecessors-successors-of-blocks" id="id103">Iterating over predecessors & successors of blocks</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#making-simple-changes" id="id104">Making simple changes</a><ul>
+<li><a class="reference internal" href="#creating-and-inserting-new-instructions" id="id105">Creating and inserting new <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>s</a></li>
+<li><a class="reference internal" href="#deleting-instructions" id="id106">Deleting Instructions</a></li>
+<li><a class="reference internal" href="#replacing-an-instruction-with-another-value" id="id107">Replacing an Instruction with another Value</a><ul>
+<li><a class="reference internal" href="#replacing-individual-instructions" id="id108">Replacing individual instructions</a></li>
+<li><a class="reference internal" href="#schanges-deleting-sub" id="id109">Deleting Instructions</a></li>
+<li><a class="reference internal" href="#replacing-multiple-uses-of-users-and-values" id="id110">Replacing multiple uses of Users and Values</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#deleting-globalvariables" id="id111">Deleting GlobalVariables</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#threads-and-llvm" id="id112">Threads and LLVM</a><ul>
+<li><a class="reference internal" href="#ending-execution-with-llvm-shutdown" id="id113">Ending Execution with <code class="docutils literal notranslate"><span class="pre">llvm_shutdown()</span></code></a></li>
+<li><a class="reference internal" href="#lazy-initialization-with-managedstatic" id="id114">Lazy Initialization with <code class="docutils literal notranslate"><span class="pre">ManagedStatic</span></code></a></li>
+<li><a class="reference internal" href="#achieving-isolation-with-llvmcontext" id="id115">Achieving Isolation with <code class="docutils literal notranslate"><span class="pre">LLVMContext</span></code></a></li>
+<li><a class="reference internal" href="#threads-and-the-jit" id="id116">Threads and the JIT</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#advanced-topics" id="id117">Advanced Topics</a><ul>
+<li><a class="reference internal" href="#the-valuesymboltable-class" id="id118">The <code class="docutils literal notranslate"><span class="pre">ValueSymbolTable</span></code> class</a></li>
+<li><a class="reference internal" href="#the-user-and-owned-use-classes-memory-layout" id="id119">The <code class="docutils literal notranslate"><span class="pre">User</span></code> and owned <code class="docutils literal notranslate"><span class="pre">Use</span></code> classesâ memory layout</a><ul>
+<li><a class="reference internal" href="#interaction-and-relationship-between-user-and-use-objects" id="id120">Interaction and relationship between <code class="docutils literal notranslate"><span class="pre">User</span></code> and <code class="docutils literal notranslate"><span class="pre">Use</span></code> objects</a></li>
+<li><a class="reference internal" href="#the-waymarking-algorithm" id="id121">The waymarking algorithm</a></li>
+<li><a class="reference internal" href="#reference-implementation" id="id122">Reference implementation</a></li>
+<li><a class="reference internal" href="#tagging-considerations" id="id123">Tagging considerations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#designing-type-hiercharies-and-polymorphic-interfaces" id="id124">Designing Type Hiercharies and Polymorphic Interfaces</a></li>
+<li><a class="reference internal" href="#abi-breaking-checks" id="id125">ABI Breaking Checks</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-core-llvm-class-hierarchy-reference" id="id126">The Core LLVM Class Hierarchy Reference</a><ul>
+<li><a class="reference internal" href="#the-type-class-and-derived-types" id="id127">The Type class and Derived Types</a><ul>
+<li><a class="reference internal" href="#important-public-methods" id="id128">Important Public Methods</a></li>
+<li><a class="reference internal" href="#important-derived-types" id="id129">Important Derived Types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-module-class" id="id130">The <code class="docutils literal notranslate"><span class="pre">Module</span></code> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-module-class" id="id131">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">Module</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-value-class" id="id132">The <code class="docutils literal notranslate"><span class="pre">Value</span></code> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-value-class" id="id133">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">Value</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-user-class" id="id134">The <code class="docutils literal notranslate"><span class="pre">User</span></code> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-user-class" id="id135">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">User</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-instruction-class" id="id136">The <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> class</a><ul>
+<li><a class="reference internal" href="#important-subclasses-of-the-instruction-class" id="id137">Important Subclasses of the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> class</a></li>
+<li><a class="reference internal" href="#important-public-members-of-the-instruction-class" id="id138">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-constant-class-and-subclasses" id="id139">The <code class="docutils literal notranslate"><span class="pre">Constant</span></code> class and subclasses</a><ul>
+<li><a class="reference internal" href="#important-subclasses-of-constant" id="id140">Important Subclasses of Constant</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-globalvalue-class" id="id141">The <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-globalvalue-class" id="id142">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-function-class" id="id143">The <code class="docutils literal notranslate"><span class="pre">Function</span></code> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-function" id="id144">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">Function</span></code></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-globalvariable-class" id="id145">The <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-globalvariable-class" id="id146">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-basicblock-class" id="id147">The <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> class</a><ul>
+<li><a class="reference internal" href="#important-public-members-of-the-basicblock-class" id="id148">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-argument-class" id="id149">The <code class="docutils literal notranslate"><span class="pre">Argument</span></code> 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="#id8">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 <code class="docutils literal notranslate"><span class="pre">InstVisitor</span></code> (<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="#id9">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="#id10">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"><span class="doc">LLVM Coding Standards</span></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="#id11">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="#id12">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="#id13">The <code class="docutils literal notranslate"><span class="pre">isa<></span></code>, <code class="docutils literal notranslate"><span class="pre">cast<></span></code> and <code class="docutils literal notranslate"><span class="pre">dyn_cast<></span></code> 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++ <code class="docutils literal notranslate"><span class="pre">dynamic_cast<></span></code> operator, but
+they donât have some drawbacks (primarily stemming from the fact that
+<code class="docutils literal notranslate"><span class="pre">dynamic_cast<></span></code> 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 <code class="docutils literal notranslate"><span class="pre">llvm/Support/Casting.h</span></code> (<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><code class="docutils literal notranslate"><span class="pre">isa<></span></code>:</dt>
+<dd>The <code class="docutils literal notranslate"><span class="pre">isa<></span></code> operator works exactly like the Java â<code class="docutils literal notranslate"><span class="pre">instanceof</span></code>â 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><code class="docutils literal notranslate"><span class="pre">cast<></span></code>:</dt>
+<dd><p class="first">The <code class="docutils literal notranslate"><span class="pre">cast<></span></code> 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 <code class="docutils literal notranslate"><span class="pre">isa<></span></code> and <code class="docutils literal notranslate"><span class="pre">cast<></span></code>
+template is:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">isa<></span></code> test followed by a <code class="docutils literal notranslate"><span class="pre">cast<></span></code>,
+for that use the <code class="docutils literal notranslate"><span class="pre">dyn_cast<></span></code> operator.</p>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">dyn_cast<></span></code>:</dt>
+<dd><p class="first">The <code class="docutils literal notranslate"><span class="pre">dyn_cast<></span></code> 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 <code class="docutils literal notranslate"><span class="pre">dynamic_cast<></span></code> operator in C++, and should be used in the same
+circumstances. Typically, the <code class="docutils literal notranslate"><span class="pre">dyn_cast<></span></code> operator is used in an <code class="docutils literal notranslate"><span class="pre">if</span></code>
+statement or some other flow control statement like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="k">auto</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 <code class="docutils literal notranslate"><span class="pre">if</span></code> statement effectively combines together a call to
+<code class="docutils literal notranslate"><span class="pre">isa<></span></code> and a call to <code class="docutils literal notranslate"><span class="pre">cast<></span></code> into one statement, which is very
+convenient.</p>
+<p class="last">Note that the <code class="docutils literal notranslate"><span class="pre">dyn_cast<></span></code> operator, like C++âs <code class="docutils literal notranslate"><span class="pre">dynamic_cast<></span></code> or Javaâs
+<code class="docutils literal notranslate"><span class="pre">instanceof</span></code> operator, can be abused. In particular, you should not use big
+chained <code class="docutils literal notranslate"><span class="pre">if/then/else</span></code> 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 <code class="docutils literal notranslate"><span class="pre">InstVisitor</span></code> class to dispatch over the instruction
+type directly.</p>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">cast_or_null<></span></code>:</dt>
+<dd>The <code class="docutils literal notranslate"><span class="pre">cast_or_null<></span></code> operator works just like the <code class="docutils literal notranslate"><span class="pre">cast<></span></code> 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><code class="docutils literal notranslate"><span class="pre">dyn_cast_or_null<></span></code>:</dt>
+<dd>The <code class="docutils literal notranslate"><span class="pre">dyn_cast_or_null<></span></code> operator works just like the <code class="docutils literal notranslate"><span class="pre">dyn_cast<></span></code>
+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"><span class="doc">How to set up LLVM-style RTTI for your class hierarchy</span></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="#id14">Passing strings (the <code class="docutils literal notranslate"><span class="pre">StringRef</span></code> and <code class="docutils literal notranslate"><span class="pre">Twine</span></code> 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 <code class="docutils literal notranslate"><span class="pre">StringMap</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">const</span>
+<span class="pre">char</span> <span class="pre">*</span></code>, and taking a <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">std::string&</span></code> requires clients to perform a heap
+allocation which is usually unnecessary. Instead, many LLVM APIs use a
+<code class="docutils literal notranslate"><span class="pre">StringRef</span></code> or a <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">Twine&</span></code> for passing strings efficiently.</p>
+<div class="section" id="the-stringref-class">
+<span id="stringref"></span><h4><a class="toc-backref" href="#id15">The <code class="docutils literal notranslate"><span class="pre">StringRef</span></code> class</a><a class="headerlink" href="#the-stringref-class" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">StringRef</span></code> data type represents a reference to a constant string (a
+character array and a length) and supports the common operations available on
+<code class="docutils literal notranslate"><span class="pre">std::string</span></code>, but does not require heap allocation.</p>
+<p>It can be implicitly constructed using a C style null-terminated string, an
+<code class="docutils literal notranslate"><span class="pre">std::string</span></code>, or explicitly with a character pointer and length. For
+example, the <code class="docutils literal notranslate"><span class="pre">StringRef</span></code> find function is declared as:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">StringRef</span></code>
+instance, which can be used directly or converted to an <code class="docutils literal notranslate"><span class="pre">std::string</span></code> using
+the <code class="docutils literal notranslate"><span class="pre">str</span></code> member function. See <code class="docutils literal notranslate"><span class="pre">llvm/ADT/StringRef.h</span></code> (<a class="reference external" href="http://llvm.org/doxygen/StringRef_8h_source.html">doxygen</a>) for more
+information.</p>
+<p>You should rarely use the <code class="docutils literal notranslate"><span class="pre">StringRef</span></code> 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).
+<code class="docutils literal notranslate"><span class="pre">StringRef</span></code> 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="#id16">The <code class="docutils literal notranslate"><span class="pre">Twine</span></code> class</a><a class="headerlink" href="#the-twine-class" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">Twine</span></code> (<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++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">Twine</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">std::string</span></code>, or a <code class="docutils literal notranslate"><span class="pre">StringRef</span></code>). 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 <code class="docutils literal notranslate"><span class="pre">llvm/ADT/Twine.h</span></code> (<a class="reference external" href="http://llvm.org/doxygen/Twine_8h_source.html">doxygen</a>) and <a class="reference internal" href="#dss-twine"><span class="std std-ref">here</span></a>
+for more information.</p>
+<p>As with a <code class="docutils literal notranslate"><span class="pre">StringRef</span></code>, <code class="docutils literal notranslate"><span class="pre">Twine</span></code> 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="formatting-strings-the-formatv-function">
+<span id="formatting-strings"></span><h3><a class="toc-backref" href="#id17">Formatting strings (the <code class="docutils literal notranslate"><span class="pre">formatv</span></code> function)</a><a class="headerlink" href="#formatting-strings-the-formatv-function" title="Permalink to this headline">¶</a></h3>
+<p>While LLVM doesnât necessarily do a lot of string manipulation and parsing, it
+does do a lot of string formatting. From diagnostic messages, to llvm tool
+outputs such as <code class="docutils literal notranslate"><span class="pre">llvm-readobj</span></code> to printing verbose disassembly listings and
+LLDB runtime logging, the need for string formatting is pervasive.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">formatv</span></code> is similar in spirit to <code class="docutils literal notranslate"><span class="pre">printf</span></code>, but uses a different syntax
+which borrows heavily from Python and C#. Unlike <code class="docutils literal notranslate"><span class="pre">printf</span></code> it deduces the type
+to be formatted at compile time, so it does not need a format specifier such as
+<code class="docutils literal notranslate"><span class="pre">%d</span></code>. This reduces the mental overhead of trying to construct portable format
+strings, especially for platform-specific types like <code class="docutils literal notranslate"><span class="pre">size_t</span></code> or pointer types.
+Unlike both <code class="docutils literal notranslate"><span class="pre">printf</span></code> and Python, it additionally fails to compile if LLVM does
+not know how to format the type. These two properties ensure that the function
+is both safer and simpler to use than traditional formatting methods such as
+the <code class="docutils literal notranslate"><span class="pre">printf</span></code> family of functions.</p>
+<div class="section" id="simple-formatting">
+<h4><a class="toc-backref" href="#id18">Simple formatting</a><a class="headerlink" href="#simple-formatting" title="Permalink to this headline">¶</a></h4>
+<p>A call to <code class="docutils literal notranslate"><span class="pre">formatv</span></code> involves a single <strong>format string</strong> consisting of 0 or more
+<strong>replacement sequences</strong>, followed by a variable length list of <strong>replacement values</strong>.
+A replacement sequence is a string of the form <code class="docutils literal notranslate"><span class="pre">{N[[,align]:style]}</span></code>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">N</span></code> refers to the 0-based index of the argument from the list of replacement
+values. Note that this means it is possible to reference the same parameter
+multiple times, possibly with different style and/or alignment options, in any order.</p>
+<p><code class="docutils literal notranslate"><span class="pre">align</span></code> is an optional string specifying the width of the field to format
+the value into, and the alignment of the value within the field. It is specified as
+an optional <strong>alignment style</strong> followed by a positive integral <strong>field width</strong>. The
+alignment style can be one of the characters <code class="docutils literal notranslate"><span class="pre">-</span></code> (left align), <code class="docutils literal notranslate"><span class="pre">=</span></code> (center align),
+or <code class="docutils literal notranslate"><span class="pre">+</span></code> (right align). The default is right aligned.</p>
+<p><code class="docutils literal notranslate"><span class="pre">style</span></code> is an optional string consisting of a type specific that controls the
+formatting of the value. For example, to format a floating point value as a percentage,
+you can use the style option <code class="docutils literal notranslate"><span class="pre">P</span></code>.</p>
+</div>
+<div class="section" id="custom-formatting">
+<h4><a class="toc-backref" href="#id19">Custom formatting</a><a class="headerlink" href="#custom-formatting" title="Permalink to this headline">¶</a></h4>
+<p>There are two ways to customize the formatting behavior for a type.</p>
+<ol class="arabic simple">
+<li>Provide a template specialization of <code class="docutils literal notranslate"><span class="pre">llvm::format_provider<T></span></code> for your
+type <code class="docutils literal notranslate"><span class="pre">T</span></code> with the appropriate static format method.</li>
+</ol>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span> <span class="n">llvm</span> <span class="p">{</span>
+ <span class="k">template</span><span class="o"><></span>
+ <span class="k">struct</span> <span class="n">format_provider</span><span class="o"><</span><span class="n">MyFooBar</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">void</span> <span class="n">format</span><span class="p">(</span><span class="k">const</span> <span class="n">MyFooBar</span> <span class="o">&</span><span class="n">V</span><span class="p">,</span> <span class="n">raw_ostream</span> <span class="o">&</span><span class="n">Stream</span><span class="p">,</span> <span class="n">StringRef</span> <span class="n">Style</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Do whatever is necessary to format `V` into `Stream`</span>
+ <span class="p">}</span>
+ <span class="p">};</span>
+ <span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">MyFooBar</span> <span class="n">X</span><span class="p">;</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0}"</span><span class="p">,</span> <span class="n">X</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This is a useful extensibility mechanism for adding support for formatting your own
+custom types with your own custom Style options. But it does not help when you want
+to extend the mechanism for formatting a type that the library already knows how to
+format. For that, we need something else.</p>
+</div></blockquote>
+<ol class="arabic simple" start="2">
+<li>Provide a <strong>format adapter</strong> inheriting from <code class="docutils literal notranslate"><span class="pre">llvm::FormatAdapter<T></span></code>.</li>
+</ol>
+<blockquote>
+<div><div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">namespace</span> <span class="n">anything</span> <span class="p">{</span>
+ <span class="k">struct</span> <span class="nl">format_int_custom</span> <span class="p">:</span> <span class="k">public</span> <span class="n">llvm</span><span class="o">::</span><span class="n">FormatAdapter</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="p">{</span>
+ <span class="k">explicit</span> <span class="n">format_int_custom</span><span class="p">(</span><span class="kt">int</span> <span class="n">N</span><span class="p">)</span> <span class="o">:</span> <span class="n">llvm</span><span class="o">::</span><span class="n">FormatAdapter</span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="p">(</span><span class="n">N</span><span class="p">)</span> <span class="p">{}</span>
+ <span class="kt">void</span> <span class="n">format</span><span class="p">(</span><span class="n">llvm</span><span class="o">::</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="n">Stream</span><span class="p">,</span> <span class="n">StringRef</span> <span class="n">Style</span><span class="p">)</span> <span class="k">override</span> <span class="p">{</span>
+ <span class="c1">// Do whatever is necessary to format ``this->Item`` into ``Stream``</span>
+ <span class="p">}</span>
+ <span class="p">};</span>
+<span class="p">}</span>
+<span class="k">namespace</span> <span class="n">llvm</span> <span class="p">{</span>
+ <span class="kt">void</span> <span class="n">foo</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">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0}"</span><span class="p">,</span> <span class="n">anything</span><span class="o">::</span><span class="n">format_int_custom</span><span class="p">(</span><span class="mi">42</span><span class="p">));</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If the type is detected to be derived from <code class="docutils literal notranslate"><span class="pre">FormatAdapter<T></span></code>, <code class="docutils literal notranslate"><span class="pre">formatv</span></code>
+will call the
+<code class="docutils literal notranslate"><span class="pre">format</span></code> method on the argument passing in the specified style. This allows
+one to provide custom formatting of any type, including one which already has
+a builtin format provider.</p>
+</div></blockquote>
+</div>
+<div class="section" id="formatv-examples">
+<h4><a class="toc-backref" href="#id20"><code class="docutils literal notranslate"><span class="pre">formatv</span></code> Examples</a><a class="headerlink" href="#formatv-examples" title="Permalink to this headline">¶</a></h4>
+<p>Below is intended to provide an incomplete set of examples demonstrating
+the usage of <code class="docutils literal notranslate"><span class="pre">formatv</span></code>. More information can be found by reading the
+doxygen documentation or by looking at the unit test suite.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">S</span><span class="p">;</span>
+<span class="c1">// Simple formatting of basic types and implicit string conversion.</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0} ({1:P})"</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mf">0.35</span><span class="p">);</span> <span class="c1">// S == "7 (35.00%)"</span>
+
+<span class="c1">// Out-of-order referencing and multi-referencing</span>
+<span class="n">outs</span><span class="p">()</span> <span class="o"><<</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0} {2} {1} {0}"</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="s">"test"</span><span class="p">,</span> <span class="mi">3</span><span class="p">);</span> <span class="c1">// prints "1 3 test 1"</span>
+
+<span class="c1">// Left, right, and center alignment</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0,7}"</span><span class="p">,</span> <span class="sc">'a'</span><span class="p">);</span> <span class="c1">// S == " a";</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0,-7}"</span><span class="p">,</span> <span class="sc">'a'</span><span class="p">);</span> <span class="c1">// S == "a ";</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0,=7}"</span><span class="p">,</span> <span class="sc">'a'</span><span class="p">);</span> <span class="c1">// S == " a ";</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0,+7}"</span><span class="p">,</span> <span class="sc">'a'</span><span class="p">);</span> <span class="c1">// S == " a";</span>
+
+<span class="c1">// Custom styles</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0:N} - {0:x} - {1:E}"</span><span class="p">,</span> <span class="mi">12345</span><span class="p">,</span> <span class="mi">123908342</span><span class="p">);</span> <span class="c1">// S == "12,345 - 0x3039 - 1.24E8"</span>
+
+<span class="c1">// Adapters</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0}"</span><span class="p">,</span> <span class="n">fmt_align</span><span class="p">(</span><span class="mi">42</span><span class="p">,</span> <span class="n">AlignStyle</span><span class="o">::</span><span class="n">Center</span><span class="p">,</span> <span class="mi">7</span><span class="p">));</span> <span class="c1">// S == " 42 "</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0}"</span><span class="p">,</span> <span class="n">fmt_repeat</span><span class="p">(</span><span class="s">"hi"</span><span class="p">,</span> <span class="mi">3</span><span class="p">));</span> <span class="c1">// S == "hihihi"</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0}"</span><span class="p">,</span> <span class="n">fmt_pad</span><span class="p">(</span><span class="s">"hi"</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">6</span><span class="p">));</span> <span class="c1">// S == " hi "</span>
+
+<span class="c1">// Ranges</span>
+<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">V</span> <span class="o">=</span> <span class="p">{</span><span class="mi">8</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">10</span><span class="p">};</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0}"</span><span class="p">,</span> <span class="n">make_range</span><span class="p">(</span><span class="n">V</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">V</span><span class="p">.</span><span class="n">end</span><span class="p">()));</span> <span class="c1">// S == "8, 9, 10"</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0:$[+]}"</span><span class="p">,</span> <span class="n">make_range</span><span class="p">(</span><span class="n">V</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">V</span><span class="p">.</span><span class="n">end</span><span class="p">()));</span> <span class="c1">// S == "8+9+10"</span>
+<span class="n">S</span> <span class="o">=</span> <span class="n">formatv</span><span class="p">(</span><span class="s">"{0:$[ + ]@[x]}"</span><span class="p">,</span> <span class="n">make_range</span><span class="p">(</span><span class="n">V</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span> <span class="n">V</span><span class="p">.</span><span class="n">end</span><span class="p">()));</span> <span class="c1">// S == "0x8 + 0x9 + 0xA"</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="error-handling">
+<span id="error-apis"></span><h3><a class="toc-backref" href="#id21">Error handling</a><a class="headerlink" href="#error-handling" title="Permalink to this headline">¶</a></h3>
+<p>Proper error handling helps us identify bugs in our code, and helps end-users
+understand errors in their tool usage. Errors fall into two broad categories:
+<em>programmatic</em> and <em>recoverable</em>, with different strategies for handling and
+reporting.</p>
+<div class="section" id="programmatic-errors">
+<h4><a class="toc-backref" href="#id22">Programmatic Errors</a><a class="headerlink" href="#programmatic-errors" title="Permalink to this headline">¶</a></h4>
+<p>Programmatic errors are violations of program invariants or API contracts, and
+represent bugs within the program itself. Our aim is to document invariants, and
+to abort quickly at the point of failure (providing some basic diagnostic) when
+invariants are broken at runtime.</p>
+<p>The fundamental tools for handling programmatic errors are assertions and the
+llvm_unreachable function. Assertions are used to express invariant conditions,
+and should include a message describing the invariant:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">assert</span><span class="p">(</span><span class="n">isPhysReg</span><span class="p">(</span><span class="n">R</span><span class="p">)</span> <span class="o">&&</span> <span class="s">"All virt regs should have been allocated already."</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The llvm_unreachable function can be used to document areas of control flow
+that should never be entered if the program invariants hold:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="p">{</span> <span class="n">Foo</span><span class="p">,</span> <span class="n">Bar</span><span class="p">,</span> <span class="n">Baz</span> <span class="p">}</span> <span class="n">X</span> <span class="o">=</span> <span class="n">foo</span><span class="p">();</span>
+
+<span class="k">switch</span> <span class="p">(</span><span class="n">X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="nl">Foo</span><span class="p">:</span> <span class="cm">/* Handle Foo */</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="nl">Bar</span><span class="p">:</span> <span class="cm">/* Handle Bar */</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="k">default</span><span class="o">:</span>
+ <span class="n">llvm_unreachable</span><span class="p">(</span><span class="s">"X should be Foo or Bar here"</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="recoverable-errors">
+<h4><a class="toc-backref" href="#id23">Recoverable Errors</a><a class="headerlink" href="#recoverable-errors" title="Permalink to this headline">¶</a></h4>
+<p>Recoverable errors represent an error in the programâs environment, for example
+a resource failure (a missing file, a dropped network connection, etc.), or
+malformed input. These errors should be detected and communicated to a level of
+the program where they can be handled appropriately. Handling the error may be
+as simple as reporting the issue to the user, or it may involve attempts at
+recovery.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">While it would be ideal to use this error handling scheme throughout
+LLVM, there are places where this hasnât been practical to apply. In
+situations where you absolutely must emit a non-programmatic error and
+the <code class="docutils literal notranslate"><span class="pre">Error</span></code> model isnât workable you can call <code class="docutils literal notranslate"><span class="pre">report_fatal_error</span></code>,
+which will call installed error handlers, print a message, and exit the
+program.</p>
+</div>
+<p>Recoverable errors are modeled using LLVMâs <code class="docutils literal notranslate"><span class="pre">Error</span></code> scheme. This scheme
+represents errors using function return values, similar to classic C integer
+error codes, or C++âs <code class="docutils literal notranslate"><span class="pre">std::error_code</span></code>. However, the <code class="docutils literal notranslate"><span class="pre">Error</span></code> class is
+actually a lightweight wrapper for user-defined error types, allowing arbitrary
+information to be attached to describe the error. This is similar to the way C++
+exceptions allow throwing of user-defined types.</p>
+<p>Success values are created by calling <code class="docutils literal notranslate"><span class="pre">Error::success()</span></code>, E.g.:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Error</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="c1">// Do something.</span>
+ <span class="c1">// Return success.</span>
+ <span class="k">return</span> <span class="n">Error</span><span class="o">::</span><span class="n">success</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Success values are very cheap to construct and return - they have minimal
+impact on program performance.</p>
+<p>Failure values are constructed using <code class="docutils literal notranslate"><span class="pre">make_error<T></span></code>, where <code class="docutils literal notranslate"><span class="pre">T</span></code> is any class
+that inherits from the ErrorInfo utility, E.g.:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">BadFileFormat</span> <span class="o">:</span> <span class="k">public</span> <span class="n">ErrorInfo</span><span class="o"><</span><span class="n">BadFileFormat</span><span class="o">></span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="k">static</span> <span class="kt">char</span> <span class="n">ID</span><span class="p">;</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">Path</span><span class="p">;</span>
+
+ <span class="n">BadFileFormat</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">Path</span><span class="p">)</span> <span class="o">:</span> <span class="n">Path</span><span class="p">(</span><span class="n">Path</span><span class="p">.</span><span class="n">str</span><span class="p">())</span> <span class="p">{}</span>
+
+ <span class="kt">void</span> <span class="n">log</span><span class="p">(</span><span class="n">raw_ostream</span> <span class="o">&</span><span class="n">OS</span><span class="p">)</span> <span class="k">const</span> <span class="k">override</span> <span class="p">{</span>
+ <span class="n">OS</span> <span class="o"><<</span> <span class="n">Path</span> <span class="o"><<</span> <span class="s">" is malformed"</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="n">convertToErrorCode</span><span class="p">()</span> <span class="k">const</span> <span class="k">override</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">make_error_code</span><span class="p">(</span><span class="n">object_error</span><span class="o">::</span><span class="n">parse_failed</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+
+<span class="kt">char</span> <span class="n">BadFileFormat</span><span class="o">::</span><span class="n">ID</span><span class="p">;</span> <span class="c1">// This should be declared in the C++ file.</span>
+
+<span class="n">Error</span> <span class="nf">printFormattedFile</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">Path</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o"><</span><span class="n">check</span> <span class="k">for</span> <span class="n">valid</span> <span class="n">format</span><span class="o">></span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">make_error</span><span class="o"><</span><span class="n">BadFileFormat</span><span class="o">></span><span class="p">(</span><span class="n">Path</span><span class="p">);</span>
+ <span class="c1">// print file contents.</span>
+ <span class="k">return</span> <span class="n">Error</span><span class="o">::</span><span class="n">success</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Error values can be implicitly converted to bool: true for error, false for
+success, enabling the following idiom:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Error</span> <span class="nf">mayFail</span><span class="p">();</span>
+
+<span class="n">Error</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">Err</span> <span class="o">=</span> <span class="n">mayFail</span><span class="p">())</span>
+ <span class="k">return</span> <span class="n">Err</span><span class="p">;</span>
+ <span class="c1">// Success! We can proceed.</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+<p>For functions that can fail but need to return a value the <code class="docutils literal notranslate"><span class="pre">Expected<T></span></code>
+utility can be used. Values of this type can be constructed with either a
+<code class="docutils literal notranslate"><span class="pre">T</span></code>, or an <code class="docutils literal notranslate"><span class="pre">Error</span></code>. Expected<T> values are also implicitly convertible to
+boolean, but with the opposite convention to <code class="docutils literal notranslate"><span class="pre">Error</span></code>: true for success, false
+for error. If success, the <code class="docutils literal notranslate"><span class="pre">T</span></code> value can be accessed via the dereference
+operator. If failure, the <code class="docutils literal notranslate"><span class="pre">Error</span></code> value can be extracted using the
+<code class="docutils literal notranslate"><span class="pre">takeError()</span></code> method. Idiomatic usage looks like:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Expected</span><span class="o"><</span><span class="n">FormattedFile</span><span class="o">></span> <span class="n">openFormattedFile</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">Path</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// If badly formatted, return an error.</span>
+ <span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">Err</span> <span class="o">=</span> <span class="n">checkFormat</span><span class="p">(</span><span class="n">Path</span><span class="p">))</span>
+ <span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">Err</span><span class="p">);</span>
+ <span class="c1">// Otherwise return a FormattedFile instance.</span>
+ <span class="k">return</span> <span class="nf">FormattedFile</span><span class="p">(</span><span class="n">Path</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="n">Error</span> <span class="n">processFormattedFile</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">Path</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Try to open a formatted file</span>
+ <span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">FileOrErr</span> <span class="o">=</span> <span class="n">openFormattedFile</span><span class="p">(</span><span class="n">Path</span><span class="p">))</span> <span class="p">{</span>
+ <span class="c1">// On success, grab a reference to the file and continue.</span>
+ <span class="k">auto</span> <span class="o">&</span><span class="n">File</span> <span class="o">=</span> <span class="o">*</span><span class="n">FileOrErr</span><span class="p">;</span>
+ <span class="p">...</span>
+ <span class="p">}</span> <span class="k">else</span>
+ <span class="c1">// On error, extract the Error value and return it.</span>
+ <span class="k">return</span> <span class="n">FileOrErr</span><span class="p">.</span><span class="n">takeError</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If an <code class="docutils literal notranslate"><span class="pre">Expected<T></span></code> value is in success mode then the <code class="docutils literal notranslate"><span class="pre">takeError()</span></code> method
+will return a success value. Using this fact, the above function can be
+rewritten as:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Error</span> <span class="nf">processFormattedFile</span><span class="p">(</span><span class="n">StringRef</span> <span class="n">Path</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Try to open a formatted file</span>
+ <span class="k">auto</span> <span class="n">FileOrErr</span> <span class="o">=</span> <span class="n">openFormattedFile</span><span class="p">(</span><span class="n">Path</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">Err</span> <span class="o">=</span> <span class="n">FileOrErr</span><span class="p">.</span><span class="n">takeError</span><span class="p">())</span>
+ <span class="c1">// On error, extract the Error value and return it.</span>
+ <span class="k">return</span> <span class="n">Err</span><span class="p">;</span>
+ <span class="c1">// On success, grab a reference to the file and continue.</span>
+ <span class="k">auto</span> <span class="o">&</span><span class="n">File</span> <span class="o">=</span> <span class="o">*</span><span class="n">FileOrErr</span><span class="p">;</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This second form is often more readable for functions that involve multiple
+<code class="docutils literal notranslate"><span class="pre">Expected<T></span></code> values as it limits the indentation required.</p>
+<p>All <code class="docutils literal notranslate"><span class="pre">Error</span></code> instances, whether success or failure, must be either checked or
+moved from (via <code class="docutils literal notranslate"><span class="pre">std::move</span></code> or a return) before they are destructed.
+Accidentally discarding an unchecked error will cause a program abort at the
+point where the unchecked valueâs destructor is run, making it easy to identify
+and fix violations of this rule.</p>
+<p>Success values are considered checked once they have been tested (by invoking
+the boolean conversion operator):</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">Err</span> <span class="o">=</span> <span class="n">mayFail</span><span class="p">(...))</span>
+ <span class="k">return</span> <span class="n">Err</span><span class="p">;</span> <span class="c1">// Failure value - move error to caller.</span>
+
+<span class="c1">// Safe to continue: Err was checked.</span>
+</pre></div>
+</div>
+<p>In contrast, the following code will always cause an abort, even if <code class="docutils literal notranslate"><span class="pre">mayFail</span></code>
+returns a success value:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">mayFail</span><span class="p">();</span>
+<span class="c1">// Program will always abort here, even if mayFail() returns Success, since</span>
+<span class="c1">// the value is not checked.</span>
+</pre></div>
+</div>
+<p>Failure values are considered checked once a handler for the error type has
+been activated:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">handleErrors</span><span class="p">(</span>
+ <span class="n">processFormattedFile</span><span class="p">(...),</span>
+ <span class="p">[](</span><span class="k">const</span> <span class="n">BadFileFormat</span> <span class="o">&</span><span class="n">BFF</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">report</span><span class="p">(</span><span class="s">"Unable to process "</span> <span class="o">+</span> <span class="n">BFF</span><span class="p">.</span><span class="n">Path</span> <span class="o">+</span> <span class="s">": bad format"</span><span class="p">);</span>
+ <span class="p">},</span>
+ <span class="p">[](</span><span class="k">const</span> <span class="n">FileNotFound</span> <span class="o">&</span><span class="n">FNF</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">report</span><span class="p">(</span><span class="s">"File not found "</span> <span class="o">+</span> <span class="n">FNF</span><span class="p">.</span><span class="n">Path</span><span class="p">);</span>
+ <span class="p">});</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> function takes an error as its first argument, followed by
+a variadic list of âhandlersâ, each of which must be a callable type (a
+function, lambda, or class with a call operator) with one argument. The
+<code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> function will visit each handler in the sequence and check its
+argument type against the dynamic type of the error, running the first handler
+that matches. This is the same decision process that is used decide which catch
+clause to run for a C++ exception.</p>
+<p>Since the list of handlers passed to <code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> may not cover every error
+type that can occur, the <code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> function also returns an Error value
+that must be checked or propagated. If the error value that is passed to
+<code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> does not match any of the handlers it will be returned from
+handleErrors. Idiomatic use of <code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> thus looks like:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">Err</span> <span class="o">=</span>
+ <span class="n">handleErrors</span><span class="p">(</span>
+ <span class="n">processFormattedFile</span><span class="p">(...),</span>
+ <span class="p">[](</span><span class="k">const</span> <span class="n">BadFileFormat</span> <span class="o">&</span><span class="n">BFF</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">report</span><span class="p">(</span><span class="s">"Unable to process "</span> <span class="o">+</span> <span class="n">BFF</span><span class="p">.</span><span class="n">Path</span> <span class="o">+</span> <span class="s">": bad format"</span><span class="p">);</span>
+ <span class="p">},</span>
+ <span class="p">[](</span><span class="k">const</span> <span class="n">FileNotFound</span> <span class="o">&</span><span class="n">FNF</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">report</span><span class="p">(</span><span class="s">"File not found "</span> <span class="o">+</span> <span class="n">FNF</span><span class="p">.</span><span class="n">Path</span><span class="p">);</span>
+ <span class="p">}))</span>
+ <span class="k">return</span> <span class="n">Err</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>In cases where you truly know that the handler list is exhaustive the
+<code class="docutils literal notranslate"><span class="pre">handleAllErrors</span></code> function can be used instead. This is identical to
+<code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> except that it will terminate the program if an unhandled
+error is passed in, and can therefore return void. The <code class="docutils literal notranslate"><span class="pre">handleAllErrors</span></code>
+function should generally be avoided: the introduction of a new error type
+elsewhere in the program can easily turn a formerly exhaustive list of errors
+into a non-exhaustive list, risking unexpected program termination. Where
+possible, use handleErrors and propagate unknown errors up the stack instead.</p>
+<p>For tool code, where errors can be handled by printing an error message then
+exiting with an error code, the <a class="reference internal" href="#err-exitonerr"><span class="std std-ref">ExitOnError</span></a> utility
+may be a better choice than handleErrors, as it simplifies control flow when
+calling fallible functions.</p>
+<p>In situations where it is known that a particular call to a fallible function
+will always succeed (for example, a call to a function that can only fail on a
+subset of inputs with an input that is known to be safe) the
+<a class="reference internal" href="#err-cantfail"><span class="std std-ref">cantFail</span></a> functions can be used to remove the error type,
+simplifying control flow.</p>
+<div class="section" id="stringerror">
+<h5><a class="toc-backref" href="#id24">StringError</a><a class="headerlink" href="#stringerror" title="Permalink to this headline">¶</a></h5>
+<p>Many kinds of errors have no recovery strategy, the only action that can be
+taken is to report them to the user so that the user can attempt to fix the
+environment. In this case representing the error as a string makes perfect
+sense. LLVM provides the <code class="docutils literal notranslate"><span class="pre">StringError</span></code> class for this purpose. It takes two
+arguments: A string error message, and an equivalent <code class="docutils literal notranslate"><span class="pre">std::error_code</span></code> for
+interoperability:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">make_error</span><span class="o"><</span><span class="n">StringError</span><span class="o">></span><span class="p">(</span><span class="s">"Bad executable"</span><span class="p">,</span>
+ <span class="n">make_error_code</span><span class="p">(</span><span class="n">errc</span><span class="o">::</span><span class="n">executable_format_error</span><span class="s">"));</span>
+</pre></div>
+</div>
+<p>If youâre certain that the error youâre building will never need to be converted
+to a <code class="docutils literal notranslate"><span class="pre">std::error_code</span></code> you can use the <code class="docutils literal notranslate"><span class="pre">inconvertibleErrorCode()</span></code> function:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">make_error</span><span class="o"><</span><span class="n">StringError</span><span class="o">></span><span class="p">(</span><span class="s">"Bad executable"</span><span class="p">,</span> <span class="n">inconvertibleErrorCode</span><span class="p">());</span>
+</pre></div>
+</div>
+<p>This should be done only after careful consideration. If any attempt is made to
+convert this error to a <code class="docutils literal notranslate"><span class="pre">std::error_code</span></code> it will trigger immediate program
+termination. Unless you are certain that your errors will not need
+interoperability you should look for an existing <code class="docutils literal notranslate"><span class="pre">std::error_code</span></code> that you
+can convert to, and even (as painful as it is) consider introducing a new one as
+a stopgap measure.</p>
+</div>
+<div class="section" id="interoperability-with-std-error-code-and-erroror">
+<h5><a class="toc-backref" href="#id25">Interoperability with std::error_code and ErrorOr</a><a class="headerlink" href="#interoperability-with-std-error-code-and-erroror" title="Permalink to this headline">¶</a></h5>
+<p>Many existing LLVM APIs use <code class="docutils literal notranslate"><span class="pre">std::error_code</span></code> and its partner <code class="docutils literal notranslate"><span class="pre">ErrorOr<T></span></code>
+(which plays the same role as <code class="docutils literal notranslate"><span class="pre">Expected<T></span></code>, but wraps a <code class="docutils literal notranslate"><span class="pre">std::error_code</span></code>
+rather than an <code class="docutils literal notranslate"><span class="pre">Error</span></code>). The infectious nature of error types means that an
+attempt to change one of these functions to return <code class="docutils literal notranslate"><span class="pre">Error</span></code> or <code class="docutils literal notranslate"><span class="pre">Expected<T></span></code>
+instead often results in an avalanche of changes to callers, callers of callers,
+and so on. (The first such attempt, returning an <code class="docutils literal notranslate"><span class="pre">Error</span></code> from
+MachOObjectFileâs constructor, was abandoned after the diff reached 3000 lines,
+impacted half a dozen libraries, and was still growing).</p>
+<p>To solve this problem, the <code class="docutils literal notranslate"><span class="pre">Error</span></code>/<code class="docutils literal notranslate"><span class="pre">std::error_code</span></code> interoperability requirement was
+introduced. Two pairs of functions allow any <code class="docutils literal notranslate"><span class="pre">Error</span></code> value to be converted to a
+<code class="docutils literal notranslate"><span class="pre">std::error_code</span></code>, any <code class="docutils literal notranslate"><span class="pre">Expected<T></span></code> to be converted to an <code class="docutils literal notranslate"><span class="pre">ErrorOr<T></span></code>, and vice
+versa:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="n">errorToErrorCode</span><span class="p">(</span><span class="n">Error</span> <span class="n">Err</span><span class="p">);</span>
+<span class="n">Error</span> <span class="nf">errorCodeToError</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">error_code</span> <span class="n">EC</span><span class="p">);</span>
+
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">ErrorOr</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">expectedToErrorOr</span><span class="p">(</span><span class="n">Expected</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">TOrErr</span><span class="p">);</span>
+<span class="k">template</span> <span class="o"><</span><span class="k">typename</span> <span class="n">T</span><span class="o">></span> <span class="n">Expected</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">errorOrToExpected</span><span class="p">(</span><span class="n">ErrorOr</span><span class="o"><</span><span class="n">T</span><span class="o">></span> <span class="n">TOrEC</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Using these APIs it is easy to make surgical patches that update individual
+functions from <code class="docutils literal notranslate"><span class="pre">std::error_code</span></code> to <code class="docutils literal notranslate"><span class="pre">Error</span></code>, and from <code class="docutils literal notranslate"><span class="pre">ErrorOr<T></span></code> to
+<code class="docutils literal notranslate"><span class="pre">Expected<T></span></code>.</p>
+</div>
+<div class="section" id="returning-errors-from-error-handlers">
+<h5><a class="toc-backref" href="#id26">Returning Errors from error handlers</a><a class="headerlink" href="#returning-errors-from-error-handlers" title="Permalink to this headline">¶</a></h5>
+<p>Error recovery attempts may themselves fail. For that reason, <code class="docutils literal notranslate"><span class="pre">handleErrors</span></code>
+actually recognises three different forms of handler signature:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// Error must be handled, no new errors produced:</span>
+<span class="kt">void</span><span class="p">(</span><span class="n">UserDefinedError</span> <span class="o">&</span><span class="n">E</span><span class="p">);</span>
+
+<span class="c1">// Error must be handled, new errors can be produced:</span>
+<span class="n">Error</span><span class="p">(</span><span class="n">UserDefinedError</span> <span class="o">&</span><span class="n">E</span><span class="p">);</span>
+
+<span class="c1">// Original error can be inspected, then re-wrapped and returned (or a new</span>
+<span class="c1">// error can be produced):</span>
+<span class="n">Error</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">UserDefinedError</span><span class="o">></span> <span class="n">E</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Any error returned from a handler will be returned from the <code class="docutils literal notranslate"><span class="pre">handleErrors</span></code>
+function so that it can be handled itself, or propagated up the stack.</p>
+</div>
+<div class="section" id="using-exitonerror-to-simplify-tool-code">
+<span id="err-exitonerr"></span><h5><a class="toc-backref" href="#id27">Using ExitOnError to simplify tool code</a><a class="headerlink" href="#using-exitonerror-to-simplify-tool-code" title="Permalink to this headline">¶</a></h5>
+<p>Library code should never call <code class="docutils literal notranslate"><span class="pre">exit</span></code> for a recoverable error, however in tool
+code (especially command line tools) this can be a reasonable approach. Calling
+<code class="docutils literal notranslate"><span class="pre">exit</span></code> upon encountering an error dramatically simplifies control flow as the
+error no longer needs to be propagated up the stack. This allows code to be
+written in straight-line style, as long as each fallible call is wrapped in a
+check and call to exit. The <code class="docutils literal notranslate"><span class="pre">ExitOnError</span></code> class supports this pattern by
+providing call operators that inspect <code class="docutils literal notranslate"><span class="pre">Error</span></code> values, stripping the error away
+in the success case and logging to <code class="docutils literal notranslate"><span class="pre">stderr</span></code> then exiting in the failure case.</p>
+<p>To use this class, declare a global <code class="docutils literal notranslate"><span class="pre">ExitOnError</span></code> variable in your program:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">ExitOnError</span> <span class="n">ExitOnErr</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Calls to fallible functions can then be wrapped with a call to <code class="docutils literal notranslate"><span class="pre">ExitOnErr</span></code>,
+turning them into non-failing calls:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Error</span> <span class="nf">mayFail</span><span class="p">();</span>
+<span class="n">Expected</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">mayFail2</span><span class="p">();</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">ExitOnErr</span><span class="p">(</span><span class="n">mayFail</span><span class="p">());</span>
+ <span class="kt">int</span> <span class="n">X</span> <span class="o">=</span> <span class="n">ExitOnErr</span><span class="p">(</span><span class="n">mayFail2</span><span class="p">());</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>On failure, the errorâs log message will be written to <code class="docutils literal notranslate"><span class="pre">stderr</span></code>, optionally
+preceded by a string âbannerâ that can be set by calling the setBanner method. A
+mapping can also be supplied from <code class="docutils literal notranslate"><span class="pre">Error</span></code> values to exit codes using the
+<code class="docutils literal notranslate"><span class="pre">setExitCodeMapper</span></code> method:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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">ExitOnErr</span><span class="p">.</span><span class="n">setBanner</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="n">argv</span><span class="p">[</span><span class="mi">0</span><span class="p">])</span> <span class="o">+</span> <span class="s">" error:"</span><span class="p">);</span>
+ <span class="n">ExitOnErr</span><span class="p">.</span><span class="n">setExitCodeMapper</span><span class="p">(</span>
+ <span class="p">[](</span><span class="k">const</span> <span class="n">Error</span> <span class="o">&</span><span class="n">Err</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Err</span><span class="p">.</span><span class="n">isA</span><span class="o"><</span><span class="n">BadFileFormat</span><span class="o">></span><span class="p">())</span>
+ <span class="k">return</span> <span class="mi">2</span><span class="p">;</span>
+ <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+ <span class="p">});</span>
+</pre></div>
+</div>
+<p>Use <code class="docutils literal notranslate"><span class="pre">ExitOnError</span></code> in your tool code where possible as it can greatly improve
+readability.</p>
+</div>
+<div class="section" id="using-cantfail-to-simplify-safe-callsites">
+<span id="err-cantfail"></span><h5><a class="toc-backref" href="#id28">Using cantFail to simplify safe callsites</a><a class="headerlink" href="#using-cantfail-to-simplify-safe-callsites" title="Permalink to this headline">¶</a></h5>
+<p>Some functions may only fail for a subset of their inputs, so calls using known
+safe inputs can be assumed to succeed.</p>
+<p>The cantFail functions encapsulate this by wrapping an assertion that their
+argument is a success value and, in the case of Expected<T>, unwrapping the
+T value:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Error</span> <span class="nf">onlyFailsForSomeXValues</span><span class="p">(</span><span class="kt">int</span> <span class="n">X</span><span class="p">);</span>
+<span class="n">Expected</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">onlyFailsForSomeXValues2</span><span class="p">(</span><span class="kt">int</span> <span class="n">X</span><span class="p">);</span>
+
+<span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">cantFail</span><span class="p">(</span><span class="n">onlyFailsForSomeXValues</span><span class="p">(</span><span class="n">KnownSafeValue</span><span class="p">));</span>
+ <span class="kt">int</span> <span class="n">Y</span> <span class="o">=</span> <span class="n">cantFail</span><span class="p">(</span><span class="n">onlyFailsForSomeXValues2</span><span class="p">(</span><span class="n">KnownSafeValue</span><span class="p">));</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Like the ExitOnError utility, cantFail simplifies control flow. Their treatment
+of error cases is very different however: Where ExitOnError is guaranteed to
+terminate the program on an error input, cantFile simply asserts that the result
+is success. In debug builds this will result in an assertion failure if an error
+is encountered. In release builds the behavior of cantFail for failure values is
+undefined. As such, care must be taken in the use of cantFail: clients must be
+certain that a cantFail wrapped call really can not fail with the given
+arguments.</p>
+<p>Use of the cantFail functions should be rare in library code, but they are
+likely to be of more use in tool and unit-test code where inputs and/or
+mocked-up classes or functions may be known to be safe.</p>
+</div>
+<div class="section" id="fallible-constructors">
+<h5><a class="toc-backref" href="#id29">Fallible constructors</a><a class="headerlink" href="#fallible-constructors" title="Permalink to this headline">¶</a></h5>
+<p>Some classes require resource acquisition or other complex initialization that
+can fail during construction. Unfortunately constructors canât return errors,
+and having clients test objects after theyâre constructed to ensure that theyâre
+valid is error prone as itâs all too easy to forget the test. To work around
+this, use the named constructor idiom and return an <code class="docutils literal notranslate"><span class="pre">Expected<T></span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">Foo</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+
+ <span class="k">static</span> <span class="n">Expected</span><span class="o"><</span><span class="n">Foo</span><span class="o">></span> <span class="n">Create</span><span class="p">(</span><span class="n">Resource</span> <span class="n">R1</span><span class="p">,</span> <span class="n">Resource</span> <span class="n">R2</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Error</span> <span class="n">Err</span><span class="p">;</span>
+ <span class="n">Foo</span> <span class="nf">F</span><span class="p">(</span><span class="n">R1</span><span class="p">,</span> <span class="n">R2</span><span class="p">,</span> <span class="n">Err</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Err</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">Err</span><span class="p">);</span>
+ <span class="k">return</span> <span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">F</span><span class="p">);</span>
+ <span class="p">}</span>
+
+<span class="k">private</span><span class="o">:</span>
+
+ <span class="n">Foo</span><span class="p">(</span><span class="n">Resource</span> <span class="n">R1</span><span class="p">,</span> <span class="n">Resource</span> <span class="n">R2</span><span class="p">,</span> <span class="n">Error</span> <span class="o">&</span><span class="n">Err</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">ErrorAsOutParameter</span> <span class="n">EAO</span><span class="p">(</span><span class="o">&</span><span class="n">Err</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">Err2</span> <span class="o">=</span> <span class="n">R1</span><span class="p">.</span><span class="n">acquire</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">Err</span> <span class="o">=</span> <span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">Err2</span><span class="p">);</span>
+ <span class="k">return</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="n">Err</span> <span class="o">=</span> <span class="n">R2</span><span class="p">.</span><span class="n">acquire</span><span class="p">();</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Here, the named constructor passes an <code class="docutils literal notranslate"><span class="pre">Error</span></code> by reference into the actual
+constructor, which the constructor can then use to return errors. The
+<code class="docutils literal notranslate"><span class="pre">ErrorAsOutParameter</span></code> utility sets the <code class="docutils literal notranslate"><span class="pre">Error</span></code> valueâs checked flag on entry
+to the constructor so that the error can be assigned to, then resets it on exit
+to force the client (the named constructor) to check the error.</p>
+<p>By using this idiom, clients attempting to construct a Foo receive either a
+well-formed Foo or an Error, never an object in an invalid state.</p>
+</div>
+<div class="section" id="propagating-and-consuming-errors-based-on-types">
+<h5><a class="toc-backref" href="#id30">Propagating and consuming errors based on types</a><a class="headerlink" href="#propagating-and-consuming-errors-based-on-types" title="Permalink to this headline">¶</a></h5>
+<p>In some contexts, certain types of error are known to be benign. For example,
+when walking an archive, some clients may be happy to skip over badly formatted
+object files rather than terminating the walk immediately. Skipping badly
+formatted objects could be achieved using an elaborate handler method, but the
+Error.h header provides two utilities that make this idiom much cleaner: the
+type inspection method, <code class="docutils literal notranslate"><span class="pre">isA</span></code>, and the <code class="docutils literal notranslate"><span class="pre">consumeError</span></code> function:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Error</span> <span class="nf">walkArchive</span><span class="p">(</span><span class="n">Archive</span> <span class="n">A</span><span class="p">)</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="n">A</span><span class="p">.</span><span class="n">numMembers</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">auto</span> <span class="n">ChildOrErr</span> <span class="o">=</span> <span class="n">A</span><span class="p">.</span><span class="n">getMember</span><span class="p">(</span><span class="n">I</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">Err</span> <span class="o">=</span> <span class="n">ChildOrErr</span><span class="p">.</span><span class="n">takeError</span><span class="p">())</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Err</span><span class="p">.</span><span class="n">isA</span><span class="o"><</span><span class="n">BadFileFormat</span><span class="o">></span><span class="p">())</span>
+ <span class="n">consumeError</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">Err</span><span class="p">))</span>
+ <span class="k">else</span>
+ <span class="k">return</span> <span class="n">Err</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">auto</span> <span class="o">&</span><span class="n">Child</span> <span class="o">=</span> <span class="o">*</span><span class="n">ChildOrErr</span><span class="p">;</span>
+ <span class="c1">// Use Child</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="n">Error</span><span class="o">::</span><span class="n">success</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="concatenating-errors-with-joinerrors">
+<h5><a class="toc-backref" href="#id31">Concatenating Errors with joinErrors</a><a class="headerlink" href="#concatenating-errors-with-joinerrors" title="Permalink to this headline">¶</a></h5>
+<p>In the archive walking example above <code class="docutils literal notranslate"><span class="pre">BadFileFormat</span></code> errors are simply
+consumed and ignored. If the client had wanted report these errors after
+completing the walk over the archive they could use the <code class="docutils literal notranslate"><span class="pre">joinErrors</span></code> utility:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Error</span> <span class="nf">walkArchive</span><span class="p">(</span><span class="n">Archive</span> <span class="n">A</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">Error</span> <span class="n">DeferredErrs</span> <span class="o">=</span> <span class="n">Error</span><span class="o">::</span><span class="n">success</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="n">A</span><span class="p">.</span><span class="n">numMembers</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">auto</span> <span class="n">ChildOrErr</span> <span class="o">=</span> <span class="n">A</span><span class="p">.</span><span class="n">getMember</span><span class="p">(</span><span class="n">I</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="k">auto</span> <span class="n">Err</span> <span class="o">=</span> <span class="n">ChildOrErr</span><span class="p">.</span><span class="n">takeError</span><span class="p">())</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">Err</span><span class="p">.</span><span class="n">isA</span><span class="o"><</span><span class="n">BadFileFormat</span><span class="o">></span><span class="p">())</span>
+ <span class="n">DeferredErrs</span> <span class="o">=</span> <span class="n">joinErrors</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">DeferredErrs</span><span class="p">),</span> <span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">Err</span><span class="p">));</span>
+ <span class="k">else</span>
+ <span class="k">return</span> <span class="n">Err</span><span class="p">;</span>
+ <span class="k">auto</span> <span class="o">&</span><span class="n">Child</span> <span class="o">=</span> <span class="o">*</span><span class="n">ChildOrErr</span><span class="p">;</span>
+ <span class="c1">// Use Child</span>
+ <span class="p">...</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="n">DeferredErrs</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">joinErrors</span></code> routine builds a special error type called <code class="docutils literal notranslate"><span class="pre">ErrorList</span></code>,
+which holds a list of user defined errors. The <code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> routine
+recognizes this type and will attempt to handle each of the contained errors in
+order. If all contained errors can be handled, <code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> will return
+<code class="docutils literal notranslate"><span class="pre">Error::success()</span></code>, otherwise <code class="docutils literal notranslate"><span class="pre">handleErrors</span></code> will concatenate the remaining
+errors and return the resulting <code class="docutils literal notranslate"><span class="pre">ErrorList</span></code>.</p>
+</div>
+<div class="section" id="building-fallible-iterators-and-iterator-ranges">
+<h5><a class="toc-backref" href="#id32">Building fallible iterators and iterator ranges</a><a class="headerlink" href="#building-fallible-iterators-and-iterator-ranges" title="Permalink to this headline">¶</a></h5>
+<p>The archive walking examples above retrieve archive members by index, however
+this requires considerable boiler-plate for iteration and error checking. We can
+clean this up by using <code class="docutils literal notranslate"><span class="pre">Error</span></code> with the âfallible iteratorâ pattern. The usual
+C++ iterator patterns do not allow for failure on increment, but we can
+incorporate support for it by having iterators hold an Error reference through
+which they can report failure. In this pattern, if an increment operation fails
+the failure is recorded via the Error reference and the iterator value is set to
+the end of the range in order to terminate the loop. This ensures that the
+dereference operation is safe anywhere that an ordinary iterator dereference
+would be safe (i.e. when the iterator is not equal to end). Where this pattern
+is followed (as in the <code class="docutils literal notranslate"><span class="pre">llvm::object::Archive</span></code> class) the result is much
+cleaner iteration idiom:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Error</span> <span class="n">Err</span><span class="p">;</span>
+<span class="k">for</span> <span class="p">(</span><span class="k">auto</span> <span class="o">&</span><span class="nl">Child</span> <span class="p">:</span> <span class="n">Ar</span><span class="o">-></span><span class="n">children</span><span class="p">(</span><span class="n">Err</span><span class="p">))</span> <span class="p">{</span>
+ <span class="c1">// Use Child - we only enter the loop when it's valid</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+<span class="c1">// Check Err after the loop to ensure it didn't break due to an error.</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">Err</span><span class="p">)</span>
+ <span class="k">return</span> <span class="n">Err</span><span class="p">;</span>
+</pre></div>
+</div>
+<p id="function-apis">More information on Error and its related utilities can be found in the
+Error.h header file.</p>
+</div>
+</div>
+</div>
+<div class="section" id="passing-functions-and-other-callable-objects">
+<h3><a class="toc-backref" href="#id33">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++ notranslate"><div class="highlight"><pre><span></span><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="#id34">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++ notranslate"><div class="highlight"><pre><span></span><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="#id35">The <code class="docutils literal notranslate"><span class="pre">function_ref</span></code> class template</a><a class="headerlink" href="#the-function-ref-class-template" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">function_ref</span></code>
+(<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1function__ref_3_01Ret_07Params_8_8_8_08_4.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, <code class="docutils literal notranslate"><span class="pre">function_ref</span></code> is to <code class="docutils literal notranslate"><span class="pre">std::function</span></code> as <code class="docutils literal notranslate"><span class="pre">StringRef</span></code> is to
+<code class="docutils literal notranslate"><span class="pre">std::string</span></code>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">function_ref<Ret(Param1,</span> <span class="pre">Param2,</span> <span class="pre">...)></span></code> can be implicitly constructed from
+any callable object that can be called with arguments of type <code class="docutils literal notranslate"><span class="pre">Param1</span></code>,
+<code class="docutils literal notranslate"><span class="pre">Param2</span></code>, â¦, and returns a value that can be converted to type <code class="docutils literal notranslate"><span class="pre">Ret</span></code>.
+For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="nl">BB</span> <span class="p">:</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++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">function_ref</span></code> 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 <code class="docutils literal notranslate"><span class="pre">std::function</span></code>. <code class="docutils literal notranslate"><span class="pre">function_ref</span></code> is small enough that it should always
+be passed by value.</p>
+</div>
+</div>
+<div class="section" id="the-llvm-debug-macro-and-debug-option">
+<span id="debug"></span><h3><a class="toc-backref" href="#id36">The <code class="docutils literal notranslate"><span class="pre">LLVM_DEBUG()</span></code> macro and <code class="docutils literal notranslate"><span class="pre">-debug</span></code> option</a><a class="headerlink" href="#the-llvm-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 <code class="docutils literal notranslate"><span class="pre">llvm/Support/Debug.h</span></code> (<a class="reference external" href="http://llvm.org/doxygen/Debug_8h_source.html">doxygen</a>) file provides a macro named
+<code class="docutils literal notranslate"><span class="pre">LLVM_DEBUG()</span></code> that is a much nicer solution to this problem. Basically, you can
+put arbitrary code into the argument of the <code class="docutils literal notranslate"><span class="pre">LLVM_DEBUG</span></code> macro, and it is only
+executed if â<code class="docutils literal notranslate"><span class="pre">opt</span></code>â (or any other tool) is run with the â<code class="docutils literal notranslate"><span class="pre">-debug</span></code>â command
+line argument:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">LLVM_DEBUG</span><span class="p">(</span><span class="n">dbgs</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 notranslate"><div class="highlight"><pre><span></span>$ opt < a.bc > /dev/null -mypass
+<no output>
+$ opt < a.bc > /dev/null -mypass -debug
+I am here!
+</pre></div>
+</div>
+<p>Using the <code class="docutils literal notranslate"><span class="pre">LLVM_DEBUG()</span></code> 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 <code class="docutils literal notranslate"><span class="pre">LLVM_DEBUG()</span></code> macros are disabled for non-asserts 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 <code class="docutils literal notranslate"><span class="pre">LLVM_DEBUG()</span></code> macro is that you can enable or
+disable it directly in gdb. Just use â<code class="docutils literal notranslate"><span class="pre">set</span> <span class="pre">DebugFlag=0</span></code>â or â<code class="docutils literal notranslate"><span class="pre">set</span>
+<span class="pre">DebugFlag=1</span></code>â from the gdb if the program is running. If the program hasnât
+been started yet, you can always just run it with <code class="docutils literal notranslate"><span class="pre">-debug</span></code>.</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="#id37">Fine grained debug info with <code class="docutils literal notranslate"><span class="pre">DEBUG_TYPE</span></code> and the <code class="docutils literal notranslate"><span class="pre">-debug-only</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-debug</span></code> 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
+should define the <code class="docutils literal notranslate"><span class="pre">DEBUG_TYPE</span></code> macro and use the <code class="docutils literal notranslate"><span class="pre">-debug-only</span></code> option as
+follows:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#define DEBUG_TYPE "foo"</span>
+<span class="n">LLVM_DEBUG</span><span class="p">(</span><span class="n">dbgs</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">LLVM_DEBUG</span><span class="p">(</span><span class="n">dbgs</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>
+</pre></div>
+</div>
+<p>Then you can run your pass like this:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ opt < a.bc > /dev/null -mypass
+<no output>
+$ opt < a.bc > /dev/null -mypass -debug
+'foo' debug type
+'bar' debug type
+$ opt < a.bc > /dev/null -mypass -debug-only=foo
+'foo' debug type
+$ opt < a.bc > /dev/null -mypass -debug-only=bar
+'bar' debug type
+$ opt < a.bc > /dev/null -mypass -debug-only=foo,bar
+'foo' debug type
+'bar' debug type
+</pre></div>
+</div>
+<p>Of course, in practice, you should only set <code class="docutils literal notranslate"><span class="pre">DEBUG_TYPE</span></code> at the top of a file,
+to specify the debug type for the entire module. Be careful that you only do
+this after including Debug.h and not around any #include of headers. 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 <code class="docutils literal notranslate"><span class="pre">-debug-only=InstrSched</span></code>, even if the source lives in multiple
+files. The name must not include a comma (,) as that is used to separate the
+arguments of the <code class="docutils literal notranslate"><span class="pre">-debug-only</span></code> option.</p>
+<p>For performance reasons, -debug-only is not available in optimized build
+(<code class="docutils literal notranslate"><span class="pre">--enable-optimized</span></code>) of LLVM.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">DEBUG_WITH_TYPE</span></code> macro is also available for situations where you would
+like to set <code class="docutils literal notranslate"><span class="pre">DEBUG_TYPE</span></code>, but only for one specific <code class="docutils literal notranslate"><span class="pre">DEBUG</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><span class="n">DEBUG_WITH_TYPE</span><span class="p">(</span><span class="s">"foo"</span><span class="p">,</span> <span class="n">dbgs</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">dbgs</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>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="the-statistic-class-stats-option">
+<span id="statistic"></span><h3><a class="toc-backref" href="#id38">The <code class="docutils literal notranslate"><span class="pre">Statistic</span></code> class & <code class="docutils literal notranslate"><span class="pre">-stats</span></code> option</a><a class="headerlink" href="#the-statistic-class-stats-option" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">llvm/ADT/Statistic.h</span></code> (<a class="reference external" href="http://llvm.org/doxygen/Statistic_8h_source.html">doxygen</a>) file provides a class
+named <code class="docutils literal notranslate"><span class="pre">Statistic</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Statistic</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Statistic</span></code> uses, but the basics of using it are as
+follows:</p>
+<p>Define your statistic like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">STATISTIC</span></code> macro defines a static variable, whose name is specified by
+the first argument. The pass name is taken from the <code class="docutils literal notranslate"><span class="pre">DEBUG_TYPE</span></code> macro, and
+the description is taken from the second argument. The variable defined
+(âNumXFormsâ in this case) acts like an unsigned integer.</p>
+<p>Whenever you make a transformation, bump the counter:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="o">++</span><span class="n">NumXForms</span><span class="p">;</span> <span class="c1">// I did stuff!</span>
+</pre></div>
+</div>
+<p>Thatâs all you have to do. To get â<code class="docutils literal notranslate"><span class="pre">opt</span></code>â to print out the statistics
+gathered, use the â<code class="docutils literal notranslate"><span class="pre">-stats</span></code>â option:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ opt -stats -mypassname < program.bc > /dev/null
+... statistics output ...
+</pre></div>
+</div>
+<p>Note that in order to use the â<code class="docutils literal notranslate"><span class="pre">-stats</span></code>â option, LLVM must be
+compiled with assertions enabled.</p>
+<p>When running <code class="docutils literal notranslate"><span class="pre">opt</span></code> on a C file from the SPEC benchmark suite, it gives a
+report that looks like this:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> 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="adding-debug-counters-to-aid-in-debugging-your-code">
+<span id="debugcounters"></span><h3><a class="toc-backref" href="#id39">Adding debug counters to aid in debugging your code</a><a class="headerlink" href="#adding-debug-counters-to-aid-in-debugging-your-code" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes, when writing new passes, or trying to track down bugs, it
+is useful to be able to control whether certain things in your pass
+happen or not. For example, there are times the minimization tooling
+can only easily give you large testcases. You would like to narrow
+your bug down to a specific transformation happening or not happening,
+automatically, using bisection. This is where debug counters help.
+They provide a framework for making parts of your code only execute a
+certain number of times.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">llvm/Support/DebugCounter.h</span></code> (<a class="reference external" href="http://llvm.org/doxygen/DebugCounter_8h_source.html">doxygen</a>) file
+provides a class named <code class="docutils literal notranslate"><span class="pre">DebugCounter</span></code> that can be used to create
+command line counter options that control execution of parts of your code.</p>
+<p>Define your DebugCounter like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">DEBUG_COUNTER</span><span class="p">(</span><span class="n">DeleteAnInstruction</span><span class="p">,</span> <span class="s">"passname-delete-instruction"</span><span class="p">,</span>
+ <span class="s">"Controls which instructions get delete"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">DEBUG_COUNTER</span></code> macro defines a static variable, whose name
+is specified by the first argument. The name of the counter
+(which is used on the command line) is specified by the second
+argument, and the description used in the help is specified by the
+third argument.</p>
+<p>Whatever code you want that control, use <code class="docutils literal notranslate"><span class="pre">DebugCounter::shouldExecute</span></code> to control it.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">DebugCounter</span><span class="o">::</span><span class="n">shouldExecute</span><span class="p">(</span><span class="n">DeleteAnInstruction</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>Thatâs all you have to do. Now, using opt, you can control when this code triggers using
+the â<code class="docutils literal notranslate"><span class="pre">--debug-counter</span></code>â option. There are two counters provided, <code class="docutils literal notranslate"><span class="pre">skip</span></code> and <code class="docutils literal notranslate"><span class="pre">count</span></code>.
+<code class="docutils literal notranslate"><span class="pre">skip</span></code> is the number of times to skip execution of the codepath. <code class="docutils literal notranslate"><span class="pre">count</span></code> is the number
+of times, once we are done skipping, to execute the codepath.</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ opt --debug-counter=passname-delete-instruction-skip=1,passname-delete-instruction-count=2 -passname
+</pre></div>
+</div>
+<p>This will skip the above code the first time we hit it, then execute it twice, then skip the rest of the executions.</p>
+<p>So if executed on the following code:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="nv nv-Anonymous">%1</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="nv nv-Anonymous">%2</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="nv nv-Anonymous">%3</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="nv nv-Anonymous">%4</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>
+</pre></div>
+</div>
+<p>It would delete number <code class="docutils literal notranslate"><span class="pre">%2</span></code> and <code class="docutils literal notranslate"><span class="pre">%3</span></code>.</p>
+<p>A utility is provided in <cite>utils/bisect-skip-count</cite> to binary search
+skip and count arguments. It can be used to automatically minimize the
+skip and count for a debug-counter variable.</p>
+</div>
+<div class="section" id="viewing-graphs-while-debugging-code">
+<span id="viewgraph"></span><h3><a class="toc-backref" href="#id40">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"><span class="std std-ref">BasicBlocks</span></a>, CFGs made out of LLVM
+<a class="reference internal" href="CodeGenerator.html#machinebasicblock"><span class="std std-ref">MachineBasicBlocks</span></a>, and <a class="reference internal" href="CodeGenerator.html#selectiondag"><span class="std std-ref">Instruction Selection
+DAGs</span></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 <code class="docutils literal notranslate"><span class="pre">Function::viewCFG()</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Function::viewCFGOnly()</span></code> (does
+not include the instructions), the <code class="docutils literal notranslate"><span class="pre">MachineFunction::viewCFG()</span></code> and
+<code class="docutils literal notranslate"><span class="pre">MachineFunction::viewCFGOnly()</span></code>, and the <code class="docutils literal notranslate"><span class="pre">SelectionDAG::viewGraph()</span></code>
+methods. Within GDB, for example, you can usually use something like <code class="docutils literal notranslate"><span class="pre">call</span>
+<span class="pre">DAG.viewGraph()</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">/Applications/Graphviz.app/Contents/MacOS/</span></code> (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><code class="docutils literal notranslate"><span class="pre">SelectionDAG</span></code> has been extended to make it easier to locate <em>interesting</em>
+nodes in large complex graphs. From gdb, if you <code class="docutils literal notranslate"><span class="pre">call</span> <span class="pre">DAG.setGraphColor(node,</span>
+<span class="pre">"color")</span></code>, then the next <code class="docutils literal notranslate"><span class="pre">call</span> <span class="pre">DAG.viewGraph()</span></code> 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 <code class="docutils literal notranslate"><span class="pre">call</span> <span class="pre">DAG.setGraphAttrs(node,</span> <span class="pre">"attributes")</span></code> (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
+<code class="docutils literal notranslate"><span class="pre">call</span> <span class="pre">DAG.clearGraphAttrs()</span></code>.</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="#id41">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 <code class="docutils literal notranslate"><span class="pre">llvm/ADT/</span></code> 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"><span class="std std-ref">map-like</span></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"><span class="std std-ref">set-like</span></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"><span class="std std-ref">sequential</span></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"><span class="std std-ref">string</span></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"><span class="std std-ref">bit</span></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"><span class="std std-ref">SmallVector</span></a> than <a class="reference internal" href="#dss-vector"><span class="std std-ref">vector</span></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="#id42">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="#id43">llvm/ADT/ArrayRef.h</a><a class="headerlink" href="#llvm-adt-arrayref-h" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">llvm::ArrayRef</span></code> 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 <code class="docutils literal notranslate"><span class="pre">ArrayRef</span></code>, the API can be passed a fixed size array, an
+<code class="docutils literal notranslate"><span class="pre">std::vector</span></code>, an <code class="docutils literal notranslate"><span class="pre">llvm::SmallVector</span></code> 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="#id44">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="#id45">Heap Allocated Arrays</a><a class="headerlink" href="#heap-allocated-arrays" title="Permalink to this headline">¶</a></h4>
+<p>Heap allocated arrays (<code class="docutils literal notranslate"><span class="pre">new[]</span></code> + <code class="docutils literal notranslate"><span class="pre">delete[]</span></code>) 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"><span class="std std-ref">SmallVector</span></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="#id46">llvm/ADT/TinyPtrVector.h</a><a class="headerlink" href="#llvm-adt-tinyptrvector-h" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">TinyPtrVector<Type></span></code> 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="#id47">llvm/ADT/SmallVector.h</a><a class="headerlink" href="#llvm-adt-smallvector-h" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">SmallVector<Type,</span> <span class="pre">N></span></code> is a simple class that looks and smells just like
+<code class="docutils literal notranslate"><span class="pre">vector<Type></span></code>: 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 main 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
+<code class="docutils literal notranslate"><span class="pre">alloca</span></code>.</p>
+<p>SmallVector has grown a few other minor advantages over std::vector, causing
+<code class="docutils literal notranslate"><span class="pre">SmallVector<Type,</span> <span class="pre">0></span></code> to be preferred over <code class="docutils literal notranslate"><span class="pre">std::vector<Type></span></code>.</p>
+<ol class="arabic simple">
+<li>std::vector is exception-safe, and some implementations have pessimizations
+that copy elements when SmallVector would move them.</li>
+<li>SmallVector understands <code class="docutils literal notranslate"><span class="pre">isPodLike<Type></span></code> and uses realloc aggressively.</li>
+<li>Many LLVM APIs take a SmallVectorImpl as an out parameter (see the note
+below).</li>
+<li>SmallVector with N equal to 0 is smaller than std::vector on 64-bit
+platforms, since it uses <code class="docutils literal notranslate"><span class="pre">unsigned</span></code> (instead of <code class="docutils literal notranslate"><span class="pre">void*</span></code>) for its size
+and capacity.</li>
+</ol>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>Prefer to use <code class="docutils literal notranslate"><span class="pre">SmallVectorImpl<T></span></code> as a parameter type.</p>
+<p>In APIs that donât care about the âsmall sizeâ (most?), prefer to use
+the <code class="docutils literal notranslate"><span class="pre">SmallVectorImpl<T></span></code> class, which is basically just the âvector
+headerâ (and methods) without the elements allocated after it. Note that
+<code class="docutils literal notranslate"><span class="pre">SmallVector<T,</span> <span class="pre">N></span></code> inherits from <code class="docutils literal notranslate"><span class="pre">SmallVectorImpl<T></span></code> so the
+conversion is implicit and costs nothing. E.g.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 â<code class="docutils literal notranslate"><span class="pre">Impl</span></code>â in the name, this is so widely used that
+it really isnât âprivate to the implementationâ anymore. A name like
+<code class="docutils literal notranslate"><span class="pre">SmallVectorHeader</span></code> would be more appropriate.</p>
+</div>
+</div>
+<div class="section" id="vector">
+<span id="dss-vector"></span><h4><a class="toc-backref" href="#id48"><vector></a><a class="headerlink" href="#vector" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">std::vector<T></span></code> is well loved and respected. However, <code class="docutils literal notranslate"><span class="pre">SmallVector<T,</span> <span class="pre">0></span></code>
+is often a better option due to the advantages listed above. std::vector is
+still useful when you need to store more than <code class="docutils literal notranslate"><span class="pre">UINT32_MAX</span></code> elements or when
+interfacing with code that expects vectors :).</p>
+<p>One worthwhile note about std::vector: avoid code like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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++ notranslate"><div class="highlight"><pre><span></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="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="#id49"><deque></a><a class="headerlink" href="#deque" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">std::deque</span></code> is, in some senses, a generalized version of <code class="docutils literal notranslate"><span class="pre">std::vector</span></code>.
+Like <code class="docutils literal notranslate"><span class="pre">std::vector</span></code>, 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, <code class="docutils literal notranslate"><span class="pre">std::deque</span></code> has significantly higher
+constant factor costs than <code class="docutils literal notranslate"><span class="pre">std::vector</span></code>. If possible, use <code class="docutils literal notranslate"><span class="pre">std::vector</span></code> or
+something cheaper.</p>
+</div>
+<div class="section" id="list">
+<span id="dss-list"></span><h4><a class="toc-backref" href="#id50"><list></a><a class="headerlink" href="#list" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">std::list</span></code> 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.
+<code class="docutils literal notranslate"><span class="pre">std::list</span></code> 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 <code class="docutils literal notranslate"><span class="pre">std::deque</span></code>, but unlike <code class="docutils literal notranslate"><span class="pre">std::vector</span></code> or
+<code class="docutils literal notranslate"><span class="pre">SmallVector</span></code>). 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="#id51">llvm/ADT/ilist.h</a><a class="headerlink" href="#llvm-adt-ilist-h" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">ilist<T></span></code> 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><code class="docutils literal notranslate"><span class="pre">ilist</span></code> has the same drawbacks as <code class="docutils literal notranslate"><span class="pre">std::list</span></code>, and additionally requires an
+<code class="docutils literal notranslate"><span class="pre">ilist_traits</span></code> 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 <code class="docutils literal notranslate"><span class="pre">ilist</span></code>s are guaranteed to support a constant-time splice
+operation.</p>
+<p>These properties are exactly what we want for things like <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>s and
+basic blocks, which is why these are implemented with <code class="docutils literal notranslate"><span class="pre">ilist</span></code>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"><span class="std std-ref">ilist_traits</span></a></li>
+<li><a class="reference internal" href="#dss-iplist"><span class="std std-ref">iplist</span></a></li>
+<li><a class="reference internal" href="#dss-ilist-node"><span class="std std-ref">llvm/ADT/ilist_node.h</span></a></li>
+<li><a class="reference internal" href="#dss-ilist-sentinel"><span class="std std-ref">Sentinels</span></a></li>
+</ul>
+</div>
+<div class="section" id="llvm-adt-packedvector-h">
+<span id="dss-packedvector"></span><h4><a class="toc-backref" href="#id52">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++ notranslate"><div class="highlight"><pre><span></span><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="#id53">ilist_traits</a><a class="headerlink" href="#ilist-traits" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">ilist_traits<T></span></code> is <code class="docutils literal notranslate"><span class="pre">ilist<T></span></code>âs customization mechanism. <code class="docutils literal notranslate"><span class="pre">iplist<T></span></code>
+(and consequently <code class="docutils literal notranslate"><span class="pre">ilist<T></span></code>) publicly derive from this traits class.</p>
+</div>
+<div class="section" id="iplist">
+<span id="dss-iplist"></span><h4><a class="toc-backref" href="#id54">iplist</a><a class="headerlink" href="#iplist" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">iplist<T></span></code> is <code class="docutils literal notranslate"><span class="pre">ilist<T></span></code>âs base and as such supports a slightly narrower
+interface. Notably, inserters from <code class="docutils literal notranslate"><span class="pre">T&</span></code> are absent.</p>
+<p><code class="docutils literal notranslate"><span class="pre">ilist_traits<T></span></code> 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="#id55">llvm/ADT/ilist_node.h</a><a class="headerlink" href="#llvm-adt-ilist-node-h" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">ilist_node<T></span></code> implements the forward and backward links that are expected
+by the <code class="docutils literal notranslate"><span class="pre">ilist<T></span></code> (and analogous containers) in the default manner.</p>
+<p><code class="docutils literal notranslate"><span class="pre">ilist_node<T></span></code>s are meant to be embedded in the node type <code class="docutils literal notranslate"><span class="pre">T</span></code>, usually
+<code class="docutils literal notranslate"><span class="pre">T</span></code> publicly derives from <code class="docutils literal notranslate"><span class="pre">ilist_node<T></span></code>.</p>
+</div>
+<div class="section" id="sentinels">
+<span id="dss-ilist-sentinel"></span><h4><a class="toc-backref" href="#id56">Sentinels</a><a class="headerlink" href="#sentinels" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">ilist</span></code>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 <code class="docutils literal notranslate"><span class="pre">begin</span></code> and <code class="docutils literal notranslate"><span class="pre">end</span></code> iterators, etc. Also, the
+<code class="docutils literal notranslate"><span class="pre">operator--</span></code> must work correctly on the <code class="docutils literal notranslate"><span class="pre">end</span></code> iterator in the case of
+non-empty <code class="docutils literal notranslate"><span class="pre">ilist</span></code>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 <code class="docutils literal notranslate"><span class="pre">end</span></code> iterator, providing
+the back-link to the last element. However conforming to the C++ convention it
+is illegal to <code class="docutils literal notranslate"><span class="pre">operator++</span></code> beyond the sentinel and it also must not be
+dereferenced.</p>
+<p>These constraints allow for some implementation freedom to the <code class="docutils literal notranslate"><span class="pre">ilist</span></code> how to
+allocate and store the sentinel. The corresponding policy is dictated by
+<code class="docutils literal notranslate"><span class="pre">ilist_traits<T></span></code>. By default a <code class="docutils literal notranslate"><span class="pre">T</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">T</span></code> does not provide a default constructor. Also, in the case of many
+instances of <code class="docutils literal notranslate"><span class="pre">ilist</span></code>s, the memory overhead of the associated sentinels is
+wasted. To alleviate the situation with numerous and voluminous
+<code class="docutils literal notranslate"><span class="pre">T</span></code>-sentinels, sometimes a trick is employed, leading to <em>ghostly sentinels</em>.</p>
+<p>Ghostly sentinels are obtained by specially-crafted <code class="docutils literal notranslate"><span class="pre">ilist_traits<T></span></code> which
+superpose the sentinel with the <code class="docutils literal notranslate"><span class="pre">ilist</span></code> instance in memory. Pointer
+arithmetic is used to obtain the sentinel, which is relative to the <code class="docutils literal notranslate"><span class="pre">ilist</span></code>âs
+<code class="docutils literal notranslate"><span class="pre">this</span></code> pointer. The <code class="docutils literal notranslate"><span class="pre">ilist</span></code> 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="#id57">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 <code class="docutils literal notranslate"><span class="pre">std::string</span></code>.</p>
+<p>There are also various STL adapter classes such as <code class="docutils literal notranslate"><span class="pre">std::queue</span></code>,
+<code class="docutils literal notranslate"><span class="pre">std::priority_queue</span></code>, <code class="docutils literal notranslate"><span class="pre">std::stack</span></code>, 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="#id58">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 it is generally preferred to <em>not</em> pass strings around as <code class="docutils literal notranslate"><span class="pre">const</span>
+<span class="pre">char*</span></code>â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 â<code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code>â is
+StringRef.</p>
+<p>For more information on choosing string containers for APIs, please see
+<a class="reference internal" href="#string-apis"><span class="std std-ref">Passing Strings</span></a>.</p>
+<div class="section" id="llvm-adt-stringref-h">
+<span id="dss-stringref"></span><h4><a class="toc-backref" href="#id59">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"><span class="std std-ref">ArrayRef</span></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"><span class="std std-ref">Twine</span></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="#id60">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++ notranslate"><div class="highlight"><pre><span></span><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++ notranslate"><div class="highlight"><pre><span></span><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="#id61">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"><span class="std std-ref">SmallVector</span></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="#id62">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="#id63">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="#id64">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 an std::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"><span class="std std-ref">sequential container</span></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.
+<code class="docutils literal notranslate"><span class="pre">std::lower_bound</span></code>; if you want the whole range of elements comparing
+equal, use <code class="docutils literal notranslate"><span class="pre">std::equal_range</span></code>).</p>
+</div>
+<div class="section" id="llvm-adt-smallset-h">
+<span id="dss-smallset"></span><h4><a class="toc-backref" href="#id65">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 <code class="docutils literal notranslate"><span class="pre">SmallSet<Type,</span> <span class="pre">N></span></code> 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 <a class="reference internal" href="#dss-set"><span class="std std-ref">std::set</span></a>, but for pointers it uses something far better,
+<a class="reference internal" href="#dss-smallptrset"><span class="std std-ref">SmallPtrSet</span></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.</p>
+</div>
+<div class="section" id="llvm-adt-smallptrset-h">
+<span id="dss-smallptrset"></span><h4><a class="toc-backref" href="#id66">llvm/ADT/SmallPtrSet.h</a><a class="headerlink" href="#llvm-adt-smallptrset-h" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">SmallPtrSet</span></code> has all the advantages of <code class="docutils literal notranslate"><span class="pre">SmallSet</span></code> (and a <code class="docutils literal notranslate"><span class="pre">SmallSet</span></code> of
+pointers is transparently implemented with a <code class="docutils literal notranslate"><span class="pre">SmallPtrSet</span></code>). 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 <a class="reference internal" href="#dss-set"><span class="std std-ref">std::set</span></a>, the iterators of <code class="docutils literal notranslate"><span class="pre">SmallPtrSet</span></code>
+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-stringset-h">
+<span id="dss-stringset"></span><h4><a class="toc-backref" href="#id67">llvm/ADT/StringSet.h</a><a class="headerlink" href="#llvm-adt-stringset-h" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">StringSet</span></code> is a thin wrapper around <a class="reference internal" href="#dss-stringmap"><span class="std std-ref">StringMap<char></span></a>,
+and it allows efficient storage and retrieval of unique strings.</p>
+<p>Functionally analogous to <code class="docutils literal notranslate"><span class="pre">SmallSet<StringRef></span></code>, <code class="docutils literal notranslate"><span class="pre">StringSet</span></code> also supports
+iteration. (The iterator dereferences to a <code class="docutils literal notranslate"><span class="pre">StringMapEntry<char></span></code>, so you
+need to call <code class="docutils literal notranslate"><span class="pre">i->getKey()</span></code> to access the item of the StringSet.) On the
+other hand, <code class="docutils literal notranslate"><span class="pre">StringSet</span></code> doesnât support range-insertion and
+copy-construction, which <a class="reference internal" href="#dss-smallset"><span class="std std-ref">SmallSet</span></a> and <a class="reference internal" href="#dss-smallptrset"><span class="std std-ref">SmallPtrSet</span></a> do support.</p>
+</div>
+<div class="section" id="llvm-adt-denseset-h">
+<span id="dss-denseset"></span><h4><a class="toc-backref" href="#id68">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"><span class="std std-ref">SmallPtrSet</span></a> for
+pointers). Note that DenseSet has the same requirements for the value type that
+<a class="reference internal" href="#dss-densemap"><span class="std std-ref">DenseMap</span></a> has.</p>
+</div>
+<div class="section" id="llvm-adt-sparseset-h">
+<span id="dss-sparseset"></span><h4><a class="toc-backref" href="#id69">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="#id70">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="#id71">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"><span class="std std-ref">SmallVector</span></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="#id72"><set></a><a class="headerlink" href="#set" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">std::set</span></code> 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="#id73">llvm/ADT/SetVector.h</a><a class="headerlink" href="#llvm-adt-setvector-h" title="Permalink to this headline">¶</a></h4>
+<p>LLVMâs <code class="docutils literal notranslate"><span class="pre">SetVector<Type></span></code> is an adapter class that combines your choice of a
+set-like container along with a <a class="reference internal" href="#ds-sequential"><span class="std std-ref">Sequential Container</span></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><code class="docutils literal notranslate"><span class="pre">SetVector</span></code> is an adapter class that defaults to using <code class="docutils literal notranslate"><span class="pre">std::vector</span></code> and a
+size 16 <code class="docutils literal notranslate"><span class="pre">SmallSet</span></code> for the underlying containers, so it is quite expensive.
+However, <code class="docutils literal notranslate"><span class="pre">"llvm/ADT/SetVector.h"</span></code> also provides a <code class="docutils literal notranslate"><span class="pre">SmallSetVector</span></code> class,
+which defaults to using a <code class="docutils literal notranslate"><span class="pre">SmallVector</span></code> and <code class="docutils literal notranslate"><span class="pre">SmallSet</span></code> of a specified size.
+If you use this, and if your sets are dynamically smaller than <code class="docutils literal notranslate"><span class="pre">N</span></code>, 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="#id74">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"><span class="std std-ref">SetVector</span></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="#id75">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="#id76">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 <a class="reference internal" href="#dss-set"><span class="std std-ref">std::set</span></a>. 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="#id77">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="#id78">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"><span class="std std-ref">sorted vectors for set-like containers</span></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="#id79">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 â<code class="docutils literal notranslate"><span class="pre">(char*)(&Value+1)</span></code>â 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 iteration 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="#id80">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="#id81">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="#id82">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"><span class="std std-ref">DenseMap</span></a> mapping
+<code class="docutils literal notranslate"><span class="pre">Value*</span></code>s (or subclasses) to another type. When a Value is deleted or
+RAUWâed, ValueMap will update itself so the new version of the key is mapped to
+the same value, just as if the key were a WeakVH. You can configure exactly how
+this happens, and what else happens on these two events, by passing a <code class="docutils literal notranslate"><span class="pre">Config</span></code>
+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="#id83">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 the 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="#id84"><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"><span class="std std-ref">std::set</span></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="#id85">llvm/ADT/MapVector.h</a><a class="headerlink" href="#llvm-adt-mapvector-h" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">MapVector<KeyT,ValueT></span></code> 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
+<code class="docutils literal notranslate"><span class="pre">remove_if()</span></code>.</p>
+</div>
+<div class="section" id="llvm-adt-inteqclasses-h">
+<span id="dss-inteqclasses"></span><h4><a class="toc-backref" href="#id86">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="#id87">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="#id88">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="#id89">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 <code class="docutils literal notranslate"><span class="pre">std::vector<bool></span></code>: 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="#id90">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="#id91">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="#id92">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="debugging">
+<span id="id3"></span><h2><a class="toc-backref" href="#id93">Debugging</a><a class="headerlink" href="#debugging" title="Permalink to this headline">¶</a></h2>
+<p>A handful of <a class="reference external" href="https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html">GDB pretty printers</a> are
+provided for some of the core LLVM libraries. To use them, execute the
+following (or add it to your <code class="docutils literal notranslate"><span class="pre">~/.gdbinit</span></code>):</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">source</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">src</span><span class="o">/</span><span class="n">utils</span><span class="o">/</span><span class="n">gdb</span><span class="o">-</span><span class="n">scripts</span><span class="o">/</span><span class="n">prettyprinters</span><span class="o">.</span><span class="n">py</span>
+</pre></div>
+</div>
+<p>It also might be handy to enable the <a class="reference external" href="http://ftp.gnu.org/old-gnu/Manuals/gdb/html_node/gdb_57.html">print pretty</a> option to
+avoid data structures being printed as a big block of text.</p>
+</div>
+<div class="section" id="helpful-hints-for-common-operations">
+<span id="common"></span><h2><a class="toc-backref" href="#id94">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"><span class="std std-ref">Core LLVM Class Hierarchy Reference</span></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="#id95">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 <code class="docutils literal notranslate"><span class="pre">XXXbegin()</span></code> function (or
+method) returns an iterator to the start of the sequence, the <code class="docutils literal notranslate"><span class="pre">XXXend()</span></code>
+function returns an iterator pointing to one past the last valid element of the
+sequence, and there is some <code class="docutils literal notranslate"><span class="pre">XXXiterator</span></code> 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="#id96">Iterating over the <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> in a <code class="docutils literal notranslate"><span class="pre">Function</span></code></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 <code class="docutils literal notranslate"><span class="pre">Function</span></code> instance that youâd like to transform
+in some way; in particular, youâd like to manipulate its <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>s. To
+facilitate this, youâll need to iterate over all of the <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>s that
+constitute the <code class="docutils literal notranslate"><span class="pre">Function</span></code>. The following is an example that prints the name
+of a <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> and the number of <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>s it contains:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">Function</span> <span class="o">&</span><span class="n">Func</span> <span class="o">=</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="nl">BB</span> <span class="p">:</span> <span class="n">Func</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">BB</span><span class="p">.</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">BB</span><span class="p">.</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>
+</div>
+<div class="section" id="iterating-over-the-instruction-in-a-basicblock">
+<span id="iterate-basicblock"></span><h4><a class="toc-backref" href="#id97">Iterating over the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> in a <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code></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 <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>s in <code class="docutils literal notranslate"><span class="pre">Function</span></code>s, itâs easy to
+iterate over the individual instructions that make up <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>s. Hereâs
+a code snippet that prints out each instruction in a <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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">Instruction</span> <span class="o">&</span><span class="nl">I</span> <span class="p">:</span> <span class="n">BB</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="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
+<code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>! 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: <code class="docutils literal notranslate"><span class="pre">errs()</span> <span class="pre"><<</span> <span class="pre">BB</span> <span class="pre"><<</span> <span class="pre">"\n";</span></code>.</p>
+</div>
+<div class="section" id="iterating-over-the-instruction-in-a-function">
+<span id="iterate-insiter"></span><h4><a class="toc-backref" href="#id98">Iterating over the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> in a <code class="docutils literal notranslate"><span class="pre">Function</span></code></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 <code class="docutils literal notranslate"><span class="pre">Function</span></code>âs
+<code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>s and then that <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>âs <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>s,
+<code class="docutils literal notranslate"><span class="pre">InstIterator</span></code> should be used instead. Youâll need to include
+<code class="docutils literal notranslate"><span class="pre">llvm/IR/InstIterator.h</span></code> (<a class="reference external" href="http://llvm.org/doxygen/InstIterator_8h.html">doxygen</a>) and then instantiate
+<code class="docutils literal notranslate"><span class="pre">InstIterator</span></code>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++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"llvm/IR/InstIterator.h"</span><span class="cp"></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 <code class="docutils literal notranslate"><span class="pre">InstIterator</span></code>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 <code class="docutils literal notranslate"><span class="pre">Function</span></code> F, all you would need to do is
+something like:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">worklist</span></code> would now contain all instructions in the <code class="docutils literal notranslate"><span class="pre">Function</span></code>
+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="#id99">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 <code class="docutils literal notranslate"><span class="pre">i</span></code> is a
+<code class="docutils literal notranslate"><span class="pre">BasicBlock::iterator</span></code> and <code class="docutils literal notranslate"><span class="pre">j</span></code> is a <code class="docutils literal notranslate"><span class="pre">BasicBlock::const_iterator</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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">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 dereferencing the iterator and then taking the address of the result,
+you can simply assign the iterator to the proper pointer type and you get the
+dereference and address-of operation as a result of the assignment (behind the
+scenes, this is a result of overloading casting mechanisms). Thus the second
+line of the last example,</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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>
+</pre></div>
+</div>
+<p>is semantically equivalent to</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">B</span></code> is a <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>, from compiling:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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
+<code class="docutils literal notranslate"><span class="pre">operator*</span></code> 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="#id100">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 <code class="docutils literal notranslate"><span class="pre">Function</span></code>) where a certain
+function (i.e., some <code class="docutils literal notranslate"><span class="pre">Function</span> <span class="pre">*</span></code>) is already in scope. As youâll learn
+later, you may want to use an <code class="docutils literal notranslate"><span class="pre">InstVisitor</span></code> 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 <code class="docutils literal notranslate"><span class="pre">InstVisitor</span></code> around. In pseudo-code, this is what we
+want to do:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>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 <code class="docutils literal notranslate"><span class="pre">FunctionPass</span></code>, our
+<code class="docutils literal notranslate"><span class="pre">FunctionPass</span></code>-derived class simply has to override the <code class="docutils literal notranslate"><span class="pre">runOnFunction</span></code>
+method):</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="k">public</span><span class="o">:</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">BasicBlock</span> <span class="o">&</span><span class="nl">B</span> <span class="p">:</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">Instruction</span> <span class="o">&</span><span class="nl">I</span><span class="p">:</span> <span class="n">B</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="k">auto</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="k">private</span><span class="o">:</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="#id101">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 <code class="docutils literal notranslate"><span class="pre">CallInst</span></code>s and
+<code class="docutils literal notranslate"><span class="pre">InvokeInst</span></code>s the same way, even though their most-specific common base
+class is <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>, which includes lots of less closely-related things.
+For these cases, LLVM provides a handy wrapper class called <code class="docutils literal notranslate"><span class="pre">CallSite</span></code>
+(<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1CallSite.html">doxygen</a>) It is
+essentially a wrapper around an <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> pointer, with some methods that
+provide functionality common to <code class="docutils literal notranslate"><span class="pre">CallInst</span></code>s and <code class="docutils literal notranslate"><span class="pre">InvokeInst</span></code>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 <code class="docutils literal notranslate"><span class="pre">operator</span> <span class="pre">new</span></code>
+or <code class="docutils literal notranslate"><span class="pre">operator</span> <span class="pre">delete</span></code>. 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="#id102">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 <code class="docutils literal notranslate"><span class="pre">Value</span></code> class (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Value.html">doxygen</a>) and we want to determine
+which <code class="docutils literal notranslate"><span class="pre">User</span></code> s use the <code class="docutils literal notranslate"><span class="pre">Value</span></code>. The list of all <code class="docutils literal notranslate"><span class="pre">User</span></code>s of a particular
+<code class="docutils literal notranslate"><span class="pre">Value</span></code> is called a <em>def-use</em> chain. For example, letâs say we have a
+<code class="docutils literal notranslate"><span class="pre">Function*</span></code> named <code class="docutils literal notranslate"><span class="pre">F</span></code> to a particular function <code class="docutils literal notranslate"><span class="pre">foo</span></code>. Finding all of the
+instructions that <em>use</em> <code class="docutils literal notranslate"><span class="pre">foo</span></code> is as simple as iterating over the <em>def-use</em>
+chain of <code class="docutils literal notranslate"><span class="pre">F</span></code>:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="nl">U</span> <span class="p">:</span> <span class="n">F</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 <code class="docutils literal notranslate"><span class="pre">User</span></code> Class (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1User.html">doxygen</a>) and need to know what
+<code class="docutils literal notranslate"><span class="pre">Value</span></code>s are used by it. The list of all <code class="docutils literal notranslate"><span class="pre">Value</span></code>s used by a <code class="docutils literal notranslate"><span class="pre">User</span></code> is
+known as a <em>use-def</em> chain. Instances of class <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> are common
+<code class="docutils literal notranslate"><span class="pre">User</span></code> s, so we might want to iterate over all of the values that a particular
+instruction uses (that is, the operands of the particular <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>):</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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="k">for</span> <span class="p">(</span><span class="n">Use</span> <span class="o">&</span><span class="nl">U</span> <span class="p">:</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 <code class="docutils literal notranslate"><span class="pre">const</span></code> is an important tool of enforcing mutation free
+algorithms (such as analyses, etc.). For this purpose above iterators come in
+constant flavors as <code class="docutils literal notranslate"><span class="pre">Value::const_use_iterator</span></code> and
+<code class="docutils literal notranslate"><span class="pre">Value::const_op_iterator</span></code>. They automatically arise when calling
+<code class="docutils literal notranslate"><span class="pre">use/op_begin()</span></code> on <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">Value*</span></code>s or <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">User*</span></code>s respectively.
+Upon dereferencing, they return <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">Use*</span></code>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="#id103">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 <code class="docutils literal notranslate"><span class="pre">"llvm/IR/CFG.h"</span></code>. Just use code like this to
+iterate over all predecessors of BB:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"llvm/IR/CFG.h"</span><span class="cp"></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">BasicBlock</span> <span class="o">*</span><span class="nl">Pred</span> <span class="p">:</span> <span class="n">predecessors</span><span class="p">(</span><span class="n">BB</span><span class="p">))</span> <span class="p">{</span>
+ <span class="c1">// ...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Similarly, to iterate over successors use <code class="docutils literal notranslate"><span class="pre">successors</span></code>.</p>
+</div>
+</div>
+<div class="section" id="making-simple-changes">
+<span id="simplechanges"></span><h3><a class="toc-backref" href="#id104">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="#id105">Creating and inserting new <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>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 <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>s is straight-forward: simply call the constructor
+for the kind of instruction to instantiate and provide the necessary parameters.
+For example, an <code class="docutils literal notranslate"><span class="pre">AllocaInst</span></code> only <em>requires</em> a (const-ptr-to) <code class="docutils literal notranslate"><span class="pre">Type</span></code>. Thus:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">auto</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 <code class="docutils literal notranslate"><span class="pre">AllocaInst</span></code> instance that represents the allocation of one
+integer in the current stack frame, at run time. Each <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">Name</span></code> (default) parameter of the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> 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 <code class="docutils literal notranslate"><span class="pre">AllocaInst</span></code> at
+the first point in the first <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> of some <code class="docutils literal notranslate"><span class="pre">Function</span></code>, and Iâm
+intending to use it within the same <code class="docutils literal notranslate"><span class="pre">Function</span></code>. I might do:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">auto</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 <code class="docutils literal notranslate"><span class="pre">indexLoc</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> into an existing
+sequence of instructions that form a <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>:</p>
+<ul>
+<li><p class="first">Insertion into an explicit instruction list</p>
+<p>Given a <code class="docutils literal notranslate"><span class="pre">BasicBlock*</span> <span class="pre">pb</span></code>, an <code class="docutils literal notranslate"><span class="pre">Instruction*</span> <span class="pre">pi</span></code> within that <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>,
+and a newly-created instruction we wish to insert before <code class="docutils literal notranslate"><span class="pre">*pi</span></code>, we do the
+following:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="k">auto</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 <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> is so common that the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>
+class and <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>-derived classes provide constructors which take a
+pointer to a <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> to be appended to. For example code that looked
+like:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">pb</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="k">auto</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++ notranslate"><div class="highlight"><pre><span></span><span class="n">BasicBlock</span> <span class="o">*</span><span class="n">pb</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="k">auto</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><code class="docutils literal notranslate"><span class="pre">Instruction</span></code> instances that are already in <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>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 <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> by doing:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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="k">auto</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 <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>
+class and <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>-derived classes provide constructors which take (as
+a default parameter) a pointer to an <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> which the newly-created
+<code class="docutils literal notranslate"><span class="pre">Instruction</span></code> should precede. That is, <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> constructors are
+capable of inserting the newly-created instance into the <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> of a
+provided instruction, immediately before that instruction. Using an
+<code class="docutils literal notranslate"><span class="pre">Instruction</span></code> constructor with a <code class="docutils literal notranslate"><span class="pre">insertBefore</span></code> (default) parameter, the
+above code becomes:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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="k">auto</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 <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>s.</p>
+</li>
+<li><p class="first">Insertion using an instance of <code class="docutils literal notranslate"><span class="pre">IRBuilder</span></code></p>
+<p>Inserting several <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>s can be quite laborious using the previous
+methods. The <code class="docutils literal notranslate"><span class="pre">IRBuilder</span></code> is a convenience class that can be used to add
+several instructions to the end of a <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> or before a particular
+<code class="docutils literal notranslate"><span class="pre">Instruction</span></code>. It also supports constant folding and renaming named
+registers (see <code class="docutils literal notranslate"><span class="pre">IRBuilder</span></code>âs template arguments).</p>
+<p>The example below demonstrates a very simple use of the <code class="docutils literal notranslate"><span class="pre">IRBuilder</span></code> where
+three instructions are inserted before the instruction <code class="docutils literal notranslate"><span class="pre">pi</span></code>. The first two
+instructions are Call instructions and third instruction multiplies the return
+value of the two calls.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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">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
+<code class="docutils literal notranslate"><span class="pre">IRBuilder</span></code> inserts instructions at the end of the <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> <code class="docutils literal notranslate"><span class="pre">pb</span></code>.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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/LangImpl03.html"><span class="doc">Kaleidoscope: Code generation to LLVM IR</span></a> for a practical use of the <code class="docutils literal notranslate"><span class="pre">IRBuilder</span></code>.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="deleting-instructions">
+<span id="schanges-deleting"></span><h4><a class="toc-backref" href="#id106">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
+<code class="docutils literal notranslate"><span class="pre">eraseFromParent()</span></code> method. For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">removeFromParent()</span></code> method.</p>
+</div>
+<div class="section" id="replacing-an-instruction-with-another-value">
+<span id="schanges-replacing"></span><h4><a class="toc-backref" href="#id107">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="#id108">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: <code class="docutils literal notranslate"><span class="pre">ReplaceInstWithValue</span></code> and
+<code class="docutils literal notranslate"><span class="pre">ReplaceInstWithInst</span></code>.</p>
+</div>
+<div class="section" id="schanges-deleting-sub">
+<span id="id4"></span><h5><a class="toc-backref" href="#id109">Deleting Instructions</a><a class="headerlink" href="#schanges-deleting-sub" title="Permalink to this headline">¶</a></h5>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">ReplaceInstWithValue</span></code></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 <code class="docutils literal notranslate"><span class="pre">AllocaInst</span></code> that allocates memory
+for a single integer with a null pointer to an integer.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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"><code class="docutils literal notranslate"><span class="pre">ReplaceInstWithInst</span></code></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
+<code class="docutils literal notranslate"><span class="pre">AllocaInst</span></code> with another.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="#id110">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 <code class="docutils literal notranslate"><span class="pre">Value::replaceAllUsesWith</span></code> and <code class="docutils literal notranslate"><span class="pre">User::replaceUsesOfWith</span></code> 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="#id111">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++ notranslate"><div class="highlight"><pre><span></span><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>
+<div class="section" id="threads-and-llvm">
+<span id="threading"></span><h2><a class="toc-backref" href="#id112">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="#id113">Ending Execution with <code class="docutils literal notranslate"><span class="pre">llvm_shutdown()</span></code></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 <code class="docutils literal notranslate"><span class="pre">llvm_shutdown()</span></code> 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="#id114">Lazy Initialization with <code class="docutils literal notranslate"><span class="pre">ManagedStatic</span></code></a><a class="headerlink" href="#lazy-initialization-with-managedstatic" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">ManagedStatic</span></code> 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="#id115">Achieving Isolation with <code class="docutils literal notranslate"><span class="pre">LLVMContext</span></code></a><a class="headerlink" href="#achieving-isolation-with-llvmcontext" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">LLVMContext</span></code> 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, <code class="docutils literal notranslate"><span class="pre">LLVMContext</span></code>
+exists to enable just this kind of scenario!</p>
+<p>Conceptually, <code class="docutils literal notranslate"><span class="pre">LLVMContext</span></code> provides isolation. Every LLVM entity
+(<code class="docutils literal notranslate"><span class="pre">Module</span></code>s, <code class="docutils literal notranslate"><span class="pre">Value</span></code>s, <code class="docutils literal notranslate"><span class="pre">Type</span></code>s, <code class="docutils literal notranslate"><span class="pre">Constant</span></code>s, etc.) in LLVMâs
+in-memory IR belongs to an <code class="docutils literal notranslate"><span class="pre">LLVMContext</span></code>. Entities in different contexts
+<em>cannot</em> interact with each other: <code class="docutils literal notranslate"><span class="pre">Module</span></code>s in different contexts cannot be
+linked together, <code class="docutils literal notranslate"><span class="pre">Function</span></code>s cannot be added to <code class="docutils literal notranslate"><span class="pre">Module</span></code>s in different
+contexts, etc. What this means is that 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
+<code class="docutils literal notranslate"><span class="pre">LLVMContext</span></code>, other than the <code class="docutils literal notranslate"><span class="pre">Type</span></code> creation/lookup APIs. Because every
+<code class="docutils literal notranslate"><span class="pre">Type</span></code> carries a reference to its owning context, most other entities can
+determine what context they belong to by looking at their own <code class="docutils literal notranslate"><span class="pre">Type</span></code>. If you
+are adding new entities to LLVM IR, please try to maintain this interface
+design.</p>
+</div>
+<div class="section" id="threads-and-the-jit">
+<span id="jitthreading"></span><h3><a class="toc-backref" href="#id116">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 <code class="docutils literal notranslate"><span class="pre">ExecutionEngine::getPointerToFunction()</span></code> or
+<code class="docutils literal notranslate"><span class="pre">ExecutionEngine::runFunction()</span></code> 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 <code class="docutils literal notranslate"><span class="pre">LLVMContext</span></code> 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 <code class="docutils literal notranslate"><span class="pre">CallbackVH</span></code>s).
+Another way is to only call <code class="docutils literal notranslate"><span class="pre">getPointerToFunction()</span></code> from the
+<code class="docutils literal notranslate"><span class="pre">LLVMContext</span></code>âs thread.</p>
+<p>When the JIT is configured to compile lazily (using
+<code class="docutils literal notranslate"><span class="pre">ExecutionEngine::DisableLazyCompilation(false)</span></code>), there is currently a <a class="reference external" href="https://bugs.llvm.org/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="#id117">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="#id118">The <code class="docutils literal notranslate"><span class="pre">ValueSymbolTable</span></code> class</a><a class="headerlink" href="#the-valuesymboltable-class" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">ValueSymbolTable</span></code> (<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"><span class="std std-ref">Function</span></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 <code class="docutils literal notranslate"><span class="pre">SymbolTable</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">begin/end/iterator</span></code> and supports querying to see if a specific name is in the
+symbol table (with <code class="docutils literal notranslate"><span class="pre">lookup</span></code>). The <code class="docutils literal notranslate"><span class="pre">ValueSymbolTable</span></code> class exposes no
+public mutator methods, instead, simply call <code class="docutils literal notranslate"><span class="pre">setName</span></code> 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="#id119">The <code class="docutils literal notranslate"><span class="pre">User</span></code> and owned <code class="docutils literal notranslate"><span class="pre">Use</span></code> 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 <code class="docutils literal notranslate"><span class="pre">User</span></code> (<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1User.html">doxygen</a>)
+class provides a basis for expressing the ownership of <code class="docutils literal notranslate"><span class="pre">User</span></code> towards other
+<a class="reference external" href="http://llvm.org/doxygen/classllvm_1_1Value.html">Value instance</a>s. The
+<code class="docutils literal notranslate"><span class="pre">Use</span></code> (<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="#id120">Interaction and relationship between <code class="docutils literal notranslate"><span class="pre">User</span></code> and <code class="docutils literal notranslate"><span class="pre">Use</span></code> 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 <code class="docutils literal notranslate"><span class="pre">User</span></code> can choose between incorporating its <code class="docutils literal notranslate"><span class="pre">Use</span></code> objects or
+refer to them out-of-line by means of a pointer. A mixed variant (some <code class="docutils literal notranslate"><span class="pre">Use</span></code>
+s inline others hung off) is impractical and breaks the invariant that the
+<code class="docutils literal notranslate"><span class="pre">Use</span></code> objects belonging to the same <code class="docutils literal notranslate"><span class="pre">User</span></code> form a contiguous array.</p>
+<p>We have 2 different layouts in the <code class="docutils literal notranslate"><span class="pre">User</span></code> (sub)classes:</p>
+<ul>
+<li><p class="first">Layout a)</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">Use</span></code> object(s) are inside (resp. at fixed offset) of the <code class="docutils literal notranslate"><span class="pre">User</span></code>
+object and there are a fixed number of them.</p>
+</li>
+<li><p class="first">Layout b)</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">Use</span></code> object(s) are referenced by a pointer to an array from the
+<code class="docutils literal notranslate"><span class="pre">User</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Use</span></code>s. Though not mandatory for layout a), we stick to this
+redundancy for the sake of simplicity. The <code class="docutils literal notranslate"><span class="pre">User</span></code> object also stores the
+number of <code class="docutils literal notranslate"><span class="pre">Use</span></code> objects it has. (Theoretically this information can also be
+calculated given the scheme presented below.)</p>
+<p>Special forms of allocation operators (<code class="docutils literal notranslate"><span class="pre">operator</span> <span class="pre">new</span></code>) enforce the following
+memory layouts:</p>
+<ul>
+<li><p class="first">Layout a) is modelled by prepending the <code class="docutils literal notranslate"><span class="pre">User</span></code> object by the <code class="docutils literal notranslate"><span class="pre">Use[]</span></code>
+array.</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>...---.---.---.---.-------...
+ | P | P | P | P | User
+'''---'---'---'---'-------'''
+</pre></div>
+</div>
+</li>
+<li><p class="first">Layout b) is modelled by pointing at the <code class="docutils literal notranslate"><span class="pre">Use[]</span></code> array.</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>.-------...
+| User
+'-------'''
+ |
+ v
+ .---.---.---.---...
+ | P | P | P | P |
+ '---'---'---'---'''
+</pre></div>
+</div>
+</li>
+</ul>
+<p><em>(In the above figures</em> â<code class="docutils literal notranslate"><span class="pre">P</span></code>â <em>stands for the</em> <code class="docutils literal notranslate"><span class="pre">Use**</span></code> <em>that is stored in
+each</em> <code class="docutils literal notranslate"><span class="pre">Use</span></code> <em>object in the member</em> <code class="docutils literal notranslate"><span class="pre">Use::Prev</span></code> <em>)</em></p>
+</div>
+<div class="section" id="the-waymarking-algorithm">
+<span id="waymarking"></span><h4><a class="toc-backref" href="#id121">The waymarking algorithm</a><a class="headerlink" href="#the-waymarking-algorithm" title="Permalink to this headline">¶</a></h4>
+<p>Since the <code class="docutils literal notranslate"><span class="pre">Use</span></code> objects are deprived of the direct (back)pointer to their
+<code class="docutils literal notranslate"><span class="pre">User</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Use::Prev</span></code>
+allows to find the start of the <code class="docutils literal notranslate"><span class="pre">User</span></code> object:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">00</span></code> â binary digit 0</li>
+<li><code class="docutils literal notranslate"><span class="pre">01</span></code> â binary digit 1</li>
+<li><code class="docutils literal notranslate"><span class="pre">10</span></code> â stop and calculate (<code class="docutils literal notranslate"><span class="pre">s</span></code>)</li>
+<li><code class="docutils literal notranslate"><span class="pre">11</span></code> â full stop (<code class="docutils literal notranslate"><span class="pre">S</span></code>)</li>
+</ul>
+<p>Given a <code class="docutils literal notranslate"><span class="pre">Use*</span></code>, all we have to do is to walk till we get a stop and we either
+have a <code class="docutils literal notranslate"><span class="pre">User</span></code> immediately behind or we have to walk to the next stop picking
+up digits and calculating the offset:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.---.----------------
+| 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 <code class="docutils literal notranslate"><span class="pre">Use</span></code> objects
+associated with a <code class="docutils literal notranslate"><span class="pre">User</span></code>.</p>
+</div>
+<div class="section" id="reference-implementation">
+<span id="referenceimpl"></span><h4><a class="toc-backref" href="#id122">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 notranslate"><div class="highlight"><pre><span></span><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="sc">'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: <code class="docutils literal notranslate"><span class="pre">"1s100000s11010s10100s1111s1010s110s11s1S"</span></code></p>
+<p>The reverse algorithm computes the length of the string just by examining a
+certain prefix:</p>
+<div class="highlight-haskell notranslate"><div class="highlight"><pre><span></span><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="sc">'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 <code class="docutils literal notranslate"><span class="pre">40</span></code>.</p>
+<p>We can <em>quickCheck</em> this with following property:</p>
+<div class="highlight-haskell notranslate"><div class="highlight"><pre><span></span><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-default notranslate"><div class="highlight"><pre><span></span><span class="o">*</span><span class="n">Main</span><span class="o">></span> <span class="n">quickCheck</span> <span class="n">identityProp</span>
+<span class="n">OK</span><span class="p">,</span> <span class="n">passed</span> <span class="mi">100</span> <span class="n">tests</span><span class="o">.</span>
+</pre></div>
+</div>
+<p>Letâs be a bit more exhaustive:</p>
+<div class="highlight-haskell notranslate"><div class="highlight"><pre><span></span><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-default notranslate"><div class="highlight"><pre><span></span><span class="o">*</span><span class="n">Main</span><span class="o">></span> <span class="n">deepCheck</span> <span class="n">identityProp</span>
+<span class="n">OK</span><span class="p">,</span> <span class="n">passed</span> <span class="mi">500</span> <span class="n">tests</span><span class="o">.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tagging-considerations">
+<span id="tagging"></span><h4><a class="toc-backref" href="#id123">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 <code class="docutils literal notranslate"><span class="pre">Use**</span></code> in <code class="docutils literal notranslate"><span class="pre">Use</span></code> never
+change after being set up, setters of <code class="docutils literal notranslate"><span class="pre">Use::Prev</span></code> must re-tag the new
+<code class="docutils literal notranslate"><span class="pre">Use**</span></code> on every modification. Accordingly getters must strip the tag bits.</p>
+<p>For layout b) instead of the <code class="docutils literal notranslate"><span class="pre">User</span></code> we find a pointer (<code class="docutils literal notranslate"><span class="pre">User*</span></code> with LSBit
+set). Following this pointer brings us to the <code class="docutils literal notranslate"><span class="pre">User</span></code>. A portable trick
+ensures that the first bytes of <code class="docutils literal notranslate"><span class="pre">User</span></code> (if interpreted as a pointer) never has
+the LSBit set. (Portability is relying on the fact that all known compilers
+place the <code class="docutils literal notranslate"><span class="pre">vptr</span></code> in the first word of the instances.)</p>
+</div>
+</div>
+<div class="section" id="designing-type-hiercharies-and-polymorphic-interfaces">
+<span id="polymorphism"></span><h3><a class="toc-backref" href="#id124">Designing Type Hiercharies and Polymorphic Interfaces</a><a class="headerlink" href="#designing-type-hiercharies-and-polymorphic-interfaces" title="Permalink to this headline">¶</a></h3>
+<p>There are two different design patterns that tend to result in the use of
+virtual dispatch for methods in a type hierarchy in C++ programs. The first is
+a genuine type hierarchy where different types in the hierarchy model
+a specific subset of the functionality and semantics, and these types nest
+strictly within each other. Good examples of this can be seen in the <code class="docutils literal notranslate"><span class="pre">Value</span></code>
+or <code class="docutils literal notranslate"><span class="pre">Type</span></code> type hierarchies.</p>
+<p>A second is the desire to dispatch dynamically across a collection of
+polymorphic interface implementations. This latter use case can be modeled with
+virtual dispatch and inheritance by defining an abstract interface base class
+which all implementations derive from and override. However, this
+implementation strategy forces an <strong>âis-aâ</strong> relationship to exist that is not
+actually meaningful. There is often not some nested hierarchy of useful
+generalizations which code might interact with and move up and down. Instead,
+there is a singular interface which is dispatched across a range of
+implementations.</p>
+<p>The preferred implementation strategy for the second use case is that of
+generic programming (sometimes called âcompile-time duck typingâ or âstatic
+polymorphismâ). For example, a template over some type parameter <code class="docutils literal notranslate"><span class="pre">T</span></code> can be
+instantiated across any particular implementation that conforms to the
+interface or <em>concept</em>. A good example here is the highly generic properties of
+any type which models a node in a directed graph. LLVM models these primarily
+through templates and generic programming. Such templates include the
+<code class="docutils literal notranslate"><span class="pre">LoopInfoBase</span></code> and <code class="docutils literal notranslate"><span class="pre">DominatorTreeBase</span></code>. When this type of polymorphism
+truly needs <strong>dynamic</strong> dispatch you can generalize it using a technique
+called <em>concept-based polymorphism</em>. This pattern emulates the interfaces and
+behaviors of templates using a very limited form of virtual dispatch for type
+erasure inside its implementation. You can find examples of this technique in
+the <code class="docutils literal notranslate"><span class="pre">PassManager.h</span></code> system, and there is a more detailed introduction to it
+by Sean Parent in several of his talks and papers:</p>
+<ol class="arabic simple">
+<li><a class="reference external" href="http://channel9.msdn.com/Events/GoingNative/2013/Inheritance-Is-The-Base-Class-of-Evil">Inheritance Is The Base Class of Evil</a>
+- The GoingNative 2013 talk describing this technique, and probably the best
+place to start.</li>
+<li><a class="reference external" href="http://www.youtube.com/watch?v=_BpMYeUFXv8">Value Semantics and Concepts-based Polymorphism</a> - The C++Now! 2012 talk
+describing this technique in more detail.</li>
+<li><a class="reference external" href="http://github.com/sean-parent/sean-parent.github.com/wiki/Papers-and-Presentations">Sean Parentâs Papers and Presentations</a>
+- A Github project full of links to slides, video, and sometimes code.</li>
+</ol>
+<p>When deciding between creating a type hierarchy (with either tagged or virtual
+dispatch) and using templates or concepts-based polymorphism, consider whether
+there is some refinement of an abstract base class which is a semantically
+meaningful type on an interface boundary. If anything more refined than the
+root abstract interface is meaningless to talk about as a partial extension of
+the semantic model, then your use case likely fits better with polymorphism and
+you should avoid using virtual dispatch. However, there may be some exigent
+circumstances that require one technique or the other to be used.</p>
+<p>If you do need to introduce a type hierarchy, we prefer to use explicitly
+closed type hierarchies with manual tagged dispatch and/or RTTI rather than the
+open inheritance model and virtual dispatch that is more common in C++ code.
+This is because LLVM rarely encourages library consumers to extend its core
+types, and leverages the closed and tag-dispatched nature of its hierarchies to
+generate significantly more efficient code. We have also found that a large
+amount of our usage of type hierarchies fits better with tag-based pattern
+matching rather than dynamic dispatch across a common interface. Within LLVM we
+have built custom helpers to facilitate this design. See this documentâs
+section on <a class="reference internal" href="#isa"><span class="std std-ref">isa and dyn_cast</span></a> and our <a class="reference internal" href="HowToSetUpLLVMStyleRTTI.html"><span class="doc">detailed document</span></a> which describes how you can implement this
+pattern for use with the LLVM helpers.</p>
+</div>
+<div class="section" id="abi-breaking-checks">
+<span id="id5"></span><h3><a class="toc-backref" href="#id125">ABI Breaking Checks</a><a class="headerlink" href="#abi-breaking-checks" title="Permalink to this headline">¶</a></h3>
+<p>Checks and asserts that alter the LLVM C++ ABI are predicated on the
+preprocessor symbol <cite>LLVM_ENABLE_ABI_BREAKING_CHECKS</cite> â LLVM
+libraries built with <cite>LLVM_ENABLE_ABI_BREAKING_CHECKS</cite> are not ABI
+compatible LLVM libraries built without it defined. By default,
+turning on assertions also turns on <cite>LLVM_ENABLE_ABI_BREAKING_CHECKS</cite>
+so a default +Asserts build is not ABI compatible with a
+default -Asserts build. Clients that want ABI compatibility
+between +Asserts and -Asserts builds should use the CMake or autoconf
+build systems to set <cite>LLVM_ENABLE_ABI_BREAKING_CHECKS</cite> independently
+of <cite>LLVM_ENABLE_ASSERTIONS</cite>.</p>
+</div>
+</div>
+<div class="section" id="the-core-llvm-class-hierarchy-reference">
+<span id="coreclasses"></span><h2><a class="toc-backref" href="#id126">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><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/IR/Type.h"</span></code></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 <code class="docutils literal notranslate"><span class="pre">include/llvm/IR</span></code> directory, and implemented in the <code class="docutils literal notranslate"><span class="pre">lib/IR</span></code>
+directory. Itâs worth noting that, for historical reasons, this library is
+called <code class="docutils literal notranslate"><span class="pre">libLLVMCore.so</span></code>, not <code class="docutils literal notranslate"><span class="pre">libLLVMIR.so</span></code> as you might expect.</p>
+<div class="section" id="the-type-class-and-derived-types">
+<span id="type"></span><h3><a class="toc-backref" href="#id127">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><code class="docutils literal notranslate"><span class="pre">Type</span></code> is a superclass of all type classes. Every <code class="docutils literal notranslate"><span class="pre">Value</span></code> has a <code class="docutils literal notranslate"><span class="pre">Type</span></code>.
+<code class="docutils literal notranslate"><span class="pre">Type</span></code> cannot be instantiated directly but only through its subclasses.
+Certain primitive types (<code class="docutils literal notranslate"><span class="pre">VoidType</span></code>, <code class="docutils literal notranslate"><span class="pre">LabelType</span></code>, <code class="docutils literal notranslate"><span class="pre">FloatType</span></code> and
+<code class="docutils literal notranslate"><span class="pre">DoubleType</span></code>) have hidden subclasses. They are hidden because they offer no
+useful functionality beyond what the <code class="docutils literal notranslate"><span class="pre">Type</span></code> class offers except to distinguish
+themselves from other subclasses of <code class="docutils literal notranslate"><span class="pre">Type</span></code>.</p>
+<p>All other types are subclasses of <code class="docutils literal notranslate"><span class="pre">DerivedType</span></code>. 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 <code class="docutils literal notranslate"><span class="pre">Type*</span></code> 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="#id128">Important Public Methods</a><a class="headerlink" href="#important-public-methods" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">isIntegerTy()</span> <span class="pre">const</span></code>: Returns true for any integer type.</li>
+<li><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">isFloatingPointTy()</span></code>: Return true if this is one of the five
+floating point types.</li>
+<li><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">isSized()</span></code>: 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="#id129">Important Derived Types</a><a class="headerlink" href="#important-derived-types" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt><code class="docutils literal notranslate"><span class="pre">IntegerType</span></code></dt>
+<dd><p class="first">Subclass of DerivedType that represents integer types of any bit width. Any
+bit width between <code class="docutils literal notranslate"><span class="pre">IntegerType::MIN_INT_BITS</span></code> (1) and
+<code class="docutils literal notranslate"><span class="pre">IntegerType::MAX_INT_BITS</span></code> (~8 million) can be represented.</p>
+<ul class="last simple">
+<li><code class="docutils literal notranslate"><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></code>: get an integer
+type of a specific bit width.</li>
+<li><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">getBitWidth()</span> <span class="pre">const</span></code>: Get the bit width of an integer type.</li>
+</ul>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">SequentialType</span></code></dt>
+<dd><p class="first">This is subclassed by ArrayType and VectorType.</p>
+<ul class="last simple">
+<li><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">Type</span> <span class="pre">*</span> <span class="pre">getElementType()</span> <span class="pre">const</span></code>: Returns the type of each
+of the elements in the sequential type.</li>
+<li><code class="docutils literal notranslate"><span class="pre">uint64_t</span> <span class="pre">getNumElements()</span> <span class="pre">const</span></code>: Returns the number of elements
+in the sequential type.</li>
+</ul>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">ArrayType</span></code></dt>
+<dd>This is a subclass of SequentialType and defines the interface for array
+types.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">PointerType</span></code></dt>
+<dd>Subclass of Type for pointer types.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">VectorType</span></code></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 an integer or floating point type.</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">StructType</span></code></dt>
+<dd>Subclass of DerivedTypes for struct types.</dd>
+</dl>
+<dl class="docutils" id="functiontype">
+<dt><code class="docutils literal notranslate"><span class="pre">FunctionType</span></code></dt>
+<dd><p class="first">Subclass of DerivedTypes for function types.</p>
+<ul class="last simple">
+<li><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">isVarArg()</span> <span class="pre">const</span></code>: Returns true if itâs a vararg function.</li>
+<li><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">Type</span> <span class="pre">*</span> <span class="pre">getReturnType()</span> <span class="pre">const</span></code>: Returns the return type of the
+function.</li>
+<li><code class="docutils literal notranslate"><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></code>: Returns the type of the ith
+parameter.</li>
+<li><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">unsigned</span> <span class="pre">getNumParams()</span> <span class="pre">const</span></code>: 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="#id130">The <code class="docutils literal notranslate"><span class="pre">Module</span></code> class</a><a class="headerlink" href="#the-module-class" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/IR/Module.h"</span></code></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 <code class="docutils literal notranslate"><span class="pre">Module</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Module</span></code> class keeps track of a list of <a class="reference internal" href="#c-function"><span class="std std-ref">Function</span></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="#id131">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">Module</span></code> 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"><code class="docutils literal notranslate"><span class="pre">Module::Module(std::string</span> <span class="pre">name</span> <span class="pre">=</span> <span class="pre">"")</span></code></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"><code class="docutils literal notranslate"><span class="pre">Module::iterator</span></code> - Typedef for function list iterator</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">Module::const_iterator</span></code> - Typedef for const_iterator.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">begin()</span></code>, <code class="docutils literal notranslate"><span class="pre">end()</span></code>, <code class="docutils literal notranslate"><span class="pre">size()</span></code>, <code class="docutils literal notranslate"><span class="pre">empty()</span></code></div>
+</div>
+<p>These are forwarding methods that make it easy to access the contents of a
+<code class="docutils literal notranslate"><span class="pre">Module</span></code> objectâs <a class="reference internal" href="#c-function"><span class="std std-ref">Function</span></a> list.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Module::FunctionListType</span> <span class="pre">&getFunctionList()</span></code></p>
+<p>Returns the list of <a class="reference internal" href="#c-function"><span class="std std-ref">Function</span></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"><code class="docutils literal notranslate"><span class="pre">Module::global_iterator</span></code> - Typedef for global variable list iterator</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">Module::const_global_iterator</span></code> - Typedef for const_iterator.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">global_begin()</span></code>, <code class="docutils literal notranslate"><span class="pre">global_end()</span></code>, <code class="docutils literal notranslate"><span class="pre">global_size()</span></code>, <code class="docutils literal notranslate"><span class="pre">global_empty()</span></code></div>
+</div>
+<p>These are forwarding methods that make it easy to access the contents of a
+<code class="docutils literal notranslate"><span class="pre">Module</span></code> objectâs <a class="reference internal" href="#globalvariable">GlobalVariable</a> list.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Module::GlobalListType</span> <span class="pre">&getGlobalList()</span></code></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"><code class="docutils literal notranslate"><span class="pre">SymbolTable</span> <span class="pre">*getSymbolTable()</span></code></p>
+<p>Return a reference to the <a class="reference internal" href="#symboltable">SymbolTable</a> for this <code class="docutils literal notranslate"><span class="pre">Module</span></code>.</p>
+</li>
+</ul>
+<hr class="docutils" />
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Function</span> <span class="pre">*getFunction(StringRef</span> <span class="pre">Name)</span> <span class="pre">const</span></code></p>
+<p>Look up the specified function in the <code class="docutils literal notranslate"><span class="pre">Module</span></code> <a class="reference internal" href="#symboltable">SymbolTable</a>. If it does not
+exist, return <code class="docutils literal notranslate"><span class="pre">null</span></code>.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><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></code></p>
+<p>Look up the specified function in the <code class="docutils literal notranslate"><span class="pre">Module</span></code> <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"><code class="docutils literal notranslate"><span class="pre">std::string</span> <span class="pre">getTypeName(const</span> <span class="pre">Type</span> <span class="pre">*Ty)</span></code></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"><code class="docutils literal notranslate"><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></code></p>
+<p>Insert an entry in the <a class="reference internal" href="#symboltable">SymbolTable</a> mapping <code class="docutils literal notranslate"><span class="pre">Name</span></code> to <code class="docutils literal notranslate"><span class="pre">Ty</span></code>. 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="#id132">The <code class="docutils literal notranslate"><span class="pre">Value</span></code> class</a><a class="headerlink" href="#the-value-class" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/IR/Value.h"</span></code></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 <code class="docutils literal notranslate"><span class="pre">Value</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Value</span></code>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"><span class="std std-ref">Function</span></a>s are <code class="docutils literal notranslate"><span class="pre">Value</span></code>s.</p>
+<p>A particular <code class="docutils literal notranslate"><span class="pre">Value</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Value</span></code>
+class keeps a list of all of the <code class="docutils literal notranslate"><span class="pre">User</span></code>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 <code class="docutils literal notranslate"><span class="pre">Value</span></code>s).
+This use list is how LLVM represents def-use information in the program, and is
+accessible through the <code class="docutils literal notranslate"><span class="pre">use_*</span></code> methods, shown below.</p>
+<p>Because LLVM is a typed representation, every LLVM <code class="docutils literal notranslate"><span class="pre">Value</span></code> is typed, and this
+<a class="reference internal" href="#type">Type</a> is available through the <code class="docutils literal notranslate"><span class="pre">getType()</span></code> method. In addition, all LLVM
+values can be named. The ânameâ of the <code class="docutils literal notranslate"><span class="pre">Value</span></code> is a symbolic string printed
+in the LLVM code:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><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
+<code class="docutils literal notranslate"><span class="pre">std::map</span></code> of pointers to the <code class="docutils literal notranslate"><span class="pre">Value</span></code> 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="#id133">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">Value</span></code> 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"><code class="docutils literal notranslate"><span class="pre">Value::use_iterator</span></code> - Typedef for iterator over the use-list</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">Value::const_use_iterator</span></code> - Typedef for const_iterator over the
+use-list</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">use_size()</span></code> - Returns the number of users of the value.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">use_empty()</span></code> - Returns true if there are no users.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">use_iterator</span> <span class="pre">use_begin()</span></code> - Get an iterator to the start of the
+use-list.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">use_iterator</span> <span class="pre">use_end()</span></code> - Get an iterator to the end of the use-list.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">User</span> <span class="pre">*use_back()</span></code> - 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"><code class="docutils literal notranslate"><span class="pre">Type</span> <span class="pre">*getType()</span> <span class="pre">const</span></code>
+This method returns the Type of the Value.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">hasName()</span> <span class="pre">const</span></code></div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">std::string</span> <span class="pre">getName()</span> <span class="pre">const</span></code></div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">setName(const</span> <span class="pre">std::string</span> <span class="pre">&Name)</span></code></div>
+</div>
+<p>This family of methods is used to access and assign a name to a <code class="docutils literal notranslate"><span class="pre">Value</span></code>, be
+aware of the <a class="reference internal" href="#namewarning"><span class="std std-ref">precaution above</span></a>.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">replaceAllUsesWith(Value</span> <span class="pre">*V)</span></code></p>
+<p>This method traverses the use list of a <code class="docutils literal notranslate"><span class="pre">Value</span></code> changing all <a class="reference internal" href="#user">User</a>s of the
+current value to refer to â<code class="docutils literal notranslate"><span class="pre">V</span></code>â 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++ notranslate"><div class="highlight"><pre><span></span><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="#id134">The <code class="docutils literal notranslate"><span class="pre">User</span></code> class</a><a class="headerlink" href="#the-user-class" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/IR/User.h"</span></code></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 <code class="docutils literal notranslate"><span class="pre">User</span></code> class is the common base class of all LLVM nodes that may refer to
+<code class="docutils literal notranslate"><span class="pre">Value</span></code>s. It exposes a list of âOperandsâ that are all of the <code class="docutils literal notranslate"><span class="pre">Value</span></code>s
+that the User is referring to. The <code class="docutils literal notranslate"><span class="pre">User</span></code> class itself is a subclass of
+<code class="docutils literal notranslate"><span class="pre">Value</span></code>.</p>
+<p>The operands of a <code class="docutils literal notranslate"><span class="pre">User</span></code> point directly to the LLVM <code class="docutils literal notranslate"><span class="pre">Value</span></code> 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="#id135">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">User</span></code> class</a><a class="headerlink" href="#important-public-members-of-the-user-class" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">User</span></code> 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"><code class="docutils literal notranslate"><span class="pre">Value</span> <span class="pre">*getOperand(unsigned</span> <span class="pre">i)</span></code></div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">getNumOperands()</span></code></div>
+</div>
+<p>These two methods expose the operands of the <code class="docutils literal notranslate"><span class="pre">User</span></code> in a convenient form for
+direct access.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><code class="docutils literal notranslate"><span class="pre">User::op_iterator</span></code> - Typedef for iterator over the operand list</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">op_iterator</span> <span class="pre">op_begin()</span></code> - Get an iterator to the start of the operand
+list.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">op_iterator</span> <span class="pre">op_end()</span></code> - 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 <code class="docutils literal notranslate"><span class="pre">User</span></code>.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-instruction-class">
+<span id="instruction"></span><h3><a class="toc-backref" href="#id136">The <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> class</a><a class="headerlink" href="#the-instruction-class" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/IR/Instruction.h"</span></code></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 <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> class itself is the opcode (instruction
+type) and the parent <a class="reference internal" href="#basicblock">BasicBlock</a> the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> is embedded into. To
+represent a specific type of instruction, one of many subclasses of
+<code class="docutils literal notranslate"><span class="pre">Instruction</span></code> are used.</p>
+<p>Because the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> class subclasses the <a class="reference internal" href="#user">User</a> class, its operands can
+be accessed in the same way as for other <code class="docutils literal notranslate"><span class="pre">User</span></code>s (with the
+<code class="docutils literal notranslate"><span class="pre">getOperand()</span></code>/<code class="docutils literal notranslate"><span class="pre">getNumOperands()</span></code> and <code class="docutils literal notranslate"><span class="pre">op_begin()</span></code>/<code class="docutils literal notranslate"><span class="pre">op_end()</span></code> methods).
+An important file for the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> class is the <code class="docutils literal notranslate"><span class="pre">llvm/Instruction.def</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">Instruction::Add</span></code> and <code class="docutils literal notranslate"><span class="pre">Instruction::ICmp</span></code>), as well as the
+concrete sub-classes of <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> 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="#id137">Important Subclasses of the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> 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"><code class="docutils literal notranslate"><span class="pre">BinaryOperator</span></code></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><code class="docutils literal notranslate"><span class="pre">CastInst</span></code>
+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"><code class="docutils literal notranslate"><span class="pre">CmpInst</span></code></p>
+<p>This subclass represents 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>
+</div>
+<div class="section" id="important-public-members-of-the-instruction-class">
+<span id="m-instruction"></span><h4><a class="toc-backref" href="#id138">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> 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"><code class="docutils literal notranslate"><span class="pre">BasicBlock</span> <span class="pre">*getParent()</span></code></p>
+<p>Returns the <a class="reference internal" href="#basicblock">BasicBlock</a> that this
+<code class="docutils literal notranslate"><span class="pre">Instruction</span></code> is embedded into.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">mayWriteToMemory()</span></code></p>
+<p>Returns true if the instruction writes to memory, i.e. it is a <code class="docutils literal notranslate"><span class="pre">call</span></code>,
+<code class="docutils literal notranslate"><span class="pre">free</span></code>, <code class="docutils literal notranslate"><span class="pre">invoke</span></code>, or <code class="docutils literal notranslate"><span class="pre">store</span></code>.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">getOpcode()</span></code></p>
+<p>Returns the opcode for the <code class="docutils literal notranslate"><span class="pre">Instruction</span></code>.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Instruction</span> <span class="pre">*clone()</span> <span class="pre">const</span></code></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="#id139">The <code class="docutils literal notranslate"><span class="pre">Constant</span></code> 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="#id140">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><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">APInt&</span> <span class="pre">getValue()</span> <span class="pre">const</span></code>: Returns the underlying
+value of this constant, an APInt value.</li>
+<li><code class="docutils literal notranslate"><span class="pre">int64_t</span> <span class="pre">getSExtValue()</span> <span class="pre">const</span></code>: 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><code class="docutils literal notranslate"><span class="pre">uint64_t</span> <span class="pre">getZExtValue()</span> <span class="pre">const</span></code>: 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><code class="docutils literal notranslate"><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></code>: Returns the ConstantInt
+object that represents the value provided by <code class="docutils literal notranslate"><span class="pre">Val</span></code>. The type is implied
+as the IntegerType that corresponds to the bit width of <code class="docutils literal notranslate"><span class="pre">Val</span></code>.</li>
+<li><code class="docutils literal notranslate"><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></code>: Returns the
+ConstantInt object that represents the value provided by <code class="docutils literal notranslate"><span class="pre">Val</span></code> for integer
+type <code class="docutils literal notranslate"><span class="pre">Ty</span></code>.</li>
+</ul>
+</li>
+<li>ConstantFP : This class represents a floating point constant.<ul>
+<li><code class="docutils literal notranslate"><span class="pre">double</span> <span class="pre">getValue()</span> <span class="pre">const</span></code>: Returns the underlying value of this constant.</li>
+</ul>
+</li>
+<li>ConstantArray : This represents a constant array.<ul>
+<li><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">std::vector<Use></span> <span class="pre">&getValues()</span> <span class="pre">const</span></code>: Returns a vector of
+component constants that makeup this array.</li>
+</ul>
+</li>
+<li>ConstantStruct : This represents a constant struct.<ul>
+<li><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">std::vector<Use></span> <span class="pre">&getValues()</span> <span class="pre">const</span></code>: 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="#id141">The <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code> class</a><a class="headerlink" href="#the-globalvalue-class" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/IR/GlobalValue.h"</span></code></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"><span class="std std-ref">Function</span></a>s) are the
+only LLVM values that are visible in the bodies of all <a class="reference internal" href="#c-function"><span class="std std-ref">Function</span></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, <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code>s know their linkage rules.
+Specifically, <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code>s know whether they have internal or external
+linkage, as defined by the <code class="docutils literal notranslate"><span class="pre">LinkageTypes</span></code> enumeration.</p>
+<p>If a <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code> has internal linkage (equivalent to being <code class="docutils literal notranslate"><span class="pre">static</span></code> 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,
+<code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code>s keep track of which <a class="reference internal" href="#module">Module</a> they are currently part of.</p>
+<p>Because <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code>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 <code class="docutils literal notranslate"><span class="pre">GetElementPtrInst</span></code>
+instruction because this pointer must be dereferenced first. For example, if
+you have a <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code> (a subclass of <code class="docutils literal notranslate"><span class="pre">GlobalValue)</span></code> that is an array
+of 24 ints, type <code class="docutils literal notranslate"><span class="pre">[24</span> <span class="pre">x</span> <span class="pre">i32]</span></code>, then the <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code> is a pointer to
+that array. Although the address of the first element of this array and the
+value of the <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code> are the same, they have different types. The
+<code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code>âs type is <code class="docutils literal notranslate"><span class="pre">[24</span> <span class="pre">x</span> <span class="pre">i32]</span></code>. The first elementâs type is
+<code class="docutils literal notranslate"><span class="pre">i32.</span></code> Because of this, accessing a global value requires you to dereference
+the pointer with <code class="docutils literal notranslate"><span class="pre">GetElementPtrInst</span></code> 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="#id142">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code> 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"><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">hasInternalLinkage()</span> <span class="pre">const</span></code></div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">hasExternalLinkage()</span> <span class="pre">const</span></code></div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">setInternalLinkage(bool</span> <span class="pre">HasInternalLinkage)</span></code></div>
+</div>
+<p>These methods manipulate the linkage characteristics of the <code class="docutils literal notranslate"><span class="pre">GlobalValue</span></code>.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Module</span> <span class="pre">*getParent()</span></code></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="#id143">The <code class="docutils literal notranslate"><span class="pre">Function</span></code> class</a><a class="headerlink" href="#the-function-class" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/IR/Function.h"</span></code></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 <code class="docutils literal notranslate"><span class="pre">Function</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Function</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Function</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">Function</span></code>. 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
+<code class="docutils literal notranslate"><span class="pre">Function</span></code>. If the <a class="reference internal" href="#basicblock">BasicBlock</a> list is empty, this indicates that the
+<code class="docutils literal notranslate"><span class="pre">Function</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Function</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Function</span></code> 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="#id144">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">Function</span></code></a><a class="headerlink" href="#important-public-members-of-the-function" title="Permalink to this headline">¶</a></h4>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><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></code></p>
+<p>Constructor used when you need to create new <code class="docutils literal notranslate"><span class="pre">Function</span></code>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 <code class="docutils literal notranslate"><span class="pre">Parent</span></code>
+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"><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">isDeclaration()</span></code></p>
+<p>Return whether or not the <code class="docutils literal notranslate"><span class="pre">Function</span></code> 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"><code class="docutils literal notranslate"><span class="pre">Function::iterator</span></code> - Typedef for basic block list iterator</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">Function::const_iterator</span></code> - Typedef for const_iterator.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">begin()</span></code>, <code class="docutils literal notranslate"><span class="pre">end()</span></code>, <code class="docutils literal notranslate"><span class="pre">size()</span></code>, <code class="docutils literal notranslate"><span class="pre">empty()</span></code></div>
+</div>
+<p>These are forwarding methods that make it easy to access the contents of a
+<code class="docutils literal notranslate"><span class="pre">Function</span></code> objectâs <a class="reference internal" href="#basicblock">BasicBlock</a> list.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Function::BasicBlockListType</span> <span class="pre">&getBasicBlockList()</span></code></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"><code class="docutils literal notranslate"><span class="pre">Function::arg_iterator</span></code> - Typedef for the argument list iterator</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">Function::const_arg_iterator</span></code> - Typedef for const_iterator.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">arg_begin()</span></code>, <code class="docutils literal notranslate"><span class="pre">arg_end()</span></code>, <code class="docutils literal notranslate"><span class="pre">arg_size()</span></code>, <code class="docutils literal notranslate"><span class="pre">arg_empty()</span></code></div>
+</div>
+<p>These are forwarding methods that make it easy to access the contents of a
+<code class="docutils literal notranslate"><span class="pre">Function</span></code> objectâs <a class="reference internal" href="#argument">Argument</a> list.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Function::ArgumentListType</span> <span class="pre">&getArgumentList()</span></code></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"><code class="docutils literal notranslate"><span class="pre">BasicBlock</span> <span class="pre">&getEntryBlock()</span></code></p>
+<p>Returns the entry <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> for the function. Because the entry block
+for the function is always the first block, this returns the first block of
+the <code class="docutils literal notranslate"><span class="pre">Function</span></code>.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><code class="docutils literal notranslate"><span class="pre">Type</span> <span class="pre">*getReturnType()</span></code></div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">FunctionType</span> <span class="pre">*getFunctionType()</span></code></div>
+</div>
+<p>This traverses the <a class="reference internal" href="#type">Type</a> of the <code class="docutils literal notranslate"><span class="pre">Function</span></code> 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"><code class="docutils literal notranslate"><span class="pre">SymbolTable</span> <span class="pre">*getSymbolTable()</span></code></p>
+<p>Return a pointer to the <a class="reference internal" href="#symboltable">SymbolTable</a> for this <code class="docutils literal notranslate"><span class="pre">Function</span></code>.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-globalvariable-class">
+<span id="globalvariable"></span><h3><a class="toc-backref" href="#id145">The <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code> class</a><a class="headerlink" href="#the-globalvariable-class" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/IR/GlobalVariable.h"</span></code></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) <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code>
+class. Like functions, <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code>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="#id146">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code> 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"><code class="docutils literal notranslate"><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></code></p>
+<p>Create a new global variable of the specified type. If <code class="docutils literal notranslate"><span class="pre">isConstant</span></code> 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"><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">isConstant()</span> <span class="pre">const</span></code></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"><code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">hasInitializer()</span></code></p>
+<p>Returns true if this <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code> has an intializer.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Constant</span> <span class="pre">*getInitializer()</span></code></p>
+<p>Returns the initial value for a <code class="docutils literal notranslate"><span class="pre">GlobalVariable</span></code>. 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="#id147">The <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> class</a><a class="headerlink" href="#the-basicblock-class" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">"llvm/IR/BasicBlock.h"</span></code></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 <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> 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.</p>
+<p>In addition to tracking the list of instructions that make up the block, the
+<code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> class also keeps track of the <a class="reference internal" href="#c-function"><span class="std std-ref">Function</span></a> that
+it is embedded into.</p>
+<p>Note that <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>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.
+<code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>s have type <code class="docutils literal notranslate"><span class="pre">label</span></code>.</p>
+<div class="section" id="important-public-members-of-the-basicblock-class">
+<span id="m-basicblock"></span><h4><a class="toc-backref" href="#id148">Important Public Members of the <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> 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"><code class="docutils literal notranslate"><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></code></p>
+<p>The <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> 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"><span class="std std-ref">Function</span></a> to insert it into. If the
+<code class="docutils literal notranslate"><span class="pre">Parent</span></code> parameter is specified, the new <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> is automatically
+inserted at the end of the specified <a class="reference internal" href="#c-function"><span class="std std-ref">Function</span></a>, if not
+specified, the BasicBlock must be manually inserted into the <a class="reference internal" href="#c-function"><span class="std std-ref">Function</span></a>.</p>
+</li>
+<li><div class="first line-block">
+<div class="line"><code class="docutils literal notranslate"><span class="pre">BasicBlock::iterator</span></code> - Typedef for instruction list iterator</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">BasicBlock::const_iterator</span></code> - Typedef for const_iterator.</div>
+<div class="line"><code class="docutils literal notranslate"><span class="pre">begin()</span></code>, <code class="docutils literal notranslate"><span class="pre">end()</span></code>, <code class="docutils literal notranslate"><span class="pre">front()</span></code>, <code class="docutils literal notranslate"><span class="pre">back()</span></code>,
+<code class="docutils literal notranslate"><span class="pre">size()</span></code>, <code class="docutils literal notranslate"><span class="pre">empty()</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">getInstList()</span></code> method.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">BasicBlock::InstListType</span> <span class="pre">&getInstList()</span></code></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 <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code> 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 <code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Function</span> <span class="pre">*getParent()</span></code></p>
+<p>Returns a pointer to <a class="reference internal" href="#c-function"><span class="std std-ref">Function</span></a> the block is embedded into,
+or a null pointer if it is homeless.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">Instruction</span> <span class="pre">*getTerminator()</span></code></p>
+<p>Returns a pointer to the terminator instruction that appears at the end of the
+<code class="docutils literal notranslate"><span class="pre">BasicBlock</span></code>. 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="#id149">The <code class="docutils literal notranslate"><span class="pre">Argument</span></code> 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" role="navigation" aria-label="related navigation">
+ <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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/Projects.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/Projects.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/Projects.html (added)
+++ www-releases/trunk/8.0.1/docs/Projects.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,327 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Creating an LLVM Project — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVMBuild Guide" href="LLVMBuild.html" />
+ <link rel="prev" title="LLVM Developer Policy" href="DeveloperPolicy.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" role="navigation" aria-label="related navigation">
+ <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="DeveloperPolicy.html" title="LLVM Developer Policy"
+ 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" role="main">
+
+ <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 <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> from a project must do the following things:</p>
+<ul class="simple">
+<li>Set <code class="docutils literal notranslate"><span class="pre">make</span></code> variables. There are several variables that a <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> needs
+to set to use the LLVM build system:<ul>
+<li><code class="docutils literal notranslate"><span class="pre">PROJECT_NAME</span></code> - The name by which your project is known.</li>
+<li><code class="docutils literal notranslate"><span class="pre">LLVM_SRC_ROOT</span></code> - The root of the LLVM source tree.</li>
+<li><code class="docutils literal notranslate"><span class="pre">LLVM_OBJ_ROOT</span></code> - The root of the LLVM object tree.</li>
+<li><code class="docutils literal notranslate"><span class="pre">PROJ_SRC_ROOT</span></code> - The root of the projectâs source tree.</li>
+<li><code class="docutils literal notranslate"><span class="pre">PROJ_OBJ_ROOT</span></code> - The root of the projectâs object tree.</li>
+<li><code class="docutils literal notranslate"><span class="pre">PROJ_INSTALL_ROOT</span></code> - The root installation directory.</li>
+<li><code class="docutils literal notranslate"><span class="pre">LEVEL</span></code> - The relative path from the current directory to the
+projectâs root <code class="docutils literal notranslate"><span class="pre">($PROJ_OBJ_ROOT)</span></code>.</li>
+</ul>
+</li>
+<li>Include <code class="docutils literal notranslate"><span class="pre">Makefile.config</span></code> from <code class="docutils literal notranslate"><span class="pre">$(LLVM_OBJ_ROOT)</span></code>.</li>
+<li>Include <code class="docutils literal notranslate"><span class="pre">Makefile.rules</span></code> from <code class="docutils literal notranslate"><span class="pre">$(LLVM_SRC_ROOT)</span></code>.</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 <code class="docutils literal notranslate"><span class="pre">Makefiles</span></code> which hard-code these values.</li>
+<li>You can use the pre-made LLVM sample project. This sample project includes
+<code class="docutils literal notranslate"><span class="pre">Makefiles</span></code>, 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
+<code class="docutils literal notranslate"><span class="pre">Makefiles</span></code> will probably provide enough information on how to write your own
+<code class="docutils literal notranslate"><span class="pre">Makefiles</span></code>.</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 <code class="docutils literal notranslate"><span class="pre">llvm/test</span></code>. These tests are run by the
+<a class="reference internal" href="CommandGuide/lit.html"><span class="doc">Lit</span></a> testing tool. This test procedure uses <code class="docutils literal notranslate"><span class="pre">RUN</span></code>
+lines in the actual test case to determine how to run the test. See the
+<a class="reference internal" href="TestingGuide.html"><span class="doc">LLVM Testing Infrastructure Guide</span></a> for more details.</p>
+</li>
+<li><p class="first">LLVM contains an optional package called <code class="docutils literal notranslate"><span class="pre">llvm-test</span></code>, 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 <code class="docutils literal notranslate"><span class="pre">llvm/test</span></code>
+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><code class="docutils literal notranslate"><span class="pre">LEVEL</span></code></p>
+<blockquote>
+<div>This variable is the relative path from this <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> to the top
+directory of your projectâs source code. For example, if your source code
+is in <code class="docutils literal notranslate"><span class="pre">/tmp/src</span></code>, then the <code class="docutils literal notranslate"><span class="pre">Makefile</span></code> in <code class="docutils literal notranslate"><span class="pre">/tmp/src/jump/high</span></code>
+would set <code class="docutils literal notranslate"><span class="pre">LEVEL</span></code> to <code class="docutils literal notranslate"><span class="pre">"../.."</span></code>.</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><code class="docutils literal notranslate"><span class="pre">DIRS</span></code></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><code class="docutils literal notranslate"><span class="pre">PARALLEL_DIRS</span></code></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><code class="docutils literal notranslate"><span class="pre">OPTIONAL_DIRS</span></code></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><code class="docutils literal notranslate"><span class="pre">LIBRARYNAME</span></code></p>
+<blockquote>
+<div>This variable contains the base name of the library that will be built. For
+example, to build a library named <code class="docutils literal notranslate"><span class="pre">libsample.a</span></code>, <code class="docutils literal notranslate"><span class="pre">LIBRARYNAME</span></code> should
+be set to <code class="docutils literal notranslate"><span class="pre">sample</span></code>.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">BUILD_ARCHIVE</span></code></p>
+<blockquote>
+<div>By default, a library is a <code class="docutils literal notranslate"><span class="pre">.o</span></code> file that is linked directly into a
+program. To build an archive (also known as a static library), set the
+<code class="docutils literal notranslate"><span class="pre">BUILD_ARCHIVE</span></code> variable.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">SHARED_LIBRARY</span></code></p>
+<blockquote>
+<div>If <code class="docutils literal notranslate"><span class="pre">SHARED_LIBRARY</span></code> 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><code class="docutils literal notranslate"><span class="pre">TOOLNAME</span></code></p>
+<blockquote>
+<div>This variable contains the name of the program that will be built. For
+example, to build an executable named <code class="docutils literal notranslate"><span class="pre">sample</span></code>, <code class="docutils literal notranslate"><span class="pre">TOOLNAME</span></code> should be set
+to <code class="docutils literal notranslate"><span class="pre">sample</span></code>.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">USEDLIBS</span></code></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
+<code class="docutils literal notranslate"><span class="pre">lib</span></code> prefix. For example, to link <code class="docutils literal notranslate"><span class="pre">libsample.a</span></code>, you would set
+<code class="docutils literal notranslate"><span class="pre">USEDLIBS</span></code> to <code class="docutils literal notranslate"><span class="pre">sample.a</span></code>.</p>
+<p>Note that this works only for statically linked libraries.</p>
+</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">LLVMLIBS</span></code></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 <code class="docutils literal notranslate"><span class="pre">lib</span></code> prefix. For example, to
+link with a driver that performs an IR transformation you might set
+<code class="docutils literal notranslate"><span class="pre">LLVMLIBS</span></code> to this minimal set of libraries <code class="docutils literal notranslate"><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></code>.</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: <code class="docutils literal notranslate"><span class="pre">llvm-config</span> <span class="pre">--libs</span> <span class="pre">all</span></code>. Using <code class="docutils literal notranslate"><span class="pre">LINK_COMPONENTS</span></code> as
+described below, obviates the need to set <code class="docutils literal notranslate"><span class="pre">LLVMLIBS</span></code>.</p>
+</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">LINK_COMPONENTS</span></code></p>
+<blockquote>
+<div>This variable holds a space separated list of components that the LLVM
+<code class="docutils literal notranslate"><span class="pre">Makefiles</span></code> pass to the <code class="docutils literal notranslate"><span class="pre">llvm-config</span></code> tool to generate a link line for
+the program. For example, to link with all LLVM libraries use
+<code class="docutils literal notranslate"><span class="pre">LINK_COMPONENTS</span> <span class="pre">=</span> <span class="pre">all</span></code>.</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">LIBS</span></code></p>
+<blockquote>
+<div><p>To link dynamic libraries, add <code class="docutils literal notranslate"><span class="pre">-l<library</span> <span class="pre">base</span> <span class="pre">name></span></code> to the <code class="docutils literal notranslate"><span class="pre">LIBS</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">libsample.so</span></code>, you would have the following line in
+your <code class="docutils literal notranslate"><span class="pre">Makefile</span></code>:</p>
+<blockquote>
+<div><div class="highlight-makefile notranslate"><div class="highlight"><pre><span></span><span class="nv">LIBS</span> <span class="o">+=</span> -lsample
+</pre></div>
+</div>
+</div></blockquote>
+</div></blockquote>
+<p>Note that <code class="docutils literal notranslate"><span class="pre">LIBS</span></code> must occur in the Makefile after the inclusion of
+<code class="docutils literal notranslate"><span class="pre">Makefile.common</span></code>.</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><code class="docutils literal notranslate"><span class="pre">CFLAGS</span></code> & <code class="docutils literal notranslate"><span class="pre">CPPFLAGS</span></code></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 <code class="docutils literal notranslate"><span class="pre">CFLAGS</span></code> and <code class="docutils literal notranslate"><span class="pre">CPPFLAGS</span></code> as
+opposed to overwriting them. The master <code class="docutils literal notranslate"><span class="pre">Makefiles</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Debug</span></code>, <code class="docutils literal notranslate"><span class="pre">Release</span></code>, or <code class="docutils literal notranslate"><span class="pre">Profile</span></code> build.</p>
+<p>Libraries</p>
+<blockquote>
+<div>All libraries (static and dynamic) will be stored in
+<code class="docutils literal notranslate"><span class="pre">PROJ_OBJ_ROOT/<type>/lib</span></code>, where <em>type</em> is <code class="docutils literal notranslate"><span class="pre">Debug</span></code>, <code class="docutils literal notranslate"><span class="pre">Release</span></code>, or
+<code class="docutils literal notranslate"><span class="pre">Profile</span></code> for a debug, optimized, or profiled build, respectively.</div></blockquote>
+<p>Executables</p>
+<blockquote>
+<div>All executables will be stored in <code class="docutils literal notranslate"><span class="pre">PROJ_OBJ_ROOT/<type>/bin</span></code>, where <em>type</em>
+is <code class="docutils literal notranslate"><span class="pre">Debug</span></code>, <code class="docutils literal notranslate"><span class="pre">Release</span></code>, or <code class="docutils literal notranslate"><span class="pre">Profile</span></code> 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.llvm.org/pipermail/llvm-dev/">LLVM Developers Mailing List</a>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="DeveloperPolicy.html" title="LLVM Developer Policy"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/Proposals/GitHubMove.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/Proposals/GitHubMove.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/Proposals/GitHubMove.html (added)
+++ www-releases/trunk/8.0.1/docs/Proposals/GitHubMove.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,993 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Moving LLVM Projects to GitHub — LLVM 8 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" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Test-Suite Extentions" href="TestSuite.html" />
+ <link rel="prev" title="LLVM Bug Life Cycle" href="../BugLifeCycle.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" role="navigation" aria-label="related navigation">
+ <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="TestSuite.html" title="Test-Suite Extentions"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../BugLifeCycle.html" title="LLVM Bug Life Cycle"
+ 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" role="main">
+
+ <div class="section" id="moving-llvm-projects-to-github">
+<h1>Moving LLVM Projects to GitHub<a class="headerlink" href="#moving-llvm-projects-to-github" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="table-of-contents">
+<p class="topic-title first">Table of Contents</p>
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id26">Introduction</a></li>
+<li><a class="reference internal" href="#what-this-proposal-is-not-about" id="id27">What This Proposal is <em>Not</em> About</a></li>
+<li><a class="reference internal" href="#why-git-and-why-github" id="id28">Why Git, and Why GitHub?</a><ul>
+<li><a class="reference internal" href="#why-move-at-all" id="id29">Why Move At All?</a></li>
+<li><a class="reference internal" href="#why-git" id="id30">Why Git?</a></li>
+<li><a class="reference internal" href="#why-github" id="id31">Why GitHub?</a></li>
+<li><a class="reference internal" href="#on-managing-revision-numbers-with-git" id="id32">On Managing Revision Numbers with Git</a></li>
+<li><a class="reference internal" href="#what-about-branches-and-merges" id="id33">What About Branches and Merges?</a></li>
+<li><a class="reference internal" href="#what-about-commit-emails" id="id34">What About Commit Emails?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#straw-man-migration-plan" id="id35">Straw Man Migration Plan</a><ul>
+<li><a class="reference internal" href="#step-1-before-the-move" id="id36">Step #1 : Before The Move</a></li>
+<li><a class="reference internal" href="#step-2-git-move" id="id37">Step #2 : Git Move</a></li>
+<li><a class="reference internal" href="#step-3-write-access-move" id="id38">Step #3: Write Access Move</a></li>
+<li><a class="reference internal" href="#step-4-post-move" id="id39">Step #4 : Post Move</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#one-or-multiple-repositories" id="id40">One or Multiple Repositories?</a><ul>
+<li><a class="reference internal" href="#multirepo-variant" id="id41">Multirepo Variant</a><ul>
+<li><a class="reference internal" href="#umbrella-repository" id="id42">Umbrella Repository</a></li>
+<li><a class="reference internal" href="#living-downstream" id="id43">Living Downstream</a></li>
+<li><a class="reference internal" href="#multirepo-preview" id="id44">Multirepo Preview</a></li>
+<li><a class="reference internal" href="#concerns" id="id45">Concerns</a></li>
+<li><a class="reference internal" href="#workflows" id="id46">Workflows</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#monorepo-variant" id="id47">Monorepo Variant</a><ul>
+<li><a class="reference internal" href="#building-a-single-sub-project" id="id48">Building a single sub-project</a></li>
+<li><a class="reference internal" href="#read-write-sub-project-mirrors" id="id49">Read/write sub-project mirrors</a></li>
+<li><a class="reference internal" href="#id9" id="id50">Living Downstream</a></li>
+<li><a class="reference internal" href="#monorepo-preview" id="id51">Monorepo Preview</a></li>
+<li><a class="reference internal" href="#id12" id="id52">Concerns</a></li>
+<li><a class="reference internal" href="#id13" id="id53">Workflows</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#multi-mono-hybrid-variant" id="id54">Multi/Mono Hybrid Variant</a><ul>
+<li><a class="reference internal" href="#id14" id="id55">Concerns</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#workflow-before-after" id="id56">Workflow Before/After</a><ul>
+<li><a class="reference internal" href="#checkout-clone-a-single-project-without-commit-access" id="id57">Checkout/Clone a Single Project, without Commit Access</a></li>
+<li><a class="reference internal" href="#checkout-clone-a-single-project-with-commit-access" id="id58">Checkout/Clone a Single Project, with Commit Access</a><ul>
+<li><a class="reference internal" href="#currently" id="id59">Currently</a></li>
+<li><a class="reference internal" href="#workflow-multicheckout-nocommit" id="id60">Multirepo Variant</a></li>
+<li><a class="reference internal" href="#workflow-monocheckout-nocommit" id="id61">Monorepo Variant</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#checkout-clone-multiple-projects-with-commit-access" id="id62">Checkout/Clone Multiple Projects, with Commit Access</a><ul>
+<li><a class="reference internal" href="#id17" id="id63">Currently</a></li>
+<li><a class="reference internal" href="#workflow-multicheckout-multicommit" id="id64">Multirepo Variant</a></li>
+<li><a class="reference internal" href="#workflow-monocheckout-multicommit" id="id65">Monorepo Variant</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#commit-an-api-change-in-llvm-and-update-the-sub-projects" id="id66">Commit an API Change in LLVM and Update the Sub-projects</a></li>
+<li><a class="reference internal" href="#branching-stashing-updating-for-local-development-or-experiments" id="id67">Branching/Stashing/Updating for Local Development or Experiments</a><ul>
+<li><a class="reference internal" href="#id20" id="id68">Currently</a></li>
+<li><a class="reference internal" href="#workflow-multi-branching" id="id69">Multirepo Variant</a></li>
+<li><a class="reference internal" href="#workflow-mono-branching" id="id70">Monorepo Variant</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#bisecting" id="id71">Bisecting</a><ul>
+<li><a class="reference internal" href="#id23" id="id72">Currently</a></li>
+<li><a class="reference internal" href="#workflow-multi-bisecting" id="id73">Multirepo Variant</a></li>
+<li><a class="reference internal" href="#workflow-mono-bisecting" id="id74">Monorepo Variant</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#references" id="id75">References</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id26">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This is a proposal to move our current revision control system from our own
+hosted Subversion to GitHub. Below are the financial and technical arguments as
+to why we are proposing such a move and how people (and validation
+infrastructure) will continue to work with a Git-based LLVM.</p>
+<p>There will be a survey pointing at this document which weâll use to gauge the
+communityâs reaction and, if we collectively decide to move, the time-frame. Be
+sure to make your view count.</p>
+<p>Additionally, we will discuss this during a BoF at the next US LLVM Developer
+meeting (<a class="reference external" href="http://llvm.org/devmtg/2016-11/">http://llvm.org/devmtg/2016-11/</a>).</p>
+</div>
+<div class="section" id="what-this-proposal-is-not-about">
+<h2><a class="toc-backref" href="#id27">What This Proposal is <em>Not</em> About</a><a class="headerlink" href="#what-this-proposal-is-not-about" title="Permalink to this headline">¶</a></h2>
+<p>Changing the development policy.</p>
+<p>This proposal relates only to moving the hosting of our source-code repository
+from SVN hosted on our own servers to Git hosted on GitHub. We are not proposing
+using GitHubâs issue tracker, pull-requests, or code-review.</p>
+<p>Contributors will continue to earn commit access on demand under the Developer
+Policy, except that that a GitHub account will be required instead of SVN
+username/password-hash.</p>
+</div>
+<div class="section" id="why-git-and-why-github">
+<h2><a class="toc-backref" href="#id28">Why Git, and Why GitHub?</a><a class="headerlink" href="#why-git-and-why-github" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="why-move-at-all">
+<h3><a class="toc-backref" href="#id29">Why Move At All?</a><a class="headerlink" href="#why-move-at-all" title="Permalink to this headline">¶</a></h3>
+<p>This discussion began because we currently host our own Subversion server
+and Git mirror on a voluntary basis. The LLVM Foundation sponsors the server and
+provides limited support, but there is only so much it can do.</p>
+<p>Volunteers are not sysadmins themselves, but compiler engineers that happen
+to know a thing or two about hosting servers. We also donât have 24/7 support,
+and we sometimes wake up to see that continuous integration is broken because
+the SVN server is either down or unresponsive.</p>
+<p>We should take advantage of one of the services out there (GitHub, GitLab,
+and BitBucket, among others) that offer better service (24/7 stability, disk
+space, Git server, code browsing, forking facilities, etc) for free.</p>
+</div>
+<div class="section" id="why-git">
+<h3><a class="toc-backref" href="#id30">Why Git?</a><a class="headerlink" href="#why-git" title="Permalink to this headline">¶</a></h3>
+<p>Many new coders nowadays start with Git, and a lot of people have never used
+SVN, CVS, or anything else. Websites like GitHub have changed the landscape
+of open source contributions, reducing the cost of first contribution and
+fostering collaboration.</p>
+<p>Git is also the version control many LLVM developers use. Despite the
+sources being stored in a SVN server, these developers are already using Git
+through the Git-SVN integration.</p>
+<p>Git allows you to:</p>
+<ul class="simple">
+<li>Commit, squash, merge, and fork locally without touching the remote server.</li>
+<li>Maintain local branches, enabling multiple threads of development.</li>
+<li>Collaborate on these branches (e.g. through your own fork of llvm on GitHub).</li>
+<li>Inspect the repository history (blame, log, bisect) without Internet access.</li>
+<li>Maintain remote forks and branches on Git hosting services and
+integrate back to the main repository.</li>
+</ul>
+<p>In addition, because Git seems to be replacing many OSS projectsâ version
+control systems, there are many tools that are built over Git.
+Future tooling may support Git first (if not only).</p>
+</div>
+<div class="section" id="why-github">
+<h3><a class="toc-backref" href="#id31">Why GitHub?</a><a class="headerlink" href="#why-github" title="Permalink to this headline">¶</a></h3>
+<p>GitHub, like GitLab and BitBucket, provides free code hosting for open source
+projects. Any of these could replace the code-hosting infrastructure that we
+have today.</p>
+<p>These services also have a dedicated team to monitor, migrate, improve and
+distribute the contents of the repositories depending on region and load.</p>
+<p>GitHub has one important advantage over GitLab and
+BitBucket: it offers read-write <strong>SVN</strong> access to the repository
+(<a class="reference external" href="https://github.com/blog/626-announcing-svn-support">https://github.com/blog/626-announcing-svn-support</a>).
+This would enable people to continue working post-migration as though our code
+were still canonically in an SVN repository.</p>
+<p>In addition, there are already multiple LLVM mirrors on GitHub, indicating that
+part of our community has already settled there.</p>
+</div>
+<div class="section" id="on-managing-revision-numbers-with-git">
+<h3><a class="toc-backref" href="#id32">On Managing Revision Numbers with Git</a><a class="headerlink" href="#on-managing-revision-numbers-with-git" title="Permalink to this headline">¶</a></h3>
+<p>The current SVN repository hosts all the LLVM sub-projects alongside each other.
+A single revision number (e.g. r123456) thus identifies a consistent version of
+all LLVM sub-projects.</p>
+<p>Git does not use sequential integer revision number but instead uses a hash to
+identify each commit. (Linus mentioned that the lack of such revision number
+is âthe only real design mistakeâ in Git <a class="reference internal" href="#torvaldrevnum" id="id1">[TorvaldRevNum]</a>.)</p>
+<p>The loss of a sequential integer revision number has been a sticking point in
+past discussions about Git:</p>
+<ul class="simple">
+<li>âThe âbranchâ I most care about is mainline, and losing the ability to say
+âfixed in r1234â (with some sort of monotonically increasing number) would
+be a tragic loss.â <a class="reference internal" href="#lattnerrevnum" id="id2">[LattnerRevNum]</a></li>
+<li>âI like those results sorted by time and the chronology should be obvious, but
+timestamps are incredibly cumbersome and make it difficult to verify that a
+given checkout matches a given set of results.â <a class="reference internal" href="#trickrevnum" id="id3">[TrickRevNum]</a></li>
+<li>âThere is still the major regression with unreadable version numbers.
+Given the amount of Bugzilla traffic with âFixed inâ¦â, thatâs a
+non-trivial issue.â <a class="reference internal" href="#jsonnrevnum" id="id4">[JSonnRevNum]</a></li>
+<li>âSequential IDs are important for LNT and llvmlab bisection tool.â <a class="reference internal" href="#matthewsrevnum" id="id5">[MatthewsRevNum]</a>.</li>
+</ul>
+<p>However, Git can emulate this increasing revision number:
+<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">rev-list</span> <span class="pre">--count</span> <span class="pre"><commit-hash></span></code>. This identifier is unique only
+within a single branch, but this means the tuple <cite>(num, branch-name)</cite> uniquely
+identifies a commit.</p>
+<p>We can thus use this revision number to ensure that e.g. <cite>clang -v</cite> reports a
+user-friendly revision number (e.g. <cite>master-12345</cite> or <cite>4.0-5321</cite>), addressing
+the objections raised above with respect to this aspect of Git.</p>
+</div>
+<div class="section" id="what-about-branches-and-merges">
+<h3><a class="toc-backref" href="#id33">What About Branches and Merges?</a><a class="headerlink" href="#what-about-branches-and-merges" title="Permalink to this headline">¶</a></h3>
+<p>In contrast to SVN, Git makes branching easy. Gitâs commit history is
+represented as a DAG, a departure from SVNâs linear history. However, we propose
+to mandate making merge commits illegal in our canonical Git repository.</p>
+<p>Unfortunately, GitHub does not support server side hooks to enforce such a
+policy. We must rely on the community to avoid pushing merge commits.</p>
+<p>GitHub offers a feature called <cite>Status Checks</cite>: a branch protected by
+<cite>status checks</cite> requires commits to be whitelisted before the push can happen.
+We could supply a pre-push hook on the client side that would run and check the
+history, before whitelisting the commit being pushed <a class="reference internal" href="#statuschecks" id="id6">[statuschecks]</a>.
+However this solution would be somewhat fragile (how do you update a script
+installed on every developer machine?) and prevents SVN access to the
+repository.</p>
+</div>
+<div class="section" id="what-about-commit-emails">
+<h3><a class="toc-backref" href="#id34">What About Commit Emails?</a><a class="headerlink" href="#what-about-commit-emails" title="Permalink to this headline">¶</a></h3>
+<p>We will need a new bot to send emails for each commit. This proposal leaves the
+email format unchanged besides the commit URL.</p>
+</div>
+</div>
+<div class="section" id="straw-man-migration-plan">
+<h2><a class="toc-backref" href="#id35">Straw Man Migration Plan</a><a class="headerlink" href="#straw-man-migration-plan" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="step-1-before-the-move">
+<h3><a class="toc-backref" href="#id36">Step #1 : Before The Move</a><a class="headerlink" href="#step-1-before-the-move" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Update docs to mention the move, so people are aware of what is going on.</li>
+<li>Set up a read-only version of the GitHub project, mirroring our current SVN
+repository.</li>
+<li>Add the required bots to implement the commit emails, as well as the
+umbrella repository update (if the multirepo is selected) or the read-only
+Git views for the sub-projects (if the monorepo is selected).</li>
+</ol>
+</div>
+<div class="section" id="step-2-git-move">
+<h3><a class="toc-backref" href="#id37">Step #2 : Git Move</a><a class="headerlink" href="#step-2-git-move" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple" start="4">
+<li>Update the buildbots to pick up updates and commits from the GitHub
+repository. Not all bots have to migrate at this point, but itâll help
+provide infrastructure testing.</li>
+<li>Update Phabricator to pick up commits from the GitHub repository.</li>
+<li>LNT and llvmlab have to be updated: they rely on unique monotonically
+increasing integer across branch <a class="reference internal" href="#matthewsrevnum" id="id7">[MatthewsRevNum]</a>.</li>
+<li>Instruct downstream integrators to pick up commits from the GitHub
+repository.</li>
+<li>Review and prepare an update for the LLVM documentation.</li>
+</ol>
+<p>Until this point nothing has changed for developers, it will just
+boil down to a lot of work for buildbot and other infrastructure
+owners.</p>
+<p>The migration will pause here until all dependencies have cleared, and all
+problems have been solved.</p>
+</div>
+<div class="section" id="step-3-write-access-move">
+<h3><a class="toc-backref" href="#id38">Step #3: Write Access Move</a><a class="headerlink" href="#step-3-write-access-move" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple" start="9">
+<li>Collect developersâ GitHub account information, and add them to the project.</li>
+<li>Switch the SVN repository to read-only and allow pushes to the GitHub repository.</li>
+<li>Update the documentation.</li>
+<li>Mirror Git to SVN.</li>
+</ol>
+</div>
+<div class="section" id="step-4-post-move">
+<h3><a class="toc-backref" href="#id39">Step #4 : Post Move</a><a class="headerlink" href="#step-4-post-move" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple" start="13">
+<li>Archive the SVN repository.</li>
+<li>Update links on the LLVM website pointing to viewvc/klaus/phab etc. to
+point to GitHub instead.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="one-or-multiple-repositories">
+<h2><a class="toc-backref" href="#id40">One or Multiple Repositories?</a><a class="headerlink" href="#one-or-multiple-repositories" title="Permalink to this headline">¶</a></h2>
+<p>There are two major variants for how to structure our Git repository: The
+âmultirepoâ and the âmonorepoâ.</p>
+<div class="section" id="multirepo-variant">
+<h3><a class="toc-backref" href="#id41">Multirepo Variant</a><a class="headerlink" href="#multirepo-variant" title="Permalink to this headline">¶</a></h3>
+<p>This variant recommends moving each LLVM sub-project to a separate Git
+repository. This mimics the existing official read-only Git repositories
+(e.g., <a class="reference external" href="http://llvm.org/git/compiler-rt.git">http://llvm.org/git/compiler-rt.git</a>), and creates new canonical
+repositories for each sub-project.</p>
+<p>This will allow the individual sub-projects to remain distinct: a
+developer interested only in compiler-rt can checkout only this repository,
+build it, and work in isolation of the other sub-projects.</p>
+<p>A key need is to be able to check out multiple projects (i.e. lldb+clang+llvm or
+clang+llvm+libcxx for example) at a specific revision.</p>
+<p>A tuple of revisions (one entry per repository) accurately describes the state
+across the sub-projects.
+For example, a given version of clang would be
+<em><LLVM-12345, clang-5432, libcxx-123, etc.></em>.</p>
+<div class="section" id="umbrella-repository">
+<h4><a class="toc-backref" href="#id42">Umbrella Repository</a><a class="headerlink" href="#umbrella-repository" title="Permalink to this headline">¶</a></h4>
+<p>To make this more convenient, a separate <em>umbrella</em> repository will be
+provided. This repository will be used for the sole purpose of understanding
+the sequence in which commits were pushed to the different repositories and to
+provide a single revision number.</p>
+<p>This umbrella repository will be read-only and continuously updated
+to record the above tuple. The proposed form to record this is to use Git
+<a class="reference internal" href="#submodules" id="id8">[submodules]</a>, possibly along with a set of scripts to help check out a
+specific revision of the LLVM distribution.</p>
+<p>A regular LLVM developer does not need to interact with the umbrella repository
+â the individual repositories can be checked out independently â but you would
+need to use the umbrella repository to bisect multiple sub-projects at the same
+time, or to check-out old revisions of LLVM with another sub-project at a
+consistent state.</p>
+<p>This umbrella repository will be updated automatically by a bot (running on
+notice from a webhook on every push, and periodically) on a per commit basis: a
+single commit in the umbrella repository would match a single commit in a
+sub-project.</p>
+</div>
+<div class="section" id="living-downstream">
+<h4><a class="toc-backref" href="#id43">Living Downstream</a><a class="headerlink" href="#living-downstream" title="Permalink to this headline">¶</a></h4>
+<p>Downstream SVN users can use the read/write SVN bridges with the following
+caveats:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Be prepared for a one-time change to the upstream revision numbers.</li>
+<li>The upstream sub-project revision numbers will no longer be in sync.</li>
+</ul>
+</div></blockquote>
+<p>Downstream Git users can continue without any major changes, with the minor
+change of upstreaming using <cite>git push</cite> instead of <cite>git svn dcommit</cite>.</p>
+<p>Git users also have the option of adopting an umbrella repository downstream.
+The tooling for the upstream umbrella can easily be reused for downstream needs,
+incorporating extra sub-projects and branching in parallel with sub-project
+branches.</p>
+</div>
+<div class="section" id="multirepo-preview">
+<h4><a class="toc-backref" href="#id44">Multirepo Preview</a><a class="headerlink" href="#multirepo-preview" title="Permalink to this headline">¶</a></h4>
+<p>As a preview (disclaimer: this rough prototype, not polished and not
+representative of the final solution), you can look at the following:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Repository: <a class="reference external" href="https://github.com/llvm-beanz/llvm-submodules">https://github.com/llvm-beanz/llvm-submodules</a></li>
+<li>Update bot: <a class="reference external" href="http://beanz-bot.com:8180/jenkins/job/submodule-update/">http://beanz-bot.com:8180/jenkins/job/submodule-update/</a></li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="concerns">
+<h4><a class="toc-backref" href="#id45">Concerns</a><a class="headerlink" href="#concerns" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>Because GitHub does not allow server-side hooks, and because there is no
+âpush timestampâ in Git, the umbrella repository sequence isnât totally
+exact: commits from different repositories pushed around the same time can
+appear in different orders. However, we donât expect it to be the common case
+or to cause serious issues in practice.</li>
+<li>You canât have a single cross-projects commit that would update both LLVM and
+other sub-projects (something that can be achieved now). It would be possible
+to establish a protocol whereby users add a special token to their commit
+messages that causes the umbrella repoâs updater bot to group all of them
+into a single revision.</li>
+<li>Another option is to group commits that were pushed closely enough together
+in the umbrella repository. This has the advantage of allowing cross-project
+commits, and is less sensitive to mis-ordering commits. However, this has the
+potential to group unrelated commits together, especially if the bot goes
+down and needs to catch up.</li>
+<li>This variant relies on heavier tooling. But the current prototype shows that
+it is not out-of-reach.</li>
+<li>Submodules donât have a good reputation / are complicating the command line.
+However, in the proposed setup, a regular developer will seldom interact with
+submodules directly, and certainly never update them.</li>
+<li>Refactoring across projects is not friendly: taking some functions from clang
+to make it part of a utility in libSupport wouldnât carry the history of the
+code in the llvm repo, preventing recursively applying <cite>git blame</cite> for
+instance. However, this is not very different than how most people are
+Interacting with the repository today, by splitting such change in multiple
+commits.</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="workflows">
+<h4><a class="toc-backref" href="#id46">Workflows</a><a class="headerlink" href="#workflows" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li><a class="reference internal" href="#workflow-checkout-commit"><span class="std std-ref">Checkout/Clone a Single Project, without Commit Access</span></a>.</li>
+<li><a class="reference internal" href="#workflow-multicheckout-nocommit"><span class="std std-ref">Checkout/Clone a Single Project, with Commit Access</span></a>.</li>
+<li><a class="reference internal" href="#workflow-multicheckout-multicommit"><span class="std std-ref">Checkout/Clone Multiple Projects, with Commit Access</span></a>.</li>
+<li><a class="reference internal" href="#workflow-cross-repo-commit"><span class="std std-ref">Commit an API Change in LLVM and Update the Sub-projects</span></a>.</li>
+<li><a class="reference internal" href="#workflow-multi-branching"><span class="std std-ref">Branching/Stashing/Updating for Local Development or Experiments</span></a>.</li>
+<li><a class="reference internal" href="#workflow-multi-bisecting"><span class="std std-ref">Bisecting</span></a>.</li>
+</ul>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="monorepo-variant">
+<h3><a class="toc-backref" href="#id47">Monorepo Variant</a><a class="headerlink" href="#monorepo-variant" title="Permalink to this headline">¶</a></h3>
+<p>This variant recommends moving all LLVM sub-projects to a single Git repository,
+similar to <a class="reference external" href="https://github.com/llvm-project/llvm-project">https://github.com/llvm-project/llvm-project</a>.
+This would mimic an export of the current SVN repository, with each sub-project
+having its own top-level directory.
+Not all sub-projects are used for building toolchains. In practice, www/
+and test-suite/ will probably stay out of the monorepo.</p>
+<p>Putting all sub-projects in a single checkout makes cross-project refactoring
+naturally simple:</p>
+<blockquote>
+<div><ul class="simple">
+<li>New sub-projects can be trivially split out for better reuse and/or layering
+(e.g., to allow libSupport and/or LIT to be used by runtimes without adding a
+dependency on LLVM).</li>
+<li>Changing an API in LLVM and upgrading the sub-projects will always be done in
+a single commit, designing away a common source of temporary build breakage.</li>
+<li>Moving code across sub-project (during refactoring for instance) in a single
+commit enables accurate <cite>git blame</cite> when tracking code change history.</li>
+<li>Tooling based on <cite>git grep</cite> works natively across sub-projects, allowing to
+easier find refactoring opportunities across projects (for example reusing a
+datastructure initially in LLDB by moving it into libSupport).</li>
+<li>Having all the sources present encourages maintaining the other sub-projects
+when changing API.</li>
+</ul>
+</div></blockquote>
+<p>Finally, the monorepo maintains the property of the existing SVN repository that
+the sub-projects move synchronously, and a single revision number (or commit
+hash) identifies the state of the development across all projects.</p>
+<div class="section" id="building-a-single-sub-project">
+<span id="build-single-project"></span><h4><a class="toc-backref" href="#id48">Building a single sub-project</a><a class="headerlink" href="#building-a-single-sub-project" title="Permalink to this headline">¶</a></h4>
+<p>Nobody will be forced to build unnecessary projects. The exact structure
+is TBD, but making it trivial to configure builds for a single sub-project
+(or a subset of sub-projects) is a hard requirement.</p>
+<p>As an example, it could look like the following:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">mkdir</span> <span class="n">build</span> <span class="o">&&</span> <span class="n">cd</span> <span class="n">build</span>
+<span class="c1"># Configure only LLVM (default)</span>
+<span class="n">cmake</span> <span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">monorepo</span>
+<span class="c1"># Configure LLVM and lld</span>
+<span class="n">cmake</span> <span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">monorepo</span> <span class="o">-</span><span class="n">DLLVM_ENABLE_PROJECTS</span><span class="o">=</span><span class="n">lld</span>
+<span class="c1"># Configure LLVM and clang</span>
+<span class="n">cmake</span> <span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">monorepo</span> <span class="o">-</span><span class="n">DLLVM_ENABLE_PROJECTS</span><span class="o">=</span><span class="n">clang</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="read-write-sub-project-mirrors">
+<span id="git-svn-mirror"></span><h4><a class="toc-backref" href="#id49">Read/write sub-project mirrors</a><a class="headerlink" href="#read-write-sub-project-mirrors" title="Permalink to this headline">¶</a></h4>
+<p>With the Monorepo, the existing single-subproject mirrors (e.g.
+<a class="reference external" href="http://llvm.org/git/compiler-rt.git">http://llvm.org/git/compiler-rt.git</a>) with git-svn read-write access would
+continue to be maintained: developers would continue to be able to use the
+existing single-subproject git repositories as they do today, with <em>no changes
+to workflow</em>. Everything (git fetch, git svn dcommit, etc.) could continue to
+work identically to how it works today. The monorepo can be set-up such that the
+SVN revision number matches the SVN revision in the GitHub SVN-bridge.</p>
+</div>
+<div class="section" id="id9">
+<h4><a class="toc-backref" href="#id50">Living Downstream</a><a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h4>
+<p>Downstream SVN users can use the read/write SVN bridge. The SVN revision
+number can be preserved in the monorepo, minimizing the impact.</p>
+<p>Downstream Git users can continue without any major changes, by using the
+git-svn mirrors on top of the SVN bridge.</p>
+<p>Git users can also work upstream with monorepo even if their downstream
+fork has split repositories. They can apply patches in the appropriate
+subdirectories of the monorepo using, e.g., <cite>git am âdirectory=â¦</cite>, or
+plain <cite>diff</cite> and <cite>patch</cite>.</p>
+<p>Alternatively, Git users can migrate their own fork to the monorepo. As a
+demonstration, weâve migrated the âCHERIâ fork to the monorepo in two ways:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Using a script that rewrites history (including merges) so that it looks
+like the fork always lived in the monorepo <a class="reference internal" href="#lebarcheri" id="id10">[LebarCHERI]</a>. The upside of
+this is when you check out an old revision, you get a copy of all llvm
+sub-projects at a consistent revision. (For instance, if itâs a clang
+fork, when you check out an old revision youâll get a consistent version
+of llvm proper.) The downside is that this changes the forkâs commit
+hashes.</li>
+<li>Merging the fork into the monorepo <a class="reference internal" href="#aminicheri" id="id11">[AminiCHERI]</a>. This preserves the
+forkâs commit hashes, but when you check out an old commit you only get
+the one sub-project.</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="monorepo-preview">
+<h4><a class="toc-backref" href="#id51">Monorepo Preview</a><a class="headerlink" href="#monorepo-preview" title="Permalink to this headline">¶</a></h4>
+<p>As a preview (disclaimer: this rough prototype, not polished and not
+representative of the final solution), you can look at the following:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Full Repository: <a class="reference external" href="https://github.com/joker-eph/llvm-project">https://github.com/joker-eph/llvm-project</a></li>
+<li>Single sub-project view with <em>SVN write access</em> to the full repo:
+<a class="reference external" href="https://github.com/joker-eph/compiler-rt">https://github.com/joker-eph/compiler-rt</a></li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="id12">
+<h4><a class="toc-backref" href="#id52">Concerns</a><a class="headerlink" href="#id12" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>Using the monolithic repository may add overhead for those contributing to a
+standalone sub-project, particularly on runtimes like libcxx and compiler-rt
+that donât rely on LLVM; currently, a fresh clone of libcxx is only 15MB (vs.
+1GB for the monorepo), and the commit rate of LLVM may cause more frequent
+<cite>git push</cite> collisions when upstreaming. Affected contributors can continue to
+use the SVN bridge or the single-subproject Git mirrors with git-svn for
+read-write.</li>
+<li>Using the monolithic repository may add overhead for those <em>integrating</em> a
+standalone sub-project, even if they arenât contributing to it, due to the
+same disk space concern as the point above. The availability of the
+sub-project Git mirror addresses this, even without SVN access.</li>
+<li>Preservation of the existing read/write SVN-based workflows relies on the
+GitHub SVN bridge, which is an extra dependency. Maintaining this locks us
+into GitHub and could restrict future workflow changes.</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="id13">
+<h4><a class="toc-backref" href="#id53">Workflows</a><a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li><a class="reference internal" href="#workflow-checkout-commit"><span class="std std-ref">Checkout/Clone a Single Project, without Commit Access</span></a>.</li>
+<li><a class="reference internal" href="#workflow-monocheckout-nocommit"><span class="std std-ref">Checkout/Clone a Single Project, with Commit Access</span></a>.</li>
+<li><a class="reference internal" href="#workflow-monocheckout-multicommit"><span class="std std-ref">Checkout/Clone Multiple Projects, with Commit Access</span></a>.</li>
+<li><a class="reference internal" href="#workflow-cross-repo-commit"><span class="std std-ref">Commit an API Change in LLVM and Update the Sub-projects</span></a>.</li>
+<li><a class="reference internal" href="#workflow-mono-branching"><span class="std std-ref">Branching/Stashing/Updating for Local Development or Experiments</span></a>.</li>
+<li><a class="reference internal" href="#workflow-mono-bisecting"><span class="std std-ref">Bisecting</span></a>.</li>
+</ul>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="multi-mono-hybrid-variant">
+<h3><a class="toc-backref" href="#id54">Multi/Mono Hybrid Variant</a><a class="headerlink" href="#multi-mono-hybrid-variant" title="Permalink to this headline">¶</a></h3>
+<p>This variant recommends moving only the LLVM sub-projects that are <em>rev-locked</em>
+to LLVM into a monorepo (clang, lld, lldb, â¦), following the multirepo
+proposal for the rest. While neither variant recommends combining sub-projects
+like www/ and test-suite/ (which are completely standalone), this goes further
+and keeps sub-projects like libcxx and compiler-rt in their own distinct
+repositories.</p>
+<div class="section" id="id14">
+<h4><a class="toc-backref" href="#id55">Concerns</a><a class="headerlink" href="#id14" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>This has most disadvantages of multirepo and monorepo, without bringing many
+of the advantages.</li>
+<li>Downstream have to upgrade to the monorepo structure, but only partially. So
+they will keep the infrastructure to integrate the other separate
+sub-projects.</li>
+<li>All projects that use LIT for testing are effectively rev-locked to LLVM.
+Furthermore, some runtimes (like compiler-rt) are rev-locked with Clang.
+Itâs not clear where to draw the lines.</li>
+</ul>
+</div></blockquote>
+</div>
+</div>
+</div>
+<div class="section" id="workflow-before-after">
+<h2><a class="toc-backref" href="#id56">Workflow Before/After</a><a class="headerlink" href="#workflow-before-after" title="Permalink to this headline">¶</a></h2>
+<p>This section goes through a few examples of workflows, intended to illustrate
+how end-users or developers would interact with the repository for
+various use-cases.</p>
+<div class="section" id="checkout-clone-a-single-project-without-commit-access">
+<span id="workflow-checkout-commit"></span><h3><a class="toc-backref" href="#id57">Checkout/Clone a Single Project, without Commit Access</a><a class="headerlink" href="#checkout-clone-a-single-project-without-commit-access" title="Permalink to this headline">¶</a></h3>
+<p>Except the URL, nothing changes. The possibilities today are:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">svn</span> <span class="n">co</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">llvm</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">svn</span><span class="o">/</span><span class="n">llvm</span><span class="o">-</span><span class="n">project</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">trunk</span> <span class="n">llvm</span>
+<span class="c1"># or with Git</span>
+<span class="n">git</span> <span class="n">clone</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">llvm</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">git</span><span class="o">/</span><span class="n">llvm</span><span class="o">.</span><span class="n">git</span>
+</pre></div>
+</div>
+<p>After the move to GitHub, you would do either:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">llvm</span><span class="o">-</span><span class="n">project</span><span class="o">/</span><span class="n">llvm</span><span class="o">.</span><span class="n">git</span>
+<span class="c1"># or using the GitHub svn native bridge</span>
+<span class="n">svn</span> <span class="n">co</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">llvm</span><span class="o">-</span><span class="n">project</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">trunk</span>
+</pre></div>
+</div>
+<p>The above works for both the monorepo and the multirepo, as weâll maintain the
+existing read-only views of the individual sub-projects.</p>
+</div>
+<div class="section" id="checkout-clone-a-single-project-with-commit-access">
+<h3><a class="toc-backref" href="#id58">Checkout/Clone a Single Project, with Commit Access</a><a class="headerlink" href="#checkout-clone-a-single-project-with-commit-access" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="currently">
+<h4><a class="toc-backref" href="#id59">Currently</a><a class="headerlink" href="#currently" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># direct SVN checkout</span>
+<span class="n">svn</span> <span class="n">co</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">user</span><span class="nd">@llvm</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">svn</span><span class="o">/</span><span class="n">llvm</span><span class="o">-</span><span class="n">project</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">trunk</span> <span class="n">llvm</span>
+<span class="c1"># or using the read-only Git view, with git-svn</span>
+<span class="n">git</span> <span class="n">clone</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">llvm</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">git</span><span class="o">/</span><span class="n">llvm</span><span class="o">.</span><span class="n">git</span>
+<span class="n">cd</span> <span class="n">llvm</span>
+<span class="n">git</span> <span class="n">svn</span> <span class="n">init</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">llvm</span><span class="o">.</span><span class="n">org</span><span class="o">/</span><span class="n">svn</span><span class="o">/</span><span class="n">llvm</span><span class="o">-</span><span class="n">project</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">trunk</span> <span class="o">--</span><span class="n">username</span><span class="o">=<</span><span class="n">username</span><span class="o">></span>
+<span class="n">git</span> <span class="n">config</span> <span class="n">svn</span><span class="o">-</span><span class="n">remote</span><span class="o">.</span><span class="n">svn</span><span class="o">.</span><span class="n">fetch</span> <span class="p">:</span><span class="n">refs</span><span class="o">/</span><span class="n">remotes</span><span class="o">/</span><span class="n">origin</span><span class="o">/</span><span class="n">master</span>
+<span class="n">git</span> <span class="n">svn</span> <span class="n">rebase</span> <span class="o">-</span><span class="n">l</span> <span class="c1"># -l avoids fetching ahead of the git mirror.</span>
+</pre></div>
+</div>
+<p>Commits are performed using <cite>svn commit</cite> or with the sequence <cite>git commit</cite> and
+<cite>git svn dcommit</cite>.</p>
+</div>
+<div class="section" id="workflow-multicheckout-nocommit">
+<span id="id15"></span><h4><a class="toc-backref" href="#id60">Multirepo Variant</a><a class="headerlink" href="#workflow-multicheckout-nocommit" title="Permalink to this headline">¶</a></h4>
+<p>With the multirepo variant, nothing changes but the URL, and commits can be
+performed using <cite>svn commit</cite> or <cite>git commit</cite> and <cite>git push</cite>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">llvm</span><span class="o">.</span><span class="n">git</span> <span class="n">llvm</span>
+<span class="c1"># or using the GitHub svn native bridge</span>
+<span class="n">svn</span> <span class="n">co</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">trunk</span><span class="o">/</span> <span class="n">llvm</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="workflow-monocheckout-nocommit">
+<span id="id16"></span><h4><a class="toc-backref" href="#id61">Monorepo Variant</a><a class="headerlink" href="#workflow-monocheckout-nocommit" title="Permalink to this headline">¶</a></h4>
+<p>With the monorepo variant, there are a few options, depending on your
+constraints. First, you could just clone the full repository:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">llvm</span><span class="o">-</span><span class="n">projects</span><span class="o">.</span><span class="n">git</span> <span class="n">llvm</span>
+<span class="c1"># or using the GitHub svn native bridge</span>
+<span class="n">svn</span> <span class="n">co</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">llvm</span><span class="o">-</span><span class="n">projects</span><span class="o">/</span><span class="n">trunk</span><span class="o">/</span> <span class="n">llvm</span>
+</pre></div>
+</div>
+<p>At this point you have every sub-project (llvm, clang, lld, lldb, â¦), which
+<a class="reference internal" href="#build-single-project"><span class="std std-ref">doesnât imply you have to build all of them</span></a>. You
+can still build only compiler-rt for instance. In this way itâs not different
+from someone who would check out all the projects with SVN today.</p>
+<p>You can commit as normal using <cite>git commit</cite> and <cite>git push</cite> or <cite>svn commit</cite>, and
+read the history for a single project (<cite>git log libcxx</cite> for example).</p>
+<p>Secondly, there are a few options to avoid checking out all the sources.</p>
+<p><strong>Using the GitHub SVN bridge</strong></p>
+<p>The GitHub SVN native bridge allows to checkout a subdirectory directly:</p>
+<blockquote>
+<div>svn co <a class="reference external" href="https://github.com/llvm/llvm-projects/trunk/compiler-rt">https://github.com/llvm/llvm-projects/trunk/compiler-rt</a> compiler-rt âusername=â¦</div></blockquote>
+<p>This checks out only compiler-rt and provides commit access using âsvn commitâ,
+in the same way as it would do today.</p>
+<p><strong>Using a Subproject Git Nirror</strong></p>
+<p>You can use <em>git-svn</em> and one of the sub-project mirrors:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span># Clone from the single read-only Git repo
+git clone http://llvm.org/git/llvm.git
+cd llvm
+# Configure the SVN remote and initialize the svn metadata
+$ git svn init https://github.com/joker-eph/llvm-project/trunk/llvm âusername=...
+git config svn-remote.svn.fetch :refs/remotes/origin/master
+git svn rebase -l
+</pre></div>
+</div>
+<p>In this case the repository contains only a single sub-project, and commits can
+be made using <cite>git svn dcommit</cite>, again exactly as we do today.</p>
+<p><strong>Using a Sparse Checkouts</strong></p>
+<p>You can hide the other directories using a Git sparse checkout:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">config</span> <span class="n">core</span><span class="o">.</span><span class="n">sparseCheckout</span> <span class="n">true</span>
+<span class="n">echo</span> <span class="o">/</span><span class="n">compiler</span><span class="o">-</span><span class="n">rt</span> <span class="o">></span> <span class="o">.</span><span class="n">git</span><span class="o">/</span><span class="n">info</span><span class="o">/</span><span class="n">sparse</span><span class="o">-</span><span class="n">checkout</span>
+<span class="n">git</span> <span class="n">read</span><span class="o">-</span><span class="n">tree</span> <span class="o">-</span><span class="n">mu</span> <span class="n">HEAD</span>
+</pre></div>
+</div>
+<p>The data for all sub-projects is still in your <cite>.git</cite> directory, but in your
+checkout, you only see <cite>compiler-rt</cite>.
+Before you push, youâll need to fetch and rebase (<cite>git pull ârebase</cite>) as
+usual.</p>
+<p>Note that when you fetch youâll likely pull in changes to sub-projects you donât
+care about. If you are using spasre checkout, the files from other projects
+wonât appear on your disk. The only effect is that your commit hash changes.</p>
+<p>You can check whether the changes in the last fetch are relevant to your commit
+by running:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">log</span> <span class="n">origin</span><span class="o">/</span><span class="n">master</span><span class="o">@</span><span class="p">{</span><span class="mi">1</span><span class="p">}</span><span class="o">..</span><span class="n">origin</span><span class="o">/</span><span class="n">master</span> <span class="o">--</span> <span class="n">libcxx</span>
+</pre></div>
+</div>
+<p>This command can be hidden in a script so that <cite>git llvmpush</cite> would perform all
+these steps, fail only if such a dependent change exists, and show immediately
+the change that prevented the push. An immediate repeat of the command would
+(almost) certainly result in a successful push.
+Note that today with SVN or git-svn, this step is not possible since the
+ârebaseâ implicitly happens while committing (unless a conflict occurs).</p>
+</div>
+</div>
+<div class="section" id="checkout-clone-multiple-projects-with-commit-access">
+<h3><a class="toc-backref" href="#id62">Checkout/Clone Multiple Projects, with Commit Access</a><a class="headerlink" href="#checkout-clone-multiple-projects-with-commit-access" title="Permalink to this headline">¶</a></h3>
+<p>Letâs look how to assemble llvm+clang+libcxx at a given revision.</p>
+<div class="section" id="id17">
+<h4><a class="toc-backref" href="#id63">Currently</a><a class="headerlink" href="#id17" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm -r $REVISION
+cd llvm/tools
+svn co http://llvm.org/svn/llvm-project/clang/trunk clang -r $REVISION
+cd ../projects
+svn co http://llvm.org/svn/llvm-project/libcxx/trunk libcxx -r $REVISION
+</pre></div>
+</div>
+<p>Or using git-svn:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>git clone http://llvm.org/git/llvm.git
+cd llvm/
+git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username>
+git config svn-remote.svn.fetch :refs/remotes/origin/master
+git svn rebase -l
+git checkout `git svn find-rev -B r258109`
+cd tools
+git clone http://llvm.org/git/clang.git
+cd clang/
+git svn init https://llvm.org/svn/llvm-project/clang/trunk --username=<username>
+git config svn-remote.svn.fetch :refs/remotes/origin/master
+git svn rebase -l
+git checkout `git svn find-rev -B r258109`
+cd ../../projects/
+git clone http://llvm.org/git/libcxx.git
+cd libcxx
+git svn init https://llvm.org/svn/llvm-project/libcxx/trunk --username=<username>
+git config svn-remote.svn.fetch :refs/remotes/origin/master
+git svn rebase -l
+git checkout `git svn find-rev -B r258109`
+</pre></div>
+</div>
+<p>Note that the list would be longer with more sub-projects.</p>
+</div>
+<div class="section" id="workflow-multicheckout-multicommit">
+<span id="id18"></span><h4><a class="toc-backref" href="#id64">Multirepo Variant</a><a class="headerlink" href="#workflow-multicheckout-multicommit" title="Permalink to this headline">¶</a></h4>
+<p>With the multirepo variant, the umbrella repository will be used. This is
+where the mapping from a single revision number to the individual repositories
+revisions is stored.:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/llvm-beanz/llvm-submodules
+cd llvm-submodules
+git checkout $REVISION
+git submodule init
+git submodule update clang llvm libcxx
+# the list of sub-project is optional, `git submodule update` would get them all.
+</pre></div>
+</div>
+<p>At this point the clang, llvm, and libcxx individual repositories are cloned
+and stored alongside each other. There are CMake flags to describe the directory
+structure; alternatively, you can just symlink <cite>clang</cite> to <cite>llvm/tools/clang</cite>,
+etc.</p>
+<p>Another option is to checkout repositories based on the commit timestamp:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>git checkout `git rev-list -n 1 --before="2009-07-27 13:37" master`
+</pre></div>
+</div>
+</div>
+<div class="section" id="workflow-monocheckout-multicommit">
+<span id="id19"></span><h4><a class="toc-backref" href="#id65">Monorepo Variant</a><a class="headerlink" href="#workflow-monocheckout-multicommit" title="Permalink to this headline">¶</a></h4>
+<p>The repository contains natively the source for every sub-projects at the right
+revision, which makes this straightforward:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/llvm/llvm-projects.git llvm-projects
+cd llvm-projects
+git checkout $REVISION
+</pre></div>
+</div>
+<p>As before, at this point clang, llvm, and libcxx are stored in directories
+alongside each other.</p>
+</div>
+</div>
+<div class="section" id="commit-an-api-change-in-llvm-and-update-the-sub-projects">
+<span id="workflow-cross-repo-commit"></span><h3><a class="toc-backref" href="#id66">Commit an API Change in LLVM and Update the Sub-projects</a><a class="headerlink" href="#commit-an-api-change-in-llvm-and-update-the-sub-projects" title="Permalink to this headline">¶</a></h3>
+<p>Today this is possible, even though not common (at least not documented) for
+subversion users and for git-svn users. For example, few Git users try to update
+LLD or Clang in the same commit as they change an LLVM API.</p>
+<p>The multirepo variant does not address this: one would have to commit and push
+separately in every individual repository. It would be possible to establish a
+protocol whereby users add a special token to their commit messages that causes
+the umbrella repoâs updater bot to group all of them into a single revision.</p>
+<p>The monorepo variant handles this natively.</p>
+</div>
+<div class="section" id="branching-stashing-updating-for-local-development-or-experiments">
+<h3><a class="toc-backref" href="#id67">Branching/Stashing/Updating for Local Development or Experiments</a><a class="headerlink" href="#branching-stashing-updating-for-local-development-or-experiments" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id20">
+<h4><a class="toc-backref" href="#id68">Currently</a><a class="headerlink" href="#id20" title="Permalink to this headline">¶</a></h4>
+<p>SVN does not allow this use case, but developers that are currently using
+git-svn can do it. Letâs look in practice what it means when dealing with
+multiple sub-projects.</p>
+<p>To update the repository to tip of trunk:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">pull</span>
+<span class="n">cd</span> <span class="n">tools</span><span class="o">/</span><span class="n">clang</span>
+<span class="n">git</span> <span class="n">pull</span>
+<span class="n">cd</span> <span class="o">../../</span><span class="n">projects</span><span class="o">/</span><span class="n">libcxx</span>
+<span class="n">git</span> <span class="n">pull</span>
+</pre></div>
+</div>
+<p>To create a new branch:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">MyBranch</span>
+<span class="n">cd</span> <span class="n">tools</span><span class="o">/</span><span class="n">clang</span>
+<span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">MyBranch</span>
+<span class="n">cd</span> <span class="o">../../</span><span class="n">projects</span><span class="o">/</span><span class="n">libcxx</span>
+<span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">MyBranch</span>
+</pre></div>
+</div>
+<p>To switch branches:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">AnotherBranch</span>
+<span class="n">cd</span> <span class="n">tools</span><span class="o">/</span><span class="n">clang</span>
+<span class="n">git</span> <span class="n">checkout</span> <span class="n">AnotherBranch</span>
+<span class="n">cd</span> <span class="o">../../</span><span class="n">projects</span><span class="o">/</span><span class="n">libcxx</span>
+<span class="n">git</span> <span class="n">checkout</span> <span class="n">AnotherBranch</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="workflow-multi-branching">
+<span id="id21"></span><h4><a class="toc-backref" href="#id69">Multirepo Variant</a><a class="headerlink" href="#workflow-multi-branching" title="Permalink to this headline">¶</a></h4>
+<p>The multirepo works the same as the current Git workflow: every command needs
+to be applied to each of the individual repositories.
+However, the umbrella repository makes this easy using <cite>git submodule foreach</cite>
+to replicate a command on all the individual repositories (or submodules
+in this case):</p>
+<p>To create a new branch:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">submodule</span> <span class="n">foreach</span> <span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">MyBranch</span>
+</pre></div>
+</div>
+<p>To switch branches:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">submodule</span> <span class="n">foreach</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">AnotherBranch</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="workflow-mono-branching">
+<span id="id22"></span><h4><a class="toc-backref" href="#id70">Monorepo Variant</a><a class="headerlink" href="#workflow-mono-branching" title="Permalink to this headline">¶</a></h4>
+<p>Regular Git commands are sufficient, because everything is in a single
+repository:</p>
+<p>To update the repository to tip of trunk:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">pull</span>
+</pre></div>
+</div>
+<p>To create a new branch:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">MyBranch</span>
+</pre></div>
+</div>
+<p>To switch branches:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">AnotherBranch</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="bisecting">
+<h3><a class="toc-backref" href="#id71">Bisecting</a><a class="headerlink" href="#bisecting" title="Permalink to this headline">¶</a></h3>
+<p>Assuming a developer is looking for a bug in clang (or lld, or lldb, â¦).</p>
+<div class="section" id="id23">
+<h4><a class="toc-backref" href="#id72">Currently</a><a class="headerlink" href="#id23" title="Permalink to this headline">¶</a></h4>
+<p>SVN does not have builtin bisection support, but the single revision across
+sub-projects makes it possible to script around.</p>
+<p>Using the existing Git read-only view of the repositories, it is possible to use
+the native Git bisection script over the llvm repository, and use some scripting
+to synchronize the clang repository to match the llvm revision.</p>
+</div>
+<div class="section" id="workflow-multi-bisecting">
+<span id="id24"></span><h4><a class="toc-backref" href="#id73">Multirepo Variant</a><a class="headerlink" href="#workflow-multi-bisecting" title="Permalink to this headline">¶</a></h4>
+<p>With the multi-repositories variant, the cross-repository synchronization is
+achieved using the umbrella repository. This repository contains only
+submodules for the other sub-projects. The native Git bisection can be used on
+the umbrella repository directly. A subtlety is that the bisect script itself
+needs to make sure the submodules are updated accordingly.</p>
+<p>For example, to find which commit introduces a regression where clang-3.9
+crashes but not clang-3.8 passes, one should be able to simply do:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">bisect</span> <span class="n">start</span> <span class="n">release_39</span> <span class="n">release_38</span>
+<span class="n">git</span> <span class="n">bisect</span> <span class="n">run</span> <span class="o">./</span><span class="n">bisect_script</span><span class="o">.</span><span class="n">sh</span>
+</pre></div>
+</div>
+<p>With the <cite>bisect_script.sh</cite> script being:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>#!/bin/sh
+cd $UMBRELLA_DIRECTORY
+git submodule update llvm clang libcxx #....
+cd $BUILD_DIR
+
+ninja clang || exit 125 # an exit code of 125 asks "git bisect"
+ # to "skip" the current commit
+
+./bin/clang some_crash_test.cpp
+</pre></div>
+</div>
+<p>When the <cite>git bisect run</cite> command returns, the umbrella repository is set to
+the state where the regression is introduced. The commit diff in the umbrella
+indicate which submodule was updated, and the last commit in this sub-projects
+is the one that the bisect found.</p>
+</div>
+<div class="section" id="workflow-mono-bisecting">
+<span id="id25"></span><h4><a class="toc-backref" href="#id74">Monorepo Variant</a><a class="headerlink" href="#workflow-mono-bisecting" title="Permalink to this headline">¶</a></h4>
+<p>Bisecting on the monorepo is straightforward, and very similar to the above,
+except that the bisection script does not need to include the
+<cite>git submodule update</cite> step.</p>
+<p>The same example, finding which commit introduces a regression where clang-3.9
+crashes but not clang-3.8 passes, will look like:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">bisect</span> <span class="n">start</span> <span class="n">release_39</span> <span class="n">release_38</span>
+<span class="n">git</span> <span class="n">bisect</span> <span class="n">run</span> <span class="o">./</span><span class="n">bisect_script</span><span class="o">.</span><span class="n">sh</span>
+</pre></div>
+</div>
+<p>With the <cite>bisect_script.sh</cite> script being:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>#!/bin/sh
+cd $BUILD_DIR
+
+ninja clang || exit 125 # an exit code of 125 asks "git bisect"
+ # to "skip" the current commit
+
+./bin/clang some_crash_test.cpp
+</pre></div>
+</div>
+<p>Also, since the monorepo handles commits update across multiple projects, youâre
+less like to encounter a build failure where a commit change an API in LLVM and
+another later one âfixesâ the build in clang.</p>
+</div>
+</div>
+</div>
+<div class="section" id="references">
+<h2><a class="toc-backref" href="#id75">References</a><a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
+<table class="docutils citation" frame="void" id="lattnerrevnum" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[LattnerRevNum]</a></td><td>Chris Lattner, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2011-July/041739.html">http://lists.llvm.org/pipermail/llvm-dev/2011-July/041739.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="trickrevnum" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id3">[TrickRevNum]</a></td><td>Andrew Trick, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2011-July/041721.html">http://lists.llvm.org/pipermail/llvm-dev/2011-July/041721.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="jsonnrevnum" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id4">[JSonnRevNum]</a></td><td>Joerg Sonnenberg, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2011-July/041688.html">http://lists.llvm.org/pipermail/llvm-dev/2011-July/041688.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="torvaldrevnum" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1">[TorvaldRevNum]</a></td><td>Linus Torvald, <a class="reference external" href="http://git.661346.n2.nabble.com/Git-commit-generation-numbers-td6584414.html">http://git.661346.n2.nabble.com/Git-commit-generation-numbers-td6584414.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="matthewsrevnum" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[MatthewsRevNum]</td><td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref" href="#id7">2</a>)</em> Chris Matthews, <a class="reference external" href="http://lists.llvm.org/pipermail/cfe-dev/2016-July/049886.html">http://lists.llvm.org/pipermail/cfe-dev/2016-July/049886.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="submodules" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id8">[submodules]</a></td><td>Git submodules, <a class="reference external" href="https://git-scm.com/book/en/v2/Git-Tools-Submodules">https://git-scm.com/book/en/v2/Git-Tools-Submodules</a>)</td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="statuschecks" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id6">[statuschecks]</a></td><td>GitHub status-checks, <a class="reference external" href="https://help.github.com/articles/about-required-status-checks/">https://help.github.com/articles/about-required-status-checks/</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="lebarcheri" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id10">[LebarCHERI]</a></td><td>Port <em>CHERI</em> to a single repository rewriting history, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2016-July/102787.html">http://lists.llvm.org/pipermail/llvm-dev/2016-July/102787.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="aminicheri" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id11">[AminiCHERI]</a></td><td>Port <em>CHERI</em> to a single repository preserving history, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2016-July/102804.html">http://lists.llvm.org/pipermail/llvm-dev/2016-July/102804.html</a></td></tr>
+</tbody>
+</table>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="TestSuite.html" title="Test-Suite Extentions"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../BugLifeCycle.html" title="LLVM Bug Life Cycle"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/Proposals/TestSuite.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/Proposals/TestSuite.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/Proposals/TestSuite.html (added)
+++ www-releases/trunk/8.0.1/docs/Proposals/TestSuite.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,431 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Test-Suite Extentions — LLVM 8 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" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="prev" title="Moving LLVM Projects to GitHub" href="GitHubMove.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" role="navigation" aria-label="related navigation">
+ <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="GitHubMove.html" title="Moving LLVM Projects to GitHub"
+ 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" role="main">
+
+ <div class="section" id="test-suite-extentions">
+<h1>Test-Suite Extentions<a class="headerlink" href="#test-suite-extentions" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#abstract" id="id1">Abstract</a></li>
+<li><a class="reference internal" href="#benchmarks" id="id2">Benchmarks</a></li>
+<li><a class="reference internal" href="#applications-libraries" id="id3">Applications/Libraries</a></li>
+<li><a class="reference internal" href="#generic-algorithms" id="id4">Generic Algorithms</a></li>
+</ul>
+</div>
+<div class="section" id="abstract">
+<h2><a class="toc-backref" href="#id1">Abstract</a><a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>These are ideas for additional programs, benchmarks, applications and
+algorithms that could be added to the LLVM Test-Suite.
+The test-suite could be much larger than it is now, which would help us
+detecting compiler errors (crashes, miscompiles) during development.</p>
+<p>Most probably, the reason why the programs below have not been added to
+the test-suite yet is that nobody has found time to do it. But there
+might be other issues as well, such as</p>
+<blockquote>
+<div><ul class="simple">
+<li><dl class="first docutils">
+<dt>Licensing (Support can still be added as external module,</dt>
+<dd>like for the SPEC benchmarks)</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>Language (in particular, there is no official LLVM frontend</dt>
+<dd>for FORTRAN yet)</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>Parallelism (currently, all programs in test-suite use</dt>
+<dd>one thread only)</dd>
+</dl>
+</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="benchmarks">
+<h2><a class="toc-backref" href="#id2">Benchmarks</a><a class="headerlink" href="#benchmarks" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="spec-cpu-2017">
+<h3>SPEC CPU 2017<a class="headerlink" href="#spec-cpu-2017" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://www.spec.org/cpu2017/">https://www.spec.org/cpu2017/</a></p>
+<p>The following have not been included yet because they contain Fortran
+code.</p>
+<p>In case of cactuBSSN only a small portion is Fortran. The hostsâs
+Fortran compiler could be used for these parts.</p>
+<p>Note that CMakeâs Ninja generator has difficulties with Fortran. See the
+<a class="reference external" href="https://cmake.org/cmake/help/v3.13/generator/Ninja.html#fortran-support">CMake documentation</a>
+for details.</p>
+<blockquote>
+<div><ul class="simple">
+<li>503.bwaves_r/603.bwaves_s</li>
+<li>507.cactuBSSN_r</li>
+<li>521.wrf_r/621.wrf_s</li>
+<li>527.cam4_r/627.cam4_s</li>
+<li>628.pop2_s</li>
+<li>548.exchange2_r/648.exchange2_s</li>
+<li>549.fotonik3d_r/649.fotonik3d_s</li>
+<li>554.roms_r/654.roms_s</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="spec-omp2012">
+<h3>SPEC OMP2012<a class="headerlink" href="#spec-omp2012" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://www.spec.org/omp2012/">https://www.spec.org/omp2012/</a></p>
+<blockquote>
+<div><ul class="simple">
+<li>350.md</li>
+<li>351.bwaves</li>
+<li>352.nab</li>
+<li>357.bt331</li>
+<li>358.botsalgn</li>
+<li>359.botsspar</li>
+<li>360.ilbdc</li>
+<li>362.fma3d</li>
+<li>363.swim</li>
+<li>367.imagick</li>
+<li>370.mgrid331</li>
+<li>371.applu331</li>
+<li>372.smithwa</li>
+<li>376.kdtree</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="opencv">
+<h3>OpenCV<a class="headerlink" href="#opencv" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://opencv.org/">https://opencv.org/</a></p>
+</div>
+<div class="section" id="openmp-4-x-simd-benchmarks">
+<h3>OpenMP 4.x SIMD Benchmarks<a class="headerlink" href="#openmp-4-x-simd-benchmarks" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/flwende/simd_benchmarks">https://github.com/flwende/simd_benchmarks</a></p>
+</div>
+<div class="section" id="pwm-benchmarking">
+<h3>PWM-benchmarking<a class="headerlink" href="#pwm-benchmarking" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/tbepler/PWM-benchmarking">https://github.com/tbepler/PWM-benchmarking</a></p>
+</div>
+<div class="section" id="slambench">
+<h3>SLAMBench<a class="headerlink" href="#slambench" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/pamela-project/slambench">https://github.com/pamela-project/slambench</a></p>
+</div>
+<div class="section" id="firehose">
+<h3>FireHose<a class="headerlink" href="#firehose" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://firehose.sandia.gov/">http://firehose.sandia.gov/</a></p>
+</div>
+<div class="section" id="a-benchmark-for-the-c-c-standard-library">
+<h3>A Benchmark for the C/C++ Standard Library<a class="headerlink" href="#a-benchmark-for-the-c-c-standard-library" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/hiraditya/std-benchmark">https://github.com/hiraditya/std-benchmark</a></p>
+</div>
+<div class="section" id="openbenchmarking-org-cpu-processor-suite">
+<h3>OpenBenchmarking.org CPU / Processor Suite<a class="headerlink" href="#openbenchmarking-org-cpu-processor-suite" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://openbenchmarking.org/suite/pts/cpu">https://openbenchmarking.org/suite/pts/cpu</a></p>
+<p>This is a subset of the
+<a class="reference external" href="https://github.com/phoronix-test-suite/phoronix-test-suite/">Phoronix Test Suite</a>
+and is itself a collection of benchmark suites</p>
+</div>
+<div class="section" id="parboil-benchmarks">
+<h3>Parboil Benchmarks<a class="headerlink" href="#parboil-benchmarks" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://impact.crhc.illinois.edu/parboil/parboil.aspx">http://impact.crhc.illinois.edu/parboil/parboil.aspx</a></p>
+</div>
+<div class="section" id="machsuite">
+<h3>MachSuite<a class="headerlink" href="#machsuite" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://breagen.github.io/MachSuite/">https://breagen.github.io/MachSuite/</a></p>
+</div>
+<div class="section" id="rodinia">
+<h3>Rodinia<a class="headerlink" href="#rodinia" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://lava.cs.virginia.edu/Rodinia/download_links.htm">http://lava.cs.virginia.edu/Rodinia/download_links.htm</a></p>
+<p>Rodinia has already been partially included in
+MultiSource/Benchmarks/Rodinia. Benchmarks still missing are:</p>
+<blockquote>
+<div><ul class="simple">
+<li>streamcluster</li>
+<li>particlefilter</li>
+<li>nw</li>
+<li>nn</li>
+<li>myocyte</li>
+<li>mummergpu</li>
+<li>lud</li>
+<li>leukocyte</li>
+<li>lavaMD</li>
+<li>kmeans</li>
+<li>hotspot3D</li>
+<li>heartwall</li>
+<li>cfd</li>
+<li>bfs</li>
+<li>b+tree</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="vecmathlib-tests-harness">
+<h3>vecmathlib tests harness<a class="headerlink" href="#vecmathlib-tests-harness" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://bitbucket.org/eschnett/vecmathlib/wiki/Home">https://bitbucket.org/eschnett/vecmathlib/wiki/Home</a></p>
+</div>
+<div class="section" id="parsec">
+<h3>PARSEC<a class="headerlink" href="#parsec" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://parsec.cs.princeton.edu/">http://parsec.cs.princeton.edu/</a></p>
+</div>
+<div class="section" id="graph500-reference-implementations">
+<h3>Graph500 reference implementations<a class="headerlink" href="#graph500-reference-implementations" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/graph500/graph500/tree/v2-spec">https://github.com/graph500/graph500/tree/v2-spec</a></p>
+</div>
+<div class="section" id="nas-parallel-benchmarks">
+<h3>NAS Parallel Benchmarks<a class="headerlink" href="#nas-parallel-benchmarks" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://www.nas.nasa.gov/publications/npb.html">https://www.nas.nasa.gov/publications/npb.html</a></p>
+<p>The official benchmark is written in Fortran, but an unofficial
+C-translation is available as well:
+<a class="reference external" href="https://github.com/benchmark-subsetting/NPB3.0-omp-C">https://github.com/benchmark-subsetting/NPB3.0-omp-C</a></p>
+</div>
+<div class="section" id="darpa-hpcs-ssca-2-c-openmp-reference-implementation">
+<h3>DARPA HPCS SSCA#2 C/OpenMP reference implementation<a class="headerlink" href="#darpa-hpcs-ssca-2-c-openmp-reference-implementation" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://www.highproductivity.org/SSCABmks.htm">http://www.highproductivity.org/SSCABmks.htm</a></p>
+<p>This web site does not exist any more, but there seems to be a copy of
+some of the benchmarks
+<a class="reference external" href="https://github.com/gtcasl/hpc-benchmarks/tree/master/SSCA2v2.2">https://github.com/gtcasl/hpc-benchmarks/tree/master/SSCA2v2.2</a></p>
+</div>
+<div class="section" id="kokkos">
+<h3>Kokkos<a class="headerlink" href="#kokkos" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/kokkos/kokkos-kernels/tree/master/perf_test">https://github.com/kokkos/kokkos-kernels/tree/master/perf_test</a>
+<a class="reference external" href="https://github.com/kokkos/kokkos/tree/master/benchmarks">https://github.com/kokkos/kokkos/tree/master/benchmarks</a></p>
+</div>
+<div class="section" id="polymage">
+<h3>PolyMage<a class="headerlink" href="#polymage" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/bondhugula/polymage-benchmarks">https://github.com/bondhugula/polymage-benchmarks</a></p>
+</div>
+<div class="section" id="polybench">
+<h3>PolyBench<a class="headerlink" href="#polybench" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://sourceforge.net/projects/polybench/">https://sourceforge.net/projects/polybench/</a></p>
+<p>A modified version of Polybench 3.2 is already presented in
+SingleSource/Benchmarks/Polybench. A newer version 4.2.1 is available.</p>
+</div>
+<div class="section" id="high-performance-geometric-multigrid">
+<h3>High Performance Geometric Multigrid<a class="headerlink" href="#high-performance-geometric-multigrid" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://crd.lbl.gov/departments/computer-science/PAR/research/hpgmg/">https://crd.lbl.gov/departments/computer-science/PAR/research/hpgmg/</a></p>
+</div>
+<div class="section" id="raja-performance-suite">
+<h3>RAJA Performance Suite<a class="headerlink" href="#raja-performance-suite" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/LLNL/RAJAPerf">https://github.com/LLNL/RAJAPerf</a></p>
+</div>
+<div class="section" id="coral-2-benchmarks">
+<h3>CORAL-2 Benchmarks<a class="headerlink" href="#coral-2-benchmarks" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://asc.llnl.gov/coral-2-benchmarks/">https://asc.llnl.gov/coral-2-benchmarks/</a></p>
+<p>Many of its programs have already been integreated in
+MultiSource/Benchmarks/DOE-ProxyApps-C and
+MultiSource/Benchmarks/DOE-ProxyApps-C++.</p>
+<blockquote>
+<div><ul class="simple">
+<li>Nekbone</li>
+<li>QMCPack</li>
+<li>LAMMPS</li>
+<li>Kripke</li>
+<li>Quicksilver</li>
+<li>PENNANT</li>
+<li>Big Data Analytic Suite</li>
+<li>Deep Learning Suite</li>
+<li>Stream</li>
+<li>Stride</li>
+<li>ML/DL micro-benchmark</li>
+<li>Pynamic</li>
+<li>ACME</li>
+<li>VPIC</li>
+<li>Laghos</li>
+<li>Parallel Integer Sort</li>
+<li>Havoq</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="nwchem">
+<h3>NWChem<a class="headerlink" href="#nwchem" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://www.nwchem-sw.org/index.php/Benchmarks">http://www.nwchem-sw.org/index.php/Benchmarks</a></p>
+</div>
+<div class="section" id="tvm">
+<h3>TVM<a class="headerlink" href="#tvm" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/dmlc/tvm/tree/master/apps/benchmark">https://github.com/dmlc/tvm/tree/master/apps/benchmark</a></p>
+</div>
+<div class="section" id="hydrobench">
+<h3>HydroBench<a class="headerlink" href="#hydrobench" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/HydroBench/Hydro">https://github.com/HydroBench/Hydro</a></p>
+</div>
+<div class="section" id="parres">
+<h3>ParRes<a class="headerlink" href="#parres" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/ParRes/Kernels/tree/master/Cxx11">https://github.com/ParRes/Kernels/tree/master/Cxx11</a></p>
+</div>
+</div>
+<div class="section" id="applications-libraries">
+<h2><a class="toc-backref" href="#id3">Applications/Libraries</a><a class="headerlink" href="#applications-libraries" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="gnupg">
+<h3>GnuPG<a class="headerlink" href="#gnupg" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://gnupg.org/">https://gnupg.org/</a></p>
+</div>
+<div class="section" id="blitz">
+<h3>Blitz++<a class="headerlink" href="#blitz" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://sourceforge.net/projects/blitz/">https://sourceforge.net/projects/blitz/</a></p>
+</div>
+<div class="section" id="ffmpeg">
+<h3>FFmpeg<a class="headerlink" href="#ffmpeg" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://ffmpeg.org/">https://ffmpeg.org/</a></p>
+</div>
+<div class="section" id="freepooma">
+<h3>FreePOOMA<a class="headerlink" href="#freepooma" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://www.nongnu.org/freepooma/">http://www.nongnu.org/freepooma/</a></p>
+</div>
+<div class="section" id="ftensors">
+<h3>FTensors<a class="headerlink" href="#ftensors" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="http://www.wlandry.net/Projects/FTensor">http://www.wlandry.net/Projects/FTensor</a></p>
+</div>
+<div class="section" id="rawspeed">
+<h3>rawspeed<a class="headerlink" href="#rawspeed" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://github.com/darktable-org/rawspeed">https://github.com/darktable-org/rawspeed</a></p>
+<p>Its test dataset is 756 MB in size, which is too large to be included
+into the test-suite repository.</p>
+</div>
+<div class="section" id="c-performance-benchmarks">
+<h3>C++ Performance Benchmarks<a class="headerlink" href="#c-performance-benchmarks" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://gitlab.com/chriscox/CppPerformanceBenchmarks">https://gitlab.com/chriscox/CppPerformanceBenchmarks</a></p>
+</div>
+</div>
+<div class="section" id="generic-algorithms">
+<h2><a class="toc-backref" href="#id4">Generic Algorithms</a><a class="headerlink" href="#generic-algorithms" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="image-processing">
+<h3>Image processing<a class="headerlink" href="#image-processing" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="resampling">
+<h4>Resampling<a class="headerlink" href="#resampling" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>Bilinear</li>
+<li>Bicubic</li>
+<li>Lanczos</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="dither">
+<h4>Dither<a class="headerlink" href="#dither" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>Threshold</li>
+<li>Random</li>
+<li>Halftone</li>
+<li>Bayer</li>
+<li>Floyd-Steinberg</li>
+<li>Jarvis</li>
+<li>Stucki</li>
+<li>Burkes</li>
+<li>Sierra</li>
+<li>Atkinson</li>
+<li>Gradient-based</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="feature-detection">
+<h4>Feature detection<a class="headerlink" href="#feature-detection" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>Harris</li>
+<li>Histogram of Oriented Gradients</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="color-conversion">
+<h4>Color conversion<a class="headerlink" href="#color-conversion" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>RGB to grayscale</li>
+<li>HSL to RGB</li>
+</ul>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="graph">
+<h3>Graph<a class="headerlink" href="#graph" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="search-algorithms">
+<h4>Search Algorithms<a class="headerlink" href="#search-algorithms" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>Breadth-First-Search</li>
+<li>Depth-First-Search</li>
+<li>Dijkstraâs algorithm</li>
+<li>A-Star</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="spanning-tree">
+<h4>Spanning Tree<a class="headerlink" href="#spanning-tree" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>Kruskalâs algorithm</li>
+<li>Primâs algorithm</li>
+</ul>
+</div></blockquote>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="GitHubMove.html" title="Moving LLVM Projects to GitHub"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/Proposals/VariableNames.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/Proposals/VariableNames.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/Proposals/VariableNames.html (added)
+++ www-releases/trunk/8.0.1/docs/Proposals/VariableNames.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,773 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Variable Names Plan — LLVM 9 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" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="prev" title="Test-Suite Extentions" href="TestSuite.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" role="navigation" aria-label="related navigation">
+ <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="TestSuite.html" title="Test-Suite Extentions"
+ 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" role="main">
+
+ <div class="section" id="variable-names-plan">
+<h1>Variable Names Plan<a class="headerlink" href="#variable-names-plan" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#too-long-didn-t-read" id="id76">Too Long; Didnât Read</a></li>
+<li><a class="reference internal" href="#introduction" id="id77">Introduction</a></li>
+<li><a class="reference internal" href="#variable-names-coding-standard-options" id="id78">Variable Names Coding Standard Options</a><ul>
+<li><a class="reference internal" href="#differentiating-variable-kinds" id="id79">Differentiating variable kinds</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reducing-the-number-of-acronyms" id="id80">Reducing the number of acronyms</a></li>
+<li><a class="reference internal" href="#transition-options" id="id81">Transition Options</a><ul>
+<li><a class="reference internal" href="#keep-the-current-coding-standard" id="id82">Keep the current coding standard</a></li>
+<li><a class="reference internal" href="#laissez-faire" id="id83">Laissez faire</a><ul>
+<li><a class="reference internal" href="#advantages" id="id84">Advantages</a></li>
+<li><a class="reference internal" href="#disadvantages" id="id85">Disadvantages</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#big-bang" id="id86">Big bang</a><ul>
+<li><a class="reference internal" href="#keeping-git-blame-usable" id="id87">Keeping git blame usable</a></li>
+<li><a class="reference internal" href="#minimising-cost-of-downstream-merges" id="id88">Minimising cost of downstream merges</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#provisional-plan" id="id89">Provisional Plan</a></li>
+<li><a class="reference internal" href="#references" id="id90">References</a></li>
+</ul>
+</div>
+<p>This plan is <em>provisional</em>. It is not agreed upon. It is written with the
+intention of capturing the desires and concerns of the LLVM community, and
+forming them into a plan that can be agreed upon.
+The original author is somewhat naïve in the ways of LLVM so there will
+inevitably be some details that are flawed. You can help - you can edit this
+page (preferably with a Phabricator review for larger changes) or reply to the
+<a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130083.html">Request For Comments thread</a>.</p>
+<div class="section" id="too-long-didn-t-read">
+<h2><a class="toc-backref" href="#id76">Too Long; Didnât Read</a><a class="headerlink" href="#too-long-didn-t-read" title="Permalink to this headline">¶</a></h2>
+<p>Improve the readability of LLVM code.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id77">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The current <a class="reference external" href="../CodingStandards.html#name-types-functions-variables-and-enumerators-properly">variable naming rule</a>
+states:</p>
+<blockquote>
+<div>Variable names should be nouns (as they represent state). The name should be
+camel case, and start with an upper case letter (e.g. Leader or Boats).</div></blockquote>
+<p>This rule is the same as that for type names. This is a problem because the
+type name cannot be reused for a variable name <a class="footnote-reference" href="#id17" id="id1">[*]</a>. LLVM developers tend to
+work around this by either prepending <code class="docutils literal notranslate"><span class="pre">The</span></code> to the type name:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Triple</span> <span class="n">TheTriple</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>⦠or more commonly use an acronym, despite the coding standard stating âAvoid
+abbreviations unless they are well knownâ:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Triple</span> <span class="n">T</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The proliferation of acronyms leads to hard-to-read code such as <a class="reference external" href="https://github.com/llvm/llvm-project/blob/0a8bc14ad7f3209fe702d18e250194cd90188596/llvm/lib/Transforms/Vectorize/LoopVectorize.cpp#L7445">this</a>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">InnerLoopVectorizer</span> <span class="n">LB</span><span class="p">(</span><span class="n">L</span><span class="p">,</span> <span class="n">PSE</span><span class="p">,</span> <span class="n">LI</span><span class="p">,</span> <span class="n">DT</span><span class="p">,</span> <span class="n">TLI</span><span class="p">,</span> <span class="n">TTI</span><span class="p">,</span> <span class="n">AC</span><span class="p">,</span> <span class="n">ORE</span><span class="p">,</span> <span class="n">VF</span><span class="o">.</span><span class="n">Width</span><span class="p">,</span> <span class="n">IC</span><span class="p">,</span>
+ <span class="o">&</span><span class="n">LVL</span><span class="p">,</span> <span class="o">&</span><span class="n">CM</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Many other coding guidelines <a class="reference internal" href="#lldb" id="id2">[LLDB]</a> <a class="reference internal" href="#google" id="id3">[Google]</a> <a class="reference internal" href="#webkit" id="id4">[WebKit]</a> <a class="reference internal" href="#qt" id="id5">[Qt]</a> <a class="reference internal" href="#rust" id="id6">[Rust]</a> <a class="reference internal" href="#swift" id="id7">[Swift]</a>
+<a class="reference internal" href="#python" id="id8">[Python]</a> require that variable names begin with a lower case letter in contrast
+to class names which begin with a capital letter. This convention means that the
+most readable variable name also requires the least thought:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Triple</span> <span class="n">triple</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>There is some agreement that the current rule is broken <a class="reference internal" href="#lattneragree" id="id9">[LattnerAgree]</a>
+<a class="reference internal" href="#arsenaultagree" id="id10">[ArsenaultAgree]</a> <a class="reference internal" href="#robinsonagree" id="id11">[RobinsonAgree]</a> and that acronyms are an obstacle to reading
+new code <a class="reference internal" href="#malyutindistinguish" id="id12">[MalyutinDistinguish]</a> <a class="reference internal" href="#carruthacronym" id="id13">[CarruthAcronym]</a> <a class="reference internal" href="#picusacronym" id="id14">[PicusAcronym]</a>. There are
+some opposing views <a class="reference internal" href="#parzyszekacronym2" id="id15">[ParzyszekAcronym2]</a> <a class="reference internal" href="#ricciacronyms" id="id16">[RicciAcronyms]</a>.</p>
+<p>This work-in-progress proposal is to change the coding standard for variable
+names to require that they start with a lower case letter.</p>
+<table class="docutils footnote" frame="void" id="id17" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1">[*]</a></td><td>In <a class="reference external" href="https://github.com/llvm/llvm-project/blob/8b72080d4d7b13072f371712eed333f987b7a18e/llvm/lib/CodeGen/SelectionDAG/SelectionDAG.cpp#L2727">some cases</a>
+the type name <em>is</em> reused as a variable name, but this shadows the type name
+and confuses many debuggers <a class="reference internal" href="#denisovcamelback" id="id18">[DenisovCamelBack]</a>.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="variable-names-coding-standard-options">
+<h2><a class="toc-backref" href="#id78">Variable Names Coding Standard Options</a><a class="headerlink" href="#variable-names-coding-standard-options" title="Permalink to this headline">¶</a></h2>
+<p>There are two main options for variable names that begin with a lower case
+letter: <code class="docutils literal notranslate"><span class="pre">camelBack</span></code> and <code class="docutils literal notranslate"><span class="pre">lower_case</span></code>. (These are also known by other names
+but here we use the terminology from clang-tidy).</p>
+<p><code class="docutils literal notranslate"><span class="pre">camelBack</span></code> is consistent with <a class="reference internal" href="#webkit" id="id19">[WebKit]</a>, <a class="reference internal" href="#qt" id="id20">[Qt]</a> and <a class="reference internal" href="#swift" id="id21">[Swift]</a> while
+<code class="docutils literal notranslate"><span class="pre">lower_case</span></code> is consistent with <a class="reference internal" href="#lldb" id="id22">[LLDB]</a>, <a class="reference internal" href="#google" id="id23">[Google]</a>, <a class="reference internal" href="#rust" id="id24">[Rust]</a> and <a class="reference internal" href="#python" id="id25">[Python]</a>.</p>
+<p><code class="docutils literal notranslate"><span class="pre">camelBack</span></code> is already used for function names, which may be considered an
+advantage <a class="reference internal" href="#lattnerfunction" id="id26">[LattnerFunction]</a> or a disadvantage <a class="reference internal" href="#carruthfunction" id="id27">[CarruthFunction]</a>.</p>
+<p>Approval for <code class="docutils literal notranslate"><span class="pre">camelBack</span></code> was expressed by <a class="reference internal" href="#denisovcamelback" id="id28">[DenisovCamelBack]</a>
+<a class="reference internal" href="#lattnerfunction" id="id29">[LattnerFunction]</a> <a class="reference internal" href="#ivanovicdistinguish" id="id30">[IvanovicDistinguish]</a>.
+Opposition to <code class="docutils literal notranslate"><span class="pre">camelBack</span></code> was expressed by <a class="reference internal" href="#carruthcamelback" id="id31">[CarruthCamelBack]</a>
+<a class="reference internal" href="#turnercamelback" id="id32">[TurnerCamelBack]</a>.
+Approval for <code class="docutils literal notranslate"><span class="pre">lower_case</span></code> was expressed by <a class="reference internal" href="#carruthlower" id="id33">[CarruthLower]</a>
+<a class="reference internal" href="#carruthcamelback" id="id34">[CarruthCamelBack]</a> <a class="reference internal" href="#turnerlldb" id="id35">[TurnerLLDB]</a>.
+Opposition to <code class="docutils literal notranslate"><span class="pre">lower_case</span></code> was expressed by <a class="reference internal" href="#lattnerlower" id="id36">[LattnerLower]</a>.</p>
+<div class="section" id="differentiating-variable-kinds">
+<h3><a class="toc-backref" href="#id79">Differentiating variable kinds</a><a class="headerlink" href="#differentiating-variable-kinds" title="Permalink to this headline">¶</a></h3>
+<p>An additional requested change is to distinguish between different kinds of
+variables <a class="reference internal" href="#robinsondistinguish" id="id37">[RobinsonDistinguish]</a> <a class="reference internal" href="#robinsondistinguish2" id="id38">[RobinsonDistinguish2]</a> <a class="reference internal" href="#jonesdistinguish" id="id39">[JonesDistinguish]</a>
+<a class="reference internal" href="#ivanovicdistinguish" id="id40">[IvanovicDistinguish]</a> <a class="reference internal" href="#carruthdistinguish" id="id41">[CarruthDistinguish]</a> <a class="reference internal" href="#malyutindistinguish" id="id42">[MalyutinDistinguish]</a>.</p>
+<p>Others oppose this idea <a class="reference internal" href="#hahnledistinguish" id="id43">[HähnleDistinguish]</a> <a class="reference internal" href="#greenedistinguish" id="id44">[GreeneDistinguish]</a>
+<a class="reference internal" href="#hendersonprefix" id="id45">[HendersonPrefix]</a>.</p>
+<p>A possibility is for member variables to be prefixed with <code class="docutils literal notranslate"><span class="pre">m_</span></code> and for global
+variables to be prefixed with <code class="docutils literal notranslate"><span class="pre">g_</span></code> to distinguish them from local variables.
+This is consistent with <a class="reference internal" href="#lldb" id="id46">[LLDB]</a>. The <code class="docutils literal notranslate"><span class="pre">m_</span></code> prefix is consistent with <a class="reference internal" href="#webkit" id="id47">[WebKit]</a>.</p>
+<p>A variation is for member variables to be prefixed with <code class="docutils literal notranslate"><span class="pre">m</span></code>
+<a class="reference internal" href="#ivanovicdistinguish" id="id48">[IvanovicDistinguish]</a> <a class="reference internal" href="#beylsdistinguish" id="id49">[BeylsDistinguish]</a>. This is consistent with <a class="reference internal" href="#mozilla" id="id50">[Mozilla]</a>.</p>
+<p>Another option is for member variables to be suffixed with <code class="docutils literal notranslate"><span class="pre">_</span></code> which is
+consistent with <a class="reference internal" href="#google" id="id51">[Google]</a> and similar to <a class="reference internal" href="#python" id="id52">[Python]</a>. Opposed by
+<a class="reference internal" href="#parzyszekdistinguish" id="id53">[ParzyszekDistinguish]</a>.</p>
+</div>
+</div>
+<div class="section" id="reducing-the-number-of-acronyms">
+<h2><a class="toc-backref" href="#id80">Reducing the number of acronyms</a><a class="headerlink" href="#reducing-the-number-of-acronyms" title="Permalink to this headline">¶</a></h2>
+<p>While switching coding standard will make it easier to use non-acronym names for
+new code, it doesnât improve the existing large body of code that uses acronyms
+extensively to the detriment of its readability. Further, it is natural and
+generally encouraged that new code be written in the style of the surrounding
+code. Therefore it is likely that much newly written code will also use
+acronyms despite what the coding standard says, much as it is today.</p>
+<p>As well as changing the case of variable names, they could also be expanded to
+their non-acronym form e.g. <code class="docutils literal notranslate"><span class="pre">Triple</span> <span class="pre">T</span></code> â <code class="docutils literal notranslate"><span class="pre">Triple</span> <span class="pre">triple</span></code>.</p>
+<p>There is support for expanding many acronyms <a class="reference internal" href="#carruthacronym" id="id54">[CarruthAcronym]</a> <a class="reference internal" href="#picusacronym" id="id55">[PicusAcronym]</a>
+but there is a preference that expanding acronyms be deferred
+<a class="reference internal" href="#parzyszekacronym" id="id56">[ParzyszekAcronym]</a> <a class="reference internal" href="#carruthacronym" id="id57">[CarruthAcronym]</a>.</p>
+<p>The consensus within the community seems to be that at least some acronyms are
+valuable <a class="reference internal" href="#parzyszekacronym" id="id58">[ParzyszekAcronym]</a> <a class="reference internal" href="#lattneracronym" id="id59">[LattnerAcronym]</a>. The most commonly cited acronym
+is <code class="docutils literal notranslate"><span class="pre">TLI</span></code> however that is used to refer to both <code class="docutils literal notranslate"><span class="pre">TargetLowering</span></code> and
+<code class="docutils literal notranslate"><span class="pre">TargetLibraryInfo</span></code> <a class="reference internal" href="#greenedistinguish" id="id60">[GreeneDistinguish]</a>.</p>
+<p>The following is a list of acronyms considered sufficiently useful that the
+benefit of using them outweighs the cost of learning them. Acronyms that are
+either not on the list or are used to refer to a different type should be
+expanded.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="68%" />
+<col width="32%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Class name</th>
+<th class="head">Variable name</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>DeterministicFiniteAutomaton</td>
+<td>dfa</td>
+</tr>
+<tr class="row-odd"><td>DominatorTree</td>
+<td>dt</td>
+</tr>
+<tr class="row-even"><td>LoopInfo</td>
+<td>li</td>
+</tr>
+<tr class="row-odd"><td>MachineFunction</td>
+<td>mf</td>
+</tr>
+<tr class="row-even"><td>MachineInstr</td>
+<td>mi</td>
+</tr>
+<tr class="row-odd"><td>MachineRegisterInfo</td>
+<td>mri</td>
+</tr>
+<tr class="row-even"><td>ScalarEvolution</td>
+<td>se</td>
+</tr>
+<tr class="row-odd"><td>TargetInstrInfo</td>
+<td>tii</td>
+</tr>
+<tr class="row-even"><td>TargetLibraryInfo</td>
+<td>tli</td>
+</tr>
+<tr class="row-odd"><td>TargetRegisterInfo</td>
+<td>tri</td>
+</tr>
+</tbody>
+</table>
+<p>In some cases renaming acronyms to the full type name will result in overly
+verbose code. Unlike most classes, a variableâs scope is limited and therefore
+some of its purpose can implied from that scope, meaning that fewer words are
+necessary to give it a clear name. For example, in an optization pass the reader
+can assume that a variableâs purpose relates to optimization and therefore an
+<code class="docutils literal notranslate"><span class="pre">OptimizationRemarkEmitter</span></code> variable could be given the name <code class="docutils literal notranslate"><span class="pre">remarkEmitter</span></code>
+or even <code class="docutils literal notranslate"><span class="pre">remarker</span></code>.</p>
+<p>The following is a list of longer class names and the associated shorter
+variable name.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="66%" />
+<col width="34%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Class name</th>
+<th class="head">Variable name</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>BasicBlock</td>
+<td>block</td>
+</tr>
+<tr class="row-odd"><td>ConstantExpr</td>
+<td>expr</td>
+</tr>
+<tr class="row-even"><td>ExecutionEngine</td>
+<td>engine</td>
+</tr>
+<tr class="row-odd"><td>MachineOperand</td>
+<td>operand</td>
+</tr>
+<tr class="row-even"><td>OptimizationRemarkEmitter</td>
+<td>remarker</td>
+</tr>
+<tr class="row-odd"><td>PreservedAnalyses</td>
+<td>analyses</td>
+</tr>
+<tr class="row-even"><td>PreservedAnalysesChecker</td>
+<td>checker</td>
+</tr>
+<tr class="row-odd"><td>TargetLowering</td>
+<td>lowering</td>
+</tr>
+<tr class="row-even"><td>TargetMachine</td>
+<td>machine</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="transition-options">
+<h2><a class="toc-backref" href="#id81">Transition Options</a><a class="headerlink" href="#transition-options" title="Permalink to this headline">¶</a></h2>
+<p>There are three main options for transitioning:</p>
+<ol class="arabic simple">
+<li>Keep the current coding standard</li>
+<li>Laissez faire</li>
+<li>Big bang</li>
+</ol>
+<div class="section" id="keep-the-current-coding-standard">
+<h3><a class="toc-backref" href="#id82">Keep the current coding standard</a><a class="headerlink" href="#keep-the-current-coding-standard" title="Permalink to this headline">¶</a></h3>
+<p>Proponents of keeping the current coding standard (i.e. not transitioning at
+all) question whether the cost of transition outweighs the benefit
+<a class="reference internal" href="#emersonconcern" id="id61">[EmersonConcern]</a> <a class="reference internal" href="#reamesconcern" id="id62">[ReamesConcern]</a> <a class="reference internal" href="#bradburyconcern" id="id63">[BradburyConcern]</a>.
+The costs are that <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">blame</span></code> will become less usable; and that merging the
+changes will be costly for downstream maintainers. See <a class="reference internal" href="#big-bang">Big bang</a> for potential
+mitigations.</p>
+</div>
+<div class="section" id="laissez-faire">
+<h3><a class="toc-backref" href="#id83">Laissez faire</a><a class="headerlink" href="#laissez-faire" title="Permalink to this headline">¶</a></h3>
+<p>The coding standard could allow both <code class="docutils literal notranslate"><span class="pre">CamelCase</span></code> and <code class="docutils literal notranslate"><span class="pre">camelBack</span></code> styles for
+variable names <a class="reference internal" href="#lattnertransition" id="id64">[LattnerTransition]</a>.</p>
+<p>A code review to implement this is at <a class="reference external" href="https://reviews.llvm.org/D57896">https://reviews.llvm.org/D57896</a>.</p>
+<div class="section" id="advantages">
+<h4><a class="toc-backref" href="#id84">Advantages</a><a class="headerlink" href="#advantages" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>Very easy to implement initially.</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="disadvantages">
+<h4><a class="toc-backref" href="#id85">Disadvantages</a><a class="headerlink" href="#disadvantages" title="Permalink to this headline">¶</a></h4>
+<blockquote>
+<div><ul class="simple">
+<li>Leads to inconsistency <a class="reference internal" href="#bradburyconcern" id="id65">[BradburyConcern]</a> <a class="reference internal" href="#aminiinconsistent" id="id66">[AminiInconsistent]</a>.</li>
+<li>Inconsistency means it will be hard to know at a guess what name a variable
+will have <a class="reference internal" href="#dasinconsistent" id="id67">[DasInconsistent]</a> <a class="reference internal" href="#carruthinconsistent" id="id68">[CarruthInconsistent]</a>.</li>
+<li>Some large-scale renaming may happen anyway, leading to its disadvantages
+without any mitigations.</li>
+</ul>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="big-bang">
+<h3><a class="toc-backref" href="#id86">Big bang</a><a class="headerlink" href="#big-bang" title="Permalink to this headline">¶</a></h3>
+<p>With this approach, variables will be renamed by an automated script in a series
+of large commits.</p>
+<p>The principle advantage of this approach is that it minimises the cost of
+inconsistency <a class="reference internal" href="#bradburytransition" id="id69">[BradburyTransition]</a> <a class="reference internal" href="#robinsontransition" id="id70">[RobinsonTransition]</a>.</p>
+<p>It goes against a policy of avoiding large-scale reformatting of existing code
+<a class="reference internal" href="#greenedistinguish" id="id71">[GreeneDistinguish]</a>.</p>
+<p>It has been suggested that LLD would be a good starter project for the renaming
+<a class="reference internal" href="#ueyama" id="id72">[Ueyama]</a>.</p>
+<div class="section" id="keeping-git-blame-usable">
+<h4><a class="toc-backref" href="#id87">Keeping git blame usable</a><a class="headerlink" href="#keeping-git-blame-usable" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">blame</span></code> (or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">annotate</span></code>) permits quickly identifying the commit that
+changed a given line in a file. After renaming variables, many lines will show
+as being changed by that one commit, requiring a further invocation of <code class="docutils literal notranslate"><span class="pre">git</span>
+<span class="pre">blame</span></code> to identify prior, more interesting commits <a class="reference internal" href="#greenegitblame" id="id73">[GreeneGitBlame]</a>
+<a class="reference internal" href="#ricciacronyms" id="id74">[RicciAcronyms]</a>.</p>
+<p><strong>Mitigation</strong>: <a class="reference external" href="https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-hyper-blame.html">git-hyper-blame</a>
+can ignore or âlook throughâ a given set of commits.
+A <code class="docutils literal notranslate"><span class="pre">.git-blame-ignore-revs</span></code> file identifying the variable renaming commits
+could be added to the LLVM git repository root directory.
+It is being <a class="reference external" href="https://public-inbox.org/git/20190324235020.49706-1-michael@platin.gs/">investigated</a>
+whether similar functionality could be added to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">blame</span></code> itself.</p>
+</div>
+<div class="section" id="minimising-cost-of-downstream-merges">
+<h4><a class="toc-backref" href="#id88">Minimising cost of downstream merges</a><a class="headerlink" href="#minimising-cost-of-downstream-merges" title="Permalink to this headline">¶</a></h4>
+<p>There are many forks of LLVM with downstream changes. Merging a large-scale
+renaming change could be difficult for the fork maintainers.</p>
+<p><strong>Mitigation</strong>: A large-scale renaming would be automated. A fork maintainer can
+merge from the commit immediately before the renaming, then apply the renaming
+script to their own branch. They can then merge again from the renaming commit,
+resolving all conflicts by choosing their own version. This could be tested on
+the <a class="reference internal" href="#sve" id="id75">[SVE]</a> fork.</p>
+</div>
+</div>
+</div>
+<div class="section" id="provisional-plan">
+<h2><a class="toc-backref" href="#id89">Provisional Plan</a><a class="headerlink" href="#provisional-plan" title="Permalink to this headline">¶</a></h2>
+<p>This is a provisional plan for the <a class="reference internal" href="#big-bang">Big bang</a> approach. It has not been agreed.</p>
+<ol class="arabic">
+<li><p class="first">Investigate improving <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">blame</span></code>. The extent to which it can be made to
+âlook throughâ commits may impact how big a change can be made.</p>
+</li>
+<li><p class="first">Write a script to expand acronyms.</p>
+</li>
+<li><p class="first">Experiment and perform dry runs of the various refactoring options.
+Results can be published in forks of the LLVM Git repository.</p>
+</li>
+<li><p class="first">Consider the evidence and agree on the new policy.</p>
+</li>
+<li><p class="first">Agree & announce a date for the renaming of the starter project (LLD).</p>
+</li>
+<li><p class="first">Update the <a class="reference external" href="../CodingStandards.html">policy page</a>. This will explain the
+old and new rules and which projects each applies to.</p>
+</li>
+<li><p class="first">Refactor the starter project in two commits:</p>
+<ol class="arabic">
+<li><p class="first">Add or change the projectâs .clang-tidy to reflect the agreed rules.
+(This is in a separate commit to enable the merging process described in
+<a class="reference internal" href="#minimising-cost-of-downstream-merges">Minimising cost of downstream merges</a>).
+Also update the project list on the policy page.</p>
+</li>
+<li><p class="first">Apply <code class="docutils literal notranslate"><span class="pre">clang-tidy</span></code> to the projectâs files, with only the
+<code class="docutils literal notranslate"><span class="pre">readability-identifier-naming</span></code> rules enabled. <code class="docutils literal notranslate"><span class="pre">clang-tidy</span></code> will also
+reformat the affected lines according to the rules in <code class="docutils literal notranslate"><span class="pre">.clang-format</span></code>.
+It is anticipated that this will be a good dog-fooding opportunity for
+clang-tidy, and bugs should be fixed in the process, likely including:</p>
+<blockquote>
+<div><ul class="simple">
+<li><a class="reference external" href="https://bugs.llvm.org/show_bug.cgi?id=41119">readability-identifier-naming incorrectly fixes lambda capture</a>.</li>
+<li><a class="reference external" href="https://bugs.llvm.org/show_bug.cgi?id=41120">readability-identifier-naming incorrectly fixes variables which
+become keywords</a>.</li>
+<li><a class="reference external" href="https://bugs.llvm.org/show_bug.cgi?id=41122">readability-identifier-naming misses fixing member variables in
+destructor</a>.</li>
+</ul>
+</div></blockquote>
+</li>
+</ol>
+</li>
+<li><p class="first">Gather feedback and refine the process as appropriate.</p>
+</li>
+<li><p class="first">Apply the process to the following projects, with a suitable delay between
+each (at least 4 weeks after the first change, at least 2 weeks subsequently)
+to allow gathering further feedback.
+This list should exclude projects that must adhere to an externally defined
+standard e.g. libcxx.
+The list is roughly in chronological order of renaming.
+Some items may not make sense to rename individually - it is expected that
+this list will change following experimentation:</p>
+<ul class="simple">
+<li>TableGen</li>
+<li>llvm/tools</li>
+<li>clang-tools-extra</li>
+<li>clang</li>
+<li>ARM backend</li>
+<li>AArch64 backend</li>
+<li>AMDGPU backend</li>
+<li>ARC backend</li>
+<li>AVR backend</li>
+<li>BPF backend</li>
+<li>Hexagon backend</li>
+<li>Lanai backend</li>
+<li>MIPS backend</li>
+<li>NVPTX backend</li>
+<li>PowerPC backend</li>
+<li>RISC-V backend</li>
+<li>Sparc backend</li>
+<li>SystemZ backend</li>
+<li>WebAssembly backend</li>
+<li>X86 backend</li>
+<li>XCore backend</li>
+<li>libLTO</li>
+<li>Debug Information</li>
+<li>Remainder of llvm</li>
+<li>compiler-rt</li>
+<li>libunwind</li>
+<li>openmp</li>
+<li>parallel-libs</li>
+<li>polly</li>
+<li>lldb</li>
+</ul>
+</li>
+<li><p class="first">Remove the old variable name rule from the policy page.</p>
+</li>
+<li><p class="first">Repeat many of the steps in the sequence, using a script to expand acronyms.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="references">
+<h2><a class="toc-backref" href="#id90">References</a><a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
+<table class="docutils citation" frame="void" id="lldb" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[LLDB]</td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id22">2</a>, <a class="fn-backref" href="#id46">3</a>)</em> LLDB Coding Conventions <a class="reference external" href="https://llvm.org/svn/llvm-project/lldb/branches/release_39/www/lldb-coding-conventions.html">https://llvm.org/svn/llvm-project/lldb/branches/release_39/www/lldb-coding-conventions.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="google" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[Google]</td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id23">2</a>, <a class="fn-backref" href="#id51">3</a>)</em> Google C++ Style Guide <a class="reference external" href="https://google.github.io/styleguide/cppguide.html#Variable_Names">https://google.github.io/styleguide/cppguide.html#Variable_Names</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="webkit" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[WebKit]</td><td><em>(<a class="fn-backref" href="#id4">1</a>, <a class="fn-backref" href="#id19">2</a>, <a class="fn-backref" href="#id47">3</a>)</em> WebKit Code Style Guidelines <a class="reference external" href="https://webkit.org/code-style-guidelines/#names">https://webkit.org/code-style-guidelines/#names</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="qt" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[Qt]</td><td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref" href="#id20">2</a>)</em> Qt Coding Style <a class="reference external" href="https://wiki.qt.io/Qt_Coding_Style#Declaring_variables">https://wiki.qt.io/Qt_Coding_Style#Declaring_variables</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="rust" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[Rust]</td><td><em>(<a class="fn-backref" href="#id6">1</a>, <a class="fn-backref" href="#id24">2</a>)</em> Rust naming conventions <a class="reference external" href="https://doc.rust-lang.org/1.0.0/style/style/naming/README.html">https://doc.rust-lang.org/1.0.0/style/style/naming/README.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="swift" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[Swift]</td><td><em>(<a class="fn-backref" href="#id7">1</a>, <a class="fn-backref" href="#id21">2</a>)</em> Swift API Design Guidelines <a class="reference external" href="https://swift.org/documentation/api-design-guidelines/#general-conventions">https://swift.org/documentation/api-design-guidelines/#general-conventions</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="python" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[Python]</td><td><em>(<a class="fn-backref" href="#id8">1</a>, <a class="fn-backref" href="#id25">2</a>, <a class="fn-backref" href="#id52">3</a>)</em> Style Guide for Python Code <a class="reference external" href="https://www.python.org/dev/peps/pep-0008/#function-and-variable-names">https://www.python.org/dev/peps/pep-0008/#function-and-variable-names</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="mozilla" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id50">[Mozilla]</a></td><td>Mozilla Coding style: Prefixes <a class="reference external" href="https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style#Prefixes">https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style#Prefixes</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="sve" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id75">[SVE]</a></td><td>LLVM with support for SVE <a class="reference external" href="https://github.com/ARM-software/LLVM-SVE">https://github.com/ARM-software/LLVM-SVE</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="aminiinconsistent" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id66">[AminiInconsistent]</a></td><td>Mehdi Amini, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130329.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130329.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="arsenaultagree" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id10">[ArsenaultAgree]</a></td><td>Matt Arsenault, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/129934.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/129934.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="beylsdistinguish" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id49">[BeylsDistinguish]</a></td><td>Kristof Beyls, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130292.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130292.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="bradburyconcern" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[BradburyConcern]</td><td><em>(<a class="fn-backref" href="#id63">1</a>, <a class="fn-backref" href="#id65">2</a>)</em> Alex Bradbury, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130266.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130266.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="bradburytransition" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id69">[BradburyTransition]</a></td><td>Alex Bradbury, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130388.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130388.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="carruthacronym" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[CarruthAcronym]</td><td><em>(<a class="fn-backref" href="#id13">1</a>, <a class="fn-backref" href="#id54">2</a>, <a class="fn-backref" href="#id57">3</a>)</em> Chandler Carruth, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130313.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130313.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="carruthcamelback" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[CarruthCamelBack]</td><td><em>(<a class="fn-backref" href="#id31">1</a>, <a class="fn-backref" href="#id34">2</a>)</em> Chandler Carruth, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130214.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130214.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="carruthdistinguish" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id41">[CarruthDistinguish]</a></td><td>Chandler Carruth, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130310.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130310.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="carruthfunction" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id27">[CarruthFunction]</a></td><td>Chandler Carruth, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130309.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130309.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="carruthinconsistent" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id68">[CarruthInconsistent]</a></td><td>Chandler Carruth, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130312.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130312.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="carruthlower" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id33">[CarruthLower]</a></td><td>Chandler Carruth, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130430.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130430.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="dasinconsistent" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id67">[DasInconsistent]</a></td><td>Sanjoy Das, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130304.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130304.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="denisovcamelback" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[DenisovCamelBack]</td><td><em>(<a class="fn-backref" href="#id18">1</a>, <a class="fn-backref" href="#id28">2</a>)</em> Alex Denisov, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130179.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130179.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="emersonconcern" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id61">[EmersonConcern]</a></td><td>Amara Emerson, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/129894.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/129894.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="greenedistinguish" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[GreeneDistinguish]</td><td><em>(<a class="fn-backref" href="#id44">1</a>, <a class="fn-backref" href="#id60">2</a>, <a class="fn-backref" href="#id71">3</a>)</em> David Greene, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130425.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130425.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="greenegitblame" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id73">[GreeneGitBlame]</a></td><td>David Greene, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130228.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130228.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="hendersonprefix" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id45">[HendersonPrefix]</a></td><td>James Henderson, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130465.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130465.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="hahnledistinguish" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id43">[HähnleDistinguish]</a></td><td>Nicolai Hähnle, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/129923.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/129923.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="ivanovicdistinguish" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[IvanovicDistinguish]</td><td><em>(<a class="fn-backref" href="#id30">1</a>, <a class="fn-backref" href="#id40">2</a>, <a class="fn-backref" href="#id48">3</a>)</em> Nemanja Ivanovic, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130249.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130249.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="jonesdistinguish" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id39">[JonesDistinguish]</a></td><td>JD Jones, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/129926.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/129926.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="lattneracronym" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id59">[LattnerAcronym]</a></td><td>Chris Lattner, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130353.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130353.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="lattneragree" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id9">[LattnerAgree]</a></td><td>Chris Latter, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/129907.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/129907.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="lattnerfunction" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[LattnerFunction]</td><td><em>(<a class="fn-backref" href="#id26">1</a>, <a class="fn-backref" href="#id29">2</a>)</em> Chris Lattner, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130630.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130630.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="lattnerlower" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id36">[LattnerLower]</a></td><td>Chris Lattner, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130629.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130629.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="lattnertransition" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id64">[LattnerTransition]</a></td><td>Chris Lattner, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130355.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130355.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="malyutindistinguish" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[MalyutinDistinguish]</td><td><em>(<a class="fn-backref" href="#id12">1</a>, <a class="fn-backref" href="#id42">2</a>)</em> Danila Malyutin, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130320.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130320.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="parzyszekacronym" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[ParzyszekAcronym]</td><td><em>(<a class="fn-backref" href="#id56">1</a>, <a class="fn-backref" href="#id58">2</a>)</em> Krzysztof Parzyszek, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130306.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130306.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="parzyszekacronym2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id15">[ParzyszekAcronym2]</a></td><td>Krzysztof Parzyszek, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130323.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130323.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="parzyszekdistinguish" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id53">[ParzyszekDistinguish]</a></td><td>Krzysztof Parzyszek, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/129941.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/129941.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="picusacronym" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[PicusAcronym]</td><td><em>(<a class="fn-backref" href="#id14">1</a>, <a class="fn-backref" href="#id55">2</a>)</em> Diana Picus, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130318.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130318.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="reamesconcern" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id62">[ReamesConcern]</a></td><td>Philip Reames, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130181.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130181.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="ricciacronyms" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[RicciAcronyms]</td><td><em>(<a class="fn-backref" href="#id16">1</a>, <a class="fn-backref" href="#id74">2</a>)</em> Bruno Ricci, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130328.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130328.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="robinsonagree" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id11">[RobinsonAgree]</a></td><td>Paul Robinson, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130111.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130111.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="robinsondistinguish" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id37">[RobinsonDistinguish]</a></td><td>Paul Robinson, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/129920.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/129920.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="robinsondistinguish2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id38">[RobinsonDistinguish2]</a></td><td>Paul Robinson, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130229.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130229.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="robinsontransition" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id70">[RobinsonTransition]</a></td><td>Paul Robinson, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130415.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130415.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="turnercamelback" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id32">[TurnerCamelBack]</a></td><td>Zachary Turner, <a class="reference external" href="https://reviews.llvm.org/D57896#1402264">https://reviews.llvm.org/D57896#1402264</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="turnerlldb" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id35">[TurnerLLDB]</a></td><td>Zachary Turner, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130213.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130213.html</a></td></tr>
+</tbody>
+</table>
+<table class="docutils citation" frame="void" id="ueyama" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id72">[Ueyama]</a></td><td>Rui Ueyama, <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-February/130435.html">http://lists.llvm.org/pipermail/llvm-dev/2019-February/130435.html</a></td></tr>
+</tbody>
+</table>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="TestSuite.html" title="Test-Suite Extentions"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-07-10.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/Proposals/VectorizationPlan.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/Proposals/VectorizationPlan.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/Proposals/VectorizationPlan.html (added)
+++ www-releases/trunk/8.0.1/docs/Proposals/VectorizationPlan.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,375 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Vectorization Plan — LLVM 8 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" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Writing an LLVM Backend" href="../WritingAnLLVMBackend.html" />
+ <link rel="prev" title="Auto-Vectorization in LLVM" href="../Vectorizers.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../Vectorizers.html" title="Auto-Vectorization in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="../Vectorizers.html" accesskey="U">Auto-Vectorization in LLVM</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="vectorization-plan">
+<h1>Vectorization Plan<a class="headerlink" href="#vectorization-plan" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#abstract" id="id20">Abstract</a></li>
+<li><a class="reference internal" href="#high-level-design" id="id21">High-level Design</a><ul>
+<li><a class="reference internal" href="#vectorization-workflow" id="id22">Vectorization Workflow</a></li>
+<li><a class="reference internal" href="#design-guidelines" id="id23">Design Guidelines</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#definitions" id="id24">Definitions</a></li>
+<li><a class="reference internal" href="#the-planning-process-and-vplan-roadmap" id="id25">The Planning Process and VPlan Roadmap</a><ul>
+<li><a class="reference internal" href="#related-llvm-components" id="id26">Related LLVM components</a></li>
+<li><a class="reference internal" href="#references" id="id27">References</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="abstract">
+<h2><a class="toc-backref" href="#id20">Abstract</a><a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>The vectorization transformation can be rather complicated, involving several
+potential alternatives, especially for outer-loops <a class="footnote-reference" href="#id11" id="id1">[1]</a> but also possibly for
+innermost loops. These alternatives may have significant performance impact,
+both positive and negative. A cost model is therefore employed to identify the
+best alternative, including the alternative of avoiding any transformation
+altogether.</p>
+<p>The Vectorization Plan is an explicit model for describing vectorization
+candidates. It serves for both optimizing candidates including estimating their
+cost reliably, and for performing their final translation into IR. This
+facilitates dealing with multiple vectorization candidates.</p>
+</div>
+<div class="section" id="high-level-design">
+<h2><a class="toc-backref" href="#id21">High-level Design</a><a class="headerlink" href="#high-level-design" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="vectorization-workflow">
+<h3><a class="toc-backref" href="#id22">Vectorization Workflow</a><a class="headerlink" href="#vectorization-workflow" title="Permalink to this headline">¶</a></h3>
+<p>VPlan-based vectorization involves three major steps, taking a âscenario-based
+approachâ to vectorization planning:</p>
+<ol class="arabic simple">
+<li>Legal Step: check if a loop can be legally vectorized; encode constraints and
+artifacts if so.</li>
+<li>Plan Step:<ol class="loweralpha">
+<li>Build initial VPlans following the constraints and decisions taken by
+Legal Step 1, and compute their cost.</li>
+<li>Apply optimizations to the VPlans, possibly forking additional VPlans.
+Prune sub-optimal VPlans having relatively high cost.</li>
+</ol>
+</li>
+<li>Execute Step: materialize the best VPlan. Note that this is the only step
+that modifies the IR.</li>
+</ol>
+</div>
+<div class="section" id="design-guidelines">
+<h3><a class="toc-backref" href="#id23">Design Guidelines</a><a class="headerlink" href="#design-guidelines" title="Permalink to this headline">¶</a></h3>
+<p>In what follows, the term âinput IRâ refers to code that is fed into the
+vectorizer whereas the term âoutput IRâ refers to code that is generated by the
+vectorizer. The output IR contains code that has been vectorized or âwidenedâ
+according to a loop Vectorization Factor (VF), and/or loop unroll-and-jammed
+according to an Unroll Factor (UF).
+The design of VPlan follows several high-level guidelines:</p>
+<ol class="arabic simple">
+<li>Analysis-like: building and manipulating VPlans must not modify the input IR.
+In particular, if the best option is not to vectorize at all, the
+vectorization process terminates before reaching Step 3, and compilation
+should proceed as if VPlans had not been built.</li>
+<li>Align Cost & Execute: each VPlan must support both estimating the cost and
+generating the output IR code, such that the cost estimation evaluates the
+to-be-generated code reliably.</li>
+<li>Support vectorizing additional constructs:<ol class="loweralpha">
+<li>Outer-loop vectorization. In particular, VPlan must be able to model the
+control-flow of the output IR which may include multiple basic-blocks and
+nested loops.</li>
+<li>SLP vectorization.</li>
+<li>Combinations of the above, including nested vectorization: vectorizing
+both an inner loop and an outer-loop at the same time (each with its own
+VF and UF), mixed vectorization: vectorizing a loop with SLP patterns
+inside <a class="footnote-reference" href="#id14" id="id2">[4]</a>, (re)vectorizing input IR containing vector code.</li>
+<li>Function vectorization <a class="footnote-reference" href="#id12" id="id3">[2]</a>.</li>
+</ol>
+</li>
+<li>Support multiple candidates efficiently. In particular, similar candidates
+related to a range of possible VFâs and UFâs must be represented efficiently.
+Potential versioning needs to be supported efficiently.</li>
+<li>Support vectorizing idioms, such as interleaved groups of strided loads or
+stores. This is achieved by modeling a sequence of output instructions using
+a âRecipeâ, which is responsible for computing its cost and generating its
+code.</li>
+<li>Encapsulate Single-Entry Single-Exit regions (SESE). During vectorization
+such regions may need to be, for example, predicated and linearized, or
+replicated VF*UF times to handle scalarized and predicated instructions.
+Innerloops are also modelled as SESE regions.</li>
+<li>Support instruction-level analysis and transformation, as part of Planning
+Step 2.b: During vectorization instructions may need to be traversed, moved,
+replaced by other instructions or be created. For example, vector idiom
+detection and formation involves searching for and optimizing instruction
+patterns.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="definitions">
+<h2><a class="toc-backref" href="#id24">Definitions</a><a class="headerlink" href="#definitions" title="Permalink to this headline">¶</a></h2>
+<p>The low-level design of VPlan comprises of the following classes.</p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name" colspan="2">LoopVectorizationPlanner:</th></tr>
+<tr class="field-odd field"><td> </td><td class="field-body">A LoopVectorizationPlanner is designed to handle the vectorization of a loop
+or a loop nest. It can construct, optimize and discard one or more VPlans,
+each VPlan modelling a distinct way to vectorize the loop or the loop nest.
+Once the best VPlan is determined, including the best VF and UF, this VPlan
+drives the generation of output IR.</td>
+</tr>
+<tr class="field-even field"><th class="field-name">VPlan:</th><td class="field-body">A model of a vectorized candidate for a given input IR loop or loop nest. This
+candidate is represented using a Hierarchical CFG. VPlan supports estimating
+the cost and driving the generation of the output IR code it represents.</td>
+</tr>
+<tr class="field-odd field"><th class="field-name" colspan="2">Hierarchical CFG:</th></tr>
+<tr class="field-odd field"><td> </td><td class="field-body">A control-flow graph whose nodes are basic-blocks or Hierarchical CFGâs. The
+Hierarchical CFG data structure is similar to the Tile Tree <a class="footnote-reference" href="#id15" id="id4">[5]</a>, where
+cross-Tile edges are lifted to connect Tiles instead of the original
+basic-blocks as in Sharir <a class="footnote-reference" href="#id16" id="id5">[6]</a>, promoting the Tile encapsulation. The terms
+Region and Block are used rather than Tile <a class="footnote-reference" href="#id15" id="id6">[5]</a> to avoid confusion with loop
+tiling.</td>
+</tr>
+<tr class="field-even field"><th class="field-name">VPBlockBase:</th><td class="field-body">The building block of the Hierarchical CFG. A pure-virtual base-class of
+VPBasicBlock and VPRegionBlock, see below. VPBlockBase models the hierarchical
+control-flow relations with other VPBlocks. Note that in contrast to the IR
+BasicBlock, a VPBlockBase models its control-flow successors and predecessors
+directly, rather than through a Terminator branch or through predecessor
+branches that âuseâ the VPBlockBase.</td>
+</tr>
+<tr class="field-odd field"><th class="field-name">VPBasicBlock:</th><td class="field-body">VPBasicBlock is a subclass of VPBlockBase, and serves as the leaves of the
+Hierarchical CFG. It represents a sequence of output IR instructions that will
+appear consecutively in an output IR basic-block. The instructions of this
+basic-block originate from one or more VPBasicBlocks. VPBasicBlock holds a
+sequence of zero or more VPRecipes that model the cost and generation of the
+output IR instructions.</td>
+</tr>
+<tr class="field-even field"><th class="field-name">VPRegionBlock:</th><td class="field-body">VPRegionBlock is a subclass of VPBlockBase. It models a collection of
+VPBasicBlocks and VPRegionBlocks which form a SESE subgraph of the output IR
+CFG. A VPRegionBlock may indicate that its contents are to be replicated a
+constant number of times when output IR is generated, effectively representing
+a loop with constant trip-count that will be completely unrolled. This is used
+to support scalarized and predicated instructions with a single model for
+multiple candidate VFâs and UFâs.</td>
+</tr>
+<tr class="field-odd field"><th class="field-name">VPRecipeBase:</th><td class="field-body">A pure-virtual base class modeling a sequence of one or more output IR
+instructions, possibly based on one or more input IR instructions. These
+input IR instructions are referred to as âIngredientsâ of the Recipe. A Recipe
+may specify how its ingredients are to be transformed to produce the output IR
+instructions; e.g., cloned once, replicated multiple times or widened
+according to selected VF.</td>
+</tr>
+<tr class="field-even field"><th class="field-name">VPValue:</th><td class="field-body">The base of VPlanâs def-use relations class hierarchy. When instantiated, it
+models a constant or a live-in Value in VPlan. It has users, which are of type
+VPUser, but no operands.</td>
+</tr>
+<tr class="field-odd field"><th class="field-name">VPUser:</th><td class="field-body">A VPValue representing a general vertex in the def-use graph of VPlan. It has
+operands which are of type VPValue. When instantiated, it represents a
+live-out Instruction that exists outside VPlan. VPUser is similar in some
+aspects to LLVMâs User class.</td>
+</tr>
+<tr class="field-even field"><th class="field-name">VPInstruction:</th><td class="field-body">A VPInstruction is both a VPRecipe and a VPUser. It models a single
+VPlan-level instruction to be generated if the VPlan is executed, including
+its opcode and possibly additional characteristics. It is the basis for
+writing instruction-level analyses and optimizations in VPlan as creating,
+replacing or moving VPInstructions record both def-use and scheduling
+decisions. VPInstructions also extend LLVM IRâs opcodes with idiomatic
+operations that enrich the Vectorizerâs semantics.</td>
+</tr>
+<tr class="field-odd field"><th class="field-name" colspan="2">VPTransformState:</th></tr>
+<tr class="field-odd field"><td> </td><td class="field-body">Stores information used for generating output IR, passed from
+LoopVectorizationPlanner to its selected VPlan for execution, and used to pass
+additional information down to VPBlocks and VPRecipes.</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="the-planning-process-and-vplan-roadmap">
+<h2><a class="toc-backref" href="#id25">The Planning Process and VPlan Roadmap</a><a class="headerlink" href="#the-planning-process-and-vplan-roadmap" title="Permalink to this headline">¶</a></h2>
+<p>Transforming the Loop Vectorizer to use VPlan follows a staged approach. First,
+VPlan is used to record the final vectorization decisions, and to execute them:
+the Hierarchical CFG models the planned control-flow, and Recipes capture
+decisions taken inside basic-blocks. Next, VPlan will be used also as the basis
+for taking these decisions, effectively turning them into a series of
+VPlan-to-VPlan algorithms. Finally, VPlan will support the planning process
+itself including cost-based analyses for making these decisions, to fully
+support compositional and iterative decision making.</p>
+<p>Some decisions are local to an instruction in the loop, such as whether to widen
+it into a vector instruction or replicate it, keeping the generated instructions
+in place. Other decisions, however, involve moving instructions, replacing them
+with other instructions, and/or introducing new instructions. For example, a
+cast may sink past a later instruction and be widened to handle first-order
+recurrence; an interleave group of strided gathers or scatters may effectively
+move to one place where they are replaced with shuffles and a common wide vector
+load or store; new instructions may be introduced to compute masks, shuffle the
+elements of vectors, and pack scalar values into vectors or vice-versa.</p>
+<p>In order for VPlan to support making instruction-level decisions and analyses,
+it needs to model the relevant instructions along with their def/use relations.
+This too follows a staged approach: first, the new instructions that compute
+masks are modeled as VPInstructions, along with their induced def/use subgraph.
+This effectively models masks in VPlan, facilitating VPlan-based predication.
+Next, the logic embedded within each Recipe for generating its instructions at
+VPlan execution time, will instead take part in the planning process by modeling
+them as VPInstructions. Finally, only logic that applies to instructions as a
+group will remain in Recipes, such as interleave groups and potentially other
+idiom groups having synergistic cost.</p>
+<div class="section" id="related-llvm-components">
+<h3><a class="toc-backref" href="#id26">Related LLVM components</a><a class="headerlink" href="#related-llvm-components" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>SLP Vectorizer: one can compare the VPlan model with LLVMâs existing SLP
+tree, where TSLP <a class="footnote-reference" href="#id13" id="id7">[3]</a> adds Plan Step 2.b.</li>
+<li>RegionInfo: one can compare VPlanâs H-CFG with the Region Analysis as used by
+Polly <a class="footnote-reference" href="#id17" id="id8">[7]</a>.</li>
+<li>Loop Vectorizer: the Vectorization Plan aims to upgrade the infrastructure of
+the Loop Vectorizer and extend it to handle outer loops <a class="footnote-reference" href="#id18" id="id9">[8]</a>, <a class="footnote-reference" href="#id19" id="id10">[9]</a>.</li>
+</ol>
+</div>
+<div class="section" id="references">
+<h3><a class="toc-backref" href="#id27">References</a><a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h3>
+<table class="docutils footnote" frame="void" id="id11" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>âOuter-loop vectorization: revisited for short SIMD architecturesâ, Dorit
+Nuzman and Ayal Zaks, PACT 2008.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id12" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id3">[2]</a></td><td>âProposal for function vectorization and loop vectorization with function
+callsâ, Xinmin Tian, [<a class="reference external" href="http://lists.llvm.org/pipermail/cfe-dev/2016-March/047732.html">cfe-dev</a>].,
+March 2, 2016.
+See also <a class="reference external" href="https://reviews.llvm.org/D22792">review</a>.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id13" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id7">[3]</a></td><td>âThrottling Automatic Vectorization: When Less is Moreâ, Vasileios
+Porpodas and Tim Jones, PACT 2015 and LLVM Developersâ Meeting 2015.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id14" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[4]</a></td><td>âExploiting mixed SIMD parallelism by reducing data reorganization
+overheadâ, Hao Zhou and Jingling Xue, CGO 2016.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id15" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label">[5]</td><td><em>(<a class="fn-backref" href="#id4">1</a>, <a class="fn-backref" href="#id6">2</a>)</em> âRegister Allocation via Hierarchical Graph Coloringâ, David Callahan and
+Brian Koblenz, PLDI 1991</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id16" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id5">[6]</a></td><td>âStructural analysis: A new approach to flow analysis in optimizing
+compilersâ, M. Sharir, Journal of Computer Languages, Jan. 1980</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id17" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id8">[7]</a></td><td>âEnabling Polyhedral Optimizations in LLVMâ, Tobias Grosser, Diploma
+thesis, 2011.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id18" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id9">[8]</a></td><td>âIntroducing VPlan to the Loop Vectorizerâ, Gil Rapaport and Ayal Zaks,
+European LLVM Developersâ Meeting 2017.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id19" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id10">[9]</a></td><td>âExtending LoopVectorizer: OpenMP4.5 SIMD and Outer Loop
+Auto-Vectorizationâ, Intel Vectorizer Team, LLVM Developersâ Meeting 2016.</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../WritingAnLLVMBackend.html" title="Writing an LLVM Backend"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../Vectorizers.html" title="Auto-Vectorization in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="../Vectorizers.html" >Auto-Vectorization in LLVM</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/ReleaseNotes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/ReleaseNotes.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/ReleaseNotes.html (added)
+++ www-releases/trunk/8.0.1/docs/ReleaseNotes.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,396 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>LLVM 8.0.0 Release Notes — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVMâs Analysis and Transform Passes" href="Passes.html" />
+ <link rel="prev" title="5. Building a JIT: Remote-JITing â Process Isolation and Laziness at a Distance" href="tutorial/BuildingAJIT5.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" role="navigation" aria-label="related navigation">
+ <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/BuildingAJIT5.html" title="5. Building a JIT: Remote-JITing â Process Isolation and Laziness at a Distance"
+ 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" role="main">
+
+ <div class="section" id="llvm-8-0-0-release-notes">
+<h1>LLVM 8.0.0 Release Notes<a class="headerlink" href="#llvm-8-0-0-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="id1">Introduction</a></li>
+<li><a class="reference internal" href="#minimum-required-compiler-version" id="id2">Minimum Required Compiler Version</a></li>
+<li><a class="reference internal" href="#known-issues" id="id3">Known Issues</a></li>
+<li><a class="reference internal" href="#non-comprehensive-list-of-changes-in-this-release" id="id4">Non-comprehensive list of changes in this release</a><ul>
+<li><a class="reference internal" href="#changes-to-the-llvm-ir" id="id5">Changes to the LLVM IR</a></li>
+<li><a class="reference internal" href="#changes-to-the-jit-apis" id="id6">Changes to the JIT APIs</a></li>
+<li><a class="reference internal" href="#changes-to-the-c-apis" id="id7">Changes to the C++ APIs</a></li>
+<li><a class="reference internal" href="#changes-to-the-aarch64-target" id="id8">Changes to the AArch64 Target</a></li>
+<li><a class="reference internal" href="#changes-to-the-hexagon-target" id="id9">Changes to the Hexagon Target</a></li>
+<li><a class="reference internal" href="#changes-to-the-mips-target" id="id10">Changes to the MIPS Target</a></li>
+<li><a class="reference internal" href="#changes-to-the-powerpc-target" id="id11">Changes to the PowerPC Target</a></li>
+<li><a class="reference internal" href="#changes-to-the-systemz-target" id="id12">Changes to the SystemZ Target</a></li>
+<li><a class="reference internal" href="#changes-to-the-x86-target" id="id13">Changes to the X86 Target</a></li>
+<li><a class="reference internal" href="#changes-to-the-webassembly-target" id="id14">Changes to the WebAssembly Target</a></li>
+<li><a class="reference internal" href="#changes-to-the-nios2-target" id="id15">Changes to the Nios2 Target</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#changes-to-lldb" id="id16">Changes to LLDB</a></li>
+<li><a class="reference internal" href="#external-open-source-projects-using-llvm-8" id="id17">External Open Source Projects Using LLVM 8</a><ul>
+<li><a class="reference internal" href="#ldc-the-llvm-based-d-compiler" id="id18">LDC - the LLVM-based D compiler</a></li>
+<li><a class="reference internal" href="#open-dylan-compiler" id="id19">Open Dylan Compiler</a></li>
+<li><a class="reference internal" href="#zig-programming-language" id="id20">Zig Programming Language</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#additional-information" id="id21">Additional Information</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>This document contains the release notes for the LLVM Compiler Infrastructure,
+release 8.0.0. 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="https://releases.llvm.org/">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="https://llvm.org/">main LLVM web site</a>. If you
+have questions or comments, the <a class="reference external" href="https://lists.llvm.org/mailman/listinfo/llvm-dev">LLVM Developerâs Mailing List</a> is a good place to send
+them.</p>
+</div>
+<div class="section" id="minimum-required-compiler-version">
+<h2><a class="toc-backref" href="#id2">Minimum Required Compiler Version</a><a class="headerlink" href="#minimum-required-compiler-version" title="Permalink to this headline">¶</a></h2>
+<p>As <a class="reference external" href="https://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html">discussed on the mailing list</a>,
+building LLVM will soon require more recent toolchains as follows:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="76%" />
+<col width="24%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>Clang</td>
+<td>3.5</td>
+</tr>
+<tr class="row-even"><td>Apple Clang</td>
+<td>6.0</td>
+</tr>
+<tr class="row-odd"><td>GCC</td>
+<td>5.1</td>
+</tr>
+<tr class="row-even"><td>Visual Studio</td>
+<td>2017</td>
+</tr>
+</tbody>
+</table>
+<p>A new CMake check when configuring LLVM provides a soft-error if your
+toolchain will become unsupported soon. You can opt out of the soft-error by
+setting the <code class="docutils literal notranslate"><span class="pre">LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN</span></code> CMake variable to
+<code class="docutils literal notranslate"><span class="pre">ON</span></code>.</p>
+</div>
+<div class="section" id="known-issues">
+<h2><a class="toc-backref" href="#id3">Known Issues</a><a class="headerlink" href="#known-issues" title="Permalink to this headline">¶</a></h2>
+<p>These are issues that couldnât be fixed before the release. See the bug reports
+for the latest status.</p>
+<ul class="simple">
+<li><a class="reference external" href="https://llvm.org/pr40547">PR40547</a> Clang gets miscompiled by trunk GCC.</li>
+<li><a class="reference external" href="https://llvm.org/pr40761">PR40761</a> âasan-dynamicâ doesnât work on FreeBSD.</li>
+</ul>
+</div>
+<div class="section" id="non-comprehensive-list-of-changes-in-this-release">
+<h2><a class="toc-backref" href="#id4">Non-comprehensive list of changes in this release</a><a class="headerlink" href="#non-comprehensive-list-of-changes-in-this-release" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>The <strong>llvm-cov</strong> tool can now export lcov trace files using the
+<cite>-format=lcov</cite> option of the <cite>export</cite> command.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">add_llvm_loadable_module</span></code> CMake macro has been removed. The
+<code class="docutils literal notranslate"><span class="pre">add_llvm_library</span></code> macro with the <code class="docutils literal notranslate"><span class="pre">MODULE</span></code> argument now provides the same
+functionality. See <a class="reference external" href="WritingAnLLVMPass.html#setting-up-the-build-environment">Writing an LLVM Pass</a>.</li>
+<li>For MinGW, references to data variables that might need to be imported
+from a dll are accessed via a stub, to allow the linker to convert it to
+a dllimport if needed.</li>
+<li>Added support for labels as offsets in <code class="docutils literal notranslate"><span class="pre">.reloc</span></code> directive.</li>
+<li>Support for precise identification of X86 instructions with memory operands,
+by using debug information. This supports profile-driven cache prefetching.
+It is enabled with the <code class="docutils literal notranslate"><span class="pre">-x86-discriminate-memops</span></code> LLVM Flag.</li>
+<li>Support for profile-driven software cache prefetching on X86. This is part of
+a larger system, consisting of: an offline cache prefetches recommender,
+AutoFDO tooling, and LLVM. In this system, a binary compiled with
+<code class="docutils literal notranslate"><span class="pre">-x86-discriminate-memops</span></code> is run under the observation of the recommender.
+The recommender identifies certain memory access instructions by their binary
+file address, and recommends a prefetch of a specific type (NTA, T0, etc) be
+performed at a specified fixed offset from such an instructionâs memory
+operand. Next, this information needs to be converted to the AutoFDO syntax
+and the resulting profile may be passed back to the compiler with the LLVM
+flag <code class="docutils literal notranslate"><span class="pre">-prefetch-hints-file</span></code>, together with the exact same set of
+compilation parameters used for the original binary. More information is
+available in the <a class="reference external" href="https://lists.llvm.org/pipermail/llvm-dev/2018-November/127461.html">RFC</a>.</li>
+<li>Windows support for libFuzzer (x86_64).</li>
+</ul>
+<div class="section" id="changes-to-the-llvm-ir">
+<h3><a class="toc-backref" href="#id5">Changes to the LLVM IR</a><a class="headerlink" href="#changes-to-the-llvm-ir" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Function attribute <code class="docutils literal notranslate"><span class="pre">speculative_load_hardening</span></code> has been introduced to
+allow indicating that <a class="reference external" href="SpeculativeLoadHardening.html">Speculative Load Hardening</a> must be enabled for the function body.</li>
+</ul>
+</div>
+<div class="section" id="changes-to-the-jit-apis">
+<h3><a class="toc-backref" href="#id6">Changes to the JIT APIs</a><a class="headerlink" href="#changes-to-the-jit-apis" title="Permalink to this headline">¶</a></h3>
+<p>The ORC (On Request Compilation) JIT APIs have been updated to support
+concurrent compilation. The existing (non-concurrent) ORC layer classes and
+related APIs are deprecated, have been renamed with a âLegacyâ prefix (e.g.
+LegacyIRCompileLayer). The deprecated clasess will be removed in LLVM 9.</p>
+<p>An example JIT stack using the concurrent ORC APIs, called LLJIT, has been
+added (see include/llvm/ExecutionEngine/Orc/LLJIT.h). The lli tool has been
+updated to use LLJIT.</p>
+<p>MCJIT and ExecutionEngine continue to be supported, though ORC should be
+preferred for new projects.</p>
+</div>
+<div class="section" id="changes-to-the-c-apis">
+<h3><a class="toc-backref" href="#id7">Changes to the C++ APIs</a><a class="headerlink" href="#changes-to-the-c-apis" title="Permalink to this headline">¶</a></h3>
+<p>Three of the IR library methods related to debugging information for
+functions and methods have changed their prototypes:</p>
+<blockquote>
+<div>DIBuilder::createMethod
+DIBuilder::createFunction
+DIBuilder::createTempFunctionFwdDecl</div></blockquote>
+<p>In all cases, several individual parameters were removed, and replaced
+by a single âSPFlagsâ (subprogram flags) parameter. The individual
+parameters are: âisLocalToUnitâ; âisDefinitionâ; âisOptimizedâ; and
+for âcreateMethodâ, âVirtualityâ. The new âSPFlagsâ parameter has a
+default value equivalent to passing âfalseâ for the three âboolâ
+parameters, and zero (non-virtual) to the âVirtualityâ parameter. For
+any old-style API call that passed âtrueâ or a non-zero virtuality to
+these methods, you will need to substitute the correct âSPFlagsâ value.
+The helper method âDISubprogram::toSPFlags()â might be useful in making
+this conversion.</p>
+</div>
+<div class="section" id="changes-to-the-aarch64-target">
+<h3><a class="toc-backref" href="#id8">Changes to the AArch64 Target</a><a class="headerlink" href="#changes-to-the-aarch64-target" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Support for Speculative Load Hardening has been added.</li>
+<li>Initial support for the Tiny code model, where code and its statically
+defined symbols must live within 1MB of each other.</li>
+<li>Added support for the <code class="docutils literal notranslate"><span class="pre">.arch_extension</span></code> assembler directive, just like
+on ARM.</li>
+</ul>
+</div>
+<div class="section" id="changes-to-the-hexagon-target">
+<h3><a class="toc-backref" href="#id9">Changes to the Hexagon Target</a><a class="headerlink" href="#changes-to-the-hexagon-target" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Added support for Hexagon/HVX V66 ISA.</li>
+</ul>
+</div>
+<div class="section" id="changes-to-the-mips-target">
+<h3><a class="toc-backref" href="#id10">Changes to the MIPS Target</a><a class="headerlink" href="#changes-to-the-mips-target" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Improved support of GlobalISel instruction selection framework.</li>
+<li>Implemented emission of <code class="docutils literal notranslate"><span class="pre">R_MIPS_JALR</span></code> and <code class="docutils literal notranslate"><span class="pre">R_MICROMIPS_JALR</span></code>
+relocations. These relocations provide hints to a linker for optimization
+of jumps to protected symbols.</li>
+<li>ORC JIT has been supported for MIPS and MIPS64 architectures.</li>
+<li>Assembler now suggests alternative MIPS instruction mnemonics when
+an invalid one is specified.</li>
+<li>Improved support for MIPS N32 ABI.</li>
+<li>Added new instructions (<code class="docutils literal notranslate"><span class="pre">pll.ps</span></code>, <code class="docutils literal notranslate"><span class="pre">plu.ps</span></code>, <code class="docutils literal notranslate"><span class="pre">cvt.s.pu</span></code>,
+<code class="docutils literal notranslate"><span class="pre">cvt.s.pl</span></code>, <code class="docutils literal notranslate"><span class="pre">cvt.ps</span></code>, <code class="docutils literal notranslate"><span class="pre">sigrie</span></code>).</li>
+<li>Numerous bug fixes and code cleanups.</li>
+</ul>
+</div>
+<div class="section" id="changes-to-the-powerpc-target">
+<h3><a class="toc-backref" href="#id11">Changes to the PowerPC Target</a><a class="headerlink" href="#changes-to-the-powerpc-target" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Switched to non-PIC default</li>
+<li>Deprecated Darwin support</li>
+<li>Enabled Out-of-Order scheduling for P9</li>
+<li>Better overload rules for compatible vector type parameter</li>
+<li>Support constraint âwiâ, modifier âxâ and VSX registers in inline asm</li>
+<li>More <code class="docutils literal notranslate"><span class="pre">__float128</span></code> support</li>
+<li>Added new builtins like vector int128 <code class="docutils literal notranslate"><span class="pre">pack</span></code>/<code class="docutils literal notranslate"><span class="pre">unpack</span></code> and
+<code class="docutils literal notranslate"><span class="pre">stxvw4x.be</span></code>/<code class="docutils literal notranslate"><span class="pre">stxvd2x.be</span></code></li>
+<li>Provided significant improvements to the automatic vectorizer</li>
+<li>Code-gen improvements (especially for Power9)</li>
+<li>Fixed some long-standing bugs in the back end</li>
+<li>Added experimental prologue/epilogue improvements</li>
+<li>Enabled builtins tests in compiler-rt</li>
+<li>Add <code class="docutils literal notranslate"><span class="pre">___fixunstfti</span></code>/<code class="docutils literal notranslate"><span class="pre">floattitf</span></code> in compiler-rt to support conversion
+between IBM double-double and unsigned int128</li>
+<li>Disable randomized address space when running the sanitizers on Linux ppc64le</li>
+<li>Completed support in LLD for ELFv2</li>
+<li>Enabled llvm-exegesis latency mode for PPC</li>
+</ul>
+</div>
+<div class="section" id="changes-to-the-systemz-target">
+<h3><a class="toc-backref" href="#id12">Changes to the SystemZ Target</a><a class="headerlink" href="#changes-to-the-systemz-target" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>A number of bugs related to C/C++ language vector extension support were
+fixed: the <code class="docutils literal notranslate"><span class="pre">-mzvector</span></code> option now actually enables the <code class="docutils literal notranslate"><span class="pre">__vector</span></code> and
+<code class="docutils literal notranslate"><span class="pre">__bool</span></code> keywords, the <code class="docutils literal notranslate"><span class="pre">vec_step</span></code> intrinsic now works, and the
+<code class="docutils literal notranslate"><span class="pre">vec_insert_and_zero</span></code> and <code class="docutils literal notranslate"><span class="pre">vec_orc</span></code> intrinsics now generate correct code.</li>
+<li>The <code class="docutils literal notranslate"><span class="pre">__float128</span></code> keyword, which had been accidentally enabled in some
+earlier releases, is now no longer supported. On SystemZ, the <code class="docutils literal notranslate"><span class="pre">long</span> <span class="pre">double</span></code>
+data type itself already uses the IEEE 128-bit floating-point format.</li>
+<li>When the compiler inlines <code class="docutils literal notranslate"><span class="pre">strcmp</span></code> or <code class="docutils literal notranslate"><span class="pre">memcmp</span></code>, the generated code no
+longer returns <code class="docutils literal notranslate"><span class="pre">INT_MIN</span></code> as the negative result value under any
+circumstances.</li>
+<li>Various code-gen improvements, in particular related to improved
+auto-vectorization, inlining, and instruction scheduling.</li>
+</ul>
+</div>
+<div class="section" id="changes-to-the-x86-target">
+<h3><a class="toc-backref" href="#id13">Changes to the X86 Target</a><a class="headerlink" href="#changes-to-the-x86-target" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Machine model for AMD bdver2 (Piledriver) CPU was added. It is used to support
+instruction scheduling and other instruction cost heuristics.</li>
+<li>New AVX512F gather and scatter intrinsics were added that take a <X x i1> mask
+instead of a scalar integer. This removes the need for a bitcast in IR. The
+new intrinsics are named like the old intrinsics with <code class="docutils literal notranslate"><span class="pre">llvm.avx512.</span></code>
+replaced with <code class="docutils literal notranslate"><span class="pre">llvm.avx512.mask.</span></code>. The old intrinsics will be removed in a
+future release.</li>
+<li>Added <code class="docutils literal notranslate"><span class="pre">cascadelake</span></code> as a CPU name for -march. This is <code class="docutils literal notranslate"><span class="pre">skylake-avx512</span></code>
+with the addition of the <code class="docutils literal notranslate"><span class="pre">avx512vnni</span></code> instruction set.</li>
+<li>ADCX instruction will no longer be emitted. This instruction is rarely better
+than the legacy ADC instruction and just increased code size.</li>
+</ul>
+</div>
+<div class="section" id="changes-to-the-webassembly-target">
+<h3><a class="toc-backref" href="#id14">Changes to the WebAssembly Target</a><a class="headerlink" href="#changes-to-the-webassembly-target" title="Permalink to this headline">¶</a></h3>
+<p>The WebAssembly target is no longer âexperimentalâ! Itâs now built by default,
+rather than needing to be enabled with LLVM_EXPERIMENTAL_TARGETS_TO_BUILD.</p>
+<p>The object file format and core C ABI are now considered stable. That said,
+the object file format has an ABI versioning capability, and one anticipated
+use for it will be to add support for returning small structs as multiple
+return values, once the underlying WebAssembly platform itself supports it.
+Additionally, multithreading support is not yet included in the stable ABI.</p>
+</div>
+<div class="section" id="changes-to-the-nios2-target">
+<h3><a class="toc-backref" href="#id15">Changes to the Nios2 Target</a><a class="headerlink" href="#changes-to-the-nios2-target" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>The Nios2 target was removed from this release.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="changes-to-lldb">
+<h2><a class="toc-backref" href="#id16">Changes to LLDB</a><a class="headerlink" href="#changes-to-lldb" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>Printed source code is now syntax highlighted in the terminal (only for C
+languages).</li>
+<li>The expression command now supports tab completing expressions.</li>
+</ul>
+</div>
+<div class="section" id="external-open-source-projects-using-llvm-8">
+<h2><a class="toc-backref" href="#id17">External Open Source Projects Using LLVM 8</a><a class="headerlink" href="#external-open-source-projects-using-llvm-8" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="ldc-the-llvm-based-d-compiler">
+<h3><a class="toc-backref" href="#id18">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 ARM
+and PowerPC (32/64 bit). Ports to other architectures like AArch64 and MIPS64
+are underway.</p>
+</div>
+<div class="section" id="open-dylan-compiler">
+<h3><a class="toc-backref" href="#id19">Open Dylan Compiler</a><a class="headerlink" href="#open-dylan-compiler" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://opendylan.org/">Dylan</a> is a multi-paradigm functional
+and object-oriented programming language. It is dynamic while
+providing a programming model designed to support efficient machine
+code generation, including fine-grained control over dynamic and
+static behavior. Dylan also features a powerful macro facility for
+expressive metaprogramming.</p>
+<p>The Open Dylan compiler can use LLVM as one of its code-generating
+back-ends, including full support for debug info generation. (Open
+Dylan generates LLVM bitcode directly using a native Dylan IR and
+bitcode library.) Development of a Dylan debugger and interactive REPL
+making use of the LLDB libraries is in progress.</p>
+</div>
+<div class="section" id="zig-programming-language">
+<h3><a class="toc-backref" href="#id20">Zig Programming Language</a><a class="headerlink" href="#zig-programming-language" title="Permalink to this headline">¶</a></h3>
+<p><a class="reference external" href="https://ziglang.org">Zig</a> is a system programming language intended to be
+an alternative to C. It provides high level features such as generics, compile
+time function execution, and partial evaluation, while exposing low level LLVM
+IR features such as aliases and intrinsics. Zig uses Clang to provide automatic
+import of .h symbols, including inline functions and simple macros. Zig uses
+LLD combined with lazily building compiler-rt to provide out-of-the-box
+cross-compiling for all supported targets.</p>
+</div>
+</div>
+<div class="section" id="additional-information">
+<h2><a class="toc-backref" href="#id21">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="https://llvm.org/">LLVM web page</a>, in particular in the <a class="reference external" href="https://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 <code class="docutils literal notranslate"><span class="pre">llvm/docs/</span></code> 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="https://llvm.org/docs/#mailing-lists">mailing lists</a>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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/BuildingAJIT5.html" title="5. Building a JIT: Remote-JITing â Process Isolation and Laziness at a Distance"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/ReleaseProcess.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/ReleaseProcess.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/ReleaseProcess.html (added)
+++ www-releases/trunk/8.0.1/docs/ReleaseProcess.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,265 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>How To Validate a New Release — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVM Bug Life Cycle" href="BugLifeCycle.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" role="navigation" aria-label="related navigation">
+ <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="BugLifeCycle.html" title="LLVM Bug Life Cycle"
+ 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" role="main">
+
+ <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"><span class="doc">How To Release LLVM To The Public</span></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 <code class="docutils literal notranslate"><span class="pre">utils/release</span></code> 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 <code class="docutils literal notranslate"><span class="pre">compiler-rt</span></code>, <code class="docutils literal notranslate"><span class="pre">libcxx</span></code>, <code class="docutils literal notranslate"><span class="pre">libomp</span></code> and <code class="docutils literal notranslate"><span class="pre">clang-extra-tools</span></code>) 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-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">test</span><span class="o">-</span><span class="n">release</span><span class="o">.</span><span class="n">sh</span> \
+ <span class="o">-</span><span class="n">release</span> <span class="mf">3.3</span> \
+ <span class="o">-</span><span class="n">rc</span> <span class="mi">1</span> \
+ <span class="o">-</span><span class="n">no</span><span class="o">-</span><span class="mi">64</span><span class="n">bit</span> \
+ <span class="o">-</span><span class="n">test</span><span class="o">-</span><span class="n">asserts</span> \
+ <span class="o">-</span><span class="n">no</span><span class="o">-</span><span class="n">compare</span><span class="o">-</span><span class="n">files</span>
+</pre></div>
+</div>
+<p>Each system will require different options. For instance, x86_64 will
+obviously not need <code class="docutils literal notranslate"><span class="pre">-no-64bit</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-rc</span> <span class="pre">1</span></code> to <code class="docutils literal notranslate"><span class="pre">-final</span></code>. On RC2,
+change it to <code class="docutils literal notranslate"><span class="pre">-rc</span> <span class="pre">2</span></code> and so on.</li>
+<li>On non-release testing, you can use <code class="docutils literal notranslate"><span class="pre">-final</span></code> in conjunction with
+<code class="docutils literal notranslate"><span class="pre">-no-checkout</span></code>, but youâll have to create the <code class="docutils literal notranslate"><span class="pre">final</span></code> directory by hand
+and link the correct source dir to <code class="docutils literal notranslate"><span class="pre">final/llvm.src</span></code>.</li>
+<li>For release candidates, you need <code class="docutils literal notranslate"><span class="pre">-test-asserts</span></code>, 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 <code class="docutils literal notranslate"><span class="pre">--help</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">rcN/Phase3/Release+Asserts/llvmCore-REL-RC.install</span></code>.
+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 <code class="docutils literal notranslate"><span class="pre">~/devel/llvm/install</span></code>:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">./</span><span class="n">sandbox</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">python</span> <span class="n">sandbox</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">lnt</span> <span class="n">runtest</span> \
+ <span class="n">nt</span> \
+ <span class="o">-</span><span class="n">j4</span> \
+ <span class="o">--</span><span class="n">sandbox</span> <span class="n">sandbox</span> \
+ <span class="o">--</span><span class="n">test</span><span class="o">-</span><span class="n">suite</span> <span class="o">~/</span><span class="n">devel</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">test</span><span class="o">/</span><span class="n">test</span><span class="o">-</span><span class="n">suite</span> \
+ <span class="o">--</span><span class="n">cc</span> <span class="o">~/</span><span class="n">devel</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">install</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">clang</span> \
+ <span class="o">--</span><span class="n">cxx</span> <span class="o">~/</span><span class="n">devel</span><span class="o">/</span><span class="n">llvm</span><span class="o">/</span><span class="n">install</span><span class="o">/</span><span class="nb">bin</span><span class="o">/</span><span class="n">clang</span><span class="o">++</span>
+</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 <code class="docutils literal notranslate"><span class="pre">final</span></code> mode (change <code class="docutils literal notranslate"><span class="pre">-rc</span> <span class="pre">1</span></code> to
+<code class="docutils literal notranslate"><span class="pre">-final</span></code>).</li>
+<li>Once all three stages are done, itâll test the final stage.</li>
+<li>Using the <code class="docutils literal notranslate"><span class="pre">Phase3/Release+Asserts/llvmCore-MAJ.MIN-final.install</span></code> base,
+run the test-suite.</li>
+</ul>
+<p>If the final phaseâs <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">check-all</span></code> failed, itâs a good idea to also test
+the intermediate stages by going on the obj directory and running
+<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">check-all</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-rc</span> <span class="pre">1</span></code>, <code class="docutils literal notranslate"><span class="pre">-rc</span> <span class="pre">2</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Release</span></code> (no Asserts) install directory on <code class="docutils literal notranslate"><span class="pre">Phase3</span></code>
+and that will be the official binary.</p>
+<ul class="simple">
+<li>Rename (or link) <code class="docutils literal notranslate"><span class="pre">clang+llvm-REL-ARCH-ENV</span></code> to the .install directory</li>
+<li>Tar that into the same name with <code class="docutils literal notranslate"><span class="pre">.tar.gz</span></code> 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" role="navigation" aria-label="related navigation">
+ <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="BugLifeCycle.html" title="LLVM Bug Life Cycle"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/Remarks.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/Remarks.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/Remarks.html (added)
+++ www-releases/trunk/8.0.1/docs/Remarks.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,459 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Remarks — LLVM 9 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVM Atomic Instructions and Concurrency Guide" href="Atomics.html" />
+ <link rel="prev" title="Building a Distribution of LLVM" href="BuildingADistribution.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" role="navigation" aria-label="related navigation">
+ <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="Atomics.html" title="LLVM Atomic Instructions and Concurrency Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="BuildingADistribution.html" title="Building a Distribution of 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" role="main">
+
+ <div class="section" id="remarks">
+<h1>Remarks<a class="headerlink" href="#remarks" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction-to-the-llvm-remark-diagnostics" id="id1">Introduction to the LLVM remark diagnostics</a></li>
+<li><a class="reference internal" href="#enabling-optimization-remarks" id="id2">Enabling optimization remarks</a><ul>
+<li><a class="reference internal" href="#remark-diagnostics" id="id3">Remark diagnostics</a></li>
+<li><a class="reference internal" href="#serialized-remarks" id="id4">Serialized remarks</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#yaml-remarks" id="id5">YAML remarks</a></li>
+<li><a class="reference internal" href="#opt-viewer" id="id6">opt-viewer</a><ul>
+<li><a class="reference internal" href="#opt-viewer-py" id="id7">opt-viewer.py</a></li>
+<li><a class="reference internal" href="#opt-stats-py" id="id8">opt-stats.py</a></li>
+<li><a class="reference internal" href="#opt-diff-py" id="id9">opt-diff.py</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#emitting-remark-diagnostics-in-the-object-file" id="id10">Emitting remark diagnostics in the object file</a></li>
+<li><a class="reference internal" href="#c-api" id="id11">C API</a></li>
+</ul>
+</div>
+<div class="section" id="introduction-to-the-llvm-remark-diagnostics">
+<h2><a class="toc-backref" href="#id1">Introduction to the LLVM remark diagnostics</a><a class="headerlink" href="#introduction-to-the-llvm-remark-diagnostics" title="Permalink to this headline">¶</a></h2>
+<p>LLVM is able to emit diagnostics from passes describing whether an optimization
+has been performed or missed for a particular reason, which should give more
+insight to users about what the compiler did during the compilation pipeline.</p>
+<p>There are three main remark types:</p>
+<p><code class="docutils literal notranslate"><span class="pre">Passed</span></code></p>
+<blockquote>
+<div><p>Remarks that describe a successful optimization performed by the compiler.</p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"></td>
+</tr>
+</tbody>
+</table>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">foo</span> <span class="n">inlined</span> <span class="n">into</span> <span class="n">bar</span> <span class="k">with</span> <span class="p">(</span><span class="n">cost</span><span class="o">=</span><span class="n">always</span><span class="p">):</span> <span class="n">always</span> <span class="n">inline</span> <span class="n">attribute</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">Missed</span></code></p>
+<blockquote>
+<div><p>Remarks that describe an attempt to an optimization by the compiler that
+could not be performed.</p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"></td>
+</tr>
+</tbody>
+</table>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">foo</span> <span class="ow">not</span> <span class="n">inlined</span> <span class="n">into</span> <span class="n">bar</span> <span class="n">because</span> <span class="n">it</span> <span class="n">should</span> <span class="n">never</span> <span class="n">be</span> <span class="n">inlined</span>
+<span class="p">(</span><span class="n">cost</span><span class="o">=</span><span class="n">never</span><span class="p">):</span> <span class="n">noinline</span> <span class="n">function</span> <span class="n">attribute</span>
+</pre></div>
+</div>
+</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">Analysis</span></code></p>
+<blockquote>
+<div><p>Remarks that describe the result of an analysis, that can bring more
+information to the user regarding the generated code.</p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"></td>
+</tr>
+</tbody>
+</table>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">16</span> <span class="n">stack</span> <span class="nb">bytes</span> <span class="ow">in</span> <span class="n">function</span>
+</pre></div>
+</div>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">10</span> <span class="n">instructions</span> <span class="ow">in</span> <span class="n">function</span>
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="enabling-optimization-remarks">
+<h2><a class="toc-backref" href="#id2">Enabling optimization remarks</a><a class="headerlink" href="#enabling-optimization-remarks" title="Permalink to this headline">¶</a></h2>
+<p>There are two modes that are supported for enabling optimization remarks in
+LLVM: through remark diagnostics, or through serialized remarks.</p>
+<div class="section" id="remark-diagnostics">
+<h3><a class="toc-backref" href="#id3">Remark diagnostics</a><a class="headerlink" href="#remark-diagnostics" title="Permalink to this headline">¶</a></h3>
+<p>Optimization remarks can be emitted as diagnostics. These diagnostics will be
+propagated to front-ends if desired, or emitted by tools like <a class="reference internal" href="CommandGuide/llc.html"><span class="doc">llc</span></a> or <a class="reference internal" href="CommandGuide/opt.html"><span class="doc">opt</span></a>.</p>
+<dl class="option">
+<dt id="cmdoption-pass-remarks">
+<code class="descname">-pass-remarks</code><code class="descclassname">=<regex></code><a class="headerlink" href="#cmdoption-pass-remarks" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enables optimization remarks from passes whose name match the given (POSIX)
+regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pass-remarks-missed">
+<code class="descname">-pass-remarks-missed</code><code class="descclassname">=<regex></code><a class="headerlink" href="#cmdoption-pass-remarks-missed" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enables missed optimization remarks from passes whose name match the given
+(POSIX) regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pass-remarks-analysis">
+<code class="descname">-pass-remarks-analysis</code><code class="descclassname">=<regex></code><a class="headerlink" href="#cmdoption-pass-remarks-analysis" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enables optimization analysis remarks from passes whose name match the given
+(POSIX) regular expression.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="serialized-remarks">
+<h3><a class="toc-backref" href="#id4">Serialized remarks</a><a class="headerlink" href="#serialized-remarks" title="Permalink to this headline">¶</a></h3>
+<p>While diagnostics are useful during development, it is often more useful to
+refer to optimization remarks post-compilation, typically during performance
+analysis.</p>
+<p>For that, LLVM can serialize the remarks produced for each compilation unit to
+a file that can be consumed later.</p>
+<p>By default, the format of the serialized remarks is <a class="reference internal" href="#yamlremarks"><span class="std std-ref">YAML</span></a>, and it can be accompanied by a <a class="reference internal" href="#remarkssection"><span class="std std-ref">section</span></a>
+in the object files to easily retrieve it.</p>
+<p><a class="reference internal" href="CommandGuide/llc.html"><span class="doc">llc</span></a> and <a class="reference internal" href="CommandGuide/opt.html"><span class="doc">opt</span></a> support the
+following options:</p>
+<p><code class="docutils literal notranslate"><span class="pre">Basic</span> <span class="pre">options</span></code></p>
+<blockquote>
+<div><dl class="option">
+<dt id="cmdoption-pass-remarks-output">
+<code class="descname">-pass-remarks-output</code><code class="descclassname">=<filename></code><a class="headerlink" href="#cmdoption-pass-remarks-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enables the serialization of remarks to a file specified in <filename>.</p>
+<p>By default, the output is serialized to <a class="reference internal" href="#yamlremarks"><span class="std std-ref">YAML</span></a>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pass-remarks-format">
+<code class="descname">-pass-remarks-format</code><code class="descclassname">=<format></code><a class="headerlink" href="#cmdoption-pass-remarks-format" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specifies the output format of the serialized remarks.</p>
+<p>Supported formats:</p>
+<ul class="simple">
+<li><a class="reference internal" href="#yamlremarks"><span class="std std-ref">yaml</span></a> (default)</li>
+</ul>
+</dd></dl>
+
+</div></blockquote>
+<p><code class="docutils literal notranslate"><span class="pre">Content</span> <span class="pre">configuration</span></code></p>
+<blockquote>
+<div><dl class="option">
+<dt id="cmdoption-pass-remarks-filter">
+<code class="descname">-pass-remarks-filter</code><code class="descclassname">=<regex></code><a class="headerlink" href="#cmdoption-pass-remarks-filter" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only passes whose name match the given (POSIX) regular expression will be
+serialized to the final output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pass-remarks-with-hotness">
+<code class="descname">-pass-remarks-with-hotness</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-pass-remarks-with-hotness" title="Permalink to this definition">¶</a></dt>
+<dd><p>With PGO, include profile count in optimization remarks.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pass-remarks-hotness-threshold">
+<code class="descname">-pass-remarks-hotness-threshold</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-pass-remarks-hotness-threshold" title="Permalink to this definition">¶</a></dt>
+<dd><p>The minimum profile count required for an optimization remark to be
+emitted.</p>
+</dd></dl>
+
+</div></blockquote>
+<p>Other tools that support remarks:</p>
+<p><strong class="program">llvm-lto</strong></p>
+<blockquote>
+<div><dl class="option">
+<dt id="cmdoption-lto-pass-remarks-output">
+<code class="descname">-lto-pass-remarks-output</code><code class="descclassname">=<filename></code><a class="headerlink" href="#cmdoption-lto-pass-remarks-output" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-lto-pass-remarks-filter">
+<code class="descname">-lto-pass-remarks-filter</code><code class="descclassname">=<regex></code><a class="headerlink" href="#cmdoption-lto-pass-remarks-filter" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-lto-pass-remarks-format">
+<code class="descname">-lto-pass-remarks-format</code><code class="descclassname">=<format></code><a class="headerlink" href="#cmdoption-lto-pass-remarks-format" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-lto-pass-remarks-with-hotness">
+<code class="descname">-lto-pass-remarks-with-hotness</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-lto-pass-remarks-with-hotness" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-lto-pass-remarks-hotness-threshold">
+<code class="descname">-lto-pass-remarks-hotness-threshold</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-lto-pass-remarks-hotness-threshold" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+</div></blockquote>
+<p><strong class="program">gold-plugin</strong> and <strong class="program">lld</strong></p>
+<blockquote>
+<div><dl class="option">
+<dt id="cmdoption-opt-remarks-filename">
+<code class="descname">-opt-remarks-filename</code><code class="descclassname">=<filename></code><a class="headerlink" href="#cmdoption-opt-remarks-filename" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-opt-remarks-filter">
+<code class="descname">-opt-remarks-filter</code><code class="descclassname">=<regex></code><a class="headerlink" href="#cmdoption-opt-remarks-filter" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-opt-remarks-format">
+<code class="descname">-opt-remarks-format</code><code class="descclassname">=<format></code><a class="headerlink" href="#cmdoption-opt-remarks-format" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-opt-remarks-with-hotness">
+<code class="descname">-opt-remarks-with-hotness</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-remarks-with-hotness" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="yaml-remarks">
+<span id="yamlremarks"></span><h2><a class="toc-backref" href="#id5">YAML remarks</a><a class="headerlink" href="#yaml-remarks" title="Permalink to this headline">¶</a></h2>
+<p>A typical remark serialized to YAML looks like this:</p>
+<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nn">---</span> <span class="kt">!<TYPE></span>
+<span class="l l-Scalar l-Scalar-Plain">Pass</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain"><pass></span>
+<span class="l l-Scalar l-Scalar-Plain">Name</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain"><name></span>
+<span class="l l-Scalar l-Scalar-Plain">DebugLoc</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">{</span> <span class="nv">File</span><span class="p p-Indicator">:</span> <span class="nv"><file></span><span class="p p-Indicator">,</span> <span class="nv">Line</span><span class="p p-Indicator">:</span> <span class="nv"><line></span><span class="p p-Indicator">,</span> <span class="nv">Column</span><span class="p p-Indicator">:</span> <span class="nv"><column></span> <span class="p p-Indicator">}</span>
+<span class="l l-Scalar l-Scalar-Plain">Function</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain"><function></span>
+<span class="l l-Scalar l-Scalar-Plain">Hotness</span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain"><hotness></span>
+<span class="l l-Scalar l-Scalar-Plain">Args</span><span class="p p-Indicator">:</span>
+ <span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain"><key></span><span class="p p-Indicator">:</span> <span class="l l-Scalar l-Scalar-Plain"><value></span>
+ <span class="l l-Scalar l-Scalar-Plain">DebugLoc</span><span class="p p-Indicator">:</span> <span class="p p-Indicator">{</span> <span class="nv">File</span><span class="p p-Indicator">:</span> <span class="nv"><arg-file></span><span class="p p-Indicator">,</span> <span class="nv">Line</span><span class="p p-Indicator">:</span> <span class="nv"><arg-line></span><span class="p p-Indicator">,</span> <span class="nv">Column</span><span class="p p-Indicator">:</span> <span class="nv"><arg-column></span> <span class="p p-Indicator">}</span>
+</pre></div>
+</div>
+<p>The following entries are mandatory:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre"><TYPE></span></code>: can be <code class="docutils literal notranslate"><span class="pre">Passed</span></code>, <code class="docutils literal notranslate"><span class="pre">Missed</span></code>, <code class="docutils literal notranslate"><span class="pre">Analysis</span></code>,
+<code class="docutils literal notranslate"><span class="pre">AnalysisFPCommute</span></code>, <code class="docutils literal notranslate"><span class="pre">AnalysisAliasing</span></code>, <code class="docutils literal notranslate"><span class="pre">Failure</span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre"><pass></span></code>: the name of the pass that emitted this remark.</li>
+<li><code class="docutils literal notranslate"><span class="pre"><name></span></code>: the name of the remark coming from <code class="docutils literal notranslate"><span class="pre"><pass></span></code>.</li>
+<li><code class="docutils literal notranslate"><span class="pre"><function></span></code>: the mangled name of the function.</li>
+</ul>
+<p>If a <code class="docutils literal notranslate"><span class="pre">DebugLoc</span></code> entry is specified, the following fields are required:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre"><file></span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre"><line></span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre"><column></span></code></li>
+</ul>
+<p>If an <code class="docutils literal notranslate"><span class="pre">arg</span></code> entry is specified, the following fields are required:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre"><key></span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre"><value></span></code></li>
+</ul>
+<p>If a <code class="docutils literal notranslate"><span class="pre">DebugLoc</span></code> entry is specified within an <code class="docutils literal notranslate"><span class="pre">arg</span></code> entry, the following
+fields are required:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre"><arg-file></span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre"><arg-line></span></code></li>
+<li><code class="docutils literal notranslate"><span class="pre"><arg-column></span></code></li>
+</ul>
+</div>
+<div class="section" id="opt-viewer">
+<h2><a class="toc-backref" href="#id6">opt-viewer</a><a class="headerlink" href="#opt-viewer" title="Permalink to this headline">¶</a></h2>
+<p>The <code class="docutils literal notranslate"><span class="pre">opt-viewer</span></code> directory contains a collection of tools that visualize and
+summarize serialized remarks.</p>
+<div class="section" id="opt-viewer-py">
+<span id="optviewerpy"></span><h3><a class="toc-backref" href="#id7">opt-viewer.py</a><a class="headerlink" href="#opt-viewer-py" title="Permalink to this headline">¶</a></h3>
+<p>Output a HTML page which gives visual feedback on compiler interactions with
+your program.</p>
+<blockquote>
+<div><table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Examples:</th><td class="field-body"></td>
+</tr>
+</tbody>
+</table>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ opt-viewer.py my_yaml_file.opt.yaml
+</pre></div>
+</div>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ opt-viewer.py my_build_dir/
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="opt-stats-py">
+<h3><a class="toc-backref" href="#id8">opt-stats.py</a><a class="headerlink" href="#opt-stats-py" title="Permalink to this headline">¶</a></h3>
+<p>Output statistics about the optimization remarks in the input set.</p>
+<blockquote>
+<div><table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"></td>
+</tr>
+</tbody>
+</table>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ opt-stats.py my_yaml_file.opt.yaml
+
+Total number of remarks 3
+
+
+Top 10 remarks by pass:
+ inline 33%
+ asm-printer 33%
+ prologepilog 33%
+
+Top 10 remarks:
+ asm-printer/InstructionCount 33%
+ inline/NoDefinition 33%
+ prologepilog/StackSize 33%
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+<div class="section" id="opt-diff-py">
+<h3><a class="toc-backref" href="#id9">opt-diff.py</a><a class="headerlink" href="#opt-diff-py" title="Permalink to this headline">¶</a></h3>
+<p>Produce a new YAML file which contains all of the changes in optimizations
+between two YAML files.</p>
+<p>Typically, this tool should be used to do diffs between:</p>
+<ul class="simple">
+<li>new compiler + fixed source vs old compiler + fixed source</li>
+<li>fixed compiler + new source vs fixed compiler + old source</li>
+</ul>
+<p>This diff file can be displayed using <a class="reference internal" href="#optviewerpy"><span class="std std-ref">opt-viewer.py</span></a>.</p>
+<blockquote>
+<div><table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Example:</th><td class="field-body"></td>
+</tr>
+</tbody>
+</table>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ opt-diff.py my_opt_yaml1.opt.yaml my_opt_yaml2.opt.yaml -o my_opt_diff.opt.yaml
+$ opt-viewer.py my_opt_diff.opt.yaml
+</pre></div>
+</div>
+</div></blockquote>
+</div>
+</div>
+<div class="section" id="emitting-remark-diagnostics-in-the-object-file">
+<span id="remarkssection"></span><h2><a class="toc-backref" href="#id10">Emitting remark diagnostics in the object file</a><a class="headerlink" href="#emitting-remark-diagnostics-in-the-object-file" title="Permalink to this headline">¶</a></h2>
+<p>A section containing metadata on remark diagnostics will be emitted when
+-remarks-section is passed. The section contains:</p>
+<ul class="simple">
+<li>a magic number: âREMARKS\0â</li>
+<li>the version number: a little-endian uint64_t</li>
+<li>the total size of the string table (the size itself excluded):
+little-endian uint64_t</li>
+<li>a list of null-terminated strings</li>
+<li>the absolute file path to the serialized remark diagnostics: a
+null-terminated string.</li>
+</ul>
+<p>The section is named:</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">__LLVM,__remarks</span></code> (MachO)</li>
+<li><code class="docutils literal notranslate"><span class="pre">.remarks</span></code> (ELF)</li>
+</ul>
+</div>
+<div class="section" id="c-api">
+<h2><a class="toc-backref" href="#id11">C API</a><a class="headerlink" href="#c-api" title="Permalink to this headline">¶</a></h2>
+<p>LLVM provides a library that can be used to parse remarks through a shared
+library named <code class="docutils literal notranslate"><span class="pre">libRemarks</span></code>.</p>
+<p>The typical usage through the C API is like the following:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">LLVMRemarkParserRef</span> <span class="n">Parser</span> <span class="o">=</span> <span class="n">LLVMRemarkParserCreateYAML</span><span class="p">(</span><span class="n">Buf</span><span class="p">,</span> <span class="n">Size</span><span class="p">);</span>
+<span class="n">LLVMRemarkEntryRef</span> <span class="n">Remark</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
+<span class="k">while</span> <span class="p">((</span><span class="n">Remark</span> <span class="o">=</span> <span class="n">LLVMRemarkParserGetNext</span><span class="p">(</span><span class="n">Parser</span><span class="p">)))</span> <span class="p">{</span>
+ <span class="c1">// use Remark</span>
+<span class="p">}</span>
+<span class="kt">bool</span> <span class="n">HasError</span> <span class="o">=</span> <span class="n">LLVMRemarkParserHasError</span><span class="p">(</span><span class="n">Parser</span><span class="p">);</span>
+<span class="n">LLVMRemarkParserDispose</span><span class="p">(</span><span class="n">Parser</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="Atomics.html" title="LLVM Atomic Instructions and Concurrency Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="BuildingADistribution.html" title="Building a Distribution of 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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-07-10.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/ReportingGuide.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/ReportingGuide.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/ReportingGuide.html (added)
+++ www-releases/trunk/8.0.1/docs/ReportingGuide.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,209 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Reporting Guide — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Benchmarking tips" href="Benchmarking.html" />
+ <link rel="prev" title="Compiling CUDA with clang" href="CompileCudaWithLLVM.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" role="navigation" aria-label="related navigation">
+ <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="Benchmarking.html" title="Benchmarking tips"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CompileCudaWithLLVM.html" title="Compiling CUDA with clang"
+ 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" role="main">
+
+ <div class="section" id="reporting-guide">
+<h1>Reporting Guide<a class="headerlink" href="#reporting-guide" title="Permalink to this headline">¶</a></h1>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This document is currently a <strong>DRAFT</strong> document while it is being discussed
+by the community.</p>
+</div>
+<p>If you believe someone is violating the <a class="reference internal" href="CodeOfConduct.html"><span class="doc">code of conduct</span></a>
+you can always report it to the LLVM Foundation Code of Conduct Advisory
+Committee by emailing <a class="reference external" href="mailto:conduct%40llvm.org">conduct<span>@</span>llvm<span>.</span>org</a>. <strong>All reports will be kept
+confidential.</strong> This isnât a public list and only <a class="reference internal" href="#members">members</a> of the advisory
+committee will receive the report.</p>
+<p>If you believe anyone is in <strong>physical danger</strong>, please notify appropriate law
+enforcement first. If you are unsure what law enforcement agency is
+appropriate, please include this in your report and we will attempt to notify
+them.</p>
+<p>If the violation occurs at an event such as a Developer Meeting and requires
+immediate attention, you can also reach out to any of the event organizers or
+staff. Event organizers and staff will be prepared to handle the incident and
+able to help. If you cannot find one of the organizers, the venue staff can
+locate one for you. We will also post detailed contact information for specific
+events as part of each eventsâ information. In person reports will still be
+kept confidential exactly as above, but also feel free to (anonymously if
+needed) email <a class="reference external" href="mailto:conduct%40llvm.org">conduct<span>@</span>llvm<span>.</span>org</a>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The LLVM community has long handled inappropriate behavior on its own, using
+both private communication and public responses. Nothing in this document is
+intended to discourage this self enforcement of community norms. Instead,
+the mechanisms described here are intended to supplement any self
+enforcement within the community. They provide avenues for handling severe
+cases or cases where the reporting party does not wish to respond directly
+for any reason.</p>
+</div>
+<div class="section" id="filing-a-report">
+<h2>Filing a report<a class="headerlink" href="#filing-a-report" title="Permalink to this headline">¶</a></h2>
+<p>Reports can be as formal or informal as needed for the situation at hand. If
+possible, please include as much information as you can. If you feel
+comfortable, please consider including:</p>
+<ul class="simple">
+<li>Your contact info (so we can get in touch with you if we need to follow up).</li>
+<li>Names (real, nicknames, or pseudonyms) of any individuals involved. If there
+were other witnesses besides you, please try to include them as well.</li>
+<li>When and where the incident occurred. Please be as specific as possible.</li>
+<li>Your account of what occurred. If there is a publicly available record (e.g.
+a mailing list archive or a public IRC logger) please include a link.</li>
+<li>Any extra context you believe existed for the incident.</li>
+<li>If you believe this incident is ongoing.</li>
+<li>Any other information you believe we should have.</li>
+</ul>
+</div>
+<div class="section" id="what-happens-after-you-file-a-report">
+<h2>What happens after you file a report?<a class="headerlink" href="#what-happens-after-you-file-a-report" title="Permalink to this headline">¶</a></h2>
+<p>You will receive an email from the advisory committee acknowledging receipt
+within 24 hours (and we will aim to respond much quicker than that).</p>
+<p>The advisory committee will immediately meet to review the incident and try to
+determine:</p>
+<ul class="simple">
+<li>What happened and who was involved.</li>
+<li>Whether this event constitutes a code of conduct violation.</li>
+<li>Whether this is an ongoing situation, or if there is a threat to anyoneâs
+physical safety.</li>
+</ul>
+<p>If this is determined to be an ongoing incident or a threat to physical safety,
+the working groupsâ immediate priority will be to protect everyone involved.
+This means we may delay an âofficialâ response until we believe that the
+situation has ended and that everyone is physically safe.</p>
+<p>The working group will try to contact other parties involved or witnessing the
+event to gain clarity on what happened and understand any different
+perspectives.</p>
+<p>Once the advisory committee has a complete account of the events they will make
+a decision as to how to respond. Responses may include:</p>
+<ul class="simple">
+<li>Nothing, if we determine no violation occurred or it has already been
+appropriately resolved.</li>
+<li>Providing either moderation or mediation to ongoing interactions (where
+appropriate, safe, and desired by both parties).</li>
+<li>A private reprimand from the working group to the individuals involved.</li>
+<li>An imposed vacation (i.e. asking someone to âtake a week offâ from a mailing
+list or IRC).</li>
+<li>A public reprimand.</li>
+<li>A permanent or temporary ban from some or all LLVM spaces (mailing lists,
+IRC, etc.)</li>
+<li>Involvement of relevant law enforcement if appropriate.</li>
+</ul>
+<p>If the situation is not resolved within one week, weâll respond within one week
+to the original reporter with an update and explanation.</p>
+<p>Once weâve determined our response, we will separately contact the original
+reporter and other individuals to let them know what actions (if any) weâll be
+taking. We will take into account feedback from the individuals involved on the
+appropriateness of our response, but we donât guarantee weâll act on it.</p>
+<p>After any incident, the advisory committee will make a report on the situation
+to the LLVM Foundation board. The board may choose to make a public statement
+about the incident. If thatâs the case, the identities of anyone involved will
+remain confidential unless instructed by those inviduals otherwise.</p>
+</div>
+<div class="section" id="appealing">
+<h2>Appealing<a class="headerlink" href="#appealing" title="Permalink to this headline">¶</a></h2>
+<p>Only permanent resolutions (such as bans) or requests for public actions may be
+appealed. To appeal a decision of the working group, contact the LLVM
+Foundation board at <a class="reference external" href="mailto:board%40llvm.org">board<span>@</span>llvm<span>.</span>org</a> with your appeal and the board will review
+the case.</p>
+<p>In general, it is <strong>not</strong> appropriate to appeal a particular decision on
+a public mailing list. Doing so would involve disclosure of information which
+whould be confidential. Disclosing this kind of information publicly may be
+considered a separate and (potentially) more serious violation of the Code of
+Conduct. This is not meant to limit discussion of the Code of Conduct, the
+advisory board itself, or the appropriateness of responses in general, but
+<strong>please</strong> refrain from mentioning specific facts about cases without the
+explicit permission of all parties involved.</p>
+</div>
+<div class="section" id="members-of-the-code-of-conduct-advisory-committee">
+<span id="members"></span><h2>Members of the Code of Conduct Advisory Committee<a class="headerlink" href="#members-of-the-code-of-conduct-advisory-committee" title="Permalink to this headline">¶</a></h2>
+<p>The members serving on the advisory committee are listed here with contact
+information in case you are more comfortable talking directly to a specific
+member of the committee.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">FIXME: When we form the initial advisory committee, the members names and private contact info need to be added here.</p>
+</div>
+<p>(This text is based on the <a class="reference external" href="https://www.djangoproject.com/conduct/">Django Project</a> Code of Conduct, which is in turn
+based on wording from the <a class="reference external" href="http://speakup.io/coc.html">Speak Up! project</a>.)</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="Benchmarking.html" title="Benchmarking tips"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CompileCudaWithLLVM.html" title="Compiling CUDA with clang"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/ScudoHardenedAllocator.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/ScudoHardenedAllocator.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/ScudoHardenedAllocator.html (added)
+++ www-releases/trunk/8.0.1/docs/ScudoHardenedAllocator.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,298 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Scudo Hardened Allocator — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Using -opt-bisect-limit to debug optimization errors" href="OptBisect.html" />
+ <link rel="prev" title="Fuzzing LLVM libraries and tools" href="FuzzingLLVM.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" role="navigation" aria-label="related navigation">
+ <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="OptBisect.html" title="Using -opt-bisect-limit to debug optimization errors"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="FuzzingLLVM.html" title="Fuzzing LLVM libraries and tools"
+ 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" role="main">
+
+ <div class="section" id="scudo-hardened-allocator">
+<h1>Scudo Hardened Allocator<a class="headerlink" href="#scudo-hardened-allocator" 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="#design" id="id2">Design</a></li>
+<li><a class="reference internal" href="#usage" id="id3">Usage</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>The Scudo Hardened Allocator is a user-mode allocator based on LLVM Sanitizerâs
+CombinedAllocator, which aims at providing additional mitigations against heap
+based vulnerabilities, while maintaining good performance.</p>
+<p>Currently, the allocator supports (was tested on) the following architectures:</p>
+<ul class="simple">
+<li>i386 (& i686) (32-bit);</li>
+<li>x86_64 (64-bit);</li>
+<li>armhf (32-bit);</li>
+<li>AArch64 (64-bit);</li>
+<li>MIPS (32-bit & 64-bit).</li>
+</ul>
+<p>The name âScudoâ has been retained from the initial implementation (Escudo
+meaning Shield in Spanish and Portuguese).</p>
+</div>
+<div class="section" id="design">
+<h2><a class="toc-backref" href="#id2">Design</a><a class="headerlink" href="#design" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="allocator">
+<h3>Allocator<a class="headerlink" href="#allocator" title="Permalink to this headline">¶</a></h3>
+<p>Scudo can be considered a Frontend to the Sanitizersâ common allocator (later
+referenced as the Backend). It is split between a Primary allocator, fast and
+efficient, that services smaller allocation sizes, and a Secondary allocator
+that services larger allocation sizes and is backed by the operating system
+memory mapping primitives.</p>
+<p>Scudo was designed with security in mind, but aims at striking a good balance
+between security and performance. It is highly tunable and configurable.</p>
+</div>
+<div class="section" id="chunk-header">
+<h3>Chunk Header<a class="headerlink" href="#chunk-header" title="Permalink to this headline">¶</a></h3>
+<p>Every chunk of heap memory will be preceded by a chunk header. This has two
+purposes, the first one being to store various information about the chunk,
+the second one being to detect potential heap overflows. In order to achieve
+this, the header will be checksummed, involving the pointer to the chunk itself
+and a global secret. Any corruption of the header will be detected when said
+header is accessed, and the process terminated.</p>
+<p>The following information is stored in the header:</p>
+<ul class="simple">
+<li>the 16-bit checksum;</li>
+<li>the class ID for that chunk, which is the âbucketâ where the chunk resides
+for Primary backed allocations, or 0 for Secondary backed allocations;</li>
+<li>the size (Primary) or unused bytes amount (Secondary) for that chunk, which is
+necessary for computing the size of the chunk;</li>
+<li>the state of the chunk (available, allocated or quarantined);</li>
+<li>the allocation type (malloc, new, new[] or memalign), to detect potential
+mismatches in the allocation APIs used;</li>
+<li>the offset of the chunk, which is the distance in bytes from the beginning of
+the returned chunk to the beginning of the Backend allocation;</li>
+</ul>
+<p>This header fits within 8 bytes, on all platforms supported.</p>
+<p>The checksum is computed as a CRC32 (made faster with hardware support)
+of the global secret, the chunk pointer itself, and the 8 bytes of header with
+the checksum field zeroed out. It is not intended to be cryptographically
+strong.</p>
+<p>The header is atomically loaded and stored to prevent races. This is important
+as two consecutive chunks could belong to different threads. We also want to
+avoid any type of double fetches of information located in the header, and use
+local copies of the header for this purpose.</p>
+</div>
+<div class="section" id="delayed-freelist">
+<h3>Delayed Freelist<a class="headerlink" href="#delayed-freelist" title="Permalink to this headline">¶</a></h3>
+<p>A delayed freelist allows us to not return a chunk directly to the Backend, but
+to keep it aside for a while. Once a criterion is met, the delayed freelist is
+emptied, and the quarantined chunks are returned to the Backend. This helps
+mitigate use-after-free vulnerabilities by reducing the determinism of the
+allocation and deallocation patterns.</p>
+<p>This feature is using the Sanitizerâs Quarantine as its base, and the amount of
+memory that it can hold is configurable by the user (see the Options section
+below).</p>
+</div>
+<div class="section" id="randomness">
+<h3>Randomness<a class="headerlink" href="#randomness" title="Permalink to this headline">¶</a></h3>
+<p>It is important for the allocator to not make use of fixed addresses. We use
+the dynamic base option for the SizeClassAllocator, allowing us to benefit
+from the randomness of the system memory mapping functions.</p>
+</div>
+</div>
+<div class="section" id="usage">
+<h2><a class="toc-backref" href="#id3">Usage</a><a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="library">
+<h3>Library<a class="headerlink" href="#library" title="Permalink to this headline">¶</a></h3>
+<p>The allocator static library can be built from the LLVM build tree thanks to
+the <code class="docutils literal notranslate"><span class="pre">scudo</span></code> CMake rule. The associated tests can be exercised thanks to the
+<code class="docutils literal notranslate"><span class="pre">check-scudo</span></code> CMake rule.</p>
+<p>Linking the static library to your project can require the use of the
+<code class="docutils literal notranslate"><span class="pre">whole-archive</span></code> linker flag (or equivalent), depending on your linker.
+Additional flags might also be necessary.</p>
+<p>Your linked binary should now make use of the Scudo allocation and deallocation
+functions.</p>
+<p>You may also build Scudo like this:</p>
+<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span>cd $LLVM/projects/compiler-rt/lib
+clang++ -fPIC -std=c++11 -msse4.2 -O2 -I. scudo/*.cpp \
+ $(\ls sanitizer_common/*.{cc,S} | grep -v "sanitizer_termination\|sanitizer_common_nolibc\|sancov_\|sanitizer_unwind\|sanitizer_symbol") \
+ -shared -o libscudo.so -pthread
+</pre></div>
+</div>
+<p>and then use it with existing binaries as follows:</p>
+<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span>LD_PRELOAD=`pwd`/libscudo.so ./a.out
+</pre></div>
+</div>
+</div>
+<div class="section" id="clang">
+<h3>Clang<a class="headerlink" href="#clang" title="Permalink to this headline">¶</a></h3>
+<p>With a recent version of Clang (post rL317337), the allocator can be linked with
+a binary at compilation using the <code class="docutils literal notranslate"><span class="pre">-fsanitize=scudo</span></code> command-line argument, if
+the target platform is supported. Currently, the only other Sanitizer Scudo is
+compatible with is UBSan (eg: <code class="docutils literal notranslate"><span class="pre">-fsanitize=scudo,undefined</span></code>). Compiling with
+Scudo will also enforce PIE for the output binary.</p>
+</div>
+<div class="section" id="options">
+<h3>Options<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
+<p>Several aspects of the allocator can be configured on a per process basis
+through the following ways:</p>
+<ul class="simple">
+<li>at compile time, by defining <code class="docutils literal notranslate"><span class="pre">SCUDO_DEFAULT_OPTIONS</span></code> to the options string
+you want set by default;</li>
+<li>by defining a <code class="docutils literal notranslate"><span class="pre">__scudo_default_options</span></code> function in oneâs program that
+returns the options string to be parsed. Said function must have the following
+prototype: <code class="docutils literal notranslate"><span class="pre">extern</span> <span class="pre">"C"</span> <span class="pre">const</span> <span class="pre">char*</span> <span class="pre">__scudo_default_options(void)</span></code>, with a
+default visibility. This will override the compile time define;</li>
+<li>through the environment variable SCUDO_OPTIONS, containing the options string
+to be parsed. Options defined this way will override any definition made
+through <code class="docutils literal notranslate"><span class="pre">__scudo_default_options</span></code>.</li>
+</ul>
+<p>The options string follows a syntax similar to ASan, where distinct options
+can be assigned in the same string, separated by colons.</p>
+<p>For example, using the environment variable:</p>
+<div class="code highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">SCUDO_OPTIONS</span><span class="o">=</span><span class="s2">"DeleteSizeMismatch=1:QuarantineSizeKb=64"</span> <span class="o">./</span><span class="n">a</span><span class="o">.</span><span class="n">out</span>
+</pre></div>
+</div>
+<p>Or using the function:</p>
+<div class="code cpp highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">extern</span> <span class="s2">"C"</span> <span class="n">const</span> <span class="n">char</span> <span class="o">*</span><span class="n">__scudo_default_options</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="s2">"DeleteSizeMismatch=1:QuarantineSizeKb=64"</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The following options are available:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="27%" />
+<col width="15%" />
+<col width="15%" />
+<col width="44%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>Option</td>
+<td>64-bit default</td>
+<td>32-bit default</td>
+<td>Description</td>
+</tr>
+<tr class="row-even"><td>QuarantineSizeKb</td>
+<td>256</td>
+<td>64</td>
+<td>The size (in Kb) of quarantine used to delay
+the actual deallocation of chunks. Lower value
+may reduce memory usage but decrease the
+effectiveness of the mitigation; a negative
+value will fallback to the defaults. Setting
+<em>both</em> this and ThreadLocalQuarantineSizeKb to
+zero will disable the quarantine entirely.</td>
+</tr>
+<tr class="row-odd"><td>QuarantineChunksUpToSize</td>
+<td>2048</td>
+<td>512</td>
+<td>Size (in bytes) up to which chunks can be
+quarantined.</td>
+</tr>
+<tr class="row-even"><td>ThreadLocalQuarantineSizeKb</td>
+<td>1024</td>
+<td>256</td>
+<td>The size (in Kb) of per-thread cache use to
+offload the global quarantine. Lower value may
+reduce memory usage but might increase
+contention on the global quarantine. Setting
+<em>both</em> this and QuarantineSizeKb to zero will
+disable the quarantine entirely.</td>
+</tr>
+<tr class="row-odd"><td>DeallocationTypeMismatch</td>
+<td>true</td>
+<td>true</td>
+<td>Whether or not we report errors on
+malloc/delete, new/free, new/delete[], etc.</td>
+</tr>
+<tr class="row-even"><td>DeleteSizeMismatch</td>
+<td>true</td>
+<td>true</td>
+<td>Whether or not we report errors on mismatch
+between sizes of new and delete.</td>
+</tr>
+<tr class="row-odd"><td>ZeroContents</td>
+<td>false</td>
+<td>false</td>
+<td>Whether or not we zero chunk contents on
+allocation and deallocation.</td>
+</tr>
+</tbody>
+</table>
+<p>Allocator related common Sanitizer options can also be passed through Scudo
+options, such as <code class="docutils literal notranslate"><span class="pre">allocator_may_return_null</span></code> or <code class="docutils literal notranslate"><span class="pre">abort_on_error</span></code>. A detailed
+list including those can be found here:
+<a class="reference external" href="https://github.com/google/sanitizers/wiki/SanitizerCommonFlags">https://github.com/google/sanitizers/wiki/SanitizerCommonFlags</a>.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="OptBisect.html" title="Using -opt-bisect-limit to debug optimization errors"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="FuzzingLLVM.html" title="Fuzzing LLVM libraries and tools"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/SegmentedStacks.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/SegmentedStacks.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/SegmentedStacks.html (added)
+++ www-releases/trunk/8.0.1/docs/SegmentedStacks.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,159 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Segmented Stacks in LLVM — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <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" role="main">
+
+ <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 <code class="docutils literal notranslate"><span class="pre">"split-stack"</span></code> 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 <code class="docutils literal notranslate"><span class="pre">libgcc</span></code>. The generated
+assembly looks like this on x86-64:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span> 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
+<code class="docutils literal notranslate"><span class="pre">__morestack</span></code> (this function is implemented in <code class="docutils literal notranslate"><span class="pre">libgcc</span></code>) 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 <code class="docutils literal notranslate"><span class="pre">ret</span></code> is needed to have the function which made a call to
+<code class="docutils literal notranslate"><span class="pre">__morestack</span></code> return correctly. <code class="docutils literal notranslate"><span class="pre">__morestack</span></code>, instead of returning, calls
+into <code class="docutils literal notranslate"><span class="pre">.LBB0_2</span></code>. This is possible since both, the size of the <code class="docutils literal notranslate"><span class="pre">ret</span></code>
+instruction and the PC of call to <code class="docutils literal notranslate"><span class="pre">__morestack</span></code> are known. When the function
+body returns, control is transferred back to <code class="docutils literal notranslate"><span class="pre">__morestack</span></code>. <code class="docutils literal notranslate"><span class="pre">__morestack</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">llvm.alloca</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">libgcc</span></code>, 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" role="navigation" aria-label="related navigation">
+ <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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/SourceLevelDebugging.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/SourceLevelDebugging.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/SourceLevelDebugging.html (added)
+++ www-releases/trunk/8.0.1/docs/SourceLevelDebugging.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,1667 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Source Level Debugging with LLVM — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Auto-Vectorization in LLVM" href="Vectorizers.html" />
+ <link rel="prev" title="Support Library" href="SupportLibrary.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" role="navigation" aria-label="related navigation">
+ <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="SupportLibrary.html" title="Support 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" role="main">
+
+ <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="id8">Introduction</a><ul>
+<li><a class="reference internal" href="#philosophy-behind-llvm-debugging-information" id="id9">Philosophy behind LLVM debugging information</a></li>
+<li><a class="reference internal" href="#debug-information-consumers" id="id10">Debug information consumers</a></li>
+<li><a class="reference internal" href="#debug-information-and-optimizations" id="id11">Debug information and optimizations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#debugging-information-format" id="id12">Debugging information format</a><ul>
+<li><a class="reference internal" href="#debugger-intrinsic-functions" id="id13">Debugger intrinsic functions</a><ul>
+<li><a class="reference internal" href="#llvm-dbg-addr" id="id14"><code class="docutils literal notranslate"><span class="pre">llvm.dbg.addr</span></code></a></li>
+<li><a class="reference internal" href="#llvm-dbg-declare" id="id15"><code class="docutils literal notranslate"><span class="pre">llvm.dbg.declare</span></code></a></li>
+<li><a class="reference internal" href="#llvm-dbg-value" id="id16"><code class="docutils literal notranslate"><span class="pre">llvm.dbg.value</span></code></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#object-lifetimes-and-scoping" id="id17">Object lifetimes and scoping</a></li>
+<li><a class="reference internal" href="#c-c-front-end-specific-debug-information" id="id18">C/C++ front-end specific debug information</a><ul>
+<li><a class="reference internal" href="#c-c-source-file-information" id="id19">C/C++ source file information</a></li>
+<li><a class="reference internal" href="#c-c-global-variable-information" id="id20">C/C++ global variable information</a></li>
+<li><a class="reference internal" href="#c-c-function-information" id="id21">C/C++ function information</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id4" id="id22">Debugging information format</a><ul>
+<li><a class="reference internal" href="#debugging-information-extension-for-objective-c-properties" id="id23">Debugging Information Extension for Objective C Properties</a><ul>
+<li><a class="reference internal" href="#id5" id="id24">Introduction</a></li>
+<li><a class="reference internal" href="#proposal" id="id25">Proposal</a></li>
+<li><a class="reference internal" href="#new-dwarf-tags" id="id26">New DWARF Tags</a></li>
+<li><a class="reference internal" href="#new-dwarf-attributes" id="id27">New DWARF Attributes</a></li>
+<li><a class="reference internal" href="#new-dwarf-constants" id="id28">New DWARF Constants</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#name-accelerator-tables" id="id29">Name Accelerator Tables</a><ul>
+<li><a class="reference internal" href="#id6" id="id30">Introduction</a></li>
+<li><a class="reference internal" href="#hash-tables" id="id31">Hash Tables</a><ul>
+<li><a class="reference internal" href="#standard-hash-tables" id="id32">Standard Hash Tables</a></li>
+<li><a class="reference internal" href="#name-hash-tables" id="id33">Name Hash Tables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#details" id="id34">Details</a><ul>
+<li><a class="reference internal" href="#header-layout" id="id35">Header Layout</a></li>
+<li><a class="reference internal" href="#fixed-lookup" id="id36">Fixed Lookup</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id7" id="id37">Contents</a></li>
+<li><a class="reference internal" href="#language-extensions-and-file-format-changes" id="id38">Language Extensions and File Format Changes</a><ul>
+<li><a class="reference internal" href="#objective-c-extensions" id="id39">Objective-C Extensions</a></li>
+<li><a class="reference internal" href="#mach-o-changes" id="id40">Mach-O Changes</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#codeview-debug-info-format" id="id41">CodeView Debug Info Format</a><ul>
+<li><a class="reference internal" href="#format-background" id="id42">Format Background</a></li>
+<li><a class="reference internal" href="#working-with-codeview" id="id43">Working with CodeView</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#testing-debug-info-preservation-in-optimizations" id="id44">Testing Debug Info Preservation in Optimizations</a><ul>
+<li><a class="reference internal" href="#the-debugify-utility" id="id45">The <code class="docutils literal notranslate"><span class="pre">debugify</span></code> utility</a><ul>
+<li><a class="reference internal" href="#fixing-errors" id="id46">Fixing errors</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#using-debugify" id="id47">Using <code class="docutils literal notranslate"><span class="pre">debugify</span></code></a><ul>
+<li><a class="reference internal" href="#debugify-in-regression-tests" id="id48"><code class="docutils literal notranslate"><span class="pre">debugify</span></code> in regression tests</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id8">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"><span class="std std-ref">actual format that the LLVM debug
+information takes</span></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="#id9">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"><span class="std std-ref">well-defined and easily described
+ways</span></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"><span class="std std-ref">intrinsic functions</span></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"><span class="std std-ref">implementation-defined format</span></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="#id10">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, there are two backend consumers of debug info: DwarfDebug and
+CodeViewDebug. DwarfDebug produces DWARF suitable for use with GDB, LLDB, and
+other DWARF-based debuggers. <a class="reference internal" href="#codeview"><span class="std std-ref">CodeViewDebug</span></a> produces CodeView,
+the Microsoft debug info format, which is usable with Microsoft debuggers such
+as Visual Studio and WinDBG. LLVMâs debug information format is mostly derived
+from and inspired by DWARF, but it is feasible to translate into other target
+debug info formats such as STABS.</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>
+</div>
+<div class="section" id="debug-information-and-optimizations">
+<span id="intro-debugopt"></span><h3><a class="toc-backref" href="#id11">Debug information and optimizations</a><a class="headerlink" href="#debug-information-and-optimizations" 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 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
+â<code class="docutils literal notranslate"><span class="pre">-O0</span> <span class="pre">-g</span></code>â and get full debug information, allowing you to arbitrarily modify
+the program as it executes from a debugger. Compiling a program with
+â<code class="docutils literal notranslate"><span class="pre">-O3</span> <span class="pre">-g</span></code>â 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 which were optimized out of the program, or inlined away
+completely.</p>
+<p>The <a class="reference internal" href="TestSuiteMakefileGuide.html"><span class="doc">LLVM test-suite</span></a> provides a framework to
+test the optimizerâs handling of debugging information. It can be run like
+this:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>% <span class="nb">cd</span> llvm/projects/test-suite/MultiSource/Benchmarks <span class="c1"># 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"><span class="doc">LLVM Testing Infrastructure Guide</span></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="#id12">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 external" href="LangRef.html#difile">source files</a>, and <a class="reference external" href="LangRef.html#diglobalvariable">program objects</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"><span class="std std-ref">C/C++ front-end specific debug information</span></a> describes the data layout
+conventions used by the C and C++ front-ends.</p>
+<p>Debug information descriptors are <a class="reference external" href="LangRef.html#specialized-metadata">specialized metadata nodes</a>, first-class subclasses of <code class="docutils literal notranslate"><span class="pre">Metadata</span></code>.</p>
+<div class="section" id="debugger-intrinsic-functions">
+<span id="format-common-intrinsics"></span><h3><a class="toc-backref" href="#id13">Debugger intrinsic functions</a><a class="headerlink" href="#debugger-intrinsic-functions" title="Permalink to this headline">¶</a></h3>
+<p>LLVM uses several intrinsic functions (name prefixed with â<code class="docutils literal notranslate"><span class="pre">llvm.dbg</span></code>â) to
+track source local variables through optimization and code generation.</p>
+<div class="section" id="llvm-dbg-addr">
+<h4><a class="toc-backref" href="#id14"><code class="docutils literal notranslate"><span class="pre">llvm.dbg.addr</span></code></a><a class="headerlink" href="#llvm-dbg-addr" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="vg">@llvm.dbg.addr</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="p">)</span>
+</pre></div>
+</div>
+<p>This intrinsic provides information about a local element (e.g., variable).
+The first argument is metadata holding the address of variable, typically a
+static alloca in the function entry block. The second argument is a
+<a class="reference external" href="LangRef.html#dilocalvariable">local variable</a> containing a description of
+the variable. The third argument is a <a class="reference external" href="LangRef.html#diexpression">complex expression</a>. An <cite>llvm.dbg.addr</cite> intrinsic describes the
+<em>address</em> of a source variable.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>%i.addr = alloca i32, align 4
+call void @llvm.dbg.addr(metadata i32* %i.addr, metadata !1,
+ metadata !DIExpression()), !dbg !2
+!1 = !DILocalVariable(name: "i", ...) ; int i
+!2 = !DILocation(...)
+...
+%buffer = alloca [256 x i8], align 8
+; The address of i is buffer+64.
+call void @llvm.dbg.addr(metadata [256 x i8]* %buffer, metadata !3,
+ metadata !DIExpression(DW_OP_plus, 64)), !dbg !4
+!3 = !DILocalVariable(name: "i", ...) ; int i
+!4 = !DILocation(...)
+</pre></div>
+</div>
+<p>A frontend should generate exactly one call to <code class="docutils literal notranslate"><span class="pre">llvm.dbg.addr</span></code> at the point
+of declaration of a source variable. Optimization passes that fully promote the
+variable from memory to SSA values will replace this call with possibly
+multiple calls to <cite>llvm.dbg.value</cite>. Passes that delete stores are effectively
+partial promotion, and they will insert a mix of calls to <code class="docutils literal notranslate"><span class="pre">llvm.dbg.value</span></code>
+and <code class="docutils literal notranslate"><span class="pre">llvm.dbg.addr</span></code> to track the source variable value when it is available.
+After optimization, there may be multiple calls to <code class="docutils literal notranslate"><span class="pre">llvm.dbg.addr</span></code> describing
+the program points where the variables lives in memory. All calls for the same
+concrete source variable must agree on the memory location.</p>
+</div>
+<div class="section" id="llvm-dbg-declare">
+<h4><a class="toc-backref" href="#id15"><code class="docutils literal notranslate"><span class="pre">llvm.dbg.declare</span></code></a><a class="headerlink" href="#llvm-dbg-declare" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span><span class="p">,</span> <span class="kt">metadata</span><span class="p">,</span> <span class="kt">metadata</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This intrinsic is identical to <cite>llvm.dbg.addr</cite>, except that there can only be
+one call to <cite>llvm.dbg.declare</cite> for a given concrete <a class="reference external" href="LangRef.html#dilocalvariable">local variable</a>. It is not control-dependent, meaning that if
+a call to <cite>llvm.dbg.declare</cite> exists and has a valid location argument, that
+address is considered to be the true home of the variable across its entire
+lifetime. This makes it hard for optimizations to preserve accurate debug info
+in the presence of <code class="docutils literal notranslate"><span class="pre">llvm.dbg.declare</span></code>, so we are transitioning away from it,
+and we plan to deprecate it in future LLVM releases.</p>
+</div>
+<div class="section" id="llvm-dbg-value">
+<h4><a class="toc-backref" href="#id16"><code class="docutils literal notranslate"><span class="pre">llvm.dbg.value</span></code></a><a class="headerlink" href="#llvm-dbg-value" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="vg">@llvm.dbg.value</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="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 a <a class="reference external" href="LangRef.html#dilocalvariable">local variable</a> containing a
+description of the variable. The third argument is a <a class="reference external" href="LangRef.html#diexpression">complex expression</a>.</p>
+<p>An <cite>llvm.dbg.value</cite> intrinsic describes the <em>value</em> of a source variable
+directly, not its address. Note that the value operand of this intrinsic may
+be indirect (i.e, a pointer to the source variable), provided that interpreting
+the complex expression derives the direct value.</p>
+</div>
+</div>
+</div>
+<div class="section" id="object-lifetimes-and-scoping">
+<h2><a class="toc-backref" href="#id17">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 notranslate"><div class="highlight"><pre><span></span><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-text notranslate"><div class="highlight"><pre><span></span>; Function Attrs: nounwind ssp uwtable
+define void @foo() #0 !dbg !4 {
+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 !11, metadata !13), !dbg !14
+ store i32 21, i32* %X, align 4, !dbg !14
+ call void @llvm.dbg.declare(metadata i32* %Y, metadata !15, metadata !13), !dbg !16
+ store i32 22, i32* %Y, align 4, !dbg !16
+ call void @llvm.dbg.declare(metadata i32* %Z, metadata !17, metadata !13), !dbg !19
+ store i32 23, i32* %Z, align 4, !dbg !19
+ %0 = load i32, i32* %X, align 4, !dbg !20
+ store i32 %0, i32* %Z, align 4, !dbg !21
+ %1 = load i32, i32* %Y, align 4, !dbg !22
+ store i32 %1, i32* %X, align 4, !dbg !23
+ ret void, !dbg !24
+}
+
+; Function Attrs: nounwind readnone
+declare void @llvm.dbg.declare(metadata, 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 = !{!7, !8, !9}
+!llvm.ident = !{!10}
+
+!0 = !DICompileUnit(language: DW_LANG_C99, file: !1, producer: "clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)", isOptimized: false, runtimeVersion: 0, emissionKind: FullDebug, enums: !2, retainedTypes: !2, subprograms: !3, globals: !2, imports: !2)
+!1 = !DIFile(filename: "/dev/stdin", directory: "/Users/dexonsmith/data/llvm/debug-info")
+!2 = !{}
+!3 = !{!4}
+!4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: false, variables: !2)
+!5 = !DISubroutineType(types: !6)
+!6 = !{null}
+!7 = !{i32 2, !"Dwarf Version", i32 2}
+!8 = !{i32 2, !"Debug Info Version", i32 3}
+!9 = !{i32 1, !"PIC Level", i32 2}
+!10 = !{!"clang version 3.7.0 (trunk 231150) (llvm/trunk 231154)"}
+!11 = !DILocalVariable(name: "X", scope: !4, file: !1, line: 2, type: !12)
+!12 = !DIBasicType(name: "int", size: 32, align: 32, encoding: DW_ATE_signed)
+!13 = !DIExpression()
+!14 = !DILocation(line: 2, column: 9, scope: !4)
+!15 = !DILocalVariable(name: "Y", scope: !4, file: !1, line: 3, type: !12)
+!16 = !DILocation(line: 3, column: 9, scope: !4)
+!17 = !DILocalVariable(name: "Z", scope: !18, file: !1, line: 5, type: !12)
+!18 = distinct !DILexicalBlock(scope: !4, file: !1, line: 4, column: 5)
+!19 = !DILocation(line: 5, column: 11, scope: !18)
+!20 = !DILocation(line: 6, column: 11, scope: !18)
+!21 = !DILocation(line: 6, column: 9, scope: !18)
+!22 = !DILocation(line: 8, column: 9, scope: !4)
+!23 = !DILocation(line: 8, column: 7, scope: !4)
+!24 = !DILocation(line: 9, column: 3, scope: !4)
+</pre></div>
+</div>
+<p>This example illustrates a few important details about LLVM debugging
+information. In particular, it shows how the <code class="docutils literal notranslate"><span class="pre">llvm.dbg.declare</span></code> 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 notranslate"><div class="highlight"><pre><span></span><span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv nv-Anonymous">!11</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv nv-Anonymous">!13</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv nv-Anonymous">!14</span>
+ <span class="c">; [debug line = 2:7] [debug variable = X]</span>
+</pre></div>
+</div>
+<p>The first intrinsic <code class="docutils literal notranslate"><span class="pre">%llvm.dbg.declare</span></code> encodes debugging information for the
+variable <code class="docutils literal notranslate"><span class="pre">X</span></code>. The metadata <code class="docutils literal notranslate"><span class="pre">!dbg</span> <span class="pre">!14</span></code> attached to the intrinsic provides
+scope information for the variable <code class="docutils literal notranslate"><span class="pre">X</span></code>.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>!14 = !DILocation(line: 2, column: 9, scope: !4)
+!4 = distinct !DISubprogram(name: "foo", scope: !1, file: !1, line: 1, type: !5,
+ isLocal: false, isDefinition: true, scopeLine: 1,
+ isOptimized: false, variables: !2)
+</pre></div>
+</div>
+<p>Here <code class="docutils literal notranslate"><span class="pre">!14</span></code> is metadata providing <a class="reference external" href="LangRef.html#dilocation">location information</a>. In this example, scope is encoded by <code class="docutils literal notranslate"><span class="pre">!4</span></code>, a
+<a class="reference external" href="LangRef.html#disubprogram">subprogram descriptor</a>. This way the location
+information attached to the intrinsics indicates that the variable <code class="docutils literal notranslate"><span class="pre">X</span></code> is
+declared at line number 2 at a function level scope in function <code class="docutils literal notranslate"><span class="pre">foo</span></code>.</p>
+<p>Now lets take another example.</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.dbg.declare</span><span class="p">(</span><span class="kt">metadata</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%Z</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv nv-Anonymous">!17</span><span class="p">,</span> <span class="kt">metadata</span> <span class="nv nv-Anonymous">!13</span><span class="p">),</span> <span class="nv">!dbg</span> <span class="nv nv-Anonymous">!19</span>
+ <span class="c">; [debug line = 5:9] [debug variable = Z]</span>
+</pre></div>
+</div>
+<p>The third intrinsic <code class="docutils literal notranslate"><span class="pre">%llvm.dbg.declare</span></code> encodes debugging information for
+variable <code class="docutils literal notranslate"><span class="pre">Z</span></code>. The metadata <code class="docutils literal notranslate"><span class="pre">!dbg</span> <span class="pre">!19</span></code> attached to the intrinsic provides
+scope information for the variable <code class="docutils literal notranslate"><span class="pre">Z</span></code>.</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>!18 = distinct !DILexicalBlock(scope: !4, file: !1, line: 4, column: 5)
+!19 = !DILocation(line: 5, column: 11, scope: !18)
+</pre></div>
+</div>
+<p>Here <code class="docutils literal notranslate"><span class="pre">!19</span></code> indicates that <code class="docutils literal notranslate"><span class="pre">Z</span></code> is declared at line number 5 and column
+number 11 inside of lexical scope <code class="docutils literal notranslate"><span class="pre">!18</span></code>. The lexical scope itself resides
+inside of subprogram <code class="docutils literal notranslate"><span class="pre">!4</span></code> 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="#id18">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 <code class="docutils literal notranslate"><span class="pre">DIDescriptor</span></code> classes defined in
+<code class="docutils literal notranslate"><span class="pre">include/llvm/IR/DebugInfo.h</span></code> and the implementations of the helper functions
+in <code class="docutils literal notranslate"><span class="pre">lib/IR/DIBuilder.cpp</span></code>.</p>
+<div class="section" id="c-c-source-file-information">
+<h3><a class="toc-backref" href="#id19">C/C++ source file information</a><a class="headerlink" href="#c-c-source-file-information" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal notranslate"><span class="pre">llvm::Instruction</span></code> provides easy access to metadata attached with an
+instruction. One can extract line number information encoded in LLVM IR using
+<code class="docutils literal notranslate"><span class="pre">Instruction::getDebugLoc()</span></code> and <code class="docutils literal notranslate"><span class="pre">DILocation::getLine()</span></code>.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">DILocation</span> <span class="o">*</span><span class="n">Loc</span> <span class="o">=</span> <span class="n">I</span><span class="o">-></span><span class="n">getDebugLoc</span><span class="p">())</span> <span class="p">{</span> <span class="c1">// Here I is an LLVM instruction</span>
+ <span class="kt">unsigned</span> <span class="n">Line</span> <span class="o">=</span> <span class="n">Loc</span><span class="o">-></span><span class="n">getLine</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="o">-></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="o">-></span><span class="n">getDirectory</span><span class="p">();</span>
+ <span class="kt">bool</span> <span class="n">ImplicitCode</span> <span class="o">=</span> <span class="n">Loc</span><span class="o">-></span><span class="n">isImplicitCode</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>When the flag ImplicitCode is true then it means that the Instruction has been
+added by the front-end but doesnât correspond to source code written by the user. For example</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="n">MyBoolean</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">MyObject</span> <span class="n">MO</span><span class="p">;</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>At the end of the scope the MyObjectâs destructor is called but it isnât written
+explicitly. This information is useful to avoid to have counters on brackets when
+making code coverage.</p>
+</div>
+<div class="section" id="c-c-global-variable-information">
+<h3><a class="toc-backref" href="#id20">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 notranslate"><div class="highlight"><pre><span></span><span class="n">_Alignas</span><span class="p">(</span><span class="mi">8</span><span class="p">)</span> <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-text notranslate"><div class="highlight"><pre><span></span>;;
+;; Define the global itself.
+;;
+ at MyGlobal = global i32 100, align 8, !dbg !0
+
+;;
+;; List of debug info of globals
+;;
+!llvm.dbg.cu = !{!1}
+
+;; Some unrelated metadata.
+!llvm.module.flags = !{!6, !7}
+!llvm.ident = !{!8}
+
+;; Define the global variable itself
+!0 = distinct !DIGlobalVariable(name: "MyGlobal", scope: !1, file: !2, line: 1, type: !5, isLocal: false, isDefinition: true, align: 64)
+
+;; Define the compile unit.
+!1 = distinct !DICompileUnit(language: DW_LANG_C99, file: !2,
+ producer: "clang version 4.0.0",
+ isOptimized: false, runtimeVersion: 0, emissionKind: FullDebug,
+ enums: !3, globals: !4)
+
+;;
+;; Define the file
+;;
+!2 = !DIFile(filename: "/dev/stdin",
+ directory: "/Users/dexonsmith/data/llvm/debug-info")
+
+;; An empty array.
+!3 = !{}
+
+;; The Array of Global Variables
+!4 = !{!0}
+
+;;
+;; Define the type
+;;
+!5 = !DIBasicType(name: "int", size: 32, encoding: DW_ATE_signed)
+
+;; Dwarf version to output.
+!6 = !{i32 2, !"Dwarf Version", i32 4}
+
+;; Debug info schema version.
+!7 = !{i32 2, !"Debug Info Version", i32 3}
+
+;; Compiler identification
+!8 = !{!"clang version 4.0.0"}
+</pre></div>
+</div>
+<p>The align value in DIGlobalVariable description specifies variable alignment in
+case it was forced by C11 _Alignas(), C++11 alignas() keywords or compiler
+attribute __attribute__((aligned ())). In other case (when this field is missing)
+alignment is considered default. This is used when producing DWARF output
+for DW_AT_alignment value.</p>
+</div>
+<div class="section" id="c-c-function-information">
+<h3><a class="toc-backref" href="#id21">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 notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">*</span><span class="n">argv</span><span class="p">[])</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>a C/C++ front-end would generate the following descriptors:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>;;
+;; Define the anchor for subprograms.
+;;
+!4 = !DISubprogram(name: "main", scope: !1, file: !1, line: 1, type: !5,
+ isLocal: false, isDefinition: true, scopeLine: 1,
+ flags: DIFlagPrototyped, isOptimized: false,
+ variables: !2)
+
+;;
+;; Define the subprogram itself.
+;;
+define i32 @main(i32 %argc, i8** %argv) !dbg !4 {
+...
+}
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="id4">
+<h2><a class="toc-backref" href="#id22">Debugging information format</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="debugging-information-extension-for-objective-c-properties">
+<h3><a class="toc-backref" href="#id23">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="id5">
+<h4><a class="toc-backref" href="#id24">Introduction</a><a class="headerlink" href="#id5" 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="#id25">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 <code class="docutils literal notranslate"><span class="pre">@interface</span></code> declaration corresponding to this ivar.</p>
+<p>To facilitate debugging, these properties we will add a new DWARF TAG into the
+<code class="docutils literal notranslate"><span class="pre">DW_TAG_structure_type</span></code> 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 <code class="docutils literal notranslate"><span class="pre">DW_TAG_member</span></code> 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 <code class="docutils literal notranslate"><span class="pre">DW_TAG_member</span></code> for that
+ivar (with the <code class="docutils literal notranslate"><span class="pre">DW_AT_artificial</span></code> 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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span>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
+<code class="docutils literal notranslate"><span class="pre">DW_AT_APPLE_property_attribute</span></code>.</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="k">@property</span> <span class="p">(</span><span class="k">readonly</span><span class="p">,</span> <span class="k">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 notranslate"><div class="highlight"><pre><span></span>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
+<code class="docutils literal notranslate"><span class="pre">DW_AT_APPLE_property_setter</span></code> and <code class="docutils literal notranslate"><span class="pre">DW_AT_APPLE_property_getter</span></code> attributes.</p>
+<div class="highlight-objc notranslate"><div class="highlight"><pre><span></span><span class="k">@interface</span> <span class="nc">I1</span>
+<span class="k">@property</span> <span class="p">(</span><span class="k">setter</span><span class="o">=</span><span class="nl">myOwnP3Setter</span><span class="p">:)</span> <span class="kt">int</span> <span class="n">p3</span><span class="p">;</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="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 notranslate"><div class="highlight"><pre><span></span>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="#id26">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="#id27">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="#id28">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="84%" />
+<col width="16%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Name</th>
+<th class="head">Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>DW_APPLE_PROPERTY_readonly</td>
+<td>0x01</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_getter</td>
+<td>0x02</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_assign</td>
+<td>0x04</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_readwrite</td>
+<td>0x08</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_retain</td>
+<td>0x10</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_copy</td>
+<td>0x20</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_nonatomic</td>
+<td>0x40</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_setter</td>
+<td>0x80</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_atomic</td>
+<td>0x100</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_weak</td>
+<td>0x200</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_strong</td>
+<td>0x400</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_unsafe_unretained</td>
+<td>0x800</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_nullability</td>
+<td>0x1000</td>
+</tr>
+<tr class="row-odd"><td>DW_APPLE_PROPERTY_null_resettable</td>
+<td>0x2000</td>
+</tr>
+<tr class="row-even"><td>DW_APPLE_PROPERTY_class</td>
+<td>0x4000</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="name-accelerator-tables">
+<h3><a class="toc-backref" href="#id29">Name Accelerator Tables</a><a class="headerlink" href="#name-accelerator-tables" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id6">
+<h4><a class="toc-backref" href="#id30">Introduction</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
+<p>The â<code class="docutils literal notranslate"><span class="pre">.debug_pubnames</span></code>â and â<code class="docutils literal notranslate"><span class="pre">.debug_pubtypes</span></code>â formats are not what a
+debugger needs. The â<code class="docutils literal notranslate"><span class="pre">pub</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">.debug_pubnames</span></code>â. No static variables or private
+class variables are in the â<code class="docutils literal notranslate"><span class="pre">.debug_pubtypes</span></code>â. 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 â<code class="docutils literal notranslate"><span class="pre">.debug_pubnames</span></code>â section is not the simple name
+given by the <code class="docutils literal notranslate"><span class="pre">DW_AT_name</span> <span class="pre">attribute</span></code> 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
+â<code class="docutils literal notranslate"><span class="pre">a::b::c(int,const</span> <span class="pre">Foo&)</span> <span class="pre">const</span></code>â, but rather as â<code class="docutils literal notranslate"><span class="pre">c</span></code>â, â<code class="docutils literal notranslate"><span class="pre">b::c</span></code>â , or
+â<code class="docutils literal notranslate"><span class="pre">a::b::c</span></code>â. 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
+use.</p>
+<p>All debuggers currently ignore the â<code class="docutils literal notranslate"><span class="pre">.debug_pubnames</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">foo</span></code>â or namespace â<code class="docutils literal notranslate"><span class="pre">bar</span></code>â, or list items in
+namespace â<code class="docutils literal notranslate"><span class="pre">baz</span></code>â. 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="#id31">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="#id32">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 notranslate"><div class="highlight"><pre><span></span>.------------.
+| HEADER |
+|------------|
+| BUCKETS |
+|------------|
+| DATA |
+`------------'
+</pre></div>
+</div>
+<p>The BUCKETS are an array of offsets to DATA for each hash:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>.------------.
+| 0x00001000 | BUCKETS[0]
+| 0x00002000 | BUCKETS[1]
+| 0x00002200 | BUCKETS[2]
+| 0x000034f0 | BUCKETS[3]
+| | ...
+| 0xXXXXXXXX | BUCKETS[n_buckets]
+'------------'
+</pre></div>
+</div>
+<p>So for <code class="docutils literal notranslate"><span class="pre">bucket[3]</span></code> 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 notranslate"><div class="highlight"><pre><span></span> .------------.
+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 â<code class="docutils literal notranslate"><span class="pre">printf</span></code>â in the table above, we would make a 32-bit
+hash for â<code class="docutils literal notranslate"><span class="pre">printf</span></code>â, it might match <code class="docutils literal notranslate"><span class="pre">bucket[3]</span></code>. 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 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="#id33">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 notranslate"><div class="highlight"><pre><span></span>.-------------.
+| HEADER |
+|-------------|
+| BUCKETS |
+|-------------|
+| HASHES |
+|-------------|
+| OFFSETS |
+|-------------|
+| DATA |
+`-------------'
+</pre></div>
+</div>
+<p>The <code class="docutils literal notranslate"><span class="pre">BUCKETS</span></code> in the name tables are an index into the <code class="docutils literal notranslate"><span class="pre">HASHES</span></code> 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 â<code class="docutils literal notranslate"><span class="pre">n_buckets</span></code>â buckets, and â<code class="docutils literal notranslate"><span class="pre">n_hashes</span></code>â unique 32 bit hash
+values, we can clarify the contents of the <code class="docutils literal notranslate"><span class="pre">BUCKETS</span></code>, <code class="docutils literal notranslate"><span class="pre">HASHES</span></code> and
+<code class="docutils literal notranslate"><span class="pre">OFFSETS</span></code> as:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>.-------------------------.
+| 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 notranslate"><div class="highlight"><pre><span></span> .------------.
+ | 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 â<code class="docutils literal notranslate"><span class="pre">printf</span></code>â lookup from above, we
+would hash â<code class="docutils literal notranslate"><span class="pre">printf</span></code>â and find it matches <code class="docutils literal notranslate"><span class="pre">BUCKETS[3]</span></code> by taking the 32 bit
+hash value and modulo it by <code class="docutils literal notranslate"><span class="pre">n_buckets</span></code>. <code class="docutils literal notranslate"><span class="pre">BUCKETS[3]</span></code> contains â6â which
+is the index into the <code class="docutils literal notranslate"><span class="pre">HASHES</span></code> table. We would then compare any consecutive
+32 bit hashes values in the <code class="docutils literal notranslate"><span class="pre">HASHES</span></code> array as long as the hashes would be in
+<code class="docutils literal notranslate"><span class="pre">BUCKETS[3]</span></code>. We do this by verifying that each subsequent hash value modulo
+<code class="docutils literal notranslate"><span class="pre">n_buckets</span></code> is still 3. In the case of a failed lookup we would access the
+memory for <code class="docutils literal notranslate"><span class="pre">BUCKETS[3]</span></code>, 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 <code class="docutils literal notranslate"><span class="pre">GNU_HASH</span></code> 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 <code class="docutils literal notranslate"><span class="pre">UINT32_MAX</span></code>.</p>
+</div>
+</div>
+<div class="section" id="details">
+<h4><a class="toc-backref" href="#id34">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 (â<code class="docutils literal notranslate"><span class="pre">HeaderData</span></code>â),
+how the string value is stored (â<code class="docutils literal notranslate"><span class="pre">KeyType</span></code>â) and the content of the data for each
+hash value.</p>
+<div class="section" id="header-layout">
+<h5><a class="toc-backref" href="#id35">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 notranslate"><div class="highlight"><pre><span></span><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 â<code class="docutils literal notranslate"><span class="pre">magic</span></code>â value which must be <code class="docutils literal notranslate"><span class="pre">'HASH'</span></code>
+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 â<code class="docutils literal notranslate"><span class="pre">magic</span></code>â value is followed by a 16 bit
+<code class="docutils literal notranslate"><span class="pre">version</span></code> number which allows the table to be revised and modified in the
+future. The current version number is 1. <code class="docutils literal notranslate"><span class="pre">hash_function</span></code> is a <code class="docutils literal notranslate"><span class="pre">uint16_t</span></code>
+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 notranslate"><div class="highlight"><pre><span></span><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><code class="docutils literal notranslate"><span class="pre">bucket_count</span></code> is a 32 bit unsigned integer that represents how many buckets
+are in the <code class="docutils literal notranslate"><span class="pre">BUCKETS</span></code> array. <code class="docutils literal notranslate"><span class="pre">hashes_count</span></code> is the number of unique 32 bit
+hash values that are in the <code class="docutils literal notranslate"><span class="pre">HASHES</span></code> array, and is the same number of offsets
+are contained in the <code class="docutils literal notranslate"><span class="pre">OFFSETS</span></code> array. <code class="docutils literal notranslate"><span class="pre">header_data_len</span></code> specifies the size
+in bytes of the <code class="docutils literal notranslate"><span class="pre">HeaderData</span></code> that is filled in by specialized versions of
+this table.</p>
+</div>
+<div class="section" id="fixed-lookup">
+<h5><a class="toc-backref" href="#id36">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 notranslate"><div class="highlight"><pre><span></span><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><code class="docutils literal notranslate"><span class="pre">buckets</span></code> is an array of 32 bit indexes into the <code class="docutils literal notranslate"><span class="pre">hashes</span></code> array. The
+<code class="docutils literal notranslate"><span class="pre">hashes</span></code> array contains all of the 32 bit hash values for all names in the
+hash table. Each hash in the <code class="docutils literal notranslate"><span class="pre">hashes</span></code> table has an offset in the <code class="docutils literal notranslate"><span class="pre">offsets</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">HeaderData</span></code> 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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span>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 notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">form</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">DW_FORM_</span></code> definitions.</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><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><code class="docutils literal notranslate"><span class="pre">HeaderData</span></code> defines the base DIE offset that should be added to any atoms
+that are encoded using the <code class="docutils literal notranslate"><span class="pre">DW_FORM_ref1</span></code>, <code class="docutils literal notranslate"><span class="pre">DW_FORM_ref2</span></code>,
+<code class="docutils literal notranslate"><span class="pre">DW_FORM_ref4</span></code>, <code class="docutils literal notranslate"><span class="pre">DW_FORM_ref8</span></code> or <code class="docutils literal notranslate"><span class="pre">DW_FORM_ref_udata</span></code>. It also defines
+what is contained in each <code class="docutils literal notranslate"><span class="pre">HashData</span></code> object â <code class="docutils literal notranslate"><span class="pre">Atom.form</span></code> tells us how large
+each field will be in the <code class="docutils literal notranslate"><span class="pre">HashData</span></code> and the <code class="docutils literal notranslate"><span class="pre">Atom.type</span></code> tells us how this data
+should be interpreted.</p>
+<p>For the current implementations of the â<code class="docutils literal notranslate"><span class="pre">.apple_names</span></code>â (all functions +
+globals), the â<code class="docutils literal notranslate"><span class="pre">.apple_types</span></code>â (names of all types that are defined), and
+the â<code class="docutils literal notranslate"><span class="pre">.apple_namespaces</span></code>â (all namespaces), we currently set the <code class="docutils literal notranslate"><span class="pre">Atom</span></code>
+array to be:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span>.------------.
+| 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 notranslate"><div class="highlight"><pre><span></span>.------------.
+| 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="id7">
+<h4><a class="toc-backref" href="#id37">Contents</a><a class="headerlink" href="#id7" 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: â<code class="docutils literal notranslate"><span class="pre">.apple_names</span></code>â,
+â<code class="docutils literal notranslate"><span class="pre">.apple_types</span></code>â, and â<code class="docutils literal notranslate"><span class="pre">.apple_namespaces</span></code>â.</p>
+<p>â<code class="docutils literal notranslate"><span class="pre">.apple_names</span></code>â sections should contain an entry for each DWARF DIE whose
+<code class="docutils literal notranslate"><span class="pre">DW_TAG</span></code> is a <code class="docutils literal notranslate"><span class="pre">DW_TAG_label</span></code>, <code class="docutils literal notranslate"><span class="pre">DW_TAG_inlined_subroutine</span></code>, or
+<code class="docutils literal notranslate"><span class="pre">DW_TAG_subprogram</span></code> that has address attributes: <code class="docutils literal notranslate"><span class="pre">DW_AT_low_pc</span></code>,
+<code class="docutils literal notranslate"><span class="pre">DW_AT_high_pc</span></code>, <code class="docutils literal notranslate"><span class="pre">DW_AT_ranges</span></code> or <code class="docutils literal notranslate"><span class="pre">DW_AT_entry_pc</span></code>. It also contains
+<code class="docutils literal notranslate"><span class="pre">DW_TAG_variable</span></code> DIEs that have a <code class="docutils literal notranslate"><span class="pre">DW_OP_addr</span></code> 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 notranslate"><div class="highlight"><pre><span></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="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 <code class="docutils literal notranslate"><span class="pre">var</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">DW_AT_MIPS_linkage_name</span></code> attribute, and the <code class="docutils literal notranslate"><span class="pre">DW_AT_name</span></code> contains the
+function basename. If global or static variables have a mangled name in a
+<code class="docutils literal notranslate"><span class="pre">DW_AT_MIPS_linkage_name</span></code> attribute, this should be emitted along with the
+simple name found in the <code class="docutils literal notranslate"><span class="pre">DW_AT_name</span></code> attribute.</p>
+<p>â<code class="docutils literal notranslate"><span class="pre">.apple_types</span></code>â 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_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_atomic_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 <code class="docutils literal notranslate"><span class="pre">DW_AT_name</span></code> attribute are included, and the entry must
+not be a forward declaration (<code class="docutils literal notranslate"><span class="pre">DW_AT_declaration</span></code> attribute with a non-zero
+value). For example, using the following code:</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span>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 <code class="docutils literal notranslate"><span class="pre">DW_AT_name</span></code>.</p>
+<p>â<code class="docutils literal notranslate"><span class="pre">.apple_namespaces</span></code>â section should contain all <code class="docutils literal notranslate"><span class="pre">DW_TAG_namespace</span></code> DIEs.
+If we run into a namespace that has no name this is an anonymous namespace, and
+the name should be output as â<code class="docutils literal notranslate"><span class="pre">(anonymous</span> <span class="pre">namespace)</span></code>â (without the quotes).
+Why? This matches the output of the <code class="docutils literal notranslate"><span class="pre">abi::cxa_demangle()</span></code> 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="#id38">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="#id39">Objective-C Extensions</a><a class="headerlink" href="#objective-c-extensions" title="Permalink to this headline">¶</a></h5>
+<p>â<code class="docutils literal notranslate"><span class="pre">.apple_objc</span></code>â section should contain all <code class="docutils literal notranslate"><span class="pre">DW_TAG_subprogram</span></code> 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 â<code class="docutils literal notranslate"><span class="pre">-[NSString(my_additions)</span> <span class="pre">stringWithSpecialString:]</span></code>â, we would add
+an entry for â<code class="docutils literal notranslate"><span class="pre">NSString</span></code>â that points to DIE 0x1234, and an entry for
+â<code class="docutils literal notranslate"><span class="pre">NSString(my_additions)</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">.debug_names</span></code>â section.</p>
+<p>In the â<code class="docutils literal notranslate"><span class="pre">.apple_names</span></code>â section for Objective-C functions, the full name is
+the entire function name with the brackets (â<code class="docutils literal notranslate"><span class="pre">-[NSString</span>
+<span class="pre">stringWithCString:]</span></code>â) and the basename is the selector only
+(â<code class="docutils literal notranslate"><span class="pre">stringWithCString:</span></code>â).</p>
+</div>
+<div class="section" id="mach-o-changes">
+<h5><a class="toc-backref" href="#id40">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 <code class="docutils literal notranslate"><span class="pre">__DWARF</span></code> segment with
+names as follows:</p>
+<ul class="simple">
+<li>â<code class="docutils literal notranslate"><span class="pre">.apple_names</span></code>â -> â<code class="docutils literal notranslate"><span class="pre">__apple_names</span></code>â</li>
+<li>â<code class="docutils literal notranslate"><span class="pre">.apple_types</span></code>â -> â<code class="docutils literal notranslate"><span class="pre">__apple_types</span></code>â</li>
+<li>â<code class="docutils literal notranslate"><span class="pre">.apple_namespaces</span></code>â -> â<code class="docutils literal notranslate"><span class="pre">__apple_namespac</span></code>â (16 character limit)</li>
+<li>â<code class="docutils literal notranslate"><span class="pre">.apple_objc</span></code>â -> â<code class="docutils literal notranslate"><span class="pre">__apple_objc</span></code>â</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="codeview-debug-info-format">
+<span id="codeview"></span><h2><a class="toc-backref" href="#id41">CodeView Debug Info Format</a><a class="headerlink" href="#codeview-debug-info-format" title="Permalink to this headline">¶</a></h2>
+<p>LLVM supports emitting CodeView, the Microsoft debug info format, and this
+section describes the design and implementation of that support.</p>
+<div class="section" id="format-background">
+<h3><a class="toc-backref" href="#id42">Format Background</a><a class="headerlink" href="#format-background" title="Permalink to this headline">¶</a></h3>
+<p>CodeView as a format is clearly oriented around C++ debugging, and in C++, the
+majority of debug information tends to be type information. Therefore, the
+overriding design constraint of CodeView is the separation of type information
+from other âsymbolâ information so that type information can be efficiently
+merged across translation units. Both type information and symbol information is
+generally stored as a sequence of records, where each record begins with a
+16-bit record size and a 16-bit record kind.</p>
+<p>Type information is usually stored in the <code class="docutils literal notranslate"><span class="pre">.debug$T</span></code> section of the object
+file. All other debug info, such as line info, string table, symbol info, and
+inlinee info, is stored in one or more <code class="docutils literal notranslate"><span class="pre">.debug$S</span></code> sections. There may only be
+one <code class="docutils literal notranslate"><span class="pre">.debug$T</span></code> section per object file, since all other debug info refers to
+it. If a PDB (enabled by the <code class="docutils literal notranslate"><span class="pre">/Zi</span></code> MSVC option) was used during compilation,
+the <code class="docutils literal notranslate"><span class="pre">.debug$T</span></code> section will contain only an <code class="docutils literal notranslate"><span class="pre">LF_TYPESERVER2</span></code> record pointing
+to the PDB. When using PDBs, symbol information appears to remain in the object
+file <code class="docutils literal notranslate"><span class="pre">.debug$S</span></code> sections.</p>
+<p>Type records are referred to by their index, which is the number of records in
+the stream before a given record plus <code class="docutils literal notranslate"><span class="pre">0x1000</span></code>. Many common basic types, such
+as the basic integral types and unqualified pointers to them, are represented
+using type indices less than <code class="docutils literal notranslate"><span class="pre">0x1000</span></code>. Such basic types are built in to
+CodeView consumers and do not require type records.</p>
+<p>Each type record may only contain type indices that are less than its own type
+index. This ensures that the graph of type stream references is acyclic. While
+the source-level type graph may contain cycles through pointer types (consider a
+linked list struct), these cycles are removed from the type stream by always
+referring to the forward declaration record of user-defined record types. Only
+âsymbolâ records in the <code class="docutils literal notranslate"><span class="pre">.debug$S</span></code> streams may refer to complete,
+non-forward-declaration type records.</p>
+</div>
+<div class="section" id="working-with-codeview">
+<h3><a class="toc-backref" href="#id43">Working with CodeView</a><a class="headerlink" href="#working-with-codeview" title="Permalink to this headline">¶</a></h3>
+<p>These are instructions for some common tasks for developers working to improve
+LLVMâs CodeView support. Most of them revolve around using the CodeView dumper
+embedded in <code class="docutils literal notranslate"><span class="pre">llvm-readobj</span></code>.</p>
+<ul>
+<li><p class="first">Testing MSVCâs output:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ cl -c -Z7 foo.cpp # Use /Z7 to keep types in the object file
+$ llvm-readobj -codeview foo.obj
+</pre></div>
+</div>
+</li>
+<li><p class="first">Getting LLVM IR debug info out of Clang:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ clang -g -gcodeview --target=x86_64-windows-msvc foo.cpp -S -emit-llvm
+</pre></div>
+</div>
+<p>Use this to generate LLVM IR for LLVM test cases.</p>
+</li>
+<li><p class="first">Generate and dump CodeView from LLVM IR metadata:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ llc foo.ll -filetype=obj -o foo.obj
+$ llvm-readobj -codeview foo.obj > foo.txt
+</pre></div>
+</div>
+<p>Use this pattern in lit test cases and FileCheck the output of llvm-readobj</p>
+</li>
+</ul>
+<p>Improving LLVMâs CodeView support is a process of finding interesting type
+records, constructing a C++ test case that makes MSVC emit those records,
+dumping the records, understanding them, and then generating equivalent records
+in LLVMâs backend.</p>
+</div>
+</div>
+<div class="section" id="testing-debug-info-preservation-in-optimizations">
+<h2><a class="toc-backref" href="#id44">Testing Debug Info Preservation in Optimizations</a><a class="headerlink" href="#testing-debug-info-preservation-in-optimizations" title="Permalink to this headline">¶</a></h2>
+<p>The following paragraphs are an introduction to the debugify utility
+and examples of how to use it in regression tests to check debug info
+preservation after optimizations.</p>
+<div class="section" id="the-debugify-utility">
+<h3><a class="toc-backref" href="#id45">The <code class="docutils literal notranslate"><span class="pre">debugify</span></code> utility</a><a class="headerlink" href="#the-debugify-utility" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">debugify</span></code> synthetic debug info testing utility consists of two
+main parts. The <code class="docutils literal notranslate"><span class="pre">debugify</span></code> pass and the <code class="docutils literal notranslate"><span class="pre">check-debugify</span></code> one. They are
+meant to be used with <code class="docutils literal notranslate"><span class="pre">opt</span></code> for development purposes.</p>
+<p>The first applies synthetic debug information to every instruction of the module,
+while the latter checks that this DI is still available after an optimization
+has occurred, reporting any errors/warnings while doing so.</p>
+<p>The instructions are assigned sequentially increasing line locations,
+and are immediately used by debug value intrinsics when possible.</p>
+<p>For example, here is a module before:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="kt">void</span> <span class="vg">@f</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="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%x.addr</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span><span class="p">*,</span> <span class="k">align</span> <span class="m">8</span>
+ <span class="k">store</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%x</span><span class="p">,</span> <span class="k">i32</span><span class="p">**</span> <span class="nv">%x.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">8</span>
+ <span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*,</span> <span class="k">i32</span><span class="p">**</span> <span class="nv">%x.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">8</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="m">10</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv nv-Anonymous">%0</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>
+</pre></div>
+</div>
+<p>and after running <code class="docutils literal notranslate"><span class="pre">opt</span> <span class="pre">-debugify</span></code> on it we get:</p>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>define void @f(i32* %x) !dbg !6 {
+entry:
+ %x.addr = alloca i32*, align 8, !dbg !12
+ call void @llvm.dbg.value(metadata i32** %x.addr, metadata !9, metadata !DIExpression()), !dbg !12
+ store i32* %x, i32** %x.addr, align 8, !dbg !13
+ %0 = load i32*, i32** %x.addr, align 8, !dbg !14
+ call void @llvm.dbg.value(metadata i32* %0, metadata !11, metadata !DIExpression()), !dbg !14
+ store i32 10, i32* %0, align 4, !dbg !15
+ ret void, !dbg !16
+}
+
+!llvm.dbg.cu = !{!0}
+!llvm.debugify = !{!3, !4}
+!llvm.module.flags = !{!5}
+
+!0 = distinct !DICompileUnit(language: DW_LANG_C, file: !1, producer: "debugify", isOptimized: true, runtimeVersion: 0, emissionKind: FullDebug, enums: !2)
+!1 = !DIFile(filename: "debugify-sample.ll", directory: "/")
+!2 = !{}
+!3 = !{i32 5}
+!4 = !{i32 2}
+!5 = !{i32 2, !"Debug Info Version", i32 3}
+!6 = distinct !DISubprogram(name: "f", linkageName: "f", scope: null, file: !1, line: 1, type: !7, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: true, unit: !0, retainedNodes: !8)
+!7 = !DISubroutineType(types: !2)
+!8 = !{!9, !11}
+!9 = !DILocalVariable(name: "1", scope: !6, file: !1, line: 1, type: !10)
+!10 = !DIBasicType(name: "ty64", size: 64, encoding: DW_ATE_unsigned)
+!11 = !DILocalVariable(name: "2", scope: !6, file: !1, line: 3, type: !10)
+!12 = !DILocation(line: 1, column: 1, scope: !6)
+!13 = !DILocation(line: 2, column: 1, scope: !6)
+!14 = !DILocation(line: 3, column: 1, scope: !6)
+!15 = !DILocation(line: 4, column: 1, scope: !6)
+!16 = !DILocation(line: 5, column: 1, scope: !6)
+</pre></div>
+</div>
+<p>The following is an example of the -check-debugify output:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ opt -enable-debugify -loop-vectorize llvm/test/Transforms/LoopVectorize/i8-induction.ll -disable-output
+ERROR: Instruction with empty DebugLoc in function f -- %index = phi i32 [ 0, %vector.ph ], [ %index.next, %vector.body ]
+</pre></div>
+</div>
+<p>Errors/warnings can range from instructions with empty debug location to an
+instruction having a type thatâs incompatible with the source variable it describes,
+all the way to missing lines and missing debug value intrinsics.</p>
+<div class="section" id="fixing-errors">
+<h4><a class="toc-backref" href="#id46">Fixing errors</a><a class="headerlink" href="#fixing-errors" title="Permalink to this headline">¶</a></h4>
+<p>Each of the errors above has a relevant API available to fix it.</p>
+<ul class="simple">
+<li>In the case of missing debug location, <code class="docutils literal notranslate"><span class="pre">Instruction::setDebugLoc</span></code> or possibly
+<code class="docutils literal notranslate"><span class="pre">IRBuilder::setCurrentDebugLocation</span></code> when using a Builder and the new location
+should be reused.</li>
+<li>When a debug value has incompatible type <code class="docutils literal notranslate"><span class="pre">llvm::replaceAllDbgUsesWith</span></code> can be used.
+After a RAUW call an incompatible type error can occur because RAUW does not handle
+widening and narrowing of variables while <code class="docutils literal notranslate"><span class="pre">llvm::replaceAllDbgUsesWith</span></code> does. It is
+also capable of changing the DWARF expression used by the debugger to describe the variable.
+It also prevents use-before-def by salvaging or deleting invalid debug values.</li>
+<li>When a debug value is missing <code class="docutils literal notranslate"><span class="pre">llvm::salvageDebugInfo</span></code> can be used when no replacement
+exists, or <code class="docutils literal notranslate"><span class="pre">llvm::replaceAllDbgUsesWith</span></code> when a replacement exists.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="using-debugify">
+<h3><a class="toc-backref" href="#id47">Using <code class="docutils literal notranslate"><span class="pre">debugify</span></code></a><a class="headerlink" href="#using-debugify" title="Permalink to this headline">¶</a></h3>
+<p>In order for <code class="docutils literal notranslate"><span class="pre">check-debugify</span></code> to work, the DI must be coming from
+<code class="docutils literal notranslate"><span class="pre">debugify</span></code>. Thus, modules with existing DI will be skipped.</p>
+<p>The most straightforward way to use <code class="docutils literal notranslate"><span class="pre">debugify</span></code> is as follows:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ opt -debugify -pass-to-test -check-debugify sample.ll
+</pre></div>
+</div>
+<p>This will inject synthetic DI to <code class="docutils literal notranslate"><span class="pre">sample.ll</span></code> run the <code class="docutils literal notranslate"><span class="pre">pass-to-test</span></code>
+and then check for missing DI.</p>
+<p>Some other ways to run debugify are avaliable:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Same as the above example.</span>
+$ opt -enable-debugify -pass-to-test sample.ll
+
+<span class="c1"># Suppresses verbose debugify output.</span>
+$ opt -enable-debugify -debugify-quiet -pass-to-test sample.ll
+
+<span class="c1"># Prepend -debugify before and append -check-debugify -strip after</span>
+<span class="c1"># each pass on the pipeline (similar to -verify-each).</span>
+$ opt -debugify-each -O2 sample.ll
+</pre></div>
+</div>
+<p><code class="docutils literal notranslate"><span class="pre">debugify</span></code> can also be used to test a backend, e.g:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ opt -debugify < sample.ll <span class="p">|</span> llc -o -
+</pre></div>
+</div>
+<div class="section" id="debugify-in-regression-tests">
+<h4><a class="toc-backref" href="#id48"><code class="docutils literal notranslate"><span class="pre">debugify</span></code> in regression tests</a><a class="headerlink" href="#debugify-in-regression-tests" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">-debugify</span></code> pass is especially helpful when it comes to testing that
+a given pass preserves DI while transforming the module. For this to work,
+the <code class="docutils literal notranslate"><span class="pre">-debugify</span></code> output must be stable enough to use in regression tests.
+Changes to this pass are not allowed to break existing tests.</p>
+<p>It allows us to test for DI loss in the same tests we check that the
+transformation is actually doing what it should.</p>
+<p>Here is an example from <code class="docutils literal notranslate"><span class="pre">test/Transforms/InstCombine/cast-mul-select.ll</span></code>:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="c">; RUN: opt < %s -debugify -instcombine -S | FileCheck %s --check-prefix=DEBUGINFO</span>
+
+<span class="k">define</span> <span class="k">i32</span> <span class="vg">@mul</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%x</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%y</span><span class="p">)</span> <span class="p">{</span>
+<span class="c">; DBGINFO-LABEL: @mul(</span>
+<span class="c">; DBGINFO-NEXT: [[C:%.*]] = mul i32 {{.*}}</span>
+<span class="c">; DBGINFO-NEXT: call void @llvm.dbg.value(metadata i32 [[C]]</span>
+<span class="c">; DBGINFO-NEXT: [[D:%.*]] = and i32 {{.*}}</span>
+<span class="c">; DBGINFO-NEXT: call void @llvm.dbg.value(metadata i32 [[D]]</span>
+
+ <span class="nv">%A</span> <span class="p">=</span> <span class="k">trunc</span> <span class="k">i32</span> <span class="nv">%x</span> <span class="k">to</span> <span class="k">i8</span>
+ <span class="nv">%B</span> <span class="p">=</span> <span class="k">trunc</span> <span class="k">i32</span> <span class="nv">%y</span> <span class="k">to</span> <span class="k">i8</span>
+ <span class="nv">%C</span> <span class="p">=</span> <span class="k">mul</span> <span class="k">i8</span> <span class="nv">%A</span><span class="p">,</span> <span class="nv">%B</span>
+ <span class="nv">%D</span> <span class="p">=</span> <span class="k">zext</span> <span class="k">i8</span> <span class="nv">%C</span> <span class="k">to</span> <span class="k">i32</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="nv">%D</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here we test that the two <code class="docutils literal notranslate"><span class="pre">dbg.value</span></code> instrinsics are preserved and
+are correctly pointing to the <code class="docutils literal notranslate"><span class="pre">[[C]]</span></code> and <code class="docutils literal notranslate"><span class="pre">[[D]]</span></code> variables.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Note, that when writing this kind of regression tests, it is important
+to make them as robust as possible. Thatâs why we should try to avoid
+hardcoding line/variable numbers in check lines. If for example you test
+for a <code class="docutils literal notranslate"><span class="pre">DILocation</span></code> to have a specific line number, and someone later adds
+an instruction before the one we check the test will fail. In the cases this
+canât be avoided (say, if a test wouldnât be precise enough), moving the
+test to its own file is preferred.</p>
+</div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="SupportLibrary.html" title="Support 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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/SpeculativeLoadHardening.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/SpeculativeLoadHardening.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/SpeculativeLoadHardening.html (added)
+++ www-releases/trunk/8.0.1/docs/SpeculativeLoadHardening.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,1107 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Speculative Load Hardening — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Stack Safety Analysis" href="StackSafetyAnalysis.html" />
+ <link rel="prev" title="Control Flow Verification Tool Design Document" href="CFIVerify.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" role="navigation" aria-label="related navigation">
+ <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="StackSafetyAnalysis.html" title="Stack Safety Analysis"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CFIVerify.html" title="Control Flow Verification Tool Design Document"
+ 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" role="main">
+
+ <div class="section" id="speculative-load-hardening">
+<h1>Speculative Load Hardening<a class="headerlink" href="#speculative-load-hardening" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="a-spectre-variant-1-mitigation-technique">
+<h2>A Spectre Variant #1 Mitigation Technique<a class="headerlink" href="#a-spectre-variant-1-mitigation-technique" title="Permalink to this headline">¶</a></h2>
+<p>Author: Chandler Carruth - <a class="reference external" href="mailto:chandlerc%40google.com">chandlerc<span>@</span>google<span>.</span>com</a></p>
+</div>
+<div class="section" id="problem-statement">
+<h2>Problem Statement<a class="headerlink" href="#problem-statement" title="Permalink to this headline">¶</a></h2>
+<p>Recently, Google Project Zero and other researchers have found information leak
+vulnerabilities by exploiting speculative execution in modern CPUs. These
+exploits are currently broken down into three variants:</p>
+<ul class="simple">
+<li>GPZ Variant #1 (a.k.a. Spectre Variant #1): Bounds check (or predicate) bypass</li>
+<li>GPZ Variant #2 (a.k.a. Spectre Variant #2): Branch target injection</li>
+<li>GPZ Variant #3 (a.k.a. Meltdown): Rogue data cache load</li>
+</ul>
+<p>For more details, see the Google Project Zero blog post and the Spectre research
+paper:</p>
+<ul class="simple">
+<li>https://googleprojectzero.blogspot.com/2018/01/reading-privileged-memory-with-side.html</li>
+<li>https://spectreattack.com/spectre.pdf</li>
+</ul>
+<p>The core problem of GPZ Variant #1 is that speculative execution uses branch
+prediction to select the path of instructions speculatively executed. This path
+is speculatively executed with the available data, and may load from memory and
+leak the loaded values through various side channels that survive even when the
+speculative execution is unwound due to being incorrect. Mispredicted paths can
+cause code to be executed with data inputs that never occur in correct
+executions, making checks against malicious inputs ineffective and allowing
+attackers to use malicious data inputs to leak secret data. Here is an example,
+extracted and simplified from the Project Zero paper:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">struct</span> <span class="n">array</span> <span class="p">{</span>
+ <span class="n">unsigned</span> <span class="n">long</span> <span class="n">length</span><span class="p">;</span>
+ <span class="n">unsigned</span> <span class="n">char</span> <span class="n">data</span><span class="p">[];</span>
+<span class="p">};</span>
+<span class="n">struct</span> <span class="n">array</span> <span class="o">*</span><span class="n">arr1</span> <span class="o">=</span> <span class="o">...</span><span class="p">;</span> <span class="o">//</span> <span class="n">small</span> <span class="n">array</span>
+<span class="n">struct</span> <span class="n">array</span> <span class="o">*</span><span class="n">arr2</span> <span class="o">=</span> <span class="o">...</span><span class="p">;</span> <span class="o">//</span> <span class="n">array</span> <span class="n">of</span> <span class="n">size</span> <span class="mh">0x400</span>
+<span class="n">unsigned</span> <span class="n">long</span> <span class="n">untrusted_offset_from_caller</span> <span class="o">=</span> <span class="o">...</span><span class="p">;</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">untrusted_offset_from_caller</span> <span class="o"><</span> <span class="n">arr1</span><span class="o">-></span><span class="n">length</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">unsigned</span> <span class="n">char</span> <span class="n">value</span> <span class="o">=</span> <span class="n">arr1</span><span class="o">-></span><span class="n">data</span><span class="p">[</span><span class="n">untrusted_offset_from_caller</span><span class="p">];</span>
+ <span class="n">unsigned</span> <span class="n">long</span> <span class="n">index2</span> <span class="o">=</span> <span class="p">((</span><span class="n">value</span><span class="o">&</span><span class="mi">1</span><span class="p">)</span><span class="o">*</span><span class="mh">0x100</span><span class="p">)</span><span class="o">+</span><span class="mh">0x200</span><span class="p">;</span>
+ <span class="n">unsigned</span> <span class="n">char</span> <span class="n">value2</span> <span class="o">=</span> <span class="n">arr2</span><span class="o">-></span><span class="n">data</span><span class="p">[</span><span class="n">index2</span><span class="p">];</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The key of the attack is to call this with that
+is far outside of the bounds when the branch predictor will predict that it
+will be in-bounds. In that case, the body of the will be executed
+speculatively, and may read secret data into and leak it via a
+cache-timing side channel when a dependent access is made to populate .</p>
+</div>
+<div class="section" id="high-level-mitigation-approach">
+<h2>High Level Mitigation Approach<a class="headerlink" href="#high-level-mitigation-approach" title="Permalink to this headline">¶</a></h2>
+<p>While several approaches are being actively pursued to mitigate specific
+branches and/or loads inside especially risky software (most notably various OS
+kernels), these approaches require manual and/or static analysis aided auditing
+of code and explicit source changes to apply the mitigation. They are unlikely
+to scale well to large applications. We are proposing a comprehensive
+mitigation approach that would apply automatically across an entire program
+rather than through manual changes to the code. While this is likely to have a
+high performance cost, some applications may be in a good position to take this
+performance / security tradeoff.</p>
+<p>The specific technique we propose is to cause loads to be checked using
+branchless code to ensure that they are executing along a valid control flow
+path. Consider the following C-pseudo-code representing the core idea of a
+predicate guarding potentially invalid loads:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">void</span> <span class="n">leak</span><span class="p">(</span><span class="nb">int</span> <span class="n">data</span><span class="p">);</span>
+<span class="n">void</span> <span class="n">example</span><span class="p">(</span><span class="nb">int</span><span class="o">*</span> <span class="n">pointer1</span><span class="p">,</span> <span class="nb">int</span><span class="o">*</span> <span class="n">pointer2</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">condition</span><span class="p">)</span> <span class="p">{</span>
+ <span class="o">//</span> <span class="o">...</span> <span class="n">lots</span> <span class="n">of</span> <span class="n">code</span> <span class="o">...</span>
+ <span class="n">leak</span><span class="p">(</span><span class="o">*</span><span class="n">pointer1</span><span class="p">);</span>
+ <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+ <span class="o">//</span> <span class="o">...</span> <span class="n">more</span> <span class="n">code</span> <span class="o">...</span>
+ <span class="n">leak</span><span class="p">(</span><span class="o">*</span><span class="n">pointer2</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This would get transformed into something resembling the following:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>uintptr_t all_ones_mask = std::numerical_limits<uintptr_t>::max();
+uintptr_t all_zeros_mask = 0;
+void leak(int data);
+void example(int* pointer1, int* pointer2) {
+ uintptr_t predicate_state = all_ones_mask;
+ if (condition) {
+ // Assuming ?: is implemented using branchless logic...
+ predicate_state = !condition ? all_zeros_mask : predicate_state;
+ // ... lots of code ...
+ //
+ // Harden the pointer so it can't be loaded
+ pointer1 &= predicate_state;
+ leak(*pointer1);
+ } else {
+ predicate_state = condition ? all_zeros_mask : predicate_state;
+ // ... more code ...
+ //
+ // Alternative: Harden the loaded value
+ int value2 = *pointer2 & predicate_state;
+ leak(value2);
+ }
+}
+</pre></div>
+</div>
+<p>The result should be that if the branch is mis-predicted,
+there is a <em>data</em> dependency on the condition used to zero out any pointers
+prior to loading through them or to zero out all of the loaded bits. Even
+though this code pattern may still execute speculatively, <em>invalid</em> speculative
+executions are prevented from leaking secret data from memory (but note that
+this data might still be loaded in safe ways, and some regions of memory are
+required to not hold secrets, see below for detailed limitations). This
+approach only requires the underlying hardware have a way to implement a
+branchless and unpredicted conditional update of a registerâs value. All modern
+architectures have support for this, and in fact such support is necessary to
+correctly implement constant time cryptographic primitives.</p>
+<p>Crucial properties of this approach:</p>
+<ul class="simple">
+<li>It is not preventing any particular side-channel from working. This is
+important as there are an unknown number of potential side channels and we
+expect to continue discovering more. Instead, it prevents the observation of
+secret data in the first place.</li>
+<li>It accumulates the predicate state, protecting even in the face of nested
+<em>correctly</em> predicted control flows.</li>
+<li>It passes this predicate state across function boundaries to provide
+<a class="reference external" href="#interprocedural-checking">interprocedural protection</a>.</li>
+<li>When hardening the address of a load, it uses a <em>destructive</em> or
+<em>non-reversible</em> modification of the address to prevent an attacker from
+reversing the check using attacker-controlled inputs.</li>
+<li>It does not completely block speculative execution, and merely prevents
+<em>mis</em>-speculated paths from leaking secrets from memory (and stalls
+speculation until this can be determined).</li>
+<li>It is completely general and makes no fundamental assumptions about the
+underlying architecture other than the ability to do branchless conditional
+data updates and a lack of value prediction.</li>
+<li>It does not require programmers to identify all possible secret data using
+static source code annotations or code vulnerable to a variant #1 style
+attack.</li>
+</ul>
+<p>Limitations of this approach:</p>
+<ul class="simple">
+<li>It requires re-compiling source code to insert hardening instruction
+sequences. Only software compiled in this mode is protected.</li>
+<li>The performance is heavily dependent on a particular architectureâs
+implementation strategy. We outline a potential x86 implementation below and
+characterize its performance.</li>
+<li>It does not defend against secret data already loaded from memory and
+residing in registers or leaked through other side-channels in
+non-speculative execution. Code dealing with this, e.g cryptographic
+routines, already uses constant-time algorithms and code to prevent
+side-channels. Such code should also scrub registers of secret data following
+<a class="reference external" href="https://github.com/HACS-workshop/spectre-mitigations/blob/master/crypto_guidelines.md">these
+guidelines</a>.</li>
+<li>To achieve reasonable performance, many loads may not be checked, such as
+those with compile-time fixed addresses. This primarily consists of accesses
+at compile-time constant offsets of global and local variables. Code which
+needs this protection and intentionally stores secret data must ensure the
+memory regions used for secret data are necessarily dynamic mappings or heap
+allocations. This is an area which can be tuned to provide more comprehensive
+protection at the cost of performance.</li>
+<li><a class="reference external" href="#hardening-the-address-of-the-load">Hardened loads</a> may still load data from
+<em>valid</em> addresses if not <em>attacker-controlled</em> addresses. To prevent these
+from reading secret data, the low 2gb of the address space and 2gb above and
+below any executable pages should be protected.</li>
+</ul>
+<p>Credit:</p>
+<ul class="simple">
+<li>The core idea of tracing misspeculation through data and marking pointers to
+block misspeculated loads was developed as part of a HACS 2018 discussion
+between Chandler Carruth, Paul Kocher, Thomas Pornin, and several other
+individuals.</li>
+<li>Core idea of masking out loaded bits was part of the original mitigation
+suggested by Jann Horn when these attacks were reported.</li>
+</ul>
+<div class="section" id="indirect-branches-calls-and-returns">
+<h3>Indirect Branches, Calls, and Returns<a class="headerlink" href="#indirect-branches-calls-and-returns" title="Permalink to this headline">¶</a></h3>
+<p>It is possible to attack control flow other than conditional branches with
+variant #1 style mispredictions.</p>
+<ul class="simple">
+<li>A prediction towards a hot call target of a virtual method can lead to it
+being speculatively executed when an expected type is used (often called
+âtype confusionâ).</li>
+<li>A hot case may be speculatively executed due to prediction instead of the
+correct case for a switch statement implemented as a jump table.</li>
+<li>A hot common return address may be predicted incorrectly when returning from
+a function.</li>
+</ul>
+<p>These code patterns are also vulnerable to Spectre variant #2, and as such are
+best mitigated with a
+<a class="reference external" href="https://support.google.com/faqs/answer/7625886">retpoline</a> on x86 platforms.
+When a mitigation technique like retpoline is used, speculation simply cannot
+proceed through an indirect control flow edge (or it cannot be mispredicted in
+the case of a filled RSB) and so it is also protected from variant #1 style
+attacks. However, some architectures, micro-architectures, or vendors do not
+employ the retpoline mitigation, and on future x86 hardware (both Intel and
+AMD) it is expected to become unnecessary due to hardware-based mitigation.</p>
+<p>When not using a retpoline, these edges will need independent protection from
+variant #1 style attacks. The analogous approach to that used for conditional
+control flow should work:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>uintptr_t all_ones_mask = std::numerical_limits<uintptr_t>::max();
+uintptr_t all_zeros_mask = 0;
+void leak(int data);
+void example(int* pointer1, int* pointer2) {
+ uintptr_t predicate_state = all_ones_mask;
+ switch (condition) {
+ case 0:
+ // Assuming ?: is implemented using branchless logic...
+ predicate_state = (condition != 0) ? all_zeros_mask : predicate_state;
+ // ... lots of code ...
+ //
+ // Harden the pointer so it can't be loaded
+ pointer1 &= predicate_state;
+ leak(*pointer1);
+ break;
+
+ case 1:
+ predicate_state = (condition != 1) ? all_zeros_mask : predicate_state;
+ // ... more code ...
+ //
+ // Alternative: Harden the loaded value
+ int value2 = *pointer2 & predicate_state;
+ leak(value2);
+ break;
+
+ // ...
+ }
+}
+</pre></div>
+</div>
+<p>The core idea remains the same: validate the control flow using data-flow and
+use that validation to check that loads cannot leak information along
+misspeculated paths. Typically this involves passing the desired target of such
+control flow across the edge and checking that it is correct afterwards. Note
+that while it is tempting to think that this mitigates variant #2 attacks, it
+does not. Those attacks go to arbitrary gadgets that donât include the checks.</p>
+</div>
+<div class="section" id="variant-1-1-and-1-2-attacks-bounds-check-bypass-store">
+<h3>Variant #1.1 and #1.2 attacks: âBounds Check Bypass Storeâ<a class="headerlink" href="#variant-1-1-and-1-2-attacks-bounds-check-bypass-store" title="Permalink to this headline">¶</a></h3>
+<p>Beyond the core variant #1 attack, there are techniques to extend this attack.
+The primary technique is known as âBounds Check Bypass Storeâ and is discussed
+in this research paper: https://people.csail.mit.edu/vlk/spectre11.pdf</p>
+<p>We will analyze these two variants independently. First, variant #1.1 works by
+speculatively storing over the return address after a bounds check bypass. This
+speculative store then ends up being used by the CPU during speculative
+execution of the return, potentially directing speculative execution to
+arbitrary gadgets in the binary. Letâs look at an example.</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">unsigned</span> <span class="n">char</span> <span class="n">local_buffer</span><span class="p">[</span><span class="mi">4</span><span class="p">];</span>
+<span class="n">unsigned</span> <span class="n">char</span> <span class="o">*</span><span class="n">untrusted_data_from_caller</span> <span class="o">=</span> <span class="o">...</span><span class="p">;</span>
+<span class="n">unsigned</span> <span class="n">long</span> <span class="n">untrusted_size_from_caller</span> <span class="o">=</span> <span class="o">...</span><span class="p">;</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">untrusted_size_from_caller</span> <span class="o"><</span> <span class="n">sizeof</span><span class="p">(</span><span class="n">local_buffer</span><span class="p">))</span> <span class="p">{</span>
+ <span class="o">//</span> <span class="n">Speculative</span> <span class="n">execution</span> <span class="n">enters</span> <span class="n">here</span> <span class="k">with</span> <span class="n">a</span> <span class="n">too</span><span class="o">-</span><span class="n">large</span> <span class="n">size</span><span class="o">.</span>
+ <span class="n">memcpy</span><span class="p">(</span><span class="n">local_buffer</span><span class="p">,</span> <span class="n">untrusted_data_from_caller</span><span class="p">,</span>
+ <span class="n">untrusted_size_from_caller</span><span class="p">);</span>
+ <span class="o">//</span> <span class="n">The</span> <span class="n">stack</span> <span class="n">has</span> <span class="n">now</span> <span class="n">been</span> <span class="n">smashed</span><span class="p">,</span> <span class="n">writing</span> <span class="n">an</span> <span class="n">attacker</span><span class="o">-</span><span class="n">controlled</span>
+ <span class="o">//</span> <span class="n">address</span> <span class="n">over</span> <span class="n">the</span> <span class="k">return</span> <span class="n">adress</span><span class="o">.</span>
+ <span class="n">minor_processing</span><span class="p">(</span><span class="n">local_buffer</span><span class="p">);</span>
+ <span class="k">return</span><span class="p">;</span>
+ <span class="o">//</span> <span class="n">Control</span> <span class="n">will</span> <span class="n">speculate</span> <span class="n">to</span> <span class="n">the</span> <span class="n">attacker</span><span class="o">-</span><span class="n">written</span> <span class="n">address</span><span class="o">.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>However, this can be mitigated by hardening the load of the return address just
+like any other load. This is sometimes complicated because x86 for example
+<em>implicitly</em> loads the return address off the stack. However, the
+implementation technique below is specifically designed to mitigate this
+implicit load by using the stack pointer to communicate misspeculation between
+functions. This additionally causes a misspeculation to have an invalid stack
+pointer and never be able to read the speculatively stored return address. See
+the detailed discussion below.</p>
+<p>For variant #1.2, the attacker speculatively stores into the vtable or jump
+table used to implement an indirect call or indirect jump. Because this is
+speculative, this will often be possible even when these are stored in
+read-only pages. For example:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>class FancyObject : public BaseObject {
+public:
+ void DoSomething() override;
+};
+void f(unsigned long attacker_offset, unsigned long attacker_data) {
+ FancyObject object = getMyObject();
+ unsigned long *arr[4] = getFourDataPointers();
+ if (attacker_offset < 4) {
+ // We have bypassed the bounds check speculatively.
+ unsigned long *data = arr[attacker_offset];
+ // Now we have computed a pointer inside of `object`, the vptr.
+ *data = attacker_data;
+ // The vptr points to the virtual table and we speculatively clobber that.
+ g(object); // Hand the object to some other routine.
+ }
+}
+// In another file, we call a method on the object.
+void g(BaseObject &object) {
+ object.DoSomething();
+ // This speculatively calls the address stored over the vtable.
+}
+</pre></div>
+</div>
+<p>Mitigating this requires hardening loads from these locations, or mitigating
+the indirect call or indirect jump. Any of these are sufficient to block the
+call or jump from using a speculatively stored value that has been read back.</p>
+<p>For both of these, using retpolines would be equally sufficient. One possible
+hybrid approach is to use retpolines for indirect call and jump, while relying
+on SLH to mitigate returns.</p>
+<p>Another approach that is sufficient for both of these is to harden all of the
+speculative stores. However, as most stores arenât interesting and donât
+inherently leak data, this is expected to be prohibitively expensive given the
+attack it is defending against.</p>
+</div>
+</div>
+<div class="section" id="implementation-details">
+<h2>Implementation Details<a class="headerlink" href="#implementation-details" title="Permalink to this headline">¶</a></h2>
+<p>There are a number of complex details impacting the implementation of this
+technique, both on a particular architecture and within a particular compiler.
+We discuss proposed implementation techniques for the x86 architecture and the
+LLVM compiler. These are primarily to serve as an example, as other
+implementation techniques are very possible.</p>
+<div class="section" id="x86-implementation-details">
+<h3>x86 Implementation Details<a class="headerlink" href="#x86-implementation-details" title="Permalink to this headline">¶</a></h3>
+<p>On the x86 platform we break down the implementation into three core
+components: accumulating the predicate state through the control flow graph,
+checking the loads, and checking control transfers between procedures.</p>
+<div class="section" id="accumulating-predicate-state">
+<h4>Accumulating Predicate State<a class="headerlink" href="#accumulating-predicate-state" title="Permalink to this headline">¶</a></h4>
+<p>Consider baseline x86 instructions like the following, which test three
+conditions and if all pass, loads data from memory and potentially leaks it
+through some side channel:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># %bb.0: # %entry</span>
+ <span class="n">pushq</span> <span class="o">%</span><span class="n">rax</span>
+ <span class="n">testl</span> <span class="o">%</span><span class="n">edi</span><span class="p">,</span> <span class="o">%</span><span class="n">edi</span>
+ <span class="n">jne</span> <span class="o">.</span><span class="n">LBB0_4</span>
+<span class="c1"># %bb.1: # %then1</span>
+ <span class="n">testl</span> <span class="o">%</span><span class="n">esi</span><span class="p">,</span> <span class="o">%</span><span class="n">esi</span>
+ <span class="n">jne</span> <span class="o">.</span><span class="n">LBB0_4</span>
+<span class="c1"># %bb.2: # %then2</span>
+ <span class="n">testl</span> <span class="o">%</span><span class="n">edx</span><span class="p">,</span> <span class="o">%</span><span class="n">edx</span>
+ <span class="n">je</span> <span class="o">.</span><span class="n">LBB0_3</span>
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %exit</span>
+ <span class="n">popq</span> <span class="o">%</span><span class="n">rax</span>
+ <span class="n">retq</span>
+<span class="o">.</span><span class="n">LBB0_3</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">movl</span> <span class="p">(</span><span class="o">%</span><span class="n">rcx</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span>
+ <span class="n">callq</span> <span class="n">leak</span>
+ <span class="n">popq</span> <span class="o">%</span><span class="n">rax</span>
+ <span class="n">retq</span>
+</pre></div>
+</div>
+<p>When we go to speculatively execute the load, we want to know whether any of
+the dynamically executed predicates have been misspeculated. To track that,
+along each conditional edge, we need to track the data which would allow that
+edge to be taken. On x86, this data is stored in the flags register used by the
+conditional jump instruction. Along both edges after this fork in control flow,
+the flags register remains alive and contains data that we can use to build up
+our accumulated predicate state. We accumulate it using the x86 conditional
+move instruction which also reads the flag registers where the state resides.
+These conditional move instructions are known to not be predicted on any x86
+processors, making them immune to misprediction that could reintroduce the
+vulnerability. When we insert the conditional moves, the code ends up looking
+like the following:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span># %bb.0: # %entry
+ pushq %rax
+ xorl %eax, %eax # Zero out initial predicate state.
+ movq $-1, %r8 # Put all-ones mask into a register.
+ testl %edi, %edi
+ jne .LBB0_1
+# %bb.2: # %then1
+ cmovneq %r8, %rax # Conditionally update predicate state.
+ testl %esi, %esi
+ jne .LBB0_1
+# %bb.3: # %then2
+ cmovneq %r8, %rax # Conditionally update predicate state.
+ testl %edx, %edx
+ je .LBB0_4
+.LBB0_1:
+ cmoveq %r8, %rax # Conditionally update predicate state.
+ popq %rax
+ retq
+.LBB0_4: # %danger
+ cmovneq %r8, %rax # Conditionally update predicate state.
+ ...
+</pre></div>
+</div>
+<p>Here we create the âemptyâ or âcorrect executionâ predicate state by zeroing
+, and we create a constant âincorrect executionâ predicate value by
+putting into . Then, along each edge coming out of a conditional
+branch we do a conditional move that in a correct execution will be a no-op,
+but if misspeculated, will replace the with the value of .
+Misspeculating any one of the three predicates will cause to hold the
+âincorrect executionâ value from as we preserve incoming values when
+execution is correct rather than overwriting it.</p>
+<p>We now have a value in in each basic block that indicates if at some
+point previously a predicate was mispredicted. And we have arranged for that
+value to be particularly effective when used below to harden loads.</p>
+<div class="section" id="indirect-call-branch-and-return-predicates">
+<h5>Indirect Call, Branch, and Return Predicates<a class="headerlink" href="#indirect-call-branch-and-return-predicates" title="Permalink to this headline">¶</a></h5>
+<p>There is no analogous flag to use when tracing indirect calls, branches, and
+returns. The predicate state must be accumulated through some other means.
+Fundamentally, this is the reverse of the problem posed in CFI: we need to
+check where we came from rather than where we are going. For function-local
+jump tables, this is easily arranged by testing the input to the jump table
+within each destination (not yet implemented, use retpolines):</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> pushq %rax
+ xorl %eax, %eax # Zero out initial predicate state.
+ movq $-1, %r8 # Put all-ones mask into a register.
+ jmpq *.LJTI0_0(,%rdi,8) # Indirect jump through table.
+.LBB0_2: # %sw.bb
+ testq $0, %rdi # Validate index used for jump table.
+ cmovneq %r8, %rax # Conditionally update predicate state.
+ ...
+ jmp _Z4leaki # TAILCALL
+
+.LBB0_3: # %sw.bb1
+ testq $1, %rdi # Validate index used for jump table.
+ cmovneq %r8, %rax # Conditionally update predicate state.
+ ...
+ jmp _Z4leaki # TAILCALL
+
+.LBB0_5: # %sw.bb10
+ testq $2, %rdi # Validate index used for jump table.
+ cmovneq %r8, %rax # Conditionally update predicate state.
+ ...
+ jmp _Z4leaki # TAILCALL
+ ...
+
+ .section .rodata,"a", at progbits
+ .p2align 3
+.LJTI0_0:
+ .quad .LBB0_2
+ .quad .LBB0_3
+ .quad .LBB0_5
+ ...
+</pre></div>
+</div>
+<p>Returns have a simple mitigation technique on x86-64 (or other ABIs which have
+what is called a âred zoneâ region beyond the end of the stack). This region is
+guaranteed to be preserved across interrupts and context switches, making the
+return address used in returning to the current code remain on the stack and
+valid to read. We can emit code in the caller to verify that a return edge was
+not mispredicted:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">callq</span> <span class="n">other_function</span>
+<span class="n">return_addr</span><span class="p">:</span>
+ <span class="n">testq</span> <span class="o">-</span><span class="mi">8</span><span class="p">(</span><span class="o">%</span><span class="n">rsp</span><span class="p">),</span> <span class="n">return_addr</span> <span class="c1"># Validate return address.</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Update predicate state.</span>
+</pre></div>
+</div>
+<p>For an ABI without a âred zoneâ (and thus unable to read the return address
+from the stack), we can compute the expected return address prior to the call
+into a register preserved across the call and use that similarly to the above.</p>
+<p>Indirect calls (and returns in the absence of a red zone ABI) pose the most
+significant challenge to propagate. The simplest technique would be to define a
+new ABI such that the intended call target is passed into the called function
+and checked in the entry. Unfortunately, new ABIs are quite expensive to deploy
+in C and C++. While the target function could be passed in TLS, we would still
+require complex logic to handle a mixture of functions compiled with and
+without this extra logic (essentially, making the ABI backwards compatible).
+Currently, we suggest using retpolines here and will continue to investigate
+ways of mitigating this.</p>
+</div>
+<div class="section" id="optimizations-alternatives-and-tradeoffs">
+<h5>Optimizations, Alternatives, and Tradeoffs<a class="headerlink" href="#optimizations-alternatives-and-tradeoffs" title="Permalink to this headline">¶</a></h5>
+<p>Merely accumulating predicate state involves significant cost. There are
+several key optimizations we employ to minimize this and various alternatives
+that present different tradeoffs in the generated code.</p>
+<p>First, we work to reduce the number of instructions used to track the state:</p>
+<ul class="simple">
+<li>Rather than inserting a instruction along every conditional edge in
+the original program, we track each set of condition flags we need to capture
+prior to entering each basic block and reuse a common sequence for
+those.<ul>
+<li>We could further reuse suffixes when there are multiple
+instructions required to capture the set of flags. Currently this is
+believed to not be worth the cost as paired flags are relatively rare and
+suffixes of them are exceedingly rare.</li>
+</ul>
+</li>
+<li>A common pattern in x86 is to have multiple conditional jump instructions
+that use the same flags but handle different conditions. Naively, we could
+consider each fallthrough between them an âedgeâ but this causes a much more
+complex control flow graph. Instead, we accumulate the set of conditions
+necessary for fallthrough and use a sequence of instructions in a
+single fallthrough edge to track it.</li>
+</ul>
+<p>Second, we trade register pressure for simpler instructions by
+allocating a register for the âbadâ state. We could read that value from memory
+as part of the conditional move instruction, however, this creates more
+micro-ops and requires the load-store unit to be involved. Currently, we place
+the value into a virtual register and allow the register allocator to decide
+when the register pressure is sufficient to make it worth spilling to memory
+and reloading.</p>
+</div>
+</div>
+<div class="section" id="hardening-loads">
+<h4>Hardening Loads<a class="headerlink" href="#hardening-loads" title="Permalink to this headline">¶</a></h4>
+<p>Once we have the predicate accumulated into a special value for correct vs.
+misspeculated, we need to apply this to loads in a way that ensures they do not
+leak secret data. There are two primary techniques for this: we can either
+harden the loaded value to prevent observation, or we can harden the address
+itself to prevent the load from occuring. These have significantly different
+performance tradeoffs.</p>
+<div class="section" id="hardening-loaded-values">
+<h5>Hardening loaded values<a class="headerlink" href="#hardening-loaded-values" title="Permalink to this headline">¶</a></h5>
+<p>The most appealing way to harden loads is to mask out all of the bits loaded.
+The key requirement is that for each bit loaded, along the misspeculated path
+that bit is always fixed at either 0 or 1 regardless of the value of the bit
+loaded. The most obvious implementation uses either an instruction with
+an all-zero mask along misspeculated paths and an all-one mask along correct
+paths, or an instruction with an all-one mask along misspeculated paths
+and an all-zero mask along correct paths. Other options become less appealing
+such as multiplying by zero, or multiple shift instructions. For reasons we
+elaborate on below, we end up suggesting you use with an all-ones mask,
+making the x86 instruction sequence look like the following:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Conditionally update predicate state.</span>
+ <span class="n">movl</span> <span class="p">(</span><span class="o">%</span><span class="n">rsi</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span> <span class="c1"># Load potentially secret data from %rsi.</span>
+ <span class="n">orl</span> <span class="o">%</span><span class="n">eax</span><span class="p">,</span> <span class="o">%</span><span class="n">edi</span>
+</pre></div>
+</div>
+<p>Other useful patterns may be to fold the load into the instruction itself
+at the cost of a register-to-register copy.</p>
+<p>There are some challenges with deploying this approach:</p>
+<ol class="simple">
+<li>Many loads on x86 are folded into other instructions. Separating them would
+add very significant and costly register pressure with prohibitive
+performance cost.</li>
+<li>Loads may not target a general purpose register requiring extra instructions
+to map the state value into the correct register class, and potentially more
+expensive instructions to mask the value in some way.</li>
+<li>The flags registers on x86 are very likely to be live, and challenging to
+preserve cheaply.</li>
+<li>There are many more values loaded than pointers & indices used for loads. As
+a consequence, hardening the result of a load requires substantially more
+instructions than hardening the address of the load (see below).</li>
+</ol>
+<p>Despite these challenges, hardening the result of the load critically allows
+the load to proceed and thus has dramatically less impact on the total
+speculative / out-of-order potential of the execution. There are also several
+interesting techniques to try and mitigate these challenges and make hardening
+the results of loads viable in at least some cases. However, we generally
+expect to fall back when unprofitable from hardening the loaded value to the
+next approach of hardening the address itself.</p>
+<div class="section" id="loads-folded-into-data-invariant-operations-can-be-hardened-after-the-operation">
+<h6>Loads folded into data-invariant operations can be hardened after the operation<a class="headerlink" href="#loads-folded-into-data-invariant-operations-can-be-hardened-after-the-operation" title="Permalink to this headline">¶</a></h6>
+<p>The first key to making this feasible is to recognize that many operations on
+x86 are âdata-invariantâ. That is, they have no (known) observable behavior
+differences due to the particular input data. These instructions are often used
+when implementing cryptographic primitives dealing with private key data
+because they are not believed to provide any side-channels. Similarly, we can
+defer hardening until after them as they will not in-and-of-themselves
+introduce a speculative execution side-channel. This results in code sequences
+that look like:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Conditionally update predicate state.</span>
+ <span class="n">addl</span> <span class="p">(</span><span class="o">%</span><span class="n">rsi</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span> <span class="c1"># Load and accumulate without leaking.</span>
+ <span class="n">orl</span> <span class="o">%</span><span class="n">eax</span><span class="p">,</span> <span class="o">%</span><span class="n">edi</span>
+</pre></div>
+</div>
+<p>While an addition happens to the loaded (potentially secret) value, that
+doesnât leak any data and we then immediately harden it.</p>
+</div>
+<div class="section" id="hardening-of-loaded-values-deferred-down-the-data-invariant-expression-graph">
+<h6>Hardening of loaded values deferred down the data-invariant expression graph<a class="headerlink" href="#hardening-of-loaded-values-deferred-down-the-data-invariant-expression-graph" title="Permalink to this headline">¶</a></h6>
+<p>We can generalize the previous idea and sink the hardening down the expression
+graph across as many data-invariant operations as desirable. This can use very
+conservative rules for whether something is data-invariant. The primary goal
+should be to handle multiple loads with a single hardening instruction:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Conditionally update predicate state.</span>
+ <span class="n">addl</span> <span class="p">(</span><span class="o">%</span><span class="n">rsi</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span> <span class="c1"># Load and accumulate without leaking.</span>
+ <span class="n">addl</span> <span class="mi">4</span><span class="p">(</span><span class="o">%</span><span class="n">rsi</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span> <span class="c1"># Continue without leaking.</span>
+ <span class="n">addl</span> <span class="mi">8</span><span class="p">(</span><span class="o">%</span><span class="n">rsi</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span>
+ <span class="n">orl</span> <span class="o">%</span><span class="n">eax</span><span class="p">,</span> <span class="o">%</span><span class="n">edi</span> <span class="c1"># Mask out bits from all three loads.</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="preserving-the-flags-while-hardening-loaded-values-on-haswell-zen-and-newer-processors">
+<h6>Preserving the flags while hardening loaded values on Haswell, Zen, and newer processors<a class="headerlink" href="#preserving-the-flags-while-hardening-loaded-values-on-haswell-zen-and-newer-processors" title="Permalink to this headline">¶</a></h6>
+<p>Sadly, there are no useful instructions on x86 that apply a mask to all 64 bits
+without touching the flag registers. However, we can harden loaded values that
+are narrower than a word (fewer than 32-bits on 32-bit systems and fewer than
+64-bits on 64-bit systems) by zero-extending the value to the full word size
+and then shifting right by at least the number of original bits using the BMI2
+ instruction:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Conditionally update predicate state.</span>
+ <span class="n">addl</span> <span class="p">(</span><span class="o">%</span><span class="n">rsi</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span> <span class="c1"># Load and accumulate 32 bits of data.</span>
+ <span class="n">shrxq</span> <span class="o">%</span><span class="n">rax</span><span class="p">,</span> <span class="o">%</span><span class="n">rdi</span><span class="p">,</span> <span class="o">%</span><span class="n">rdi</span> <span class="c1"># Shift out all 32 bits loaded.</span>
+</pre></div>
+</div>
+<p>Because on x86 the zero-extend is free, this can efficiently harden the loaded
+value.</p>
+</div>
+</div>
+<div class="section" id="hardening-the-address-of-the-load">
+<h5>Hardening the address of the load<a class="headerlink" href="#hardening-the-address-of-the-load" title="Permalink to this headline">¶</a></h5>
+<p>When hardening the loaded value is inapplicable, most often because the
+instruction directly leaks information (like or ), we switch to
+hardening the <em>address</em> of the load instead of the loaded value. This avoids
+increasing register pressure by unfolding the load or paying some other high
+cost.</p>
+<p>To understand how this works in practice, we need to examine the exact
+semantics of the x86 addressing modes which, in its fully general form, looks
+like . Here and are 64-bit
+registers that can potentially be any value, and may be attacker controlled,
+and and are fixed immediate values. must be , ,
+, or , and can be any 32-bit sign extended value. The exact
+computation performed to find the address is then: under 64-bit 2âs complement modular arithmetic.</p>
+<p>One issue with this approach is that, after hardening, the subexpression will compute a value near zero () and
+then a large, positive will index into memory within the first two
+gigabytes of address space. While these offsets are not attacker controlled,
+the attacker could chose to attack a load which happens to have the desired
+offset and then successfully read memory in that region. This significantly
+raises the burden on the attacker and limits the scope of attack but does not
+eliminate it. To fully close the attack we must work with the operating system
+to preclude mapping memory in the low two gigabytes of address space.</p>
+<div class="section" id="bit-load-checking-instructions">
+<h6>64-bit load checking instructions<a class="headerlink" href="#bit-load-checking-instructions" title="Permalink to this headline">¶</a></h6>
+<p>We can use the following instruction sequences to check loads. We set up
+in these examples to hold the special value of which will be ed over
+ in misspeculated paths.</p>
+<p>Single register addressing mode:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Conditionally update predicate state.</span>
+ <span class="n">orq</span> <span class="o">%</span><span class="n">rax</span><span class="p">,</span> <span class="o">%</span><span class="n">rsi</span> <span class="c1"># Mask the pointer if misspeculating.</span>
+ <span class="n">movl</span> <span class="p">(</span><span class="o">%</span><span class="n">rsi</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span>
+</pre></div>
+</div>
+<p>Two register addressing mode:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Conditionally update predicate state.</span>
+ <span class="n">orq</span> <span class="o">%</span><span class="n">rax</span><span class="p">,</span> <span class="o">%</span><span class="n">rsi</span> <span class="c1"># Mask the pointer if misspeculating.</span>
+ <span class="n">orq</span> <span class="o">%</span><span class="n">rax</span><span class="p">,</span> <span class="o">%</span><span class="n">rcx</span> <span class="c1"># Mask the index if misspeculating.</span>
+ <span class="n">movl</span> <span class="p">(</span><span class="o">%</span><span class="n">rsi</span><span class="p">,</span><span class="o">%</span><span class="n">rcx</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span>
+</pre></div>
+</div>
+<p>This will result in a negative address near zero or in wrapping the
+address space back to a small positive address. Small, negative addresses will
+fault in user-mode for most operating systems, but targets which need the high
+address space to be user accessible may need to adjust the exact sequence used
+above. Additionally, the low addresses will need to be marked unreadable by the
+OS to fully harden the load.</p>
+</div>
+<div class="section" id="rip-relative-addressing-is-even-easier-to-break">
+<h6>RIP-relative addressing is even easier to break<a class="headerlink" href="#rip-relative-addressing-is-even-easier-to-break" title="Permalink to this headline">¶</a></h6>
+<p>There is a common addressing mode idiom that is substantially harder to check:
+addressing relative to the instruction pointer. We cannot change the value of
+the instruction pointer register and so we have the harder problem of forcing
+ to be an invalid address, by <em>only</em> changing
+. The only advantage we have is that the attacker also cannot modify
+. If we use the fast instruction sequence above, but only apply it to
+the index, we will always access . If the
+attacker can find a load which with this address happens to point to secret
+data, then they can reach it. However, the loader and base libraries can also
+simply refuse to map the heap, data segments, or stack within 2gb of any of the
+text in the program, much like it can reserve the low 2gb of address space.</p>
+</div>
+<div class="section" id="the-flag-registers-again-make-everything-hard">
+<h6>The flag registers again make everything hard<a class="headerlink" href="#the-flag-registers-again-make-everything-hard" title="Permalink to this headline">¶</a></h6>
+<p>Unfortunately, the technique of using -instructions has a serious flaw on
+x86. The very thing that makes it easy to accumulate state, the flag registers
+containing predicates, causes serious problems here because they may be alive
+and used by the loading instruction or subsequent instructions. On x86, the
+ instruction <strong>sets</strong> the flags and will override anything already there.
+This makes inserting them into the instruction stream very hazardous.
+Unfortunately, unlike when hardening the loaded value, we have no fallback here
+and so we must have a fully general approach available.</p>
+<p>The first thing we must do when generating these sequences is try to analyze
+the surrounding code to prove that the flags are not in fact alive or being
+used. Typically, it has been set by some other instruction which just happens
+to set the flags register (much like ours!) with no actual dependency. In those
+cases, it is safe to directly insert these instructions. Alternatively we may
+be able to move them earlier to avoid clobbering the used value.</p>
+<p>However, this may ultimately be impossible. In that case, we need to preserve
+the flags around these instructions:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Conditionally update predicate state.</span>
+ <span class="n">pushfq</span>
+ <span class="n">orq</span> <span class="o">%</span><span class="n">rax</span><span class="p">,</span> <span class="o">%</span><span class="n">rcx</span> <span class="c1"># Mask the pointer if misspeculating.</span>
+ <span class="n">orq</span> <span class="o">%</span><span class="n">rax</span><span class="p">,</span> <span class="o">%</span><span class="n">rdx</span> <span class="c1"># Mask the index if misspeculating.</span>
+ <span class="n">popfq</span>
+ <span class="n">movl</span> <span class="p">(</span><span class="o">%</span><span class="n">rcx</span><span class="p">,</span><span class="o">%</span><span class="n">rdx</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span>
+</pre></div>
+</div>
+<p>Using the and instructions saves the flags register around our
+inserted code, but comes at a high cost. First, we must store the flags to the
+stack and reload them. Second, this causes the stack pointer to be adjusted
+dynamically, requiring a frame pointer be used for referring to temporaries
+spilled to the stack, etc.</p>
+<p>On newer x86 processors we can use the and instructions to save
+all of the flags besides the overflow flag in a register rather than on the
+stack. We can then use and to save and restore the overflow flag
+in a register. Combined, this will save and restore flags in the same manner as
+above but using two registers rather than the stack. That is still very
+expensive if slightly less expensive than and in most cases.</p>
+</div>
+<div class="section" id="a-flag-less-alternative-on-haswell-zen-and-newer-processors">
+<h6>A flag-less alternative on Haswell, Zen and newer processors<a class="headerlink" href="#a-flag-less-alternative-on-haswell-zen-and-newer-processors" title="Permalink to this headline">¶</a></h6>
+<p>Starting with the BMI2 x86 instruction set extensions available on Haswell and
+Zen processors, there is an instruction for shifting that does not set any
+flags: . We can use this and the instruction to implement analogous
+code sequences to the above ones. However, these are still very marginally
+slower, as there are fewer ports able to dispatch shift instructions in most
+modern x86 processors than there are for instructions.</p>
+<p>Fast, single register addressing mode:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Conditionally update predicate state.</span>
+ <span class="n">shrxq</span> <span class="o">%</span><span class="n">rax</span><span class="p">,</span> <span class="o">%</span><span class="n">rsi</span><span class="p">,</span> <span class="o">%</span><span class="n">rsi</span> <span class="c1"># Shift away bits if misspeculating.</span>
+ <span class="n">movl</span> <span class="p">(</span><span class="o">%</span><span class="n">rsi</span><span class="p">),</span> <span class="o">%</span><span class="n">edi</span>
+</pre></div>
+</div>
+<p>This will collapse the register to zero or one, and everything but the offset
+in the addressing mode to be less than or equal to 9. This means the full
+address can only be guaranteed to be less than . The OS may wish
+to protect an extra page of the low address space to account for this</p>
+</div>
+</div>
+<div class="section" id="optimizations">
+<h5>Optimizations<a class="headerlink" href="#optimizations" title="Permalink to this headline">¶</a></h5>
+<p>A very large portion of the cost for this approach comes from checking loads in
+this way, so it is important to work to optimize this. However, beyond making
+the instruction sequences to <em>apply</em> the checks efficient (for example by
+avoiding and sequences), the only significant optimization is
+to check fewer loads without introducing a vulnerability. We apply several
+techniques to accomplish that.</p>
+<div class="section" id="don-t-check-loads-from-compile-time-constant-stack-offsets">
+<h6>Donât check loads from compile-time constant stack offsets<a class="headerlink" href="#don-t-check-loads-from-compile-time-constant-stack-offsets" title="Permalink to this headline">¶</a></h6>
+<p>We implement this optimization on x86 by skipping the checking of loads which
+use a fixed frame pointer offset.</p>
+<p>The result of this optimization is that patterns like reloading a spilled
+register or accessing a global field donât get checked. This is a very
+significant performance win.</p>
+</div>
+<div class="section" id="don-t-check-dependent-loads">
+<h6>Donât check dependent loads<a class="headerlink" href="#don-t-check-dependent-loads" title="Permalink to this headline">¶</a></h6>
+<p>A core part of why this mitigation strategy works is that it establishes a
+data-flow check on the loaded address. However, this means that if the address
+itself was already loaded using a checked load, there is no need to check a
+dependent load provided it is within the same basic block as the checked load,
+and therefore has no additional predicates guarding it. Consider code like the
+following:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">movq</span> <span class="p">(</span><span class="o">%</span><span class="n">rcx</span><span class="p">),</span> <span class="o">%</span><span class="n">rdi</span>
+ <span class="n">movl</span> <span class="p">(</span><span class="o">%</span><span class="n">rdi</span><span class="p">),</span> <span class="o">%</span><span class="n">edx</span>
+</pre></div>
+</div>
+<p>This will get transformed into:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="o">...</span>
+
+<span class="o">.</span><span class="n">LBB0_4</span><span class="p">:</span> <span class="c1"># %danger</span>
+ <span class="n">cmovneq</span> <span class="o">%</span><span class="n">r8</span><span class="p">,</span> <span class="o">%</span><span class="n">rax</span> <span class="c1"># Conditionally update predicate state.</span>
+ <span class="n">orq</span> <span class="o">%</span><span class="n">rax</span><span class="p">,</span> <span class="o">%</span><span class="n">rcx</span> <span class="c1"># Mask the pointer if misspeculating.</span>
+ <span class="n">movq</span> <span class="p">(</span><span class="o">%</span><span class="n">rcx</span><span class="p">),</span> <span class="o">%</span><span class="n">rdi</span> <span class="c1"># Hardened load.</span>
+ <span class="n">movl</span> <span class="p">(</span><span class="o">%</span><span class="n">rdi</span><span class="p">),</span> <span class="o">%</span><span class="n">edx</span> <span class="c1"># Unhardened load due to dependent addr.</span>
+</pre></div>
+</div>
+<p>This doesnât check the load through as that pointer is dependent on a
+checked load already.</p>
+</div>
+<div class="section" id="protect-large-load-heavy-blocks-with-a-single-lfence">
+<h6>Protect large, load-heavy blocks with a single lfence<a class="headerlink" href="#protect-large-load-heavy-blocks-with-a-single-lfence" title="Permalink to this headline">¶</a></h6>
+<p>It may be worth using a single instruction at the start of a block
+which begins with a (very) large number of loads that require independent
+protection <em>and</em> which require hardening the address of the load. However, this
+is unlikely to be profitable in practice. The latency hit of the hardening
+would need to exceed that of an when <em>correctly</em> speculatively
+executed. But in that case, the cost is a complete loss of speculative
+execution (at a minimum). So far, the evidence we have of the performance cost
+of using indicates few if any hot code patterns where this trade off
+would make sense.</p>
+</div>
+<div class="section" id="tempting-optimizations-that-break-the-security-model">
+<h6>Tempting optimizations that break the security model<a class="headerlink" href="#tempting-optimizations-that-break-the-security-model" title="Permalink to this headline">¶</a></h6>
+<p>Several optimizations were considered which didnât pan out due to failure to
+uphold the security model. One in particular is worth discussing as many others
+will reduce to it.</p>
+<p>We wondered whether only the <em>first</em> load in a basic block could be checked. If
+the check works as intended, it forms an invalid pointer that doesnât even
+virtual-address translate in the hardware. It should fault very early on in its
+processing. Maybe that would stop things in time for the misspeculated path to
+fail to leak any secrets. This doesnât end up working because the processor is
+fundamentally out-of-order, even in its speculative domain. As a consequence,
+the attacker could cause the initial address computation itself to stall and
+allow an arbitrary number of unrelated loads (including attacked loads of
+secret data) to pass through.</p>
+</div>
+</div>
+</div>
+<div class="section" id="interprocedural-checking">
+<h4>Interprocedural Checking<a class="headerlink" href="#interprocedural-checking" title="Permalink to this headline">¶</a></h4>
+<p>Modern x86 processors may speculate into called functions and out of functions
+to their return address. As a consequence, we need a way to check loads that
+occur after a misspeculated predicate but where the load and the misspeculated
+predicate are in different functions. In essence, we need some interprocedural
+generalization of the predicate state tracking. A primary challenge to passing
+the predicate state between functions is that we would like to not require a
+change to the ABI or calling convention in order to make this mitigation more
+deployable, and further would like code mitigated in this way to be easily
+mixed with code not mitigated in this way and without completely losing the
+value of the mitigation.</p>
+<div class="section" id="embed-the-predicate-state-into-the-high-bit-s-of-the-stack-pointer">
+<h5>Embed the predicate state into the high bit(s) of the stack pointer<a class="headerlink" href="#embed-the-predicate-state-into-the-high-bit-s-of-the-stack-pointer" title="Permalink to this headline">¶</a></h5>
+<p>We can use the same technique that allows hardening pointers to pass the
+predicate state into and out of functions. The stack pointer is trivially
+passed between functions and we can test for it having the high bits set to
+detect when it has been marked due to misspeculation. The callsite instruction
+sequence looks like (assuming a misspeculated state value of ):</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> ...
+
+.LBB0_4: # %danger
+ cmovneq %r8, %rax # Conditionally update predicate state.
+ shlq $47, %rax
+ orq %rax, %rsp
+ callq other_function
+ movq %rsp, %rax
+ sarq 63, %rax # Sign extend the high bit to all bits.
+</pre></div>
+</div>
+<p>This first puts the predicate state into the high bits of before calling
+the function and then reads it back out of high bits of afterward. When
+correctly executing (speculatively or not), these are all no-ops. When
+misspeculating, the stack pointer will end up negative. We arrange for it to
+remain a canonical address, but otherwise leave the low bits alone to allow
+stack adjustments to proceed normally without disrupting this. Within the
+called function, we can extract this predicate state and then reset it on
+return:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>other_function:
+ # prolog
+ callq other_function
+ movq %rsp, %rax
+ sarq 63, %rax # Sign extend the high bit to all bits.
+ # ...
+
+.LBB0_N:
+ cmovneq %r8, %rax # Conditionally update predicate state.
+ shlq $47, %rax
+ orq %rax, %rsp
+ retq
+</pre></div>
+</div>
+<p>This approach is effective when all code is mitigated in this fashion, and can
+even survive very limited reaches into unmitigated code (the state will
+round-trip in and back out of an unmitigated function, it just wonât be
+updated). But it does have some limitations. There is a cost to merging the
+state into and it doesnât insulate mitigated code from misspeculation in
+an unmitigated caller.</p>
+<p>There is also an advantage to using this form of interprocedural mitigation: by
+forming these invalid stack pointer addresses we can prevent speculative
+returns from successfully reading speculatively written values to the actual
+stack. This works first by forming a data-dependency between computing the
+address of the return address on the stack and our predicate state. And even
+when satisfied, if a misprediction causes the state to be poisoned the
+resulting stack pointer will be invalid.</p>
+</div>
+<div class="section" id="rewrite-api-of-internal-functions-to-directly-propagate-predicate-state">
+<h5>Rewrite API of internal functions to directly propagate predicate state<a class="headerlink" href="#rewrite-api-of-internal-functions-to-directly-propagate-predicate-state" title="Permalink to this headline">¶</a></h5>
+<p>(Not yet implemented.)</p>
+<p>We have the option with internal functions to directly adjust their API to
+accept the predicate as an argument and return it. This is likely to be
+marginally cheaper than embedding into for entering functions.</p>
+</div>
+<div class="section" id="use-to-guard-function-transitions">
+<h5>Use to guard function transitions<a class="headerlink" href="#use-to-guard-function-transitions" title="Permalink to this headline">¶</a></h5>
+<p>An instruction can be used to prevent subsequent loads from
+speculatively executing until all prior mispredicted predicates have resolved.
+We can use this broader barrier to speculative loads executing between
+functions. We emit it in the entry block to handle calls, and prior to each
+return. This approach also has the advantage of providing the strongest degree
+of mitigation when mixed with unmitigated code by halting all misspeculation
+entering a function which is mitigated, regardless of what occured in the
+caller. However, such a mixture is inherently more risky. Whether this kind of
+mixture is a sufficient mitigation requires careful analysis.</p>
+<p>Unfortunately, experimental results indicate that the performance overhead of
+this approach is very high for certain patterns of code. A classic example is
+any form of recursive evaluation engine. The hot, rapid call and return
+sequences exhibit dramatic performance loss when mitigated with . This
+component alone can regress performance by 2x or more, making it an unpleasant
+tradeoff even when only used in a mixture of code.</p>
+</div>
+<div class="section" id="use-an-internal-tls-location-to-pass-predicate-state">
+<h5>Use an internal TLS location to pass predicate state<a class="headerlink" href="#use-an-internal-tls-location-to-pass-predicate-state" title="Permalink to this headline">¶</a></h5>
+<p>We can define a special thread-local value to hold the predicate state between
+functions. This avoids direct ABI implications by using a side channel between
+callers and callees to communicate the predicate state. It also allows implicit
+zero-initialization of the state, which allows non-checked code to be the first
+code executed.</p>
+<p>However, this requires a load from TLS in the entry block, a store to TLS
+before every call and every ret, and a load from TLS after every call. As a
+consequence it is expected to be substantially more expensive even than using
+ and potentially within the function entry block.</p>
+</div>
+<div class="section" id="define-a-new-abi-and-or-calling-convention">
+<h5>Define a new ABI and/or calling convention<a class="headerlink" href="#define-a-new-abi-and-or-calling-convention" title="Permalink to this headline">¶</a></h5>
+<p>We could define a new ABI and/or calling convention to explicitly pass the
+predicate state in and out of functions. This may be interesting if none of the
+alternatives have adequate performance, but it makes deployment and adoption
+dramatically more complex, and potentially infeasible.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="high-level-alternative-mitigation-strategies">
+<h2>High-Level Alternative Mitigation Strategies<a class="headerlink" href="#high-level-alternative-mitigation-strategies" title="Permalink to this headline">¶</a></h2>
+<p>There are completely different alternative approaches to mitigating variant 1
+attacks. <a class="reference external" href="https://lwn.net/Articles/743265/">Most</a>
+<a class="reference external" href="https://lwn.net/Articles/744287/">discussion</a> so far focuses on mitigating
+specific known attackable components in the Linux kernel (or other kernels) by
+manually rewriting the code to contain an instruction sequence that is not
+vulnerable. For x86 systems this is done by either injecting an
+instruction along the code path which would leak data if executed speculatively
+or by rewriting memory accesses to have branch-less masking to a known safe
+region. On Intel systems, <a class="reference external" href="https://newsroom.intel.com/wp-content/uploads/sites/11/2018/01/Intel-Analysis-of-Speculative-Execution-Side-Channels.pdf">will prevent the speculative load of secret
+data</a>.
+On AMD systems is currently a no-op, but can be made
+dispatch-serializing by setting an MSR, and thus preclude misspeculation of the
+code path (<a class="reference external" href="https://developer.amd.com/wp-content/resources/Managing-Speculation-on-AMD-Processors.pdf">mitigation G-2 +
+V1-1</a>).</p>
+<p>However, this relies on finding and enumerating all possible points in code
+which could be attacked to leak information. While in some cases static
+analysis is effective at doing this at scale, in many cases it still relies on
+human judgement to evaluate whether code might be vulnerable. Especially for
+software systems which receive less detailed scrutiny but remain sensitive to
+these attacks, this seems like an impractical security model. We need an
+automatic and systematic mitigation strategy.</p>
+<div class="section" id="automatic-on-conditional-edges">
+<h3>Automatic on Conditional Edges<a class="headerlink" href="#automatic-on-conditional-edges" title="Permalink to this headline">¶</a></h3>
+<p>A natural way to scale up the existing hand-coded mitigations is simply to
+inject an instruction into both the target and fallthrough
+destinations of every conditional branch. This ensures that no predicate or
+bounds check can be bypassed speculatively. However, the performance overhead
+of this approach is, simply put, catastrophic. Yet it remains the only truly
+âsecure by defaultâ approach known prior to this effort and serves as the
+baseline for performance.</p>
+<p>One attempt to address the performance overhead of this and make it more
+realistic to deploy is <a class="reference external" href="https://blogs.msdn.microsoft.com/vcblog/2018/01/15/spectre-mitigations-in-msvc/">MSVCâs /Qspectre
+switch</a>.
+Their technique is to use static analysis within the compiler to only insert
+ instructions into conditional edges at risk of attack. However,
+<a class="reference external" href="https://arstechnica.com/gadgets/2018/02/microsofts-compiler-level-spectre-fix-shows-how-hard-this-problem-will-be-to-solve/">initial</a>
+<a class="reference external" href="https://www.paulkocher.com/doc/MicrosoftCompilerSpectreMitigation.html">analysis</a>
+has shown that this approach is incomplete and only catches a small and limited
+subset of attackable patterns which happen to resemble very closely the initial
+proofs of concept. As such, while its performance is acceptable, it does not
+appear to be an adequate systematic mitigation.</p>
+</div>
+</div>
+<div class="section" id="performance-overhead">
+<h2>Performance Overhead<a class="headerlink" href="#performance-overhead" title="Permalink to this headline">¶</a></h2>
+<p>The performance overhead of this style of comprehensive mitigation is very
+high. However, it compares very favorably with previously recommended
+approaches such as the instruction. Just as users can restrict the
+scope of to control its performance impact, this mitigation technique
+could be restricted in scope as well.</p>
+<p>However, it is important to understand what it would cost to get a fully
+mitigated baseline. Here we assume targeting a Haswell (or newer) processor and
+using all of the tricks to improve performance (so leaves the low 2gb
+unprotected and +/- 2gb surrounding any PC in the program). We ran both
+Googleâs microbenchmark suite and a large highly-tuned server built using
+ThinLTO and PGO. All were built with to give access to BMI2
+instructions, and benchmarks were run on large Haswell servers. We collected
+data both with an -based mitigation and load hardening as presented
+here. The summary is that mitigating with load hardening is 1.77x faster than
+mitigating with , and the overhead of load hardening compared to a
+normal program is likely between a 10% overhead and a 50% overhead with most
+large applications seeing a 30% overhead or less.</p>
+<p>| Benchmark | | Load Hardening | Mitigated Speedup |
+| âââââââââââââ | ââ-: | ââââ-: | âââââ-: |
+| Google microbenchmark suite | -74.8% | -36.4% | <strong>2.5x</strong> |
+| Large server QPS (using ThinLTO & PGO) | -62% | -29% | <strong>1.8x</strong> |</p>
+<p>Below is a visualization of the microbenchmark suite results which helps show
+the distribution of results that is somewhat lost in the summary. The y-axis is
+a log-scale speedup ratio of load hardening relative to (up -> faster
+-> better). Each box-and-whiskers represents one microbenchmark which may have
+many different metrics measured. The red line marks the median, the box marks
+the first and third quartiles, and the whiskers mark the min and max.</p>
+<p><img alt="_images/speculative_load_hardening_microbenchmarks.png" src="_images/speculative_load_hardening_microbenchmarks.png" />Microbenchmark result visualization</p>
+<p>We donât yet have benchmark data on SPEC or the LLVM test suite, but we can
+work on getting that. Still, the above should give a pretty clear
+characterization of the performance, and specific benchmarks are unlikely to
+reveal especially interesting properties.</p>
+<div class="section" id="future-work-fine-grained-control-and-api-integration">
+<h3>Future Work: Fine Grained Control and API-Integration<a class="headerlink" href="#future-work-fine-grained-control-and-api-integration" title="Permalink to this headline">¶</a></h3>
+<p>The performance overhead of this technique is likely to be very significant and
+something users wish to control or reduce. There are interesting options here
+that impact the implementation strategy used.</p>
+<p>One particularly appealing option is to allow both opt-in and opt-out of this
+mitigation at reasonably fine granularity such as on a per-function basis,
+including intelligent handling of inlining decisions â protected code can be
+prevented from inlining into unprotected code, and unprotected code will become
+protected when inlined into protected code. For systems where only a limited
+set of code is reachable by externally controlled inputs, it may be possible to
+limit the scope of mitigation through such mechanisms without compromising the
+applicationâs overall security. The performance impact may also be focused in a
+few key functions that can be hand-mitigated in ways that have lower
+performance overhead while the remainder of the application receives automatic
+protection.</p>
+<p>For both limiting the scope of mitigation or manually mitigating hot functions,
+there needs to be some support for mixing mitigated and unmitigated code
+without completely defeating the mitigation. For the first use case, it would
+be particularly desirable that mitigated code remains safe when being called
+during misspeculation from unmitigated code.</p>
+<p>For the second use case, it may be important to connect the automatic
+mitigation technique to explicit mitigation APIs such as what is described in
+http://wg21.link/p0928 (or any other eventual API) so that there is a clean way
+to switch from automatic to manual mitigation without immediately exposing a
+hole. However, the design for how to do this is hard to come up with until the
+APIs are better established. We will revisit this as those APIs mature.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="StackSafetyAnalysis.html" title="Stack Safety Analysis"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CFIVerify.html" title="Control Flow Verification Tool Design Document"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/SphinxQuickstartTemplate.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/SphinxQuickstartTemplate.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/SphinxQuickstartTemplate.html (added)
+++ www-releases/trunk/8.0.1/docs/SphinxQuickstartTemplate.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,213 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Sphinx Quickstart Template — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Markdown Quickstart Template" href="MarkdownQuickstartTemplate.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" role="navigation" aria-label="related navigation">
+ <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="MarkdownQuickstartTemplate.html" title="Markdown Quickstart Template"
+ 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" role="main">
+
+ <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 <code class="docutils literal notranslate"><span class="pre">docs/SphinxQuickstartTemplate.rst</span></code>. 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 <code class="docutils literal notranslate"><span class="pre">docs/README.txt</span></code> for information.</p>
+<p>Once you have finished with the content, please send the <code class="docutils literal notranslate"><span class="pre">.rst</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Introduction</span></code>, <code class="docutils literal notranslate"><span class="pre">Overview</span></code>, or
+<code class="docutils literal notranslate"><span class="pre">Background</span></code>.</p>
+<p>If possible, make your document a âhow toâ. Give it a name <code class="docutils literal notranslate"><span class="pre">HowTo*.rst</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">monospace</span></code>.</p>
+<p>Use blank lines to separate paragraphs.</p>
+<p>Headings (like <code class="docutils literal notranslate"><span class="pre">Example</span> <span class="pre">Section</span></code> just above) give your document its
+structure. Use the same kind of adornments (e.g. <code class="docutils literal notranslate"><span class="pre">======</span></code> vs. <code class="docutils literal notranslate"><span class="pre">------</span></code>)
+as are used in this document. The adornment must be the same length as the
+text above it. For Vim users, variations of <code class="docutils literal notranslate"><span class="pre">yypVr=</span></code> 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 <code class="docutils literal notranslate"><span class="pre">..</span> <span class="pre">_`link</span> <span class="pre">text`:</span> <span class="pre"><URL></span></code> 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 <code class="docutils literal notranslate"><span class="pre">#.</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">console</span></code> code block (some existing docs use
+<code class="docutils literal notranslate"><span class="pre">bash</span></code>):</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">llvm</span></code> code block.</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">c</span></code>, <code class="docutils literal notranslate"><span class="pre">objc</span></code>, <code class="docutils literal notranslate"><span class="pre">make</span></code>,
+and <code class="docutils literal notranslate"><span class="pre">cmake</span></code>. 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-default notranslate"><div class="highlight"><pre><span></span> <span class="o">.</span>
+ <span class="o">+</span><span class="p">:</span><span class="o">.</span>
+ <span class="o">..</span><span class="p">::</span> <span class="p">::</span>
+ <span class="o">.++</span><span class="p">:</span><span class="o">+</span><span class="p">::</span> <span class="p">::</span><span class="o">+</span><span class="p">:</span><span class="o">.</span><span class="p">:</span><span class="o">.</span>
+ <span class="o">.</span><span class="p">:</span><span class="o">+</span> <span class="p">:</span>
+ <span class="p">::</span><span class="o">.</span><span class="p">::</span><span class="o">..</span><span class="p">::</span> <span class="o">.+.</span>
+ <span class="o">..</span><span class="p">:</span><span class="o">+</span> <span class="p">::</span> <span class="p">:</span>
+<span class="o">......+</span><span class="p">:</span><span class="o">.</span> <span class="o">..</span>
+ <span class="p">:</span><span class="o">++.</span> <span class="o">..</span> <span class="p">:</span>
+ <span class="o">.+</span><span class="p">:::</span><span class="o">+</span><span class="p">::</span> <span class="p">:</span>
+ <span class="o">..</span> <span class="o">.</span> <span class="o">.+</span> <span class="p">::</span>
+ <span class="o">+.</span><span class="p">:</span> <span class="o">.</span><span class="p">::</span><span class="o">+.</span>
+ <span class="o">...+.</span> <span class="o">.</span><span class="p">:</span> <span class="o">.</span>
+ <span class="o">.++</span><span class="p">:</span><span class="o">..</span>
+ <span class="o">...</span>
+</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" role="navigation" aria-label="related navigation">
+ <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="MarkdownQuickstartTemplate.html" title="Markdown Quickstart Template"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/StackMaps.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/StackMaps.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/StackMaps.html (added)
+++ www-releases/trunk/8.0.1/docs/StackMaps.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,578 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Stack maps and patch points in LLVM — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Design and Usage of the InAlloca Attribute" href="InAlloca.html" />
+ <link rel="prev" title="AMDGPU Instructions Notation" href="AMDGPUInstructionNotation.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" role="navigation" aria-label="related navigation">
+ <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="AMDGPUInstructionNotation.html" title="AMDGPU Instructions Notation"
+ 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" role="main">
+
+ <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">â<code class="docutils literal notranslate"><span class="pre">llvm.experimental.stackmap</span></code>â Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-experimental-patchpoint-intrinsic" id="id9">â<code class="docutils literal notranslate"><span class="pre">llvm.experimental.patchpoint.*</span></code>â 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>
+<li><a class="reference internal" href="#supported-architectures" id="id14">Supported Architectures</a></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 <code class="docutils literal notranslate"><span class="pre">live</span> <span class="pre">values</span></code> at a particular
+instruction address. These <code class="docutils literal notranslate"><span class="pre">live</span> <span class="pre">values</span></code> 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"><span class="std std-ref">Stack Map Section</span></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 <code class="docutils literal notranslate"><span class="pre">live</span> <span class="pre">values</span></code> 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"><span class="std std-ref">Computing stack maps</span></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: <code class="docutils literal notranslate"><span class="pre">llvm.experimental.stackmap</span></code> and
+<code class="docutils literal notranslate"><span class="pre">llvm.experimental.patchpoint</span></code>. 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. <code class="docutils literal notranslate"><span class="pre">llvm.experimental.patchpoint</span></code>
+implicitly generates a stack map without the need for an additional
+call to <code class="docutils literal notranslate"><span class="pre">llvm.experimental.stackmap</span></code>). 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. <code class="docutils literal notranslate"><span class="pre">llvm.experimental.stackmap</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">llvm.experimental.patchpoint</span></code>, which reserves space for in-place
+patching without overwriting surrounding code. The
+<code class="docutils literal notranslate"><span class="pre">llvm.experimental.patchpoint</span></code> 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"><span class="std std-ref">Stack Map Section</span></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">â<code class="docutils literal notranslate"><span class="pre">llvm.experimental.stackmap</span></code>â 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">void</span>
+ <span class="nd">@llvm</span><span class="o">.</span><span class="n">experimental</span><span class="o">.</span><span class="n">stackmap</span><span class="p">(</span><span class="n">i64</span> <span class="o"><</span><span class="nb">id</span><span class="o">></span><span class="p">,</span> <span class="n">i32</span> <span class="o"><</span><span class="n">numShadowBytes</span><span class="o">></span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
+</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 â<code class="docutils literal notranslate"><span class="pre">llvm.experimental.stackmap</span></code>â 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 <code class="docutils literal notranslate"><span class="pre">live</span>
+<span class="pre">values</span></code> 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 <code class="docutils literal notranslate"><span class="pre">llvm.experimental.stackmap</span></code> or
+<code class="docutils literal notranslate"><span class="pre">llvm.experimental.patchpoint</span></code> 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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span>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 notranslate"><div class="highlight"><pre><span></span>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">â<code class="docutils literal notranslate"><span class="pre">llvm.experimental.patchpoint.*</span></code>â 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">void</span>
+ <span class="nd">@llvm</span><span class="o">.</span><span class="n">experimental</span><span class="o">.</span><span class="n">patchpoint</span><span class="o">.</span><span class="n">void</span><span class="p">(</span><span class="n">i64</span> <span class="o"><</span><span class="nb">id</span><span class="o">></span><span class="p">,</span> <span class="n">i32</span> <span class="o"><</span><span class="n">numBytes</span><span class="o">></span><span class="p">,</span>
+ <span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">target</span><span class="o">></span><span class="p">,</span> <span class="n">i32</span> <span class="o"><</span><span class="n">numArgs</span><span class="o">></span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
+<span class="n">declare</span> <span class="n">i64</span>
+ <span class="nd">@llvm</span><span class="o">.</span><span class="n">experimental</span><span class="o">.</span><span class="n">patchpoint</span><span class="o">.</span><span class="n">i64</span><span class="p">(</span><span class="n">i64</span> <span class="o"><</span><span class="nb">id</span><span class="o">></span><span class="p">,</span> <span class="n">i32</span> <span class="o"><</span><span class="n">numBytes</span><span class="o">></span><span class="p">,</span>
+ <span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">target</span><span class="o">></span><span class="p">,</span> <span class="n">i32</span> <span class="o"><</span><span class="n">numArgs</span><span class="o">></span><span class="p">,</span> <span class="o">...</span><span class="p">)</span>
+</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 â<code class="docutils literal notranslate"><span class="pre">llvm.experimental.patchpoint.*</span></code>â intrinsics creates a function
+call to the specified <code class="docutils literal notranslate"><span class="pre"><target></span></code> 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 <code class="docutils literal notranslate"><span class="pre">live</span> <span class="pre">values</span></code> 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 <code class="docutils literal notranslate"><span class="pre"><target></span></code> 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 <code class="docutils literal notranslate"><span class="pre"><target></span></code> must be the ABI function pointer for the
+intended target of the indirect call. Specifically, when compiling for the
+ELF V1 ABI, <code class="docutils literal notranslate"><span class="pre"><target></span></code> is the function-descriptor address normally used as
+the C/C++ function-pointer representation.</p>
+<p>Requesting zero patch point arguments is valid. In this case, all
+variable operands are handled just like
+<code class="docutils literal notranslate"><span class="pre">llvm.experimental.stackmap.*</span></code>. 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 <code class="docutils literal notranslate"><span class="pre">live</span> <span class="pre">values</span></code> 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 <code class="docutils literal notranslate"><span class="pre">live</span> <span class="pre">values</span></code>.</p>
+<p>The patch point also emits nops to cover at least <code class="docutils literal notranslate"><span class="pre"><numBytes></span></code> of
+instruction encoding space. Hence, the client must ensure that
+<code class="docutils literal notranslate"><span class="pre"><numBytes></span></code> 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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span>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 <code class="docutils literal notranslate"><span class="pre">anyregcc</span></code> convention may be used:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>%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 notranslate"><div class="highlight"><pre><span></span>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 notranslate"><div class="highlight"><pre><span></span>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"><span class="std std-ref">Stack Map Section</span></a>. The
+format of this section follows:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Header {
+ uint8 : Stack Map Version (current version is 3)
+ 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
+ uint64 : Record Count
+}
+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 (expected to be 0)
+ uint16 : Location Size
+ uint16 : Dwarf RegNum
+ uint16 : Reserved (expected to be 0)
+ int32 : Offset or SmallConstant
+ }
+ uint32 : Padding (only if required to align to 8 byte)
+ 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 <code class="docutils literal notranslate"><span class="pre">RegNum</span></code> and <code class="docutils literal notranslate"><span class="pre">Offset</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">Offset</span></code> field will be zero. Values spilled to the stack are encoded
+as <code class="docutils literal notranslate"><span class="pre">Indirect</span></code> locations. The runtime must load those values from a
+stack address, typically in the form <code class="docutils literal notranslate"><span class="pre">[BP</span> <span class="pre">+</span> <span class="pre">Offset]</span></code>. If an
+<code class="docutils literal notranslate"><span class="pre">alloca</span></code> 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 <code class="docutils literal notranslate"><span class="pre">Direct</span></code> locations in the form <code class="docutils literal notranslate"><span class="pre">BP</span> <span class="pre">+</span> <span class="pre">Offset</span></code>. LLVM may
+also optimize constants by emitting them directly in the stack map,
+either in the <code class="docutils literal notranslate"><span class="pre">Offset</span></code> of a <code class="docutils literal notranslate"><span class="pre">Constant</span></code> location or in the constant
+pool, referred to by <code class="docutils literal notranslate"><span class="pre">ConstantIndex</span></code> 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 <code class="docutils literal notranslate"><span class="pre">%rax</span></code>, then the value may be in either <code class="docutils literal notranslate"><span class="pre">%al</span></code> or
+<code class="docutils literal notranslate"><span class="pre">%ah</span></code>. It doesnât matter in practice, because the runtime will
+simply save <code class="docutils literal notranslate"><span class="pre">%rax</span></code>. However, if the stackmap reports 16 bytes at
+<code class="docutils literal notranslate"><span class="pre">%ymm0</span></code>, then the runtime can safely optimize by saving only
+<code class="docutils literal notranslate"><span class="pre">%xmm0</span></code>.</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
+<code class="docutils literal notranslate"><span class="pre">LLVMCreateSimpleMCJITMemoryManager()</span></code>. When creating the memory
+manager, the JIT provides a callback:
+<code class="docutils literal notranslate"><span class="pre">LLVMMemoryManagerAllocateDataSectionCallback()</span></code>. 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>For MachO (e.g. on Darwin), the stack map section name is
+â__llvm_stackmapsâ. The segment name is â__LLVM_STACKMAPSâ.</p>
+<p>For ELF (e.g. on Linux), 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, records, and functions, 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"><span class="std std-ref">Stack Map Section</span></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 notranslate"><div class="highlight"><pre><span></span>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 class="section" id="supported-architectures">
+<h2><a class="toc-backref" href="#id14">Supported Architectures</a><a class="headerlink" href="#supported-architectures" title="Permalink to this headline">¶</a></h2>
+<p>Support for StackMap generation and the related intrinsics requires
+some code for each backend. Today, only a subset of LLVMâs backends
+are supported. The currently supported architectures are X86_64,
+PowerPC, and Aarch64.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="AMDGPUInstructionNotation.html" title="AMDGPU Instructions Notation"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.1/docs/StackSafetyAnalysis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.1/docs/StackSafetyAnalysis.html?rev=368037&view=auto
==============================================================================
--- www-releases/trunk/8.0.1/docs/StackSafetyAnalysis.html (added)
+++ www-releases/trunk/8.0.1/docs/StackSafetyAnalysis.html Tue Aug 6 06:51:02 2019
@@ -0,0 +1,130 @@
+
+
+<!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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Stack Safety Analysis — LLVM 8 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" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Contributing to LLVM" href="Contributing.html" />
+ <link rel="prev" title="Speculative Load Hardening" href="SpeculativeLoadHardening.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" role="navigation" aria-label="related navigation">
+ <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="Contributing.html" title="Contributing to LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SpeculativeLoadHardening.html" title="Speculative Load Hardening"
+ 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" role="main">
+
+ <div class="section" id="stack-safety-analysis">
+<h1>Stack Safety Analysis<a class="headerlink" href="#stack-safety-analysis" 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 Stack Safety Analysis determines if stack allocated variables can be
+considered âsafeâ from memory access bugs.</p>
+<p>The primary purpose of the analysis is to be used by sanitizers to avoid
+unnecessary instrumentation of âsafeâ variables. SafeStack is going to be the
+first user.</p>
+<p>âsafeâ variables can be defined as variables that can not be used out-of-scope
+(e.g. use-after-return) or accessed out of bounds. In the future it can be
+extended to track other variable properties. E.g. we plan to extend
+implementation with a check to make sure that variable is always initialized
+before every read to optimize use-of-uninitialized-memory checks.</p>
+</div>
+<div class="section" id="how-it-works">
+<h2>How it works<a class="headerlink" href="#how-it-works" title="Permalink to this headline">¶</a></h2>
+<p>The analysis is implemented in two stages:</p>
+<p>The intra-procedural, or âlocalâ, stage performs a depth-first search inside
+functions to collect all uses of each alloca, including loads/stores and uses as
+arguments functions. After this stage we know which parts of the alloca are used
+by functions itself but we donât know what happens after it is passed as
+an argument to another function.</p>
+<p>The inter-procedural, or âglobalâ, stage, resolves what happens to allocas after
+they are passed as function arguments. This stage performs a depth-first search
+on function calls inside a single module and propagates allocas usage through
+functions calls.</p>
+<p>When used with ThinLTO, the global stage performs a whole program analysis over
+the Module Summary Index.</p>
+</div>
+<div class="section" id="testing">
+<h2>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2>
+<p>The analysis is covered with lit tests.</p>
+<p>We expect that users can tolerate false classification of variables as
+âunsafeâ when in-fact itâs âsafeâ. This may lead to inefficient code. However, we
+canât accept false âsafeâ classification which may cause sanitizers to miss actual
+bugs in instrumented code. To avoid that we want additional validation tool.</p>
+<p>AddressSanitizer may help with this validation. We can instrument all variables
+as usual but additionally store stack-safe information in the
+<code class="docutils literal notranslate"><span class="pre">ASanStackVariableDescription</span></code>. Then if AddressSanitizer detects a bug on
+a âsafeâ variable we can produce an additional report to let the user know that
+probably Stack Safety Analysis failed and we should check for a bug in the
+compiler.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <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="Contributing.html" title="Contributing to LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SpeculativeLoadHardening.html" title="Speculative Load Hardening"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-08-05.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list