[www-releases] r326992 - 6.0.0 files
Hans Wennborg via llvm-commits
llvm-commits at lists.llvm.org
Thu Mar 8 02:24:48 PST 2018
Added: www-releases/trunk/6.0.0/docs/Lexicon.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/Lexicon.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/Lexicon.html (added)
+++ www-releases/trunk/6.0.0/docs/Lexicon.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,355 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The LLVM Lexicon — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="How To Add Your Build Configuration To LLVM Buildbot Infrastructure" href="HowToAddABuilder.html" />
+ <link rel="prev" title="Frequently Asked Questions (FAQ)" href="FAQ.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="HowToAddABuilder.html" title="How To Add Your Build Configuration To LLVM Buildbot Infrastructure"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="FAQ.html" title="Frequently Asked Questions (FAQ)"
+ 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="the-llvm-lexicon">
+<h1>The LLVM Lexicon<a class="headerlink" href="#the-llvm-lexicon" title="Permalink to this headline">¶</a></h1>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This document is a work in progress!</p>
+</div>
+<div class="section" id="definitions">
+<h2>Definitions<a class="headerlink" href="#definitions" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="a">
+<h3>A<a class="headerlink" href="#a" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>ADCE</strong></dt>
+<dd>Aggressive Dead Code Elimination</dd>
+<dt><strong>AST</strong></dt>
+<dd><p class="first">Abstract Syntax Tree.</p>
+<p>Due to Clang’s influence (mostly the fact that parsing and semantic
+analysis are so intertwined for C and especially C++), the typical
+working definition of AST in the LLVM community is roughly “the
+compiler’s first complete symbolic (as opposed to textual)
+representation of an input program”.
+As such, an “AST” might be a more general graph instead of a “tree”
+(consider the symbolic representation for the type of a typical “linked
+list node”). This working definition is closer to what some authors
+call an “annotated abstract syntax tree”.</p>
+<p class="last">Consult your favorite compiler book or search engine for more details.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="b">
+<h3>B<a class="headerlink" href="#b" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils" id="lexicon-bb-vectorization">
+<dt><strong>BB Vectorization</strong></dt>
+<dd>Basic-Block Vectorization</dd>
+<dt><strong>BDCE</strong></dt>
+<dd>Bit-tracking dead code elimination. Some bit-wise instructions (shifts,
+ands, ors, etc.) “kill” some of their input bits – that is, they make it
+such that those bits can be either zero or one without affecting control or
+data flow of a program. The BDCE pass removes instructions that only
+compute these dead bits.</dd>
+<dt><strong>BURS</strong></dt>
+<dd>Bottom Up Rewriting System — A method of instruction selection for code
+generation. An example is the <a class="reference external" href="http://www.program-transformation.org/Transform/BURG">BURG</a> tool.</dd>
+</dl>
+</div>
+<div class="section" id="c">
+<h3>C<a class="headerlink" href="#c" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>CFI</strong></dt>
+<dd>Call Frame Information. Used in DWARF debug info and in C++ unwind info
+to show how the function prolog lays out the stack frame.</dd>
+<dt><strong>CIE</strong></dt>
+<dd>Common Information Entry. A kind of CFI used to reduce the size of FDEs.
+The compiler creates a CIE which contains the information common across all
+the FDEs. Each FDE then points to its CIE.</dd>
+<dt><strong>CSE</strong></dt>
+<dd>Common Subexpression Elimination. An optimization that removes common
+subexpression compuation. For example <code class="docutils literal"><span class="pre">(a+b)*(a+b)</span></code> has two subexpressions
+that are the same: <code class="docutils literal"><span class="pre">(a+b)</span></code>. This optimization would perform the addition
+only once and then perform the multiply (but only if it’s computationally
+correct/safe).</dd>
+</dl>
+</div>
+<div class="section" id="d">
+<h3>D<a class="headerlink" href="#d" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>DAG</strong></dt>
+<dd>Directed Acyclic Graph</dd>
+</dl>
+<span id="derived-pointer"></span><dl class="docutils" id="derived-pointers">
+<dt><strong>Derived Pointer</strong></dt>
+<dd>A pointer to the interior of an object, such that a garbage collector is
+unable to use the pointer for reachability analysis. While a derived pointer
+is live, the corresponding object pointer must be kept in a root, otherwise
+the collector might free the referenced object. With copying collectors,
+derived pointers pose an additional hazard that they may be invalidated at
+any <a class="reference internal" href="#safe-point">safe point</a>. This term is used in opposition to <a class="reference internal" href="#object-pointer">object pointer</a>.</dd>
+<dt><strong>DSA</strong></dt>
+<dd>Data Structure Analysis</dd>
+<dt><strong>DSE</strong></dt>
+<dd>Dead Store Elimination</dd>
+</dl>
+</div>
+<div class="section" id="f">
+<h3>F<a class="headerlink" href="#f" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>FCA</strong></dt>
+<dd>First Class Aggregate</dd>
+<dt><strong>FDE</strong></dt>
+<dd>Frame Description Entry. A kind of CFI used to describe the stack frame of
+one function.</dd>
+</dl>
+</div>
+<div class="section" id="g">
+<h3>G<a class="headerlink" href="#g" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>GC</strong></dt>
+<dd>Garbage Collection. The practice of using reachability analysis instead of
+explicit memory management to reclaim unused memory.</dd>
+<dt><strong>GEP</strong></dt>
+<dd><code class="docutils literal"><span class="pre">GetElementPtr</span></code>. An LLVM IR instruction that is used to get the address
+of a subelement of an aggregate data structure. It is documented in detail
+<a class="reference external" href="http://llvm.org/docs/GetElementPtr.html">here</a>.</dd>
+<dt><strong>GVN</strong></dt>
+<dd>Global Value Numbering. GVN is a pass that partitions values computed by a
+function into congruence classes. Values ending up in the same congruence
+class are guaranteed to be the same for every execution of the program.
+In that respect, congruency is a compile-time approximation of equivalence
+of values at runtime.</dd>
+</dl>
+</div>
+<div class="section" id="h">
+<h3>H<a class="headerlink" href="#h" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils" id="heap">
+<dt><strong>Heap</strong></dt>
+<dd>In garbage collection, the region of memory which is managed using
+reachability analysis.</dd>
+</dl>
+</div>
+<div class="section" id="i">
+<h3>I<a class="headerlink" href="#i" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>IPA</strong></dt>
+<dd>Inter-Procedural Analysis. Refers to any variety of code analysis that
+occurs between procedures, functions or compilation units (modules).</dd>
+<dt><strong>IPO</strong></dt>
+<dd>Inter-Procedural Optimization. Refers to any variety of code optimization
+that occurs between procedures, functions or compilation units (modules).</dd>
+<dt><strong>ISel</strong></dt>
+<dd>Instruction Selection</dd>
+</dl>
+</div>
+<div class="section" id="l">
+<h3>L<a class="headerlink" href="#l" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>LCSSA</strong></dt>
+<dd>Loop-Closed Static Single Assignment Form</dd>
+<dt><strong>LGTM</strong></dt>
+<dd>“Looks Good To Me”. In a review thread, this indicates that the
+reviewer thinks that the patch is okay to commit.</dd>
+<dt><strong>LICM</strong></dt>
+<dd>Loop Invariant Code Motion</dd>
+<dt><strong>LSDA</strong></dt>
+<dd>Language Specific Data Area. C++ “zero cost” unwinding is built on top a
+generic unwinding mechanism. As the unwinder walks each frame, it calls
+a “personality” function to do language specific analysis. Each function’s
+FDE points to an optional LSDA which is passed to the personality function.
+For C++, the LSDA contain info about the type and location of catch
+statements in that function.</dd>
+<dt><strong>Load-VN</strong></dt>
+<dd>Load Value Numbering</dd>
+<dt><strong>LTO</strong></dt>
+<dd>Link-Time Optimization</dd>
+</dl>
+</div>
+<div class="section" id="m">
+<h3>M<a class="headerlink" href="#m" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>MC</strong></dt>
+<dd>Machine Code</dd>
+</dl>
+</div>
+<div class="section" id="n">
+<h3>N<a class="headerlink" href="#n" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>NFC</strong></dt>
+<dd>“No functional change”. Used in a commit message to indicate that a patch
+is a pure refactoring/cleanup.
+Usually used in the first line, so it is visible without opening the
+actual commit email.</dd>
+</dl>
+</div>
+<div class="section" id="o">
+<h3>O<a class="headerlink" href="#o" title="Permalink to this headline">¶</a></h3>
+<span id="object-pointer"></span><dl class="docutils" id="object-pointers">
+<dt><strong>Object Pointer</strong></dt>
+<dd>A pointer to an object such that the garbage collector is able to trace
+references contained within the object. This term is used in opposition to
+<a class="reference internal" href="#derived-pointer">derived pointer</a>.</dd>
+</dl>
+</div>
+<div class="section" id="p">
+<h3>P<a class="headerlink" href="#p" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>PR</strong></dt>
+<dd>Problem report. A bug filed on <a class="reference external" href="https://bugs.llvm.org/enter_bug.cgi">the LLVM Bug Tracking System</a>.</dd>
+<dt><strong>PRE</strong></dt>
+<dd>Partial Redundancy Elimination</dd>
+</dl>
+</div>
+<div class="section" id="r">
+<h3>R<a class="headerlink" href="#r" title="Permalink to this headline">¶</a></h3>
+<p><strong>RAUW</strong></p>
+<blockquote>
+<div>Replace All Uses With. The functions <code class="docutils literal"><span class="pre">User::replaceUsesOfWith()</span></code>,
+<code class="docutils literal"><span class="pre">Value::replaceAllUsesWith()</span></code>, and
+<code class="docutils literal"><span class="pre">Constant::replaceUsesOfWithOnConstant()</span></code> implement the replacement of one
+Value with another by iterating over its def/use chain and fixing up all of
+the pointers to point to the new value. See
+also <a class="reference external" href="ProgrammersManual.html#iterating-over-def-use-use-def-chains">def/use chains</a>.</div></blockquote>
+<dl class="docutils">
+<dt><strong>Reassociation</strong></dt>
+<dd>Rearranging associative expressions to promote better redundancy elimination
+and other optimization. For example, changing <code class="docutils literal"><span class="pre">(A+B-A)</span></code> into <code class="docutils literal"><span class="pre">(B+A-A)</span></code>,
+permitting it to be optimized into <code class="docutils literal"><span class="pre">(B+0)</span></code> then <code class="docutils literal"><span class="pre">(B)</span></code>.</dd>
+</dl>
+<span id="roots"></span><dl class="docutils" id="stack-roots">
+<dt><strong>Root</strong></dt>
+<dd>In garbage collection, a pointer variable lying outside of the <a class="reference internal" href="#heap">heap</a> from
+which the collector begins its reachability analysis. In the context of code
+generation, “root” almost always refers to a “stack root” — a local or
+temporary variable within an executing function.</dd>
+<dt><strong>RPO</strong></dt>
+<dd>Reverse postorder</dd>
+</dl>
+</div>
+<div class="section" id="s">
+<h3>S<a class="headerlink" href="#s" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils" id="safe-point">
+<dt><strong>Safe Point</strong></dt>
+<dd>In garbage collection, it is necessary to identify <a class="reference internal" href="#stack-roots">stack roots</a> so that
+reachability analysis may proceed. It may be infeasible to provide this
+information for every instruction, so instead the information may is
+calculated only at designated safe points. With a copying collector,
+<a class="reference internal" href="#derived-pointers">derived pointers</a> must not be retained across safe points and <a class="reference internal" href="#object-pointers">object
+pointers</a> must be reloaded from stack roots.</dd>
+<dt><strong>SDISel</strong></dt>
+<dd>Selection DAG Instruction Selection.</dd>
+<dt><strong>SCC</strong></dt>
+<dd>Strongly Connected Component</dd>
+<dt><strong>SCCP</strong></dt>
+<dd>Sparse Conditional Constant Propagation</dd>
+<dt><strong>SLP</strong></dt>
+<dd>Superword-Level Parallelism, same as <a class="reference internal" href="#lexicon-bb-vectorization"><span class="std std-ref">Basic-Block Vectorization</span></a>.</dd>
+<dt><strong>Splat</strong></dt>
+<dd><p class="first">Splat refers to a vector of identical scalar elements.</p>
+<p class="last">The term is based on the PowerPC Altivec instructions that provided
+this functionality in hardware. For example, “vsplth” and the corresponding
+software intrinsic “vec_splat()”. Examples of other hardware names for this
+action include “duplicate” (ARM) and “broadcast” (x86).</p>
+</dd>
+<dt><strong>SRoA</strong></dt>
+<dd>Scalar Replacement of Aggregates</dd>
+<dt><strong>SSA</strong></dt>
+<dd>Static Single Assignment</dd>
+<dt><strong>Stack Map</strong></dt>
+<dd>In garbage collection, metadata emitted by the code generator which
+identifies <a class="reference internal" href="#roots">roots</a> within the stack frame of an executing function.</dd>
+</dl>
+</div>
+<div class="section" id="t">
+<h3>T<a class="headerlink" href="#t" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>TBAA</strong></dt>
+<dd>Type-Based Alias Analysis</dd>
+</dl>
+</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="HowToAddABuilder.html" title="How To Add Your Build Configuration To LLVM Buildbot Infrastructure"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="FAQ.html" title="Frequently Asked Questions (FAQ)"
+ >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-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/LibFuzzer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/LibFuzzer.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/LibFuzzer.html (added)
+++ www-releases/trunk/6.0.0/docs/LibFuzzer.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,769 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>libFuzzer â a library for coverage-guided fuzz testing. — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="Fuzzing LLVM libraries and tools" href="FuzzingLLVM.html" />
+ <link rel="prev" title="LLVM Extensions" href="Extensions.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="FuzzingLLVM.html" title="Fuzzing LLVM libraries and tools"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Extensions.html" title="LLVM Extensions"
+ 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="libfuzzer-a-library-for-coverage-guided-fuzz-testing">
+<h1>libFuzzer â a library for coverage-guided fuzz testing.<a class="headerlink" href="#libfuzzer-a-library-for-coverage-guided-fuzz-testing" 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="id12">Introduction</a></li>
+<li><a class="reference internal" href="#versions" id="id13">Versions</a></li>
+<li><a class="reference internal" href="#getting-started" id="id14">Getting Started</a></li>
+<li><a class="reference internal" href="#options" id="id15">Options</a></li>
+<li><a class="reference internal" href="#output" id="id16">Output</a></li>
+<li><a class="reference internal" href="#examples" id="id17">Examples</a></li>
+<li><a class="reference internal" href="#advanced-features" id="id18">Advanced features</a></li>
+<li><a class="reference internal" href="#developing-libfuzzer" id="id19">Developing libFuzzer</a></li>
+<li><a class="reference internal" href="#faq" id="id20">FAQ</a></li>
+<li><a class="reference internal" href="#trophies" id="id21">Trophies</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id12">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>LibFuzzer is in-process, coverage-guided, evolutionary fuzzing engine.</p>
+<p>LibFuzzer is linked with the library under test, and feeds fuzzed inputs to the
+library via a specific fuzzing entrypoint (aka “target function”); the fuzzer
+then tracks which areas of the code are reached, and generates mutations on the
+corpus of input data in order to maximize the code coverage.
+The code coverage
+information for libFuzzer is provided by LLVM’s <a class="reference external" href="http://clang.llvm.org/docs/SanitizerCoverage.html">SanitizerCoverage</a>
+instrumentation.</p>
+<p>Contact: libfuzzer(#)googlegroups.com</p>
+</div>
+<div class="section" id="versions">
+<h2><a class="toc-backref" href="#id13">Versions</a><a class="headerlink" href="#versions" title="Permalink to this headline">¶</a></h2>
+<p>LibFuzzer is under active development so you will need the current
+(or at least a very recent) version of the Clang compiler (see <a class="reference external" href="http://clang.llvm.org/get_started.html">building Clang from trunk</a>)</p>
+<p>Refer to <a class="reference external" href="https://releases.llvm.org/5.0.0/docs/LibFuzzer.html">https://releases.llvm.org/5.0.0/docs/LibFuzzer.html</a> for documentation on the older version.</p>
+</div>
+<div class="section" id="getting-started">
+<h2><a class="toc-backref" href="#id14">Getting Started</a><a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
+<div class="contents local topic" id="id1">
+<ul class="simple">
+<li><a class="reference internal" href="#fuzz-target" id="id22">Fuzz Target</a></li>
+<li><a class="reference internal" href="#fuzzer-usage" id="id23">Fuzzer Usage</a></li>
+<li><a class="reference internal" href="#corpus" id="id24">Corpus</a></li>
+<li><a class="reference internal" href="#running" id="id25">Running</a></li>
+<li><a class="reference internal" href="#parallel-fuzzing" id="id26">Parallel Fuzzing</a></li>
+<li><a class="reference internal" href="#resuming-merge" id="id27">Resuming merge</a></li>
+</ul>
+</div>
+<div class="section" id="fuzz-target">
+<h3><a class="toc-backref" href="#id22">Fuzz Target</a><a class="headerlink" href="#fuzz-target" title="Permalink to this headline">¶</a></h3>
+<p>The first step in using libFuzzer on a library is to implement a
+<em>fuzz target</em> – a function that accepts an array of bytes and
+does something interesting with these bytes using the API under test.
+Like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="c1">// fuzz_target.cc</span>
+<span class="k">extern</span> <span class="s">"C"</span> <span class="kt">int</span> <span class="n">LLVMFuzzerTestOneInput</span><span class="p">(</span><span class="k">const</span> <span class="kt">uint8_t</span> <span class="o">*</span><span class="n">Data</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">Size</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">DoSomethingInterestingWithMyAPI</span><span class="p">(</span><span class="n">Data</span><span class="p">,</span> <span class="n">Size</span><span class="p">);</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span> <span class="c1">// Non-zero return values are reserved for future use.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that this fuzz target does not depend on libFuzzer in any way
+and so it is possible and even desirable to use it with other fuzzing engines
+e.g. <a class="reference external" href="http://lcamtuf.coredump.cx/afl/">AFL</a> and/or <a class="reference external" href="https://github.com/aoh/radamsa">Radamsa</a>.</p>
+<p>Some important things to remember about fuzz targets:</p>
+<ul class="simple">
+<li>The fuzzing engine will execute the fuzz target many times with different inputs in the same process.</li>
+<li>It must tolerate any kind of input (empty, huge, malformed, etc).</li>
+<li>It must not <cite>exit()</cite> on any input.</li>
+<li>It may use threads but ideally all threads should be joined at the end of the function.</li>
+<li>It must be as deterministic as possible. Non-determinism (e.g. random decisions not based on the input bytes) will make fuzzing inefficient.</li>
+<li>It must be fast. Try avoiding cubic or greater complexity, logging, or excessive memory consumption.</li>
+<li>Ideally, it should not modify any global state (although that’s not strict).</li>
+<li>Usually, the narrower the target the better. E.g. if your target can parse several data formats, split it into several targets, one per format.</li>
+</ul>
+</div>
+<div class="section" id="fuzzer-usage">
+<h3><a class="toc-backref" href="#id23">Fuzzer Usage</a><a class="headerlink" href="#fuzzer-usage" title="Permalink to this headline">¶</a></h3>
+<p>Recent versions of Clang (starting from 6.0) include libFuzzer, and no extra installation is necessary.</p>
+<p>In order to build your fuzzer binary, use the <cite>-fsanitize=fuzzer</cite> flag during the
+compilation and linking. In most cases you may want to combine libFuzzer with
+<a class="reference external" href="http://clang.llvm.org/docs/AddressSanitizer.html">AddressSanitizer</a> (ASAN), <a class="reference external" href="http://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html">UndefinedBehaviorSanitizer</a> (UBSAN), or both:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">clang</span> <span class="o">-</span><span class="n">g</span> <span class="o">-</span><span class="n">O1</span> <span class="o">-</span><span class="n">fsanitize</span><span class="o">=</span><span class="n">fuzzer</span> <span class="n">mytarget</span><span class="o">.</span><span class="n">c</span> <span class="c1"># Builds the fuzz target w/o sanitizers</span>
+<span class="n">clang</span> <span class="o">-</span><span class="n">g</span> <span class="o">-</span><span class="n">O1</span> <span class="o">-</span><span class="n">fsanitize</span><span class="o">=</span><span class="n">fuzzer</span><span class="p">,</span><span class="n">address</span> <span class="n">mytarget</span><span class="o">.</span><span class="n">c</span> <span class="c1"># Builds the fuzz target with ASAN</span>
+<span class="n">clang</span> <span class="o">-</span><span class="n">g</span> <span class="o">-</span><span class="n">O1</span> <span class="o">-</span><span class="n">fsanitize</span><span class="o">=</span><span class="n">fuzzer</span><span class="p">,</span><span class="n">signed</span><span class="o">-</span><span class="n">integer</span><span class="o">-</span><span class="n">overflow</span> <span class="n">mytarget</span><span class="o">.</span><span class="n">c</span> <span class="c1"># Builds the fuzz target with a part of UBSAN</span>
+</pre></div>
+</div>
+<p>This will perform the necessary instrumentation, as well as linking with the libFuzzer library.
+Note that <code class="docutils literal"><span class="pre">-fsanitize=fuzzer</span></code> links in the libFuzzer’s <code class="docutils literal"><span class="pre">main()</span></code> symbol.</p>
+<p>If modifying <code class="docutils literal"><span class="pre">CFLAGS</span></code> of a large project, which also compiles executables
+requiring their own <code class="docutils literal"><span class="pre">main</span></code> symbol, it may be desirable to request just the
+instrumentation without linking:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">clang</span> <span class="o">-</span><span class="n">fsanitize</span><span class="o">=</span><span class="n">fuzzer</span><span class="o">-</span><span class="n">no</span><span class="o">-</span><span class="n">link</span> <span class="n">mytarget</span><span class="o">.</span><span class="n">c</span>
+</pre></div>
+</div>
+<p>Then libFuzzer can be linked to the desired driver by passing in
+<code class="docutils literal"><span class="pre">-fsanitize=fuzzer</span></code> during the linking stage.</p>
+<p>Using <a class="reference external" href="http://clang.llvm.org/docs/MemorySanitizer.html">MemorySanitizer</a> (MSAN) with libFuzzer is possible too, but tricky.
+The exact details are out of scope, we expect to simplify this in future
+versions.</p>
+</div>
+<div class="section" id="corpus">
+<span id="libfuzzer-corpus"></span><h3><a class="toc-backref" href="#id24">Corpus</a><a class="headerlink" href="#corpus" title="Permalink to this headline">¶</a></h3>
+<p>Coverage-guided fuzzers like libFuzzer rely on a corpus of sample inputs for the
+code under test. This corpus should ideally be seeded with a varied collection
+of valid and invalid inputs for the code under test; for example, for a graphics
+library the initial corpus might hold a variety of different small PNG/JPG/GIF
+files. The fuzzer generates random mutations based around the sample inputs in
+the current corpus. If a mutation triggers execution of a previously-uncovered
+path in the code under test, then that mutation is saved to the corpus for
+future variations.</p>
+<p>LibFuzzer will work without any initial seeds, but will be less
+efficient if the library under test accepts complex,
+structured inputs.</p>
+<p>The corpus can also act as a sanity/regression check, to confirm that the
+fuzzing entrypoint still works and that all of the sample inputs run through
+the code under test without problems.</p>
+<p>If you have a large corpus (either generated by fuzzing or acquired by other means)
+you may want to minimize it while still preserving the full coverage. One way to do that
+is to use the <cite>-merge=1</cite> flag:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">mkdir NEW_CORPUS_DIR # Store minimized corpus here.</span>
+<span class="go">./my_fuzzer -merge=1 NEW_CORPUS_DIR FULL_CORPUS_DIR</span>
+</pre></div>
+</div>
+<p>You may use the same flag to add more interesting items to an existing corpus.
+Only the inputs that trigger new coverage will be added to the first corpus.</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">./my_fuzzer -merge=1 CURRENT_CORPUS_DIR NEW_POTENTIALLY_INTERESTING_INPUTS_DIR</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="running">
+<h3><a class="toc-backref" href="#id25">Running</a><a class="headerlink" href="#running" title="Permalink to this headline">¶</a></h3>
+<p>To run the fuzzer, first create a <a class="reference internal" href="#corpus">Corpus</a> directory that holds the
+initial “seed” sample inputs:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">mkdir CORPUS_DIR</span>
+<span class="go">cp /some/input/samples/* CORPUS_DIR</span>
+</pre></div>
+</div>
+<p>Then run the fuzzer on the corpus directory:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">./my_fuzzer CORPUS_DIR # -max_len=1000 -jobs=20 ...</span>
+</pre></div>
+</div>
+<p>As the fuzzer discovers new interesting test cases (i.e. test cases that
+trigger coverage of new paths through the code under test), those test cases
+will be added to the corpus directory.</p>
+<p>By default, the fuzzing process will continue indefinitely â at least until
+a bug is found. Any crashes or sanitizer failures will be reported as usual,
+stopping the fuzzing process, and the particular input that triggered the bug
+will be written to disk (typically as <code class="docutils literal"><span class="pre">crash-<sha1></span></code>, <code class="docutils literal"><span class="pre">leak-<sha1></span></code>,
+or <code class="docutils literal"><span class="pre">timeout-<sha1></span></code>).</p>
+</div>
+<div class="section" id="parallel-fuzzing">
+<h3><a class="toc-backref" href="#id26">Parallel Fuzzing</a><a class="headerlink" href="#parallel-fuzzing" title="Permalink to this headline">¶</a></h3>
+<p>Each libFuzzer process is single-threaded, unless the library under test starts
+its own threads. However, it is possible to run multiple libFuzzer processes in
+parallel with a shared corpus directory; this has the advantage that any new
+inputs found by one fuzzer process will be available to the other fuzzer
+processes (unless you disable this with the <code class="docutils literal"><span class="pre">-reload=0</span></code> option).</p>
+<p>This is primarily controlled by the <code class="docutils literal"><span class="pre">-jobs=N</span></code> option, which indicates that
+that <cite>N</cite> fuzzing jobs should be run to completion (i.e. until a bug is found or
+time/iteration limits are reached). These jobs will be run across a set of
+worker processes, by default using half of the available CPU cores; the count of
+worker processes can be overridden by the <code class="docutils literal"><span class="pre">-workers=N</span></code> option. For example,
+running with <code class="docutils literal"><span class="pre">-jobs=30</span></code> on a 12-core machine would run 6 workers by default,
+with each worker averaging 5 bugs by completion of the entire process.</p>
+</div>
+<div class="section" id="resuming-merge">
+<h3><a class="toc-backref" href="#id27">Resuming merge</a><a class="headerlink" href="#resuming-merge" title="Permalink to this headline">¶</a></h3>
+<p>Merging large corpora may be time consuming, and it is often desirable to do it
+on preemptable VMs, where the process may be killed at any time.
+In order to seamlessly resume the merge, use the <code class="docutils literal"><span class="pre">-merge_control_file</span></code> flag
+and use <code class="docutils literal"><span class="pre">killall</span> <span class="pre">-SIGUSR1</span> <span class="pre">/path/to/fuzzer/binary</span></code> to stop the merge gracefully. Example:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">%</span> rm -f SomeLocalPath
+<span class="gp">%</span> ./my_fuzzer CORPUS1 CORPUS2 -merge<span class="o">=</span><span class="m">1</span> -merge_control_file<span class="o">=</span>SomeLocalPath
+<span class="go">...</span>
+<span class="go">MERGE-INNER: using the control file 'SomeLocalPath'</span>
+<span class="go">...</span>
+<span class="gp">#</span> While this is running, <span class="k">do</span> <span class="sb">`</span>killall -SIGUSR1 my_fuzzer<span class="sb">`</span> in another console
+<span class="go">==9015== INFO: libFuzzer: exiting as requested</span>
+
+<span class="gp">#</span> This will leave the file SomeLocalPath with the partial state of the merge.
+<span class="gp">#</span> Now, you can <span class="k">continue</span> the merge by executing the same command. The merge
+<span class="gp">#</span> will <span class="k">continue</span> from where it has been interrupted.
+<span class="gp">%</span> ./my_fuzzer CORPUS1 CORPUS2 -merge<span class="o">=</span><span class="m">1</span> -merge_control_file<span class="o">=</span>SomeLocalPath
+<span class="go">...</span>
+<span class="go">MERGE-OUTER: non-empty control file provided: 'SomeLocalPath'</span>
+<span class="go">MERGE-OUTER: control file ok, 32 files total, first not processed file 20</span>
+<span class="go">...</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="options">
+<h2><a class="toc-backref" href="#id15">Options</a><a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p>To run the fuzzer, pass zero or more corpus directories as command line
+arguments. The fuzzer will read test inputs from each of these corpus
+directories, and any new test inputs that are generated will be written
+back to the first corpus directory:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">./fuzzer [-flag1=val1 [-flag2=val2 ...] ] [dir1 [dir2 ...] ]</span>
+</pre></div>
+</div>
+<p>If a list of files (rather than directories) are passed to the fuzzer program,
+then it will re-run those files as test inputs but will not perform any fuzzing.
+In this mode the fuzzer binary can be used as a regression test (e.g. on a
+continuous integration system) to check the target function and saved inputs
+still work.</p>
+<p>The most important command line options are:</p>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">-help</span></code></dt>
+<dd>Print help message.</dd>
+<dt><code class="docutils literal"><span class="pre">-seed</span></code></dt>
+<dd>Random seed. If 0 (the default), the seed is generated.</dd>
+<dt><code class="docutils literal"><span class="pre">-runs</span></code></dt>
+<dd>Number of individual test runs, -1 (the default) to run indefinitely.</dd>
+<dt><code class="docutils literal"><span class="pre">-max_len</span></code></dt>
+<dd>Maximum length of a test input. If 0 (the default), libFuzzer tries to guess
+a good value based on the corpus (and reports it).</dd>
+<dt><code class="docutils literal"><span class="pre">-timeout</span></code></dt>
+<dd>Timeout in seconds, default 1200. If an input takes longer than this timeout,
+the process is treated as a failure case.</dd>
+<dt><code class="docutils literal"><span class="pre">-rss_limit_mb</span></code></dt>
+<dd>Memory usage limit in Mb, default 2048. Use 0 to disable the limit.
+If an input requires more than this amount of RSS memory to execute,
+the process is treated as a failure case.
+The limit is checked in a separate thread every second.
+If running w/o ASAN/MSAN, you may use ‘ulimit -v’ instead.</dd>
+<dt><code class="docutils literal"><span class="pre">-malloc_limit_mb</span></code></dt>
+<dd>If non-zero, the fuzzer will exit if the target tries to allocate this
+number of Mb with one malloc call.
+If zero (default) same limit as rss_limit_mb is applied.</dd>
+<dt><code class="docutils literal"><span class="pre">-timeout_exitcode</span></code></dt>
+<dd>Exit code (default 77) used if libFuzzer reports a timeout.</dd>
+<dt><code class="docutils literal"><span class="pre">-error_exitcode</span></code></dt>
+<dd>Exit code (default 77) used if libFuzzer itself (not a sanitizer) reports a bug (leak, OOM, etc).</dd>
+<dt><code class="docutils literal"><span class="pre">-max_total_time</span></code></dt>
+<dd>If positive, indicates the maximum total time in seconds to run the fuzzer.
+If 0 (the default), run indefinitely.</dd>
+<dt><code class="docutils literal"><span class="pre">-merge</span></code></dt>
+<dd>If set to 1, any corpus inputs from the 2nd, 3rd etc. corpus directories
+that trigger new code coverage will be merged into the first corpus
+directory. Defaults to 0. This flag can be used to minimize a corpus.</dd>
+<dt><code class="docutils literal"><span class="pre">-merge_control_file</span></code></dt>
+<dd>Specify a control file used for the merge proccess.
+If a merge process gets killed it tries to leave this file in a state
+suitable for resuming the merge. By default a temporary file will be used.</dd>
+<dt><code class="docutils literal"><span class="pre">-minimize_crash</span></code></dt>
+<dd>If 1, minimizes the provided crash input.
+Use with -runs=N or -max_total_time=N to limit the number of attempts.</dd>
+<dt><code class="docutils literal"><span class="pre">-reload</span></code></dt>
+<dd>If set to 1 (the default), the corpus directory is re-read periodically to
+check for new inputs; this allows detection of new inputs that were discovered
+by other fuzzing processes.</dd>
+<dt><code class="docutils literal"><span class="pre">-jobs</span></code></dt>
+<dd>Number of fuzzing jobs to run to completion. Default value is 0, which runs a
+single fuzzing process until completion. If the value is >= 1, then this
+number of jobs performing fuzzing are run, in a collection of parallel
+separate worker processes; each such worker process has its
+<code class="docutils literal"><span class="pre">stdout</span></code>/<code class="docutils literal"><span class="pre">stderr</span></code> redirected to <code class="docutils literal"><span class="pre">fuzz-<JOB>.log</span></code>.</dd>
+<dt><code class="docutils literal"><span class="pre">-workers</span></code></dt>
+<dd>Number of simultaneous worker processes to run the fuzzing jobs to completion
+in. If 0 (the default), <code class="docutils literal"><span class="pre">min(jobs,</span> <span class="pre">NumberOfCpuCores()/2)</span></code> is used.</dd>
+<dt><code class="docutils literal"><span class="pre">-dict</span></code></dt>
+<dd>Provide a dictionary of input keywords; see <a class="reference internal" href="#dictionaries">Dictionaries</a>.</dd>
+<dt><code class="docutils literal"><span class="pre">-use_counters</span></code></dt>
+<dd>Use <a class="reference external" href="http://clang.llvm.org/docs/SanitizerCoverage.html#coverage-counters">coverage counters</a> to generate approximate counts of how often code
+blocks are hit; defaults to 1.</dd>
+<dt><code class="docutils literal"><span class="pre">-reduce_inputs</span></code></dt>
+<dd>Try to reduce the size of inputs while preserving their full feature sets;
+defaults to 1.</dd>
+<dt><code class="docutils literal"><span class="pre">-use_value_profile</span></code></dt>
+<dd>Use <a class="reference external" href="#value-profile">value profile</a> to guide corpus expansion; defaults to 0.</dd>
+<dt><code class="docutils literal"><span class="pre">-only_ascii</span></code></dt>
+<dd>If 1, generate only ASCII (<code class="docutils literal"><span class="pre">isprint``+``isspace</span></code>) inputs. Defaults to 0.</dd>
+<dt><code class="docutils literal"><span class="pre">-artifact_prefix</span></code></dt>
+<dd>Provide a prefix to use when saving fuzzing artifacts (crash, timeout, or
+slow inputs) as <code class="docutils literal"><span class="pre">$(artifact_prefix)file</span></code>. Defaults to empty.</dd>
+<dt><code class="docutils literal"><span class="pre">-exact_artifact_path</span></code></dt>
+<dd>Ignored if empty (the default). If non-empty, write the single artifact on
+failure (crash, timeout) as <code class="docutils literal"><span class="pre">$(exact_artifact_path)</span></code>. This overrides
+<code class="docutils literal"><span class="pre">-artifact_prefix</span></code> and will not use checksum in the file name. Do not use
+the same path for several parallel processes.</dd>
+<dt><code class="docutils literal"><span class="pre">-print_pcs</span></code></dt>
+<dd>If 1, print out newly covered PCs. Defaults to 0.</dd>
+<dt><code class="docutils literal"><span class="pre">-print_final_stats</span></code></dt>
+<dd>If 1, print statistics at exit. Defaults to 0.</dd>
+<dt><code class="docutils literal"><span class="pre">-detect_leaks</span></code></dt>
+<dd>If 1 (default) and if LeakSanitizer is enabled
+try to detect memory leaks during fuzzing (i.e. not only at shut down).</dd>
+<dt><code class="docutils literal"><span class="pre">-close_fd_mask</span></code></dt>
+<dd><p class="first">Indicate output streams to close at startup. Be careful, this will
+remove diagnostic output from target code (e.g. messages on assert failure).</p>
+<blockquote class="last">
+<div><ul class="simple">
+<li>0 (default): close neither <code class="docutils literal"><span class="pre">stdout</span></code> nor <code class="docutils literal"><span class="pre">stderr</span></code></li>
+<li>1 : close <code class="docutils literal"><span class="pre">stdout</span></code></li>
+<li>2 : close <code class="docutils literal"><span class="pre">stderr</span></code></li>
+<li>3 : close both <code class="docutils literal"><span class="pre">stdout</span></code> and <code class="docutils literal"><span class="pre">stderr</span></code>.</li>
+</ul>
+</div></blockquote>
+</dd>
+</dl>
+<p>For the full list of flags run the fuzzer binary with <code class="docutils literal"><span class="pre">-help=1</span></code>.</p>
+</div>
+<div class="section" id="output">
+<h2><a class="toc-backref" href="#id16">Output</a><a class="headerlink" href="#output" title="Permalink to this headline">¶</a></h2>
+<p>During operation the fuzzer prints information to <code class="docutils literal"><span class="pre">stderr</span></code>, for example:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">INFO</span><span class="p">:</span> <span class="n">Seed</span><span class="p">:</span> <span class="mi">1523017872</span>
+<span class="n">INFO</span><span class="p">:</span> <span class="n">Loaded</span> <span class="mi">1</span> <span class="n">modules</span> <span class="p">(</span><span class="mi">16</span> <span class="n">guards</span><span class="p">):</span> <span class="p">[</span><span class="mh">0x744e60</span><span class="p">,</span> <span class="mh">0x744ea0</span><span class="p">),</span>
+<span class="n">INFO</span><span class="p">:</span> <span class="o">-</span><span class="n">max_len</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">provided</span><span class="p">,</span> <span class="n">using</span> <span class="mi">64</span>
+<span class="n">INFO</span><span class="p">:</span> <span class="n">A</span> <span class="n">corpus</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">provided</span><span class="p">,</span> <span class="n">starting</span> <span class="kn">from</span> <span class="nn">an</span> <span class="n">empty</span> <span class="n">corpus</span>
+<span class="c1">#0 READ units: 1</span>
+<span class="c1">#1 INITED cov: 3 ft: 2 corp: 1/1b exec/s: 0 rss: 24Mb</span>
+<span class="c1">#3811 NEW cov: 4 ft: 3 corp: 2/2b exec/s: 0 rss: 25Mb L: 1 MS: 5 ChangeBit-ChangeByte-ChangeBit-ShuffleBytes-ChangeByte-</span>
+<span class="c1">#3827 NEW cov: 5 ft: 4 corp: 3/4b exec/s: 0 rss: 25Mb L: 2 MS: 1 CopyPart-</span>
+<span class="c1">#3963 NEW cov: 6 ft: 5 corp: 4/6b exec/s: 0 rss: 25Mb L: 2 MS: 2 ShuffleBytes-ChangeBit-</span>
+<span class="c1">#4167 NEW cov: 7 ft: 6 corp: 5/9b exec/s: 0 rss: 25Mb L: 3 MS: 1 InsertByte-</span>
+<span class="o">...</span>
+</pre></div>
+</div>
+<p>The early parts of the output include information about the fuzzer options and
+configuration, including the current random seed (in the <code class="docutils literal"><span class="pre">Seed:</span></code> line; this
+can be overridden with the <code class="docutils literal"><span class="pre">-seed=N</span></code> flag).</p>
+<p>Further output lines have the form of an event code and statistics. The
+possible event codes are:</p>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">READ</span></code></dt>
+<dd>The fuzzer has read in all of the provided input samples from the corpus
+directories.</dd>
+<dt><code class="docutils literal"><span class="pre">INITED</span></code></dt>
+<dd>The fuzzer has completed initialization, which includes running each of
+the initial input samples through the code under test.</dd>
+<dt><code class="docutils literal"><span class="pre">NEW</span></code></dt>
+<dd>The fuzzer has created a test input that covers new areas of the code
+under test. This input will be saved to the primary corpus directory.</dd>
+<dt><code class="docutils literal"><span class="pre">REDUCE</span></code></dt>
+<dd>The fuzzer has found a better (smaller) input that triggers previously
+discovered features (set <code class="docutils literal"><span class="pre">-reduce_inputs=0</span></code> to disable).</dd>
+<dt><code class="docutils literal"><span class="pre">pulse</span></code></dt>
+<dd>The fuzzer has generated 2<sup>n</sup> inputs (generated periodically to reassure
+the user that the fuzzer is still working).</dd>
+<dt><code class="docutils literal"><span class="pre">DONE</span></code></dt>
+<dd>The fuzzer has completed operation because it has reached the specified
+iteration limit (<code class="docutils literal"><span class="pre">-runs</span></code>) or time limit (<code class="docutils literal"><span class="pre">-max_total_time</span></code>).</dd>
+<dt><code class="docutils literal"><span class="pre">RELOAD</span></code></dt>
+<dd>The fuzzer is performing a periodic reload of inputs from the corpus
+directory; this allows it to discover any inputs discovered by other
+fuzzer processes (see <a class="reference internal" href="#parallel-fuzzing">Parallel Fuzzing</a>).</dd>
+</dl>
+<p>Each output line also reports the following statistics (when non-zero):</p>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">cov:</span></code></dt>
+<dd>Total number of code blocks or edges covered by the executing the current
+corpus.</dd>
+<dt><code class="docutils literal"><span class="pre">ft:</span></code></dt>
+<dd>libFuzzer uses different signals to evaluate the code coverage:
+edge coverage, edge counters, value profiles, indirect caller/callee pairs, etc.
+These signals combined are called <em>features</em> (<cite>ft:</cite>).</dd>
+<dt><code class="docutils literal"><span class="pre">corp:</span></code></dt>
+<dd>Number of entries in the current in-memory test corpus and its size in bytes.</dd>
+<dt><code class="docutils literal"><span class="pre">exec/s:</span></code></dt>
+<dd>Number of fuzzer iterations per second.</dd>
+<dt><code class="docutils literal"><span class="pre">rss:</span></code></dt>
+<dd>Current memory consumption.</dd>
+</dl>
+<p>For <code class="docutils literal"><span class="pre">NEW</span></code> events, the output line also includes information about the mutation
+operation that produced the new input:</p>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">L:</span></code></dt>
+<dd>Size of the new input in bytes.</dd>
+<dt><code class="docutils literal"><span class="pre">MS:</span> <span class="pre"><n></span> <span class="pre"><operations></span></code></dt>
+<dd>Count and list of the mutation operations used to generate the input.</dd>
+</dl>
+</div>
+<div class="section" id="examples">
+<h2><a class="toc-backref" href="#id17">Examples</a><a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
+<div class="contents local topic" id="id2">
+<ul class="simple">
+<li><a class="reference internal" href="#toy-example" id="id28">Toy example</a></li>
+<li><a class="reference internal" href="#more-examples" id="id29">More examples</a></li>
+</ul>
+</div>
+<div class="section" id="toy-example">
+<h3><a class="toc-backref" href="#id28">Toy example</a><a class="headerlink" href="#toy-example" title="Permalink to this headline">¶</a></h3>
+<p>A simple function that does something interesting if it receives the input
+“HI!”:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">cat</span> <span class="o"><<</span> <span class="n">EOF</span> <span class="o">></span> <span class="n">test_fuzzer</span><span class="o">.</span><span class="n">cc</span>
+<span class="c1">#include <stdint.h></span>
+<span class="c1">#include <stddef.h></span>
+<span class="n">extern</span> <span class="s2">"C"</span> <span class="nb">int</span> <span class="n">LLVMFuzzerTestOneInput</span><span class="p">(</span><span class="n">const</span> <span class="n">uint8_t</span> <span class="o">*</span><span class="n">data</span><span class="p">,</span> <span class="n">size_t</span> <span class="n">size</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">size</span> <span class="o">></span> <span class="mi">0</span> <span class="o">&&</span> <span class="n">data</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span> <span class="o">==</span> <span class="s1">'H'</span><span class="p">)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">size</span> <span class="o">></span> <span class="mi">1</span> <span class="o">&&</span> <span class="n">data</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="s1">'I'</span><span class="p">)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">size</span> <span class="o">></span> <span class="mi">2</span> <span class="o">&&</span> <span class="n">data</span><span class="p">[</span><span class="mi">2</span><span class="p">]</span> <span class="o">==</span> <span class="s1">'!'</span><span class="p">)</span>
+ <span class="n">__builtin_trap</span><span class="p">();</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="n">EOF</span>
+<span class="c1"># Build test_fuzzer.cc with asan and link against libFuzzer.a</span>
+<span class="n">clang</span><span class="o">++</span> <span class="o">-</span><span class="n">fsanitize</span><span class="o">=</span><span class="n">address</span> <span class="o">-</span><span class="n">fsanitize</span><span class="o">-</span><span class="n">coverage</span><span class="o">=</span><span class="n">trace</span><span class="o">-</span><span class="n">pc</span><span class="o">-</span><span class="n">guard</span> <span class="n">test_fuzzer</span><span class="o">.</span><span class="n">cc</span> <span class="n">libFuzzer</span><span class="o">.</span><span class="n">a</span>
+<span class="c1"># Run the fuzzer with no corpus.</span>
+<span class="o">./</span><span class="n">a</span><span class="o">.</span><span class="n">out</span>
+</pre></div>
+</div>
+<p>You should get an error pretty quickly:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">INFO</span><span class="p">:</span> <span class="n">Seed</span><span class="p">:</span> <span class="mi">1523017872</span>
+<span class="n">INFO</span><span class="p">:</span> <span class="n">Loaded</span> <span class="mi">1</span> <span class="n">modules</span> <span class="p">(</span><span class="mi">16</span> <span class="n">guards</span><span class="p">):</span> <span class="p">[</span><span class="mh">0x744e60</span><span class="p">,</span> <span class="mh">0x744ea0</span><span class="p">),</span>
+<span class="n">INFO</span><span class="p">:</span> <span class="o">-</span><span class="n">max_len</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">provided</span><span class="p">,</span> <span class="n">using</span> <span class="mi">64</span>
+<span class="n">INFO</span><span class="p">:</span> <span class="n">A</span> <span class="n">corpus</span> <span class="ow">is</span> <span class="ow">not</span> <span class="n">provided</span><span class="p">,</span> <span class="n">starting</span> <span class="kn">from</span> <span class="nn">an</span> <span class="n">empty</span> <span class="n">corpus</span>
+<span class="c1">#0 READ units: 1</span>
+<span class="c1">#1 INITED cov: 3 ft: 2 corp: 1/1b exec/s: 0 rss: 24Mb</span>
+<span class="c1">#3811 NEW cov: 4 ft: 3 corp: 2/2b exec/s: 0 rss: 25Mb L: 1 MS: 5 ChangeBit-ChangeByte-ChangeBit-ShuffleBytes-ChangeByte-</span>
+<span class="c1">#3827 NEW cov: 5 ft: 4 corp: 3/4b exec/s: 0 rss: 25Mb L: 2 MS: 1 CopyPart-</span>
+<span class="c1">#3963 NEW cov: 6 ft: 5 corp: 4/6b exec/s: 0 rss: 25Mb L: 2 MS: 2 ShuffleBytes-ChangeBit-</span>
+<span class="c1">#4167 NEW cov: 7 ft: 6 corp: 5/9b exec/s: 0 rss: 25Mb L: 3 MS: 1 InsertByte-</span>
+<span class="o">==</span><span class="mi">31511</span><span class="o">==</span> <span class="n">ERROR</span><span class="p">:</span> <span class="n">libFuzzer</span><span class="p">:</span> <span class="n">deadly</span> <span class="n">signal</span>
+<span class="o">...</span>
+<span class="n">artifact_prefix</span><span class="o">=</span><span class="s1">'./'</span><span class="p">;</span> <span class="n">Test</span> <span class="n">unit</span> <span class="n">written</span> <span class="n">to</span> <span class="o">./</span><span class="n">crash</span><span class="o">-</span><span class="n">b13e8756b13a00cf168300179061fb4b91fefbed</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="more-examples">
+<h3><a class="toc-backref" href="#id29">More examples</a><a class="headerlink" href="#more-examples" title="Permalink to this headline">¶</a></h3>
+<p>Examples of real-life fuzz targets and the bugs they find can be found
+at <a class="reference external" href="http://tutorial.libfuzzer.info">http://tutorial.libfuzzer.info</a>. Among other things you can learn how
+to detect <a class="reference external" href="http://en.wikipedia.org/wiki/Heartbleed">Heartbleed</a> in one second.</p>
+</div>
+</div>
+<div class="section" id="advanced-features">
+<h2><a class="toc-backref" href="#id18">Advanced features</a><a class="headerlink" href="#advanced-features" title="Permalink to this headline">¶</a></h2>
+<div class="contents local topic" id="id3">
+<ul class="simple">
+<li><a class="reference internal" href="#dictionaries" id="id30">Dictionaries</a></li>
+<li><a class="reference internal" href="#tracing-cmp-instructions" id="id31">Tracing CMP instructions</a></li>
+<li><a class="reference internal" href="#value-profile" id="id32">Value Profile</a></li>
+<li><a class="reference internal" href="#fuzzer-friendly-build-mode" id="id33">Fuzzer-friendly build mode</a></li>
+<li><a class="reference internal" href="#afl-compatibility" id="id34">AFL compatibility</a></li>
+<li><a class="reference internal" href="#how-good-is-my-fuzzer" id="id35">How good is my fuzzer?</a></li>
+<li><a class="reference internal" href="#user-supplied-mutators" id="id36">User-supplied mutators</a></li>
+<li><a class="reference internal" href="#startup-initialization" id="id37">Startup initialization</a></li>
+<li><a class="reference internal" href="#leaks" id="id38">Leaks</a></li>
+</ul>
+</div>
+<div class="section" id="dictionaries">
+<h3><a class="toc-backref" href="#id30">Dictionaries</a><a class="headerlink" href="#dictionaries" title="Permalink to this headline">¶</a></h3>
+<p>LibFuzzer supports user-supplied dictionaries with input language keywords
+or other interesting byte sequences (e.g. multi-byte magic values).
+Use <code class="docutils literal"><span class="pre">-dict=DICTIONARY_FILE</span></code>. For some input languages using a dictionary
+may significantly improve the search speed.
+The dictionary syntax is similar to that used by <a class="reference external" href="http://lcamtuf.coredump.cx/afl/">AFL</a> for its <code class="docutils literal"><span class="pre">-x</span></code> option:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Lines starting with '#' and empty lines are ignored.</span>
+
+<span class="c1"># Adds "blah" (w/o quotes) to the dictionary.</span>
+<span class="n">kw1</span><span class="o">=</span><span class="s2">"blah"</span>
+<span class="c1"># Use \\ for backslash and \" for quotes.</span>
+<span class="n">kw2</span><span class="o">=</span><span class="s2">"</span><span class="se">\"</span><span class="s2">ac</span><span class="se">\\</span><span class="s2">dc</span><span class="se">\"</span><span class="s2">"</span>
+<span class="c1"># Use \xAB for hex values</span>
+<span class="n">kw3</span><span class="o">=</span><span class="s2">"</span><span class="se">\xF7\xF8</span><span class="s2">"</span>
+<span class="c1"># the name of the keyword followed by '=' may be omitted:</span>
+<span class="s2">"foo</span><span class="se">\x0A</span><span class="s2">bar"</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="tracing-cmp-instructions">
+<h3><a class="toc-backref" href="#id31">Tracing CMP instructions</a><a class="headerlink" href="#tracing-cmp-instructions" title="Permalink to this headline">¶</a></h3>
+<p>With an additional compiler flag <code class="docutils literal"><span class="pre">-fsanitize-coverage=trace-cmp</span></code>
+(on by default as part of <code class="docutils literal"><span class="pre">-fsanitize=fuzzer</span></code>, see <a class="reference external" href="http://clang.llvm.org/docs/SanitizerCoverage.html#tracing-data-flow">SanitizerCoverageTraceDataFlow</a>)
+libFuzzer will intercept CMP instructions and guide mutations based
+on the arguments of intercepted CMP instructions. This may slow down
+the fuzzing but is very likely to improve the results.</p>
+</div>
+<div class="section" id="value-profile">
+<h3><a class="toc-backref" href="#id32">Value Profile</a><a class="headerlink" href="#value-profile" title="Permalink to this headline">¶</a></h3>
+<p>With <code class="docutils literal"><span class="pre">-fsanitize-coverage=trace-cmp</span></code>
+and extra run-time flag <code class="docutils literal"><span class="pre">-use_value_profile=1</span></code> the fuzzer will
+collect value profiles for the parameters of compare instructions
+and treat some new values as new coverage.</p>
+<p>The current imlpementation does roughly the following:</p>
+<ul class="simple">
+<li>The compiler instruments all CMP instructions with a callback that receives both CMP arguments.</li>
+<li>The callback computes <cite>(caller_pc&4095) | (popcnt(Arg1 ^ Arg2) << 12)</cite> and uses this value to set a bit in a bitset.</li>
+<li>Every new observed bit in the bitset is treated as new coverage.</li>
+</ul>
+<p>This feature has a potential to discover many interesting inputs,
+but there are two downsides.
+First, the extra instrumentation may bring up to 2x additional slowdown.
+Second, the corpus may grow by several times.</p>
+</div>
+<div class="section" id="fuzzer-friendly-build-mode">
+<h3><a class="toc-backref" href="#id33">Fuzzer-friendly build mode</a><a class="headerlink" href="#fuzzer-friendly-build-mode" title="Permalink to this headline">¶</a></h3>
+<p>Sometimes the code under test is not fuzzing-friendly. Examples:</p>
+<blockquote>
+<div><ul class="simple">
+<li>The target code uses a PRNG seeded e.g. by system time and
+thus two consequent invocations may potentially execute different code paths
+even if the end result will be the same. This will cause a fuzzer to treat
+two similar inputs as significantly different and it will blow up the test corpus.
+E.g. libxml uses <code class="docutils literal"><span class="pre">rand()</span></code> inside its hash table.</li>
+<li>The target code uses checksums to protect from invalid inputs.
+E.g. png checks CRC for every chunk.</li>
+</ul>
+</div></blockquote>
+<p>In many cases it makes sense to build a special fuzzing-friendly build
+with certain fuzzing-unfriendly features disabled. We propose to use a common build macro
+for all such cases for consistency: <code class="docutils literal"><span class="pre">FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION</span></code>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="nf">MyInitPRNG</span><span class="p">()</span> <span class="p">{</span>
+<span class="cp">#ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION</span>
+ <span class="c1">// In fuzzing mode the behavior of the code should be deterministic.</span>
+ <span class="n">srand</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+<span class="cp">#else</span>
+ <span class="n">srand</span><span class="p">(</span><span class="n">time</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span>
+<span class="cp">#endif</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="afl-compatibility">
+<h3><a class="toc-backref" href="#id34">AFL compatibility</a><a class="headerlink" href="#afl-compatibility" title="Permalink to this headline">¶</a></h3>
+<p>LibFuzzer can be used together with <a class="reference external" href="http://lcamtuf.coredump.cx/afl/">AFL</a> on the same test corpus.
+Both fuzzers expect the test corpus to reside in a directory, one file per input.
+You can run both fuzzers on the same corpus, one after another:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">./afl-fuzz -i testcase_dir -o findings_dir /path/to/program @@</span>
+<span class="go">./llvm-fuzz testcase_dir findings_dir # Will write new tests to testcase_dir</span>
+</pre></div>
+</div>
+<p>Periodically restart both fuzzers so that they can use each other’s findings.
+Currently, there is no simple way to run both fuzzing engines in parallel while sharing the same corpus dir.</p>
+<p>You may also use AFL on your target function <code class="docutils literal"><span class="pre">LLVMFuzzerTestOneInput</span></code>:
+see an example <a class="reference external" href="https://github.com/llvm-mirror/compiler-rt/tree/master/lib/fuzzer/afl">here</a>.</p>
+</div>
+<div class="section" id="how-good-is-my-fuzzer">
+<h3><a class="toc-backref" href="#id35">How good is my fuzzer?</a><a class="headerlink" href="#how-good-is-my-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>Once you implement your target function <code class="docutils literal"><span class="pre">LLVMFuzzerTestOneInput</span></code> and fuzz it to death,
+you will want to know whether the function or the corpus can be improved further.
+One easy to use metric is, of course, code coverage.</p>
+<p>We recommend to use
+<a class="reference external" href="http://clang.llvm.org/docs/SourceBasedCodeCoverage.html">Clang Coverage</a>,
+to visualize and study your code coverage
+(<a class="reference external" href="https://github.com/google/fuzzer-test-suite/blob/master/tutorial/libFuzzerTutorial.md#visualizing-coverage">example</a>).</p>
+</div>
+<div class="section" id="user-supplied-mutators">
+<h3><a class="toc-backref" href="#id36">User-supplied mutators</a><a class="headerlink" href="#user-supplied-mutators" title="Permalink to this headline">¶</a></h3>
+<p>LibFuzzer allows to use custom (user-supplied) mutators,
+see <a class="reference external" href="https://github.com/llvm-mirror/compiler-rt/blob/master/lib/fuzzer/FuzzerInterface.h">FuzzerInterface.h</a></p>
+</div>
+<div class="section" id="startup-initialization">
+<h3><a class="toc-backref" href="#id37">Startup initialization</a><a class="headerlink" href="#startup-initialization" title="Permalink to this headline">¶</a></h3>
+<p>If the library being tested needs to be initialized, there are several options.</p>
+<p>The simplest way is to have a statically initialized global object inside
+<cite>LLVMFuzzerTestOneInput</cite> (or in global scope if that works for you):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="s">"C"</span> <span class="kt">int</span> <span class="n">LLVMFuzzerTestOneInput</span><span class="p">(</span><span class="k">const</span> <span class="kt">uint8_t</span> <span class="o">*</span><span class="n">Data</span><span class="p">,</span> <span class="kt">size_t</span> <span class="n">Size</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">static</span> <span class="kt">bool</span> <span class="n">Initialized</span> <span class="o">=</span> <span class="n">DoInitialization</span><span class="p">();</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+<p>Alternatively, you may define an optional init function and it will receive
+the program arguments that you can read and modify. Do this <strong>only</strong> if you
+really need to access <code class="docutils literal"><span class="pre">argv</span></code>/<code class="docutils literal"><span class="pre">argc</span></code>.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">extern</span> <span class="s">"C"</span> <span class="kt">int</span> <span class="n">LLVMFuzzerInitialize</span><span class="p">(</span><span class="kt">int</span> <span class="o">*</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">ReadAndMaybeModify</span><span class="p">(</span><span class="n">argc</span><span class="p">,</span> <span class="n">argv</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>
+</div>
+<div class="section" id="leaks">
+<h3><a class="toc-backref" href="#id38">Leaks</a><a class="headerlink" href="#leaks" title="Permalink to this headline">¶</a></h3>
+<p>Binaries built with <a class="reference external" href="http://clang.llvm.org/docs/AddressSanitizer.html">AddressSanitizer</a> or <a class="reference external" href="http://clang.llvm.org/docs/LeakSanitizer.html">LeakSanitizer</a> will try to detect
+memory leaks at the process shutdown.
+For in-process fuzzing this is inconvenient
+since the fuzzer needs to report a leak with a reproducer as soon as the leaky
+mutation is found. However, running full leak detection after every mutation
+is expensive.</p>
+<p>By default (<code class="docutils literal"><span class="pre">-detect_leaks=1</span></code>) libFuzzer will count the number of
+<code class="docutils literal"><span class="pre">malloc</span></code> and <code class="docutils literal"><span class="pre">free</span></code> calls when executing every mutation.
+If the numbers don’t match (which by itself doesn’t mean there is a leak)
+libFuzzer will invoke the more expensive <a class="reference external" href="http://clang.llvm.org/docs/LeakSanitizer.html">LeakSanitizer</a>
+pass and if the actual leak is found, it will be reported with the reproducer
+and the process will exit.</p>
+<p>If your target has massive leaks and the leak detection is disabled
+you will eventually run out of RAM (see the <code class="docutils literal"><span class="pre">-rss_limit_mb</span></code> flag).</p>
+</div>
+</div>
+<div class="section" id="developing-libfuzzer">
+<h2><a class="toc-backref" href="#id19">Developing libFuzzer</a><a class="headerlink" href="#developing-libfuzzer" title="Permalink to this headline">¶</a></h2>
+<p>LibFuzzer is built as a part of LLVM project by default on macos and Linux.
+Users of other operating systems can explicitly request compilation using
+<code class="docutils literal"><span class="pre">-DLIBFUZZER_ENABLE=YES</span></code> flag.
+Tests are run using <code class="docutils literal"><span class="pre">check-fuzzer</span></code> target from the build directory
+which was configured with <code class="docutils literal"><span class="pre">-DLIBFUZZER_ENABLE_TESTS=ON</span></code> flag.</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">ninja check-fuzzer</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="faq">
+<h2><a class="toc-backref" href="#id20">FAQ</a><a class="headerlink" href="#faq" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="q-why-doesn-t-libfuzzer-use-any-of-the-llvm-support">
+<h3>Q. Why doesn’t libFuzzer use any of the LLVM support?<a class="headerlink" href="#q-why-doesn-t-libfuzzer-use-any-of-the-llvm-support" title="Permalink to this headline">¶</a></h3>
+<p>There are two reasons.</p>
+<p>First, we want this library to be used outside of the LLVM without users having to
+build the rest of LLVM. This may sound unconvincing for many LLVM folks,
+but in practice the need for building the whole LLVM frightens many potential
+users – and we want more users to use this code.</p>
+<p>Second, there is a subtle technical reason not to rely on the rest of LLVM, or
+any other large body of code (maybe not even STL). When coverage instrumentation
+is enabled, it will also instrument the LLVM support code which will blow up the
+coverage set of the process (since the fuzzer is in-process). In other words, by
+using more external dependencies we will slow down the fuzzer while the main
+reason for it to exist is extreme speed.</p>
+</div>
+<div class="section" id="q-what-about-windows-then-the-fuzzer-contains-code-that-does-not-build-on-windows">
+<h3>Q. What about Windows then? The fuzzer contains code that does not build on Windows.<a class="headerlink" href="#q-what-about-windows-then-the-fuzzer-contains-code-that-does-not-build-on-windows" title="Permalink to this headline">¶</a></h3>
+<p>Volunteers are welcome.</p>
+</div>
+<div class="section" id="q-when-libfuzzer-is-not-a-good-solution-for-a-problem">
+<h3>Q. When libFuzzer is not a good solution for a problem?<a class="headerlink" href="#q-when-libfuzzer-is-not-a-good-solution-for-a-problem" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>If the test inputs are validated by the target library and the validator
+asserts/crashes on invalid inputs, in-process fuzzing is not applicable.</li>
+<li>Bugs in the target library may accumulate without being detected. E.g. a memory
+corruption that goes undetected at first and then leads to a crash while
+testing another input. This is why it is highly recommended to run this
+in-process fuzzer with all sanitizers to detect most bugs on the spot.</li>
+<li>It is harder to protect the in-process fuzzer from excessive memory
+consumption and infinite loops in the target library (still possible).</li>
+<li>The target library should not have significant global state that is not
+reset between the runs.</li>
+<li>Many interesting target libraries are not designed in a way that supports
+the in-process fuzzer interface (e.g. require a file path instead of a
+byte array).</li>
+<li>If a single test run takes a considerable fraction of a second (or
+more) the speed benefit from the in-process fuzzer is negligible.</li>
+<li>If the target library runs persistent threads (that outlive
+execution of one test) the fuzzing results will be unreliable.</li>
+</ul>
+</div>
+<div class="section" id="q-so-what-exactly-this-fuzzer-is-good-for">
+<h3>Q. So, what exactly this Fuzzer is good for?<a class="headerlink" href="#q-so-what-exactly-this-fuzzer-is-good-for" title="Permalink to this headline">¶</a></h3>
+<p>This Fuzzer might be a good choice for testing libraries that have relatively
+small inputs, each input takes < 10ms to run, and the library code is not expected
+to crash on invalid inputs.
+Examples: regular expression matchers, text or binary format parsers, compression,
+network, crypto.</p>
+</div>
+</div>
+<div class="section" id="trophies">
+<h2><a class="toc-backref" href="#id21">Trophies</a><a class="headerlink" href="#trophies" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li>Thousands of bugs found on OSS-Fuzz: <a class="reference external" href="https://opensource.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html">https://opensource.googleblog.com/2017/05/oss-fuzz-five-months-later-and.html</a></li>
+<li>GLIBC: <a class="reference external" href="https://sourceware.org/glibc/wiki/FuzzingLibc">https://sourceware.org/glibc/wiki/FuzzingLibc</a></li>
+<li>MUSL LIBC: <a class="reference external" href="http://git.musl-libc.org/cgit/musl/commit/?id=39dfd58417ef642307d90306e1c7e50aaec5a35c">[1]</a> <a class="reference external" href="http://www.openwall.com/lists/oss-security/2015/03/30/3">[2]</a></li>
+<li><a class="reference external" href="https://github.com/zeux/pugixml/issues/39">pugixml</a></li>
+<li>PCRE: Search for “LLVM fuzzer” in <a class="reference external" href="http://vcs.pcre.org/pcre2/code/trunk/ChangeLog?view=markup">http://vcs.pcre.org/pcre2/code/trunk/ChangeLog?view=markup</a>;
+also in <a class="reference external" href="https://bugs.exim.org/buglist.cgi?bug_status=__all__&content=libfuzzer&no_redirect=1&order=Importance&product=PCRE&query_format=specific">bugzilla</a></li>
+<li><a class="reference external" href="http://bugs.icu-project.org/trac/ticket/11838">ICU</a></li>
+<li><a class="reference external" href="https://savannah.nongnu.org/search/?words=LibFuzzer&type_of_search=bugs&Search=Search&exact=1#options">Freetype</a></li>
+<li><a class="reference external" href="https://github.com/behdad/harfbuzz/issues/139">Harfbuzz</a></li>
+<li><a class="reference external" href="http://www3.sqlite.org/cgi/src/info/088009efdd56160b">SQLite</a></li>
+<li><a class="reference external" href="http://bugs.python.org/issue25388">Python</a></li>
+<li>OpenSSL/BoringSSL: <a class="reference external" href="https://boringssl.googlesource.com/boringssl/+/cb852981cd61733a7a1ae4fd8755b7ff950e857d">[1]</a> <a class="reference external" href="https://openssl.org/news/secadv/20160301.txt">[2]</a> <a class="reference external" href="https://boringssl.googlesource.com/boringssl/+/2b07fa4b22198ac02e0cee8f37f3337c3dba91bc">[3]</a> <a class="reference external" href="https://boringssl.googlesource.com/boringssl/+/6b6e0b20893e2be0e68af605a60ffa2cbb0ffa64">[4]</a> <a class="reference external" href="https://github.com/openssl/openssl/pull/931/commits/dd5ac557f052cc2b7f718ac44a8cb7ac6f77dca8">[5]</a> <a class="reference external" href="https://github.com/openssl/openssl/pull/931/commits/19b5b9194071d1d84e38ac9a952e715afbc85a81">[6]</a></li>
+<li><a class="reference external" href="https://bugzilla.gnome.org/buglist.cgi?bug_status=__all__&content=libFuzzer&list_id=68957&order=Importance&product=libxml2&query_format=specific">Libxml2</a> and <a class="reference external" href="https://support.apple.com/en-gb/HT206167">[HT206167]</a> (CVE-2015-5312, CVE-2015-7500, CVE-2015-7942)</li>
+<li><a class="reference external" href="https://github.com/iovisor/bpf-fuzzer">Linux Kernel’s BPF verifier</a></li>
+<li><a class="reference external" href="https://www.spinics.net/lists/stable/msg199712.html">Linux Kernel’s Crypto code</a></li>
+<li>Capstone: <a class="reference external" href="https://github.com/aquynh/capstone/issues/600">[1]</a> <a class="reference external" href="https://github.com/aquynh/capstone/commit/6b88d1d51eadf7175a8f8a11b690684443b11359">[2]</a></li>
+<li>file:<a class="reference external" href="http://bugs.gw.com/view.php?id=550">[1]</a> <a class="reference external" href="http://bugs.gw.com/view.php?id=551">[2]</a> <a class="reference external" href="http://bugs.gw.com/view.php?id=553">[3]</a> <a class="reference external" href="http://bugs.gw.com/view.php?id=554">[4]</a></li>
+<li>Radare2: <a class="reference external" href="https://github.com/revskills?tab=contributions&from=2016-04-09">[1]</a></li>
+<li>gRPC: <a class="reference external" href="https://github.com/grpc/grpc/pull/6071/commits/df04c1f7f6aec6e95722ec0b023a6b29b6ea871c">[1]</a> <a class="reference external" href="https://github.com/grpc/grpc/pull/6071/commits/22a3dfd95468daa0db7245a4e8e6679a52847579">[2]</a> <a class="reference external" href="https://github.com/grpc/grpc/pull/6071/commits/9cac2a12d9e181d130841092e9d40fa3309d7aa7">[3]</a> <a class="reference external" href="https://github.com/grpc/grpc/pull/6012/commits/82a91c91d01ce9b999c8821ed13515883468e203">[4]</a> <a class="reference external" href="https://github.com/grpc/grpc/pull/6202/commits/2e3e0039b30edaf89fb93bfb2c1d0909098519fa">[5]</a> <a class="reference external" href="https://github.com/grpc/grpc/pull/6106/files">[6]</a></li>
+<li>WOFF2: <a class="reference external" href="https://github.com/google/woff2/commit/a15a8ab">[1]</a></li>
+<li>LLVM: <a class="reference external" href="https://llvm.org/bugs/show_bug.cgi?id=23057">Clang</a>, <a class="reference external" href="https://llvm.org/bugs/show_bug.cgi?id=23052">Clang-format</a>, <a class="reference external" href="https://llvm.org/bugs/show_bug.cgi?id=24411">libc++</a>, <a class="reference external" href="https://llvm.org/bugs/show_bug.cgi?id=24639">llvm-as</a>, <a class="reference external" href="https://bugs.chromium.org/p/chromium/issues/detail?id=606626">Demangler</a>, Disassembler: <a class="reference external" href="http://reviews.llvm.org/rL247405">http://reviews.llvm.org/rL247405</a>, <a class="reference external" href="http://reviews.llvm.org/rL247414">http://reviews.llvm.org/rL247414</a>, <a class="reference external" href="http://reviews.llvm.org/rL247416">http://reviews.llvm.org/rL247416</a>, <a class="reference external" href="http://reviews.llvm.org/rL247417">http://reviews.llvm.org/rL247417</a>, <a class="reference external" href="http://reviews.llvm.org/rL247420">http://reviews.llvm.org/rL247420</a>, <a class="reference external" href="http://reviews.llvm.org/rL247422">http://reviews.llvm.org/rL247422</a>.</li>
+<li>Tensorflow: <a class="reference external" href="https://da-data.blogspot.com/2017/01/finding-bugs-in-tensorflow-with.html">[1]</a></li>
+<li>Ffmpeg: <a class="reference external" href="https://github.com/FFmpeg/FFmpeg/commit/c92f55847a3d9cd12db60bfcd0831ff7f089c37c">[1]</a> <a class="reference external" href="https://github.com/FFmpeg/FFmpeg/commit/25ab1a65f3acb5ec67b53fb7a2463a7368f1ad16">[2]</a> <a class="reference external" href="https://github.com/FFmpeg/FFmpeg/commit/85d23e5cbc9ad6835eef870a5b4247de78febe56">[3]</a> <a class="reference external" href="https://github.com/FFmpeg/FFmpeg/commit/04bd1b38ee6b8df410d0ab8d4949546b6c4af26a">[4]</a></li>
+<li><a class="reference external" href="https://bugs.wireshark.org/bugzilla/buglist.cgi?bug_status=UNCONFIRMED&bug_status=CONFIRMED&bug_status=IN_PROGRESS&bug_status=INCOMPLETE&bug_status=RESOLVED&bug_status=VERIFIED&f0=OP&f1=OP&f2=product&f3=component&f4=alias&f5=short_desc&f7=content&f8=CP&f9=CP&j1=OR&o2=substring&o3=substring&o4=substring&o5=substring&o6=substring&o7=matches&order=bug_id%20DESC&query_format=advanced&v2=libfuzzer&v3=libfuzzer&v4=libfuzzer&v5=libfuzzer&v6=libfuzzer&v7=%22libfuzzer%22">Wireshark</a></li>
+<li><a class="reference external" href="https://researchcenter.paloaltonetworks.com/2017/09/unit42-palo-alto-networks-discovers-new-qemu-vulnerability/">QEMU</a></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="FuzzingLLVM.html" title="Fuzzing LLVM libraries and tools"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Extensions.html" title="LLVM Extensions"
+ >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-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/LinkTimeOptimization.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/LinkTimeOptimization.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/LinkTimeOptimization.html (added)
+++ www-releases/trunk/6.0.0/docs/LinkTimeOptimization.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,372 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVM Link Time Optimization: Design and Implementation — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="Segmented Stacks in LLVM" href="SegmentedStacks.html" />
+ <link rel="prev" title="Exception Handling in LLVM" href="ExceptionHandling.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="SegmentedStacks.html" title="Segmented Stacks in LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ExceptionHandling.html" title="Exception Handling in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-link-time-optimization-design-and-implementation">
+<h1>LLVM Link Time Optimization: Design and Implementation<a class="headerlink" href="#llvm-link-time-optimization-design-and-implementation" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#description" id="id2">Description</a></li>
+<li><a class="reference internal" href="#design-philosophy" id="id3">Design Philosophy</a><ul>
+<li><a class="reference internal" href="#example-of-link-time-optimization" id="id4">Example of link time optimization</a></li>
+<li><a class="reference internal" href="#alternative-approaches" id="id5">Alternative Approaches</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#multi-phase-communication-between-liblto-and-linker" id="id6">Multi-phase communication between <code class="docutils literal"><span class="pre">libLTO</span></code> and linker</a><ul>
+<li><a class="reference internal" href="#phase-1-read-llvm-bitcode-files" id="id7">Phase 1 : Read LLVM Bitcode Files</a></li>
+<li><a class="reference internal" href="#phase-2-symbol-resolution" id="id8">Phase 2 : Symbol Resolution</a></li>
+<li><a class="reference internal" href="#phase-3-optimize-bitcode-files" id="id9">Phase 3 : Optimize Bitcode Files</a></li>
+<li><a class="reference internal" href="#phase-4-symbol-resolution-after-optimization" id="id10">Phase 4 : Symbol Resolution after optimization</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#liblto" id="id11"><code class="docutils literal"><span class="pre">libLTO</span></code></a><ul>
+<li><a class="reference internal" href="#lto-module-t" id="id12"><code class="docutils literal"><span class="pre">lto_module_t</span></code></a></li>
+<li><a class="reference internal" href="#lto-code-gen-t" id="id13"><code class="docutils literal"><span class="pre">lto_code_gen_t</span></code></a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="description">
+<h2><a class="toc-backref" href="#id2">Description</a><a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>LLVM features powerful intermodular optimizations which can be used at link
+time. Link Time Optimization (LTO) is another name for intermodular
+optimization when performed during the link stage. This document describes the
+interface and design between the LTO optimizer and the linker.</p>
+</div>
+<div class="section" id="design-philosophy">
+<h2><a class="toc-backref" href="#id3">Design Philosophy</a><a class="headerlink" href="#design-philosophy" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM Link Time Optimizer provides complete transparency, while doing
+intermodular optimization, in the compiler tool chain. Its main goal is to let
+the developer take advantage of intermodular optimizations without making any
+significant changes to the developer’s makefiles or build system. This is
+achieved through tight integration with the linker. In this model, the linker
+treats LLVM bitcode files like native object files and allows mixing and
+matching among them. The linker uses <a class="reference internal" href="#liblto">libLTO</a>, a shared object, to handle LLVM
+bitcode files. This tight integration between the linker and LLVM optimizer
+helps to do optimizations that are not possible in other models. The linker
+input allows the optimizer to avoid relying on conservative escape analysis.</p>
+<div class="section" id="example-of-link-time-optimization">
+<span id="liblto-example"></span><h3><a class="toc-backref" href="#id4">Example of link time optimization</a><a class="headerlink" href="#example-of-link-time-optimization" title="Permalink to this headline">¶</a></h3>
+<p>The following example illustrates the advantages of LTO’s integrated approach
+and clean interface. This example requires a system linker which supports LTO
+through the interface described in this document. Here, clang transparently
+invokes system linker.</p>
+<ul class="simple">
+<li>Input source file <code class="docutils literal"><span class="pre">a.c</span></code> is compiled into LLVM bitcode form.</li>
+<li>Input source file <code class="docutils literal"><span class="pre">main.c</span></code> is compiled into native object code.</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="o">---</span> <span class="n">a</span><span class="p">.</span><span class="n">h</span> <span class="o">---</span>
+<span class="k">extern</span> <span class="kt">int</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+<span class="k">extern</span> <span class="kt">void</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+<span class="k">extern</span> <span class="kt">void</span> <span class="nf">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
+
+<span class="o">---</span> <span class="n">a</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
+<span class="cp">#include</span> <span class="cpf">"a.h"</span><span class="cp"></span>
+
+<span class="k">static</span> <span class="kt">signed</span> <span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+<span class="kt">void</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">i</span> <span class="o">=</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="k">static</span> <span class="kt">int</span> <span class="nf">foo3</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo4</span><span class="p">();</span>
+ <span class="k">return</span> <span class="mi">10</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="nf">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">data</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="k">if</span> <span class="p">(</span><span class="n">i</span> <span class="o"><</span> <span class="mi">0</span><span class="p">)</span>
+ <span class="n">data</span> <span class="o">=</span> <span class="n">foo3</span><span class="p">();</span>
+
+ <span class="n">data</span> <span class="o">=</span> <span class="n">data</span> <span class="o">+</span> <span class="mi">42</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">data</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="o">---</span> <span class="n">main</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
+<span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"a.h"</span><span class="cp"></span>
+
+<span class="kt">void</span> <span class="n">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">printf</span><span class="p">(</span><span class="s">"Hi</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="n">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">foo1</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>To compile, run:</p>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">%</span> clang -flto -c a.c -o a.o <span class="c1"># <-- a.o is LLVM bitcode file</span>
+<span class="gp">%</span> clang -c main.c -o main.o <span class="c1"># <-- main.o is native object file</span>
+<span class="gp">%</span> clang -flto a.o main.o -o main <span class="c1"># <-- standard link command with -flto</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li>In this example, the linker recognizes that <code class="docutils literal"><span class="pre">foo2()</span></code> is an externally
+visible symbol defined in LLVM bitcode file. The linker completes its usual
+symbol resolution pass and finds that <code class="docutils literal"><span class="pre">foo2()</span></code> is not used
+anywhere. This information is used by the LLVM optimizer and it
+removes <code class="docutils literal"><span class="pre">foo2()</span></code>.</li>
+<li>As soon as <code class="docutils literal"><span class="pre">foo2()</span></code> is removed, the optimizer recognizes that condition <code class="docutils literal"><span class="pre">i</span>
+<span class="pre"><</span> <span class="pre">0</span></code> is always false, which means <code class="docutils literal"><span class="pre">foo3()</span></code> is never used. Hence, the
+optimizer also removes <code class="docutils literal"><span class="pre">foo3()</span></code>.</li>
+<li>And this in turn, enables linker to remove <code class="docutils literal"><span class="pre">foo4()</span></code>.</li>
+</ul>
+<p>This example illustrates the advantage of tight integration with the
+linker. Here, the optimizer can not remove <code class="docutils literal"><span class="pre">foo3()</span></code> without the linker’s
+input.</p>
+</div>
+<div class="section" id="alternative-approaches">
+<h3><a class="toc-backref" href="#id5">Alternative Approaches</a><a class="headerlink" href="#alternative-approaches" title="Permalink to this headline">¶</a></h3>
+<dl class="docutils">
+<dt><strong>Compiler driver invokes link time optimizer separately.</strong></dt>
+<dd>In this model the link time optimizer is not able to take advantage of
+information collected during the linker’s normal symbol resolution phase.
+In the above example, the optimizer can not remove <code class="docutils literal"><span class="pre">foo2()</span></code> without the
+linker’s input because it is externally visible. This in turn prohibits the
+optimizer from removing <code class="docutils literal"><span class="pre">foo3()</span></code>.</dd>
+<dt><strong>Use separate tool to collect symbol information from all object files.</strong></dt>
+<dd>In this model, a new, separate, tool or library replicates the linker’s
+capability to collect information for link time optimization. Not only is
+this code duplication difficult to justify, but it also has several other
+disadvantages. For example, the linking semantics and the features provided
+by the linker on various platform are not unique. This means, this new tool
+needs to support all such features and platforms in one super tool or a
+separate tool per platform is required. This increases maintenance cost for
+link time optimizer significantly, which is not necessary. This approach
+also requires staying synchronized with linker developments on various
+platforms, which is not the main focus of the link time optimizer. Finally,
+this approach increases end user’s build time due to the duplication of work
+done by this separate tool and the linker itself.</dd>
+</dl>
+</div>
+</div>
+<div class="section" id="multi-phase-communication-between-liblto-and-linker">
+<h2><a class="toc-backref" href="#id6">Multi-phase communication between <code class="docutils literal"><span class="pre">libLTO</span></code> and linker</a><a class="headerlink" href="#multi-phase-communication-between-liblto-and-linker" title="Permalink to this headline">¶</a></h2>
+<p>The linker collects information about symbol definitions and uses in various
+link objects which is more accurate than any information collected by other
+tools during typical build cycles. The linker collects this information by
+looking at the definitions and uses of symbols in native .o files and using
+symbol visibility information. The linker also uses user-supplied information,
+such as a list of exported symbols. LLVM optimizer collects control flow
+information, data flow information and knows much more about program structure
+from the optimizer’s point of view. Our goal is to take advantage of tight
+integration between the linker and the optimizer by sharing this information
+during various linking phases.</p>
+<div class="section" id="phase-1-read-llvm-bitcode-files">
+<h3><a class="toc-backref" href="#id7">Phase 1 : Read LLVM Bitcode Files</a><a class="headerlink" href="#phase-1-read-llvm-bitcode-files" title="Permalink to this headline">¶</a></h3>
+<p>The linker first reads all object files in natural order and collects symbol
+information. This includes native object files as well as LLVM bitcode files.
+To minimize the cost to the linker in the case that all .o files are native
+object files, the linker only calls <code class="docutils literal"><span class="pre">lto_module_create()</span></code> when a supplied
+object file is found to not be a native object file. If <code class="docutils literal"><span class="pre">lto_module_create()</span></code>
+returns that the file is an LLVM bitcode file, the linker then iterates over the
+module using <code class="docutils literal"><span class="pre">lto_module_get_symbol_name()</span></code> and
+<code class="docutils literal"><span class="pre">lto_module_get_symbol_attribute()</span></code> to get all symbols defined and referenced.
+This information is added to the linker’s global symbol table.</p>
+<p>The lto* functions are all implemented in a shared object libLTO. This allows
+the LLVM LTO code to be updated independently of the linker tool. On platforms
+that support it, the shared object is lazily loaded.</p>
+</div>
+<div class="section" id="phase-2-symbol-resolution">
+<h3><a class="toc-backref" href="#id8">Phase 2 : Symbol Resolution</a><a class="headerlink" href="#phase-2-symbol-resolution" title="Permalink to this headline">¶</a></h3>
+<p>In this stage, the linker resolves symbols using global symbol table. It may
+report undefined symbol errors, read archive members, replace weak symbols, etc.
+The linker is able to do this seamlessly even though it does not know the exact
+content of input LLVM bitcode files. If dead code stripping is enabled then the
+linker collects the list of live symbols.</p>
+</div>
+<div class="section" id="phase-3-optimize-bitcode-files">
+<h3><a class="toc-backref" href="#id9">Phase 3 : Optimize Bitcode Files</a><a class="headerlink" href="#phase-3-optimize-bitcode-files" title="Permalink to this headline">¶</a></h3>
+<p>After symbol resolution, the linker tells the LTO shared object which symbols
+are needed by native object files. In the example above, the linker reports
+that only <code class="docutils literal"><span class="pre">foo1()</span></code> is used by native object files using
+<code class="docutils literal"><span class="pre">lto_codegen_add_must_preserve_symbol()</span></code>. Next the linker invokes the LLVM
+optimizer and code generators using <code class="docutils literal"><span class="pre">lto_codegen_compile()</span></code> which returns a
+native object file creating by merging the LLVM bitcode files and applying
+various optimization passes.</p>
+</div>
+<div class="section" id="phase-4-symbol-resolution-after-optimization">
+<h3><a class="toc-backref" href="#id10">Phase 4 : Symbol Resolution after optimization</a><a class="headerlink" href="#phase-4-symbol-resolution-after-optimization" title="Permalink to this headline">¶</a></h3>
+<p>In this phase, the linker reads optimized a native object file and updates the
+internal global symbol table to reflect any changes. The linker also collects
+information about any changes in use of external symbols by LLVM bitcode
+files. In the example above, the linker notes that <code class="docutils literal"><span class="pre">foo4()</span></code> is not used any
+more. If dead code stripping is enabled then the linker refreshes the live
+symbol information appropriately and performs dead code stripping.</p>
+<p>After this phase, the linker continues linking as if it never saw LLVM bitcode
+files.</p>
+</div>
+</div>
+<div class="section" id="liblto">
+<span id="id1"></span><h2><a class="toc-backref" href="#id11"><code class="docutils literal"><span class="pre">libLTO</span></code></a><a class="headerlink" href="#liblto" title="Permalink to this headline">¶</a></h2>
+<p><code class="docutils literal"><span class="pre">libLTO</span></code> is a shared object that is part of the LLVM tools, and is intended
+for use by a linker. <code class="docutils literal"><span class="pre">libLTO</span></code> provides an abstract C interface to use the LLVM
+interprocedural optimizer without exposing details of LLVM’s internals. The
+intention is to keep the interface as stable as possible even when the LLVM
+optimizer continues to evolve. It should even be possible for a completely
+different compilation technology to provide a different libLTO that works with
+their object files and the standard linker tool.</p>
+<div class="section" id="lto-module-t">
+<h3><a class="toc-backref" href="#id12"><code class="docutils literal"><span class="pre">lto_module_t</span></code></a><a class="headerlink" href="#lto-module-t" title="Permalink to this headline">¶</a></h3>
+<p>A non-native object file is handled via an <code class="docutils literal"><span class="pre">lto_module_t</span></code>. The following
+functions allow the linker to check if a file (on disk or in a memory buffer) is
+a file which libLTO can process:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_module_is_object_file</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span><span class="p">)</span>
+<span class="n">lto_module_is_object_file_for_target</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span><span class="p">)</span>
+<span class="n">lto_module_is_object_file_in_memory</span><span class="p">(</span><span class="k">const</span> <span class="kt">void</span><span class="o">*</span><span class="p">,</span> <span class="kt">size_t</span><span class="p">)</span>
+<span class="n">lto_module_is_object_file_in_memory_for_target</span><span class="p">(</span><span class="k">const</span> <span class="kt">void</span><span class="o">*</span><span class="p">,</span> <span class="kt">size_t</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>If the object file can be processed by <code class="docutils literal"><span class="pre">libLTO</span></code>, the linker creates a
+<code class="docutils literal"><span class="pre">lto_module_t</span></code> by using one of:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_module_create</span><span class="p">(</span><span class="k">const</span> <span class="kt">char</span><span class="o">*</span><span class="p">)</span>
+<span class="n">lto_module_create_from_memory</span><span class="p">(</span><span class="k">const</span> <span class="kt">void</span><span class="o">*</span><span class="p">,</span> <span class="kt">size_t</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>and when done, the handle is released via</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_module_dispose</span><span class="p">(</span><span class="n">lto_module_t</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The linker can introspect the non-native object file by getting the number of
+symbols and getting the name and attributes of each symbol via:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_module_get_num_symbols</span><span class="p">(</span><span class="n">lto_module_t</span><span class="p">)</span>
+<span class="n">lto_module_get_symbol_name</span><span class="p">(</span><span class="n">lto_module_t</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">int</span><span class="p">)</span>
+<span class="n">lto_module_get_symbol_attribute</span><span class="p">(</span><span class="n">lto_module_t</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="kt">int</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The attributes of a symbol include the alignment, visibility, and kind.</p>
+</div>
+<div class="section" id="lto-code-gen-t">
+<h3><a class="toc-backref" href="#id13"><code class="docutils literal"><span class="pre">lto_code_gen_t</span></code></a><a class="headerlink" href="#lto-code-gen-t" title="Permalink to this headline">¶</a></h3>
+<p>Once the linker has loaded each non-native object files into an
+<code class="docutils literal"><span class="pre">lto_module_t</span></code>, it can request <code class="docutils literal"><span class="pre">libLTO</span></code> to process them all and generate a
+native object file. This is done in a couple of steps. First, a code generator
+is created with:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_codegen_create</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>Then, each non-native object file is added to the code generator with:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_codegen_add_module</span><span class="p">(</span><span class="n">lto_code_gen_t</span><span class="p">,</span> <span class="n">lto_module_t</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The linker then has the option of setting some codegen options. Whether or not
+to generate DWARF debug info is set with:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_codegen_set_debug_model</span><span class="p">(</span><span class="n">lto_code_gen_t</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>which kind of position independence is set with:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_codegen_set_pic_model</span><span class="p">(</span><span class="n">lto_code_gen_t</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>And each symbol that is referenced by a native object file or otherwise must not
+be optimized away is set with:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_codegen_add_must_preserve_symbol</span><span class="p">(</span><span class="n">lto_code_gen_t</span><span class="p">,</span> <span class="k">const</span> <span class="kt">char</span><span class="o">*</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>After all these settings are done, the linker requests that a native object file
+be created from the modules with the settings using:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">lto_codegen_compile</span><span class="p">(</span><span class="n">lto_code_gen_t</span><span class="p">,</span> <span class="n">size</span><span class="o">*</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>which returns a pointer to a buffer containing the generated native object file.
+The linker then parses that and links it with the rest of the native object
+files.</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="SegmentedStacks.html" title="Segmented Stacks in LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ExceptionHandling.html" title="Exception Handling in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/MCJITDesignAndImplementation.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/MCJITDesignAndImplementation.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/MCJITDesignAndImplementation.html (added)
+++ www-releases/trunk/6.0.0/docs/MCJITDesignAndImplementation.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,247 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>MCJIT Design and Implementation — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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 Community Code of Conduct" href="CodeOfConduct.html" />
+ <link rel="prev" title="Performance Tips for Frontend Authors" href="Frontend/PerformanceTips.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="CodeOfConduct.html" title="LLVM Community Code of Conduct"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
+ 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="mcjit-design-and-implementation">
+<h1>MCJIT Design and Implementation<a class="headerlink" href="#mcjit-design-and-implementation" 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>This document describes the internal workings of the MCJIT execution
+engine and the RuntimeDyld component. It is intended as a high level
+overview of the implementation, showing the flow and interactions of
+objects throughout the code generation and dynamic loading process.</p>
+</div>
+<div class="section" id="engine-creation">
+<h2>Engine Creation<a class="headerlink" href="#engine-creation" title="Permalink to this headline">¶</a></h2>
+<p>In most cases, an EngineBuilder object is used to create an instance of
+the MCJIT execution engine. The EngineBuilder takes an llvm::Module
+object as an argument to its constructor. The client may then set various
+options that we control the later be passed along to the MCJIT engine,
+including the selection of MCJIT as the engine type to be created.
+Of particular interest is the EngineBuilder::setMCJITMemoryManager
+function. If the client does not explicitly create a memory manager at
+this time, a default memory manager (specifically SectionMemoryManager)
+will be created when the MCJIT engine is instantiated.</p>
+<p>Once the options have been set, a client calls EngineBuilder::create to
+create an instance of the MCJIT engine. If the client does not use the
+form of this function that takes a TargetMachine as a parameter, a new
+TargetMachine will be created based on the target triple associated with
+the Module that was used to create the EngineBuilder.</p>
+<img alt="_images/MCJIT-engine-builder.png" src="_images/MCJIT-engine-builder.png" />
+<p>EngineBuilder::create will call the static MCJIT::createJIT function,
+passing in its pointers to the module, memory manager and target machine
+objects, all of which will subsequently be owned by the MCJIT object.</p>
+<p>The MCJIT class has a member variable, Dyld, which contains an instance of
+the RuntimeDyld wrapper class. This member will be used for
+communications between MCJIT and the actual RuntimeDyldImpl object that
+gets created when an object is loaded.</p>
+<img alt="_images/MCJIT-creation.png" src="_images/MCJIT-creation.png" />
+<p>Upon creation, MCJIT holds a pointer to the Module object that it received
+from EngineBuilder but it does not immediately generate code for this
+module. Code generation is deferred until either the
+MCJIT::finalizeObject method is called explicitly or a function such as
+MCJIT::getPointerToFunction is called which requires the code to have been
+generated.</p>
+</div>
+<div class="section" id="code-generation">
+<h2>Code Generation<a class="headerlink" href="#code-generation" title="Permalink to this headline">¶</a></h2>
+<p>When code generation is triggered, as described above, MCJIT will first
+attempt to retrieve an object image from its ObjectCache member, if one
+has been set. If a cached object image cannot be retrieved, MCJIT will
+call its emitObject method. MCJIT::emitObject uses a local PassManager
+instance and creates a new ObjectBufferStream instance, both of which it
+passes to TargetMachine::addPassesToEmitMC before calling PassManager::run
+on the Module with which it was created.</p>
+<img alt="_images/MCJIT-load.png" src="_images/MCJIT-load.png" />
+<p>The PassManager::run call causes the MC code generation mechanisms to emit
+a complete relocatable binary object image (either in either ELF or MachO
+format, depending on the target) into the ObjectBufferStream object, which
+is flushed to complete the process. If an ObjectCache is being used, the
+image will be passed to the ObjectCache here.</p>
+<p>At this point, the ObjectBufferStream contains the raw object image.
+Before the code can be executed, the code and data sections from this
+image must be loaded into suitable memory, relocations must be applied and
+memory permission and code cache invalidation (if required) must be completed.</p>
+</div>
+<div class="section" id="object-loading">
+<h2>Object Loading<a class="headerlink" href="#object-loading" title="Permalink to this headline">¶</a></h2>
+<p>Once an object image has been obtained, either through code generation or
+having been retrieved from an ObjectCache, it is passed to RuntimeDyld to
+be loaded. The RuntimeDyld wrapper class examines the object to determine
+its file format and creates an instance of either RuntimeDyldELF or
+RuntimeDyldMachO (both of which derive from the RuntimeDyldImpl base
+class) and calls the RuntimeDyldImpl::loadObject method to perform that
+actual loading.</p>
+<img alt="_images/MCJIT-dyld-load.png" src="_images/MCJIT-dyld-load.png" />
+<p>RuntimeDyldImpl::loadObject begins by creating an ObjectImage instance
+from the ObjectBuffer it received. ObjectImage, which wraps the
+ObjectFile class, is a helper class which parses the binary object image
+and provides access to the information contained in the format-specific
+headers, including section, symbol and relocation information.</p>
+<p>RuntimeDyldImpl::loadObject then iterates through the symbols in the
+image. Information about common symbols is collected for later use. For
+each function or data symbol, the associated section is loaded into memory
+and the symbol is stored in a symbol table map data structure. When the
+iteration is complete, a section is emitted for the common symbols.</p>
+<p>Next, RuntimeDyldImpl::loadObject iterates through the sections in the
+object image and for each section iterates through the relocations for
+that sections. For each relocation, it calls the format-specific
+processRelocationRef method, which will examine the relocation and store
+it in one of two data structures, a section-based relocation list map and
+an external symbol relocation map.</p>
+<img alt="_images/MCJIT-load-object.png" src="_images/MCJIT-load-object.png" />
+<p>When RuntimeDyldImpl::loadObject returns, all of the code and data
+sections for the object will have been loaded into memory allocated by the
+memory manager and relocation information will have been prepared, but the
+relocations have not yet been applied and the generated code is still not
+ready to be executed.</p>
+<p>[Currently (as of August 2013) the MCJIT engine will immediately apply
+relocations when loadObject completes. However, this shouldn’t be
+happening. Because the code may have been generated for a remote target,
+the client should be given a chance to re-map the section addresses before
+relocations are applied. It is possible to apply relocations multiple
+times, but in the case where addresses are to be re-mapped, this first
+application is wasted effort.]</p>
+</div>
+<div class="section" id="address-remapping">
+<h2>Address Remapping<a class="headerlink" href="#address-remapping" title="Permalink to this headline">¶</a></h2>
+<p>At any time after initial code has been generated and before
+finalizeObject is called, the client can remap the address of sections in
+the object. Typically this is done because the code was generated for an
+external process and is being mapped into that process’ address space.
+The client remaps the section address by calling MCJIT::mapSectionAddress.
+This should happen before the section memory is copied to its new
+location.</p>
+<p>When MCJIT::mapSectionAddress is called, MCJIT passes the call on to
+RuntimeDyldImpl (via its Dyld member). RuntimeDyldImpl stores the new
+address in an internal data structure but does not update the code at this
+time, since other sections are likely to change.</p>
+<p>When the client is finished remapping section addresses, it will call
+MCJIT::finalizeObject to complete the remapping process.</p>
+</div>
+<div class="section" id="final-preparations">
+<h2>Final Preparations<a class="headerlink" href="#final-preparations" title="Permalink to this headline">¶</a></h2>
+<p>When MCJIT::finalizeObject is called, MCJIT calls
+RuntimeDyld::resolveRelocations. This function will attempt to locate any
+external symbols and then apply all relocations for the object.</p>
+<p>External symbols are resolved by calling the memory manager’s
+getPointerToNamedFunction method. The memory manager will return the
+address of the requested symbol in the target address space. (Note, this
+may not be a valid pointer in the host process.) RuntimeDyld will then
+iterate through the list of relocations it has stored which are associated
+with this symbol and invoke the resolveRelocation method which, through an
+format-specific implementation, will apply the relocation to the loaded
+section memory.</p>
+<p>Next, RuntimeDyld::resolveRelocations iterates through the list of
+sections and for each section iterates through a list of relocations that
+have been saved which reference that symbol and call resolveRelocation for
+each entry in this list. The relocation list here is a list of
+relocations for which the symbol associated with the relocation is located
+in the section associated with the list. Each of these locations will
+have a target location at which the relocation will be applied that is
+likely located in a different section.</p>
+<img alt="_images/MCJIT-resolve-relocations.png" src="_images/MCJIT-resolve-relocations.png" />
+<p>Once relocations have been applied as described above, MCJIT calls
+RuntimeDyld::getEHFrameSection, and if a non-zero result is returned
+passes the section data to the memory manager’s registerEHFrames method.
+This allows the memory manager to call any desired target-specific
+functions, such as registering the EH frame information with a debugger.</p>
+<p>Finally, MCJIT calls the memory manager’s finalizeMemory method. In this
+method, the memory manager will invalidate the target code cache, if
+necessary, and apply final permissions to the memory pages it has
+allocated for code and data memory.</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="CodeOfConduct.html" title="LLVM Community Code of Conduct"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
+ >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-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/MIRLangRef.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/MIRLangRef.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/MIRLangRef.html (added)
+++ www-releases/trunk/6.0.0/docs/MIRLangRef.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,727 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Machine IR (MIR) Format Reference Manual — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="Coroutines in LLVM" href="Coroutines.html" />
+ <link rel="prev" title="FaultMaps and implicit checks" href="FaultMaps.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="Coroutines.html" title="Coroutines in LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="FaultMaps.html" title="FaultMaps and implicit checks"
+ 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="machine-ir-mir-format-reference-manual">
+<h1>Machine IR (MIR) Format Reference Manual<a class="headerlink" href="#machine-ir-mir-format-reference-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="id10">Introduction</a></li>
+<li><a class="reference internal" href="#overview" id="id11">Overview</a></li>
+<li><a class="reference internal" href="#mir-testing-guide" id="id12">MIR Testing Guide</a><ul>
+<li><a class="reference internal" href="#testing-individual-code-generation-passes" id="id13">Testing Individual Code Generation Passes</a><ul>
+<li><a class="reference internal" href="#simplifying-mir-files" id="id14">Simplifying MIR files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#limitations" id="id15">Limitations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#high-level-structure" id="id16">High Level Structure</a><ul>
+<li><a class="reference internal" href="#embedded-module" id="id17">Embedded Module</a></li>
+<li><a class="reference internal" href="#machine-functions" id="id18">Machine Functions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#machine-instructions-format-reference" id="id19">Machine Instructions Format Reference</a><ul>
+<li><a class="reference internal" href="#machine-basic-blocks" id="id20">Machine Basic Blocks</a><ul>
+<li><a class="reference internal" href="#block-references" id="id21">Block References</a></li>
+<li><a class="reference internal" href="#successors" id="id22">Successors</a></li>
+<li><a class="reference internal" href="#live-in-registers" id="id23">Live In Registers</a></li>
+<li><a class="reference internal" href="#miscellaneous-attributes" id="id24">Miscellaneous Attributes</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#machine-instructions" id="id25">Machine Instructions</a><ul>
+<li><a class="reference internal" href="#instruction-flags" id="id26">Instruction Flags</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#registers" id="id27">Registers</a></li>
+<li><a class="reference internal" href="#machine-operands" id="id28">Machine Operands</a><ul>
+<li><a class="reference internal" href="#immediate-operands" id="id29">Immediate Operands</a></li>
+<li><a class="reference internal" href="#register-operands" id="id30">Register Operands</a><ul>
+<li><a class="reference internal" href="#register-flags" id="id31">Register Flags</a></li>
+<li><a class="reference internal" href="#subregister-indices" id="id32">Subregister Indices</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#constant-pool-indices" id="id33">Constant Pool Indices</a></li>
+<li><a class="reference internal" href="#global-value-operands" id="id34">Global Value Operands</a></li>
+<li><a class="reference internal" href="#target-dependent-index-operands" id="id35">Target-dependent Index Operands</a></li>
+<li><a class="reference internal" href="#jump-table-index-operands" id="id36">Jump-table Index Operands</a></li>
+<li><a class="reference internal" href="#external-symbol-operands" id="id37">External Symbol Operands</a></li>
+<li><a class="reference internal" href="#mcsymbol-operands" id="id38">MCSymbol Operands</a></li>
+<li><a class="reference internal" href="#cfiindex-operands" id="id39">CFIIndex Operands</a></li>
+<li><a class="reference internal" href="#intrinsicid-operands" id="id40">IntrinsicID Operands</a></li>
+<li><a class="reference internal" href="#predicate-operands" id="id41">Predicate Operands</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This is a work in progress.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id10">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is a reference manual for the Machine IR (MIR) serialization
+format. MIR is a human readable serialization format that is used to represent
+LLVM’s <a class="reference internal" href="CodeGenerator.html#machine-code-representation"><span class="std std-ref">machine specific intermediate representation</span></a>.</p>
+<p>The MIR serialization format is designed to be used for testing the code
+generation passes in LLVM.</p>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id11">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>The MIR serialization format uses a YAML container. YAML is a standard
+data serialization language, and the full YAML language spec can be read at
+<a class="reference external" href="http://www.yaml.org/spec/1.2/spec.html#Introduction">yaml.org</a>.</p>
+<p>A MIR file is split up into a series of <a class="reference external" href="http://www.yaml.org/spec/1.2/spec.html#id2800132">YAML documents</a>. The first document
+can contain an optional embedded LLVM IR module, and the rest of the documents
+contain the serialized machine functions.</p>
+</div>
+<div class="section" id="mir-testing-guide">
+<h2><a class="toc-backref" href="#id12">MIR Testing Guide</a><a class="headerlink" href="#mir-testing-guide" title="Permalink to this headline">¶</a></h2>
+<p>You can use the MIR format for testing in two different ways:</p>
+<ul class="simple">
+<li>You can write MIR tests that invoke a single code generation pass using the
+<code class="docutils literal"><span class="pre">-run-pass</span></code> option in llc.</li>
+<li>You can use llc’s <code class="docutils literal"><span class="pre">-stop-after</span></code> option with existing or new LLVM assembly
+tests and check the MIR output of a specific code generation pass.</li>
+</ul>
+<div class="section" id="testing-individual-code-generation-passes">
+<h3><a class="toc-backref" href="#id13">Testing Individual Code Generation Passes</a><a class="headerlink" href="#testing-individual-code-generation-passes" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal"><span class="pre">-run-pass</span></code> option in llc allows you to create MIR tests that invoke just
+a single code generation pass. When this option is used, llc will parse an
+input MIR file, run the specified code generation pass(es), and output the
+resulting MIR code.</p>
+<p>You can generate an input MIR file for the test by using the <code class="docutils literal"><span class="pre">-stop-after</span></code> or
+<code class="docutils literal"><span class="pre">-stop-before</span></code> option in llc. For example, if you would like to write a test
+for the post register allocation pseudo instruction expansion pass, you can
+specify the machine copy propagation pass in the <code class="docutils literal"><span class="pre">-stop-after</span></code> option, as it
+runs just before the pass that we are trying to test:</p>
+<blockquote>
+<div><code class="docutils literal"><span class="pre">llc</span> <span class="pre">-stop-after=machine-cp</span> <span class="pre">bug-trigger.ll</span> <span class="pre">></span> <span class="pre">test.mir</span></code></div></blockquote>
+<p>After generating the input MIR file, you’ll have to add a run line that uses
+the <code class="docutils literal"><span class="pre">-run-pass</span></code> option to it. In order to test the post register allocation
+pseudo instruction expansion pass on X86-64, a run line like the one shown
+below can be used:</p>
+<blockquote>
+<div><code class="docutils literal"><span class="pre">#</span> <span class="pre">RUN:</span> <span class="pre">llc</span> <span class="pre">-o</span> <span class="pre">-</span> <span class="pre">%s</span> <span class="pre">-mtriple=x86_64--</span> <span class="pre">-run-pass=postrapseudos</span> <span class="pre">|</span> <span class="pre">FileCheck</span> <span class="pre">%s</span></code></div></blockquote>
+<p>The MIR files are target dependent, so they have to be placed in the target
+specific test directories (<code class="docutils literal"><span class="pre">lib/CodeGen/TARGETNAME</span></code>). They also need to
+specify a target triple or a target architecture either in the run line or in
+the embedded LLVM IR module.</p>
+<div class="section" id="simplifying-mir-files">
+<h4><a class="toc-backref" href="#id14">Simplifying MIR files</a><a class="headerlink" href="#simplifying-mir-files" title="Permalink to this headline">¶</a></h4>
+<p>The MIR code coming out of <code class="docutils literal"><span class="pre">-stop-after</span></code>/<code class="docutils literal"><span class="pre">-stop-before</span></code> is very verbose;
+Tests are more accessible and future proof when simplified:</p>
+<ul class="simple">
+<li>Use the <code class="docutils literal"><span class="pre">-simplify-mir</span></code> option with llc.</li>
+<li>Machine function attributes often have default values or the test works just
+as well with default values. Typical candidates for this are: <cite>alignment:</cite>,
+<cite>exposesReturnsTwice</cite>, <cite>legalized</cite>, <cite>regBankSelected</cite>, <cite>selected</cite>.
+The whole <cite>frameInfo</cite> section is often unnecessary if there is no special
+frame usage in the function. <cite>tracksRegLiveness</cite> on the other hand is often
+necessary for some passes that care about block livein lists.</li>
+<li>The (global) <cite>liveins:</cite> list is typically only interesting for early
+instruction selection passes and can be removed when testing later passes.
+The per-block <cite>liveins:</cite> on the other hand are necessary if
+<cite>tracksRegLiveness</cite> is true.</li>
+<li>Branch probability data in block <cite>successors:</cite> lists can be dropped if the
+test doesn’t depend on it. Example:
+<cite>successors: %bb.1(0x40000000), %bb.2(0x40000000)</cite> can be replaced with
+<cite>successors: %bb.1, %bb.2</cite>.</li>
+<li>MIR code contains a whole IR module. This is necessary because there are
+no equivalents in MIR for global variables, references to external functions,
+function attributes, metadata, debug info. Instead some MIR data references
+the IR constructs. You can often remove them if the test doesn’t depend on
+them.</li>
+<li>Alias Analysis is performed on IR values. These are referenced by memory
+operands in MIR. Example: <cite>:: (load 8 from %ir.foobar, !alias.scope !9)</cite>.
+If the test doesn’t depend on (good) alias analysis the references can be
+dropped: <cite>:: (load 8)</cite></li>
+<li>MIR blocks can reference IR blocks for debug printing, profile information
+or debug locations. Example: <cite>bb.42.myblock</cite> in MIR references the IR block
+<cite>myblock</cite>. It is usually possible to drop the <cite>.myblock</cite> reference and simply
+use <cite>bb.42</cite>.</li>
+<li>If there are no memory operands or blocks referencing the IR then the
+IR function can be replaced by a parameterless dummy function like
+<cite>define @func() { ret void }</cite>.</li>
+<li>It is possible to drop the whole IR section of the MIR file if it only
+contains dummy functions (see above). The .mir loader will create the
+IR functions automatically in this case.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="limitations">
+<span id="id1"></span><h3><a class="toc-backref" href="#id15">Limitations</a><a class="headerlink" href="#limitations" title="Permalink to this headline">¶</a></h3>
+<p>Currently the MIR format has several limitations in terms of which state it
+can serialize:</p>
+<ul class="simple">
+<li>The target-specific state in the target-specific <code class="docutils literal"><span class="pre">MachineFunctionInfo</span></code>
+subclasses isn’t serialized at the moment.</li>
+<li>The target-specific <code class="docutils literal"><span class="pre">MachineConstantPoolValue</span></code> subclasses (in the ARM and
+SystemZ backends) aren’t serialized at the moment.</li>
+<li>The <code class="docutils literal"><span class="pre">MCSymbol</span></code> machine operands are only printed, they can’t be parsed.</li>
+<li>A lot of the state in <code class="docutils literal"><span class="pre">MachineModuleInfo</span></code> isn’t serialized - only the CFI
+instructions and the variable debug information from MMI is serialized right
+now.</li>
+</ul>
+<p>These limitations impose restrictions on what you can test with the MIR format.
+For now, tests that would like to test some behaviour that depends on the state
+of certain <code class="docutils literal"><span class="pre">MCSymbol</span></code> operands or the exception handling state in MMI, can’t
+use the MIR format. As well as that, tests that test some behaviour that
+depends on the state of the target specific <code class="docutils literal"><span class="pre">MachineFunctionInfo</span></code> or
+<code class="docutils literal"><span class="pre">MachineConstantPoolValue</span></code> subclasses can’t use the MIR format at the moment.</p>
+</div>
+</div>
+<div class="section" id="high-level-structure">
+<h2><a class="toc-backref" href="#id16">High Level Structure</a><a class="headerlink" href="#high-level-structure" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="embedded-module">
+<span id="id2"></span><h3><a class="toc-backref" href="#id17">Embedded Module</a><a class="headerlink" href="#embedded-module" title="Permalink to this headline">¶</a></h3>
+<p>When the first YAML document contains a <a class="reference external" href="http://www.yaml.org/spec/1.2/spec.html#id2795688">YAML block literal string</a>, the MIR
+parser will treat this string as an LLVM assembly language string that
+represents an embedded LLVM IR module.
+Here is an example of a YAML document that contains an LLVM module:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">i32</span> <span class="vg">@inc</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 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</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 nv-Anonymous">%0</span><span class="p">,</span> <span class="m">1</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv nv-Anonymous">%1</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%x</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="nv nv-Anonymous">%1</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="machine-functions">
+<h3><a class="toc-backref" href="#id18">Machine Functions</a><a class="headerlink" href="#machine-functions" title="Permalink to this headline">¶</a></h3>
+<p>The remaining YAML documents contain the machine functions. This is an example
+of such YAML document:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>---
+name: inc
+tracksRegLiveness: true
+liveins:
+ - { reg: '%rdi' }
+body: |
+ bb.0.entry:
+ liveins: %rdi
+
+ %eax = MOV32rm %rdi, 1, _, 0, _
+ %eax = INC32r killed %eax, implicit-def dead %eflags
+ MOV32mr killed %rdi, 1, _, 0, _, %eax
+ RETQ %eax
+...
+</pre></div>
+</div>
+<p>The document above consists of attributes that represent the various
+properties and data structures in a machine function.</p>
+<p>The attribute <code class="docutils literal"><span class="pre">name</span></code> is required, and its value should be identical to the
+name of a function that this machine function is based on.</p>
+<p>The attribute <code class="docutils literal"><span class="pre">body</span></code> is a <a class="reference external" href="http://www.yaml.org/spec/1.2/spec.html#id2795688">YAML block literal string</a>. Its value represents
+the function’s machine basic blocks and their machine instructions.</p>
+</div>
+</div>
+<div class="section" id="machine-instructions-format-reference">
+<h2><a class="toc-backref" href="#id19">Machine Instructions Format Reference</a><a class="headerlink" href="#machine-instructions-format-reference" title="Permalink to this headline">¶</a></h2>
+<p>The machine basic blocks and their instructions are represented using a custom,
+human readable serialization language. This language is used in the
+<a class="reference external" href="http://www.yaml.org/spec/1.2/spec.html#id2795688">YAML block literal string</a> that corresponds to the machine function’s body.</p>
+<p>A source string that uses this language contains a list of machine basic
+blocks, which are described in the section below.</p>
+<div class="section" id="machine-basic-blocks">
+<h3><a class="toc-backref" href="#id20">Machine Basic Blocks</a><a class="headerlink" href="#machine-basic-blocks" title="Permalink to this headline">¶</a></h3>
+<p>A machine basic block is defined in a single block definition source construct
+that contains the block’s ID.
+The example below defines two blocks that have an ID of zero and one:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>bb.0:
+ <instructions>
+bb.1:
+ <instructions>
+</pre></div>
+</div>
+<p>A machine basic block can also have a name. It should be specified after the ID
+in the block’s definition:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>bb.0.entry: ; This block's name is "entry"
+ <instructions>
+</pre></div>
+</div>
+<p>The block’s name should be identical to the name of the IR block that this
+machine block is based on.</p>
+<div class="section" id="block-references">
+<span id="id3"></span><h4><a class="toc-backref" href="#id21">Block References</a><a class="headerlink" href="#block-references" title="Permalink to this headline">¶</a></h4>
+<p>The machine basic blocks are identified by their ID numbers. Individual
+blocks are referenced using the following syntax:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%bb.<id>
+</pre></div>
+</div>
+<p>Example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="nv">%bb.0</span>
+</pre></div>
+</div>
+<p>The following syntax is also supported, but the former syntax is preferred for
+block references:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%bb.<id>[.<name>]
+</pre></div>
+</div>
+<p>Example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="nv">%bb.1.then</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="successors">
+<h4><a class="toc-backref" href="#id22">Successors</a><a class="headerlink" href="#successors" title="Permalink to this headline">¶</a></h4>
+<p>The machine basic block’s successors have to be specified before any of the
+instructions:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>bb.0.entry:
+ successors: %bb.1.then, %bb.2.else
+ <instructions>
+bb.1.then:
+ <instructions>
+bb.2.else:
+ <instructions>
+</pre></div>
+</div>
+<p>The branch weights can be specified in brackets after the successor blocks.
+The example below defines a block that has two successors with branch weights
+of 32 and 16:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>bb.0.entry:
+ successors: %bb.1.then(32), %bb.2.else(16)
+</pre></div>
+</div>
+</div>
+<div class="section" id="live-in-registers">
+<span id="bb-liveins"></span><h4><a class="toc-backref" href="#id23">Live In Registers</a><a class="headerlink" href="#live-in-registers" title="Permalink to this headline">¶</a></h4>
+<p>The machine basic block’s live in registers have to be specified before any of
+the instructions:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>bb.0.entry:
+ liveins: %edi, %esi
+</pre></div>
+</div>
+<p>The list of live in registers and successors can be empty. The language also
+allows multiple live in register and successor lists - they are combined into
+one list by the parser.</p>
+</div>
+<div class="section" id="miscellaneous-attributes">
+<h4><a class="toc-backref" href="#id24">Miscellaneous Attributes</a><a class="headerlink" href="#miscellaneous-attributes" title="Permalink to this headline">¶</a></h4>
+<p>The attributes <code class="docutils literal"><span class="pre">IsAddressTaken</span></code>, <code class="docutils literal"><span class="pre">IsLandingPad</span></code> and <code class="docutils literal"><span class="pre">Alignment</span></code> can be
+specified in brackets after the block’s definition:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>bb.0.entry (address-taken):
+ <instructions>
+bb.2.else (align 4):
+ <instructions>
+bb.3(landing-pad, align 4):
+ <instructions>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="machine-instructions">
+<h3><a class="toc-backref" href="#id25">Machine Instructions</a><a class="headerlink" href="#machine-instructions" title="Permalink to this headline">¶</a></h3>
+<p>A machine instruction is composed of a name,
+<a class="reference internal" href="#machine-operands"><span class="std std-ref">machine operands</span></a>,
+<a class="reference internal" href="#instruction-flags"><span class="std std-ref">instruction flags</span></a>, and machine memory operands.</p>
+<p>The instruction’s name is usually specified before the operands. The example
+below shows an instance of the X86 <code class="docutils literal"><span class="pre">RETQ</span></code> instruction with a single machine
+operand:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>RETQ %eax
+</pre></div>
+</div>
+<p>However, if the machine instruction has one or more explicitly defined register
+operands, the instruction’s name has to be specified after them. The example
+below shows an instance of the AArch64 <code class="docutils literal"><span class="pre">LDPXpost</span></code> instruction with three
+defined register operands:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%sp, %fp, %lr = LDPXpost %sp, 2
+</pre></div>
+</div>
+<p>The instruction names are serialized using the exact definitions from the
+target’s <code class="docutils literal"><span class="pre">*InstrInfo.td</span></code> files, and they are case sensitive. This means that
+similar instruction names like <code class="docutils literal"><span class="pre">TSTri</span></code> and <code class="docutils literal"><span class="pre">tSTRi</span></code> represent different
+machine instructions.</p>
+<div class="section" id="instruction-flags">
+<span id="id4"></span><h4><a class="toc-backref" href="#id26">Instruction Flags</a><a class="headerlink" href="#instruction-flags" title="Permalink to this headline">¶</a></h4>
+<p>The flag <code class="docutils literal"><span class="pre">frame-setup</span></code> can be specified before the instruction’s name:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%fp = frame-setup ADDXri %sp, 0, 0
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="registers">
+<span id="id5"></span><h3><a class="toc-backref" href="#id27">Registers</a><a class="headerlink" href="#registers" title="Permalink to this headline">¶</a></h3>
+<p>Registers are one of the key primitives in the machine instructions
+serialization language. They are primarly used in the
+<a class="reference internal" href="#register-operands"><span class="std std-ref">register machine operands</span></a>,
+but they can also be used in a number of other places, like the
+<a class="reference internal" href="#bb-liveins"><span class="std std-ref">basic block’s live in list</span></a>.</p>
+<p>The physical registers are identified by their name. They use the following
+syntax:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%<name>
+</pre></div>
+</div>
+<p>The example below shows three X86 physical registers:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%eax
+%r15
+%eflags
+</pre></div>
+</div>
+<p>The virtual registers are identified by their ID number. They use the following
+syntax:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%<id>
+</pre></div>
+</div>
+<p>Example:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%0
+</pre></div>
+</div>
+<p>The null registers are represented using an underscore (‘<code class="docutils literal"><span class="pre">_</span></code>‘). They can also be
+represented using a ‘<code class="docutils literal"><span class="pre">%noreg</span></code>‘ named register, although the former syntax
+is preferred.</p>
+</div>
+<div class="section" id="machine-operands">
+<span id="id6"></span><h3><a class="toc-backref" href="#id28">Machine Operands</a><a class="headerlink" href="#machine-operands" title="Permalink to this headline">¶</a></h3>
+<p>There are seventeen different kinds of machine operands, and all of them, except
+the <code class="docutils literal"><span class="pre">MCSymbol</span></code> operand, can be serialized. The <code class="docutils literal"><span class="pre">MCSymbol</span></code> operands are
+just printed out - they can’t be parsed back yet.</p>
+<div class="section" id="immediate-operands">
+<h4><a class="toc-backref" href="#id29">Immediate Operands</a><a class="headerlink" href="#immediate-operands" title="Permalink to this headline">¶</a></h4>
+<p>The immediate machine operands are untyped, 64-bit signed integers. The
+example below shows an instance of the X86 <code class="docutils literal"><span class="pre">MOV32ri</span></code> instruction that has an
+immediate machine operand <code class="docutils literal"><span class="pre">-42</span></code>:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%eax = MOV32ri -42
+</pre></div>
+</div>
+<p>An immediate operand is also used to represent a subregister index when the
+machine instruction has one of the following opcodes:</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">EXTRACT_SUBREG</span></code></li>
+<li><code class="docutils literal"><span class="pre">INSERT_SUBREG</span></code></li>
+<li><code class="docutils literal"><span class="pre">REG_SEQUENCE</span></code></li>
+<li><code class="docutils literal"><span class="pre">SUBREG_TO_REG</span></code></li>
+</ul>
+<p>In case this is true, the Machine Operand is printed according to the target.</p>
+<p>For example:</p>
+<p>In AArch64RegisterInfo.td:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>def sub_32 : SubRegIndex<32>;
+</pre></div>
+</div>
+<p>If the third operand is an immediate with the value <code class="docutils literal"><span class="pre">15</span></code> (target-dependent
+value), based on the instruction’s opcode and the operand’s index the operand
+will be printed as <code class="docutils literal"><span class="pre">%subreg.sub_32</span></code>:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%1:gpr64 = SUBREG_TO_REG 0, %0, %subreg.sub_32
+</pre></div>
+</div>
+<p>For integers > 64bit, we use a special machine operand, <code class="docutils literal"><span class="pre">MO_CImmediate</span></code>,
+which stores the immediate in a <code class="docutils literal"><span class="pre">ConstantInt</span></code> using an <code class="docutils literal"><span class="pre">APInt</span></code> (LLVM’s
+arbitrary precision integers).</p>
+</div>
+<div class="section" id="register-operands">
+<span id="id7"></span><h4><a class="toc-backref" href="#id30">Register Operands</a><a class="headerlink" href="#register-operands" title="Permalink to this headline">¶</a></h4>
+<p>The <a class="reference internal" href="#registers"><span class="std std-ref">register</span></a> primitive is used to represent the register
+machine operands. The register operands can also have optional
+<a class="reference internal" href="#register-flags"><span class="std std-ref">register flags</span></a>,
+<a class="reference internal" href="#subregister-indices"><span class="std std-ref">a subregister index</span></a>,
+and a reference to the tied register operand.
+The full syntax of a register operand is shown below:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>[<flags>] <register> [ :<subregister-idx-name> ] [ (tied-def <tied-op>) ]
+</pre></div>
+</div>
+<p>This example shows an instance of the X86 <code class="docutils literal"><span class="pre">XOR32rr</span></code> instruction that has
+5 register operands with different register flags:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>dead %eax = XOR32rr undef %eax, undef %eax, implicit-def dead %eflags, implicit-def %al
+</pre></div>
+</div>
+<div class="section" id="register-flags">
+<span id="id8"></span><h5><a class="toc-backref" href="#id31">Register Flags</a><a class="headerlink" href="#register-flags" title="Permalink to this headline">¶</a></h5>
+<p>The table below shows all of the possible register flags along with the
+corresponding internal <code class="docutils literal"><span class="pre">llvm::RegState</span></code> representation:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="50%" />
+<col width="50%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Flag</th>
+<th class="head">Internal Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">implicit</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::Implicit</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">implicit-def</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::ImplicitDefine</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">def</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::Define</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">dead</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::Dead</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">killed</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::Kill</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">undef</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::Undef</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">internal</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::InternalRead</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">early-clobber</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::EarlyClobber</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">debug-use</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::Debug</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">renamable</span></code></td>
+<td><code class="docutils literal"><span class="pre">RegState::Renamable</span></code></td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="subregister-indices">
+<span id="id9"></span><h5><a class="toc-backref" href="#id32">Subregister Indices</a><a class="headerlink" href="#subregister-indices" title="Permalink to this headline">¶</a></h5>
+<p>The register machine operands can reference a portion of a register by using
+the subregister indices. The example below shows an instance of the <code class="docutils literal"><span class="pre">COPY</span></code>
+pseudo instruction that uses the X86 <code class="docutils literal"><span class="pre">sub_8bit</span></code> subregister index to copy 8
+lower bits from the 32-bit virtual register 0 to the 8-bit virtual register 1:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%1 = COPY %0:sub_8bit
+</pre></div>
+</div>
+<p>The names of the subregister indices are target specific, and are typically
+defined in the target’s <code class="docutils literal"><span class="pre">*RegisterInfo.td</span></code> file.</p>
+</div>
+</div>
+<div class="section" id="constant-pool-indices">
+<h4><a class="toc-backref" href="#id33">Constant Pool Indices</a><a class="headerlink" href="#constant-pool-indices" title="Permalink to this headline">¶</a></h4>
+<p>A constant pool index (CPI) operand is printed using its index in the
+function’s <code class="docutils literal"><span class="pre">MachineConstantPool</span></code> and an offset.</p>
+<p>For example, a CPI with the index 1 and offset 8:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%1:gr64 = MOV64ri %const.1 + 8
+</pre></div>
+</div>
+<p>For a CPI with the index 0 and offset -12:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%1:gr64 = MOV64ri %const.0 - 12
+</pre></div>
+</div>
+<p>A constant pool entry is bound to a LLVM IR <code class="docutils literal"><span class="pre">Constant</span></code> or a target-specific
+<code class="docutils literal"><span class="pre">MachineConstantPoolValue</span></code>. When serializing all the function’s constants the
+following format is used:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>constants:
+ - id: <index>
+ value: <value>
+ alignment: <alignment>
+ isTargetSpecific: <target-specific>
+</pre></div>
+</div>
+<p>where <code class="docutils literal"><span class="pre"><index></span></code> is a 32-bit unsigned integer, <code class="docutils literal"><span class="pre"><value></span></code> is a <a class="reference external" href="https://www.llvm.org/docs/LangRef.html#constants">LLVM IR Constant</a>, alignment is a 32-bit
+unsigned integer, and <code class="docutils literal"><span class="pre"><target-specific></span></code> is either true or false.</p>
+<p>Example:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>constants:
+ - id: 0
+ value: 'double 3.250000e+00'
+ alignment: 8
+ - id: 1
+ value: 'g-(LPC0+8)'
+ alignment: 4
+ isTargetSpecific: true
+</pre></div>
+</div>
+</div>
+<div class="section" id="global-value-operands">
+<h4><a class="toc-backref" href="#id34">Global Value Operands</a><a class="headerlink" href="#global-value-operands" title="Permalink to this headline">¶</a></h4>
+<p>The global value machine operands reference the global values from the
+<a class="reference internal" href="#embedded-module"><span class="std std-ref">embedded LLVM IR module</span></a>.
+The example below shows an instance of the X86 <code class="docutils literal"><span class="pre">MOV64rm</span></code> instruction that has
+a global value operand named <code class="docutils literal"><span class="pre">G</span></code>:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%rax = MOV64rm %rip, 1, _, @G, _
+</pre></div>
+</div>
+<p>The named global values are represented using an identifier with the ‘@’ prefix.
+If the identifier doesn’t match the regular expression
+<cite>[-a-zA-Z$._][-a-zA-Z$._0-9]*</cite>, then this identifier must be quoted.</p>
+<p>The unnamed global values are represented using an unsigned numeric value with
+the ‘@’ prefix, like in the following examples: <code class="docutils literal"><span class="pre">@0</span></code>, <code class="docutils literal"><span class="pre">@989</span></code>.</p>
+</div>
+<div class="section" id="target-dependent-index-operands">
+<h4><a class="toc-backref" href="#id35">Target-dependent Index Operands</a><a class="headerlink" href="#target-dependent-index-operands" title="Permalink to this headline">¶</a></h4>
+<p>A target index operand is a target-specific index and an offset. The
+target-specific index is printed using target-specific names and a positive or
+negative offset.</p>
+<p>For example, the <code class="docutils literal"><span class="pre">amdgpu-constdata-start</span></code> is associated with the index <code class="docutils literal"><span class="pre">0</span></code>
+in the AMDGPU backend. So if we have a target index operand with the index 0
+and the offset 8:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%sgpr2 = S_ADD_U32 _, target-index(amdgpu-constdata-start) + 8, implicit-def _, implicit-def _
+</pre></div>
+</div>
+</div>
+<div class="section" id="jump-table-index-operands">
+<h4><a class="toc-backref" href="#id36">Jump-table Index Operands</a><a class="headerlink" href="#jump-table-index-operands" title="Permalink to this headline">¶</a></h4>
+<p>A jump-table index operand with the index 0 is printed as following:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>tBR_JTr killed %r0, %jump-table.0
+</pre></div>
+</div>
+<p>A machine jump-table entry contains a list of <code class="docutils literal"><span class="pre">MachineBasicBlocks</span></code>. When serializing all the function’s jump-table entries, the following format is used:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>jumpTable:
+ kind: <kind>
+ entries:
+ - id: <index>
+ blocks: [ <bbreference>, <bbreference>, ... ]
+</pre></div>
+</div>
+<p>where <code class="docutils literal"><span class="pre"><kind></span></code> is describing how the jump table is represented and emitted (plain address, relocations, PIC, etc.), and each <code class="docutils literal"><span class="pre"><index></span></code> is a 32-bit unsigned integer and <code class="docutils literal"><span class="pre">blocks</span></code> contains a list of <a class="reference internal" href="#block-references"><span class="std std-ref">machine basic block references</span></a>.</p>
+<p>Example:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>jumpTable:
+ kind: inline
+ entries:
+ - id: 0
+ blocks: [ '%bb.3', '%bb.9', '%bb.4.d3' ]
+ - id: 1
+ blocks: [ '%bb.7', '%bb.7', '%bb.4.d3', '%bb.5' ]
+</pre></div>
+</div>
+</div>
+<div class="section" id="external-symbol-operands">
+<h4><a class="toc-backref" href="#id37">External Symbol Operands</a><a class="headerlink" href="#external-symbol-operands" title="Permalink to this headline">¶</a></h4>
+<p>An external symbol operand is represented using an identifier with the <code class="docutils literal"><span class="pre">$</span></code>
+prefix. The identifier is surrounded with ““‘s and escaped if it has any
+special non-printable characters in it.</p>
+<p>Example:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>CALL64pcrel32 $__stack_chk_fail, csr_64, implicit %rsp, implicit-def %rsp
+</pre></div>
+</div>
+</div>
+<div class="section" id="mcsymbol-operands">
+<h4><a class="toc-backref" href="#id38">MCSymbol Operands</a><a class="headerlink" href="#mcsymbol-operands" title="Permalink to this headline">¶</a></h4>
+<p>A MCSymbol operand is holding a pointer to a <code class="docutils literal"><span class="pre">MCSymbol</span></code>. For the limitations
+of this operand in MIR, see <a class="reference internal" href="#limitations"><span class="std std-ref">limitations</span></a>.</p>
+<p>The syntax is:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>EH_LABEL <mcsymbol Ltmp1>
+</pre></div>
+</div>
+</div>
+<div class="section" id="cfiindex-operands">
+<h4><a class="toc-backref" href="#id39">CFIIndex Operands</a><a class="headerlink" href="#cfiindex-operands" title="Permalink to this headline">¶</a></h4>
+<p>A CFI Index operand is holding an index into a per-function side-table,
+<code class="docutils literal"><span class="pre">MachineFunction::getFrameInstructions()</span></code>, which references all the frame
+instructions in a <code class="docutils literal"><span class="pre">MachineFunction</span></code>. A <code class="docutils literal"><span class="pre">CFI_INSTRUCTION</span></code> may look like it
+contains multiple operands, but the only operand it contains is the CFI Index.
+The other operands are tracked by the <code class="docutils literal"><span class="pre">MCCFIInstruction</span></code> object.</p>
+<p>The syntax is:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>CFI_INSTRUCTION offset %w30, -16
+</pre></div>
+</div>
+<p>which may be emitted later in the MC layer as:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>.cfi_offset w30, -16
+</pre></div>
+</div>
+</div>
+<div class="section" id="intrinsicid-operands">
+<h4><a class="toc-backref" href="#id40">IntrinsicID Operands</a><a class="headerlink" href="#intrinsicid-operands" title="Permalink to this headline">¶</a></h4>
+<p>An Intrinsic ID operand contains a generic intrinsic ID or a target-specific ID.</p>
+<p>The syntax for the <code class="docutils literal"><span class="pre">returnaddress</span></code> intrinsic is:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%x0 = COPY intrinsic(@llvm.returnaddress)
+</pre></div>
+</div>
+</div>
+<div class="section" id="predicate-operands">
+<h4><a class="toc-backref" href="#id41">Predicate Operands</a><a class="headerlink" href="#predicate-operands" title="Permalink to this headline">¶</a></h4>
+<p>A Predicate operand contains an IR predicate from <code class="docutils literal"><span class="pre">CmpInst::Predicate</span></code>, like
+<code class="docutils literal"><span class="pre">ICMP_EQ</span></code>, etc.</p>
+<p>For an int eq predicate <code class="docutils literal"><span class="pre">ICMP_EQ</span></code>, the syntax is:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>%2:gpr(s32) = G_ICMP intpred(eq), %0, %1
+</pre></div>
+</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="Coroutines.html" title="Coroutines in LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="FaultMaps.html" title="FaultMaps and implicit checks"
+ >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-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/MarkedUpDisassembly.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/MarkedUpDisassembly.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/MarkedUpDisassembly.html (added)
+++ www-releases/trunk/6.0.0/docs/MarkedUpDisassembly.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,171 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVMâs Optional Rich Disassembly Output — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="System Library" href="SystemLibrary.html" />
+ <link rel="prev" title="The LLVM gold plugin" href="GoldPlugin.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="SystemLibrary.html" title="System Library"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GoldPlugin.html" title="The LLVM gold plugin"
+ 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-s-optional-rich-disassembly-output">
+<h1>LLVM’s Optional Rich Disassembly Output<a class="headerlink" href="#llvm-s-optional-rich-disassembly-output" 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="#instruction-annotations" id="id3">Instruction Annotations</a><ul>
+<li><a class="reference internal" href="#contextual-markups" id="id4">Contextual markups</a></li>
+<li><a class="reference internal" href="#c-api-details" id="id5">C API Details</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>LLVM’s default disassembly output is raw text. To allow consumers more ability
+to introspect the instructions’ textual representation or to reformat for a more
+user friendly display there is an optional rich disassembly output.</p>
+<p>This optional output is sufficient to reference into individual portions of the
+instruction text. This is intended for clients like disassemblers, list file
+generators, and pretty-printers, which need more than the raw instructions and
+the ability to print them.</p>
+<p>To provide this functionality the assembly text is marked up with annotations.
+The markup is simple enough in syntax to be robust even in the case of version
+mismatches between consumers and producers. That is, the syntax generally does
+not carry semantics beyond “this text has an annotation,” so consumers can
+simply ignore annotations they do not understand or do not care about.</p>
+<p>After calling <code class="docutils literal"><span class="pre">LLVMCreateDisasm()</span></code> to create a disassembler context the
+optional output is enable with this call:</p>
+<div class="highlight-c"><div class="highlight"><pre><span></span><span class="n">LLVMSetDisasmOptions</span><span class="p">(</span><span class="n">DC</span><span class="p">,</span> <span class="n">LLVMDisassembler_Option_UseMarkup</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Then subsequent calls to <code class="docutils literal"><span class="pre">LLVMDisasmInstruction()</span></code> will return output strings
+with the marked up annotations.</p>
+</div>
+<div class="section" id="instruction-annotations">
+<h2><a class="toc-backref" href="#id3">Instruction Annotations</a><a class="headerlink" href="#instruction-annotations" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="contextual-markups">
+<span id="id1"></span><h3><a class="toc-backref" href="#id4">Contextual markups</a><a class="headerlink" href="#contextual-markups" title="Permalink to this headline">¶</a></h3>
+<p>Annoated assembly display will supply contextual markup to help clients more
+efficiently implement things like pretty printers. Most markup will be target
+independent, so clients can effectively provide good display without any target
+specific knowledge.</p>
+<p>Annotated assembly goes through the normal instruction printer, but optionally
+includes contextual tags on portions of the instruction string. An annotation
+is any ‘<’ ‘>’ delimited section of text(1).</p>
+<div class="highlight-bat"><div class="highlight"><pre><span></span>annotation: '<span class="p"><</span>' tag-name tag-modifier-list ':' annotated-text '<span class="p">></span>'
+tag-name: identifier
+tag-modifier-list: comma delimited identifier list
+</pre></div>
+</div>
+<p>The tag-name is an identifier which gives the type of the annotation. For the
+first pass, this will be very simple, with memory references, registers, and
+immediates having the tag names “mem”, “reg”, and “imm”, respectively.</p>
+<p>The tag-modifier-list is typically additional target-specific context, such as
+register class.</p>
+<p>Clients should accept and ignore any tag-names or tag-modifiers they do not
+understand, allowing the annotations to grow in richness without breaking older
+clients.</p>
+<p>For example, a possible annotation of an ARM load of a stack-relative location
+might be annotated as:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>ldr <reg gpr:r0>, <mem regoffset:[<reg gpr:sp>, <imm:#4>]>
+</pre></div>
+</div>
+<p>1: For assembly dialects in which ‘<’ and/or ‘>’ are legal tokens, a literal token is escaped by following immediately with a repeat of the character. For example, a literal ‘<’ character is output as ‘<<’ in an annotated assembly string.</p>
+</div>
+<div class="section" id="c-api-details">
+<h3><a class="toc-backref" href="#id5">C API Details</a><a class="headerlink" href="#c-api-details" title="Permalink to this headline">¶</a></h3>
+<p>The intended consumers of this information use the C API, therefore the new C
+API function for the disassembler will be added to provide an option to produce
+disassembled instructions with annotations, <code class="docutils literal"><span class="pre">LLVMSetDisasmOptions()</span></code> and the
+<code class="docutils literal"><span class="pre">LLVMDisassembler_Option_UseMarkup</span></code> option (see above).</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="SystemLibrary.html" title="System Library"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GoldPlugin.html" title="The LLVM gold plugin"
+ >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-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/MemorySSA.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/MemorySSA.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/MemorySSA.html (added)
+++ www-releases/trunk/6.0.0/docs/MemorySSA.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,435 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>MemorySSA — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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 Bitcode File Format" href="BitCodeFormat.html" />
+ <link rel="prev" title="LLVM Alias Analysis Infrastructure" href="AliasAnalysis.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="BitCodeFormat.html" title="LLVM Bitcode File Format"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="AliasAnalysis.html" title="LLVM Alias Analysis Infrastructure"
+ 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="memoryssa">
+<h1>MemorySSA<a class="headerlink" href="#memoryssa" 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="#memoryssa-structure" id="id2">MemorySSA Structure</a></li>
+<li><a class="reference internal" href="#design-of-memoryssa" id="id3">Design of MemorySSA</a><ul>
+<li><a class="reference internal" href="#the-walker" id="id4">The walker</a><ul>
+<li><a class="reference internal" href="#locating-clobbers-yourself" id="id5">Locating clobbers yourself</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#build-time-use-optimization" id="id6">Build-time use optimization</a></li>
+<li><a class="reference internal" href="#invalidation-and-updating" id="id7">Invalidation and updating</a><ul>
+<li><a class="reference internal" href="#phi-placement" id="id8">Phi placement</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#non-goals" id="id9">Non-Goals</a></li>
+<li><a class="reference internal" href="#design-tradeoffs" id="id10">Design tradeoffs</a><ul>
+<li><a class="reference internal" href="#precision" id="id11">Precision</a></li>
+<li><a class="reference internal" href="#use-optimization" id="id12">Use Optimization</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p><code class="docutils literal"><span class="pre">MemorySSA</span></code> is an analysis that allows us to cheaply reason about the
+interactions between various memory operations. Its goal is to replace
+<code class="docutils literal"><span class="pre">MemoryDependenceAnalysis</span></code> for most (if not all) use-cases. This is because,
+unless you’re very careful, use of <code class="docutils literal"><span class="pre">MemoryDependenceAnalysis</span></code> can easily
+result in quadratic-time algorithms in LLVM. Additionally, <code class="docutils literal"><span class="pre">MemorySSA</span></code> doesn’t
+have as many arbitrary limits as <code class="docutils literal"><span class="pre">MemoryDependenceAnalysis</span></code>, so you should get
+better results, too.</p>
+<p>At a high level, one of the goals of <code class="docutils literal"><span class="pre">MemorySSA</span></code> is to provide an SSA based
+form for memory, complete with def-use and use-def chains, which
+enables users to quickly find may-def and may-uses of memory operations.
+It can also be thought of as a way to cheaply give versions to the complete
+state of heap memory, and associate memory operations with those versions.</p>
+<p>This document goes over how <code class="docutils literal"><span class="pre">MemorySSA</span></code> is structured, and some basic
+intuition on how <code class="docutils literal"><span class="pre">MemorySSA</span></code> works.</p>
+<p>A paper on MemorySSA (with notes about how it’s implemented in GCC) <a class="reference external" href="http://www.airs.com/dnovillo/Papers/mem-ssa.pdf">can be
+found here</a>. Though, it’s
+relatively out-of-date; the paper references multiple heap partitions, but GCC
+eventually swapped to just using one, like we now have in LLVM. Like
+GCC’s, LLVM’s MemorySSA is intraprocedural.</p>
+</div>
+<div class="section" id="memoryssa-structure">
+<h2><a class="toc-backref" href="#id2">MemorySSA Structure</a><a class="headerlink" href="#memoryssa-structure" title="Permalink to this headline">¶</a></h2>
+<p>MemorySSA is a virtual IR. After it’s built, <code class="docutils literal"><span class="pre">MemorySSA</span></code> will contain a
+structure that maps <code class="docutils literal"><span class="pre">Instruction</span></code>s to <code class="docutils literal"><span class="pre">MemoryAccess</span></code>es, which are
+<code class="docutils literal"><span class="pre">MemorySSA</span></code>‘s parallel to LLVM <code class="docutils literal"><span class="pre">Instruction</span></code>s.</p>
+<p>Each <code class="docutils literal"><span class="pre">MemoryAccess</span></code> can be one of three types:</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">MemoryPhi</span></code></li>
+<li><code class="docutils literal"><span class="pre">MemoryUse</span></code></li>
+<li><code class="docutils literal"><span class="pre">MemoryDef</span></code></li>
+</ul>
+<p><code class="docutils literal"><span class="pre">MemoryPhi</span></code>s are <code class="docutils literal"><span class="pre">PhiNode</span></code>s, but for memory operations. If at any
+point we have two (or more) <code class="docutils literal"><span class="pre">MemoryDef</span></code>s that could flow into a
+<code class="docutils literal"><span class="pre">BasicBlock</span></code>, the block’s top <code class="docutils literal"><span class="pre">MemoryAccess</span></code> will be a
+<code class="docutils literal"><span class="pre">MemoryPhi</span></code>. As in LLVM IR, <code class="docutils literal"><span class="pre">MemoryPhi</span></code>s don’t correspond to any
+concrete operation. As such, <code class="docutils literal"><span class="pre">BasicBlock</span></code>s are mapped to <code class="docutils literal"><span class="pre">MemoryPhi</span></code>s
+inside <code class="docutils literal"><span class="pre">MemorySSA</span></code>, whereas <code class="docutils literal"><span class="pre">Instruction</span></code>s are mapped to <code class="docutils literal"><span class="pre">MemoryUse</span></code>s
+and <code class="docutils literal"><span class="pre">MemoryDef</span></code>s.</p>
+<p>Note also that in SSA, Phi nodes merge must-reach definitions (that is,
+definitions that <em>must</em> be new versions of variables). In MemorySSA, PHI nodes
+merge may-reach definitions (that is, until disambiguated, the versions that
+reach a phi node may or may not clobber a given variable).</p>
+<p><code class="docutils literal"><span class="pre">MemoryUse</span></code>s are operations which use but don’t modify memory. An example of
+a <code class="docutils literal"><span class="pre">MemoryUse</span></code> is a <code class="docutils literal"><span class="pre">load</span></code>, or a <code class="docutils literal"><span class="pre">readonly</span></code> function call.</p>
+<p><code class="docutils literal"><span class="pre">MemoryDef</span></code>s are operations which may either modify memory, or which
+introduce some kind of ordering constraints. Examples of <code class="docutils literal"><span class="pre">MemoryDef</span></code>s
+include <code class="docutils literal"><span class="pre">store</span></code>s, function calls, <code class="docutils literal"><span class="pre">load</span></code>s with <code class="docutils literal"><span class="pre">acquire</span></code> (or higher)
+ordering, volatile operations, memory fences, etc.</p>
+<p>Every function that exists has a special <code class="docutils literal"><span class="pre">MemoryDef</span></code> called <code class="docutils literal"><span class="pre">liveOnEntry</span></code>.
+It dominates every <code class="docutils literal"><span class="pre">MemoryAccess</span></code> in the function that <code class="docutils literal"><span class="pre">MemorySSA</span></code> is being
+run on, and implies that we’ve hit the top of the function. It’s the only
+<code class="docutils literal"><span class="pre">MemoryDef</span></code> that maps to no <code class="docutils literal"><span class="pre">Instruction</span></code> in LLVM IR. Use of
+<code class="docutils literal"><span class="pre">liveOnEntry</span></code> implies that the memory being used is either undefined or
+defined before the function begins.</p>
+<p>An example of all of this overlaid on LLVM IR (obtained by running <code class="docutils literal"><span class="pre">opt</span>
+<span class="pre">-passes='print<memoryssa>'</span> <span class="pre">-disable-output</span></code> on an <code class="docutils literal"><span class="pre">.ll</span></code> file) is below. When
+viewing this example, it may be helpful to view it in terms of clobbers. The
+operands of a given <code class="docutils literal"><span class="pre">MemoryAccess</span></code> are all (potential) clobbers of said
+MemoryAccess, and the value produced by a <code class="docutils literal"><span class="pre">MemoryAccess</span></code> can act as a clobber
+for other <code class="docutils literal"><span class="pre">MemoryAccess</span></code>es. Another useful way of looking at it is in
+terms of heap versions. In that view, operands of of a given
+<code class="docutils literal"><span class="pre">MemoryAccess</span></code> are the version of the heap before the operation, and
+if the access produces a value, the value is the new version of the heap
+after the operation.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%p1</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i8</span>
+ <span class="nv">%p2</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i8</span>
+ <span class="nv">%p3</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i8</span>
+ <span class="c">; 1 = MemoryDef(liveOnEntry)</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p3</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%while.cond</span>
+
+<span class="nl">while.cond:</span>
+ <span class="c">; 6 = MemoryPhi({%0,1},{if.end,4})</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="k">undef</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%if.then</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%if.else</span>
+
+<span class="nl">if.then:</span>
+ <span class="c">; 2 = MemoryDef(6)</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p1</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+
+<span class="nl">if.else:</span>
+ <span class="c">; 3 = MemoryDef(6)</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p2</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+
+<span class="nl">if.end:</span>
+ <span class="c">; 5 = MemoryPhi({if.then,2},{if.else,3})</span>
+ <span class="c">; MemoryUse(5)</span>
+ <span class="nv nv-Anonymous">%1</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i8</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p1</span>
+ <span class="c">; 4 = MemoryDef(5)</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="m">2</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p2</span>
+ <span class="c">; MemoryUse(1)</span>
+ <span class="nv nv-Anonymous">%2</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i8</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p3</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%while.cond</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The <code class="docutils literal"><span class="pre">MemorySSA</span></code> IR is shown in comments that precede the instructions they map
+to (if such an instruction exists). For example, <code class="docutils literal"><span class="pre">1</span> <span class="pre">=</span> <span class="pre">MemoryDef(liveOnEntry)</span></code>
+is a <code class="docutils literal"><span class="pre">MemoryAccess</span></code> (specifically, a <code class="docutils literal"><span class="pre">MemoryDef</span></code>), and it describes the LLVM
+instruction <code class="docutils literal"><span class="pre">store</span> <span class="pre">i8</span> <span class="pre">0,</span> <span class="pre">i8*</span> <span class="pre">%p3</span></code>. Other places in <code class="docutils literal"><span class="pre">MemorySSA</span></code> refer to this
+particular <code class="docutils literal"><span class="pre">MemoryDef</span></code> as <code class="docutils literal"><span class="pre">1</span></code> (much like how one can refer to <code class="docutils literal"><span class="pre">load</span> <span class="pre">i8,</span> <span class="pre">i8*</span>
+<span class="pre">%p1</span></code> in LLVM with <code class="docutils literal"><span class="pre">%1</span></code>). Again, <code class="docutils literal"><span class="pre">MemoryPhi</span></code>s don’t correspond to any LLVM
+Instruction, so the line directly below a <code class="docutils literal"><span class="pre">MemoryPhi</span></code> isn’t special.</p>
+<p>Going from the top down:</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">6</span> <span class="pre">=</span> <span class="pre">MemoryPhi({entry,1},{if.end,4})</span></code> notes that, when entering
+<code class="docutils literal"><span class="pre">while.cond</span></code>, the reaching definition for it is either <code class="docutils literal"><span class="pre">1</span></code> or <code class="docutils literal"><span class="pre">4</span></code>. This
+<code class="docutils literal"><span class="pre">MemoryPhi</span></code> is referred to in the textual IR by the number <code class="docutils literal"><span class="pre">6</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">2</span> <span class="pre">=</span> <span class="pre">MemoryDef(6)</span></code> notes that <code class="docutils literal"><span class="pre">store</span> <span class="pre">i8</span> <span class="pre">0,</span> <span class="pre">i8*</span> <span class="pre">%p1</span></code> is a definition,
+and its reaching definition before it is <code class="docutils literal"><span class="pre">6</span></code>, or the <code class="docutils literal"><span class="pre">MemoryPhi</span></code> after
+<code class="docutils literal"><span class="pre">while.cond</span></code>. (See the <a class="reference internal" href="#build-time-use-optimization">Build-time use optimization</a> and <a class="reference internal" href="#precision">Precision</a>
+sections below for why this <code class="docutils literal"><span class="pre">MemoryDef</span></code> isn’t linked to a separate,
+disambiguated <code class="docutils literal"><span class="pre">MemoryPhi</span></code>.)</li>
+<li><code class="docutils literal"><span class="pre">3</span> <span class="pre">=</span> <span class="pre">MemoryDef(6)</span></code> notes that <code class="docutils literal"><span class="pre">store</span> <span class="pre">i8</span> <span class="pre">0,</span> <span class="pre">i8*</span> <span class="pre">%p2</span></code> is a definition; its
+reaching definition is also <code class="docutils literal"><span class="pre">6</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">5</span> <span class="pre">=</span> <span class="pre">MemoryPhi({if.then,2},{if.else,3})</span></code> notes that the clobber before
+this block could either be <code class="docutils literal"><span class="pre">2</span></code> or <code class="docutils literal"><span class="pre">3</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">MemoryUse(5)</span></code> notes that <code class="docutils literal"><span class="pre">load</span> <span class="pre">i8,</span> <span class="pre">i8*</span> <span class="pre">%p1</span></code> is a use of memory, and that
+it’s clobbered by <code class="docutils literal"><span class="pre">5</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">4</span> <span class="pre">=</span> <span class="pre">MemoryDef(5)</span></code> notes that <code class="docutils literal"><span class="pre">store</span> <span class="pre">i8</span> <span class="pre">2,</span> <span class="pre">i8*</span> <span class="pre">%p2</span></code> is a definition; it’s
+reaching definition is <code class="docutils literal"><span class="pre">5</span></code>.</li>
+<li><code class="docutils literal"><span class="pre">MemoryUse(1)</span></code> notes that <code class="docutils literal"><span class="pre">load</span> <span class="pre">i8,</span> <span class="pre">i8*</span> <span class="pre">%p3</span></code> is just a user of memory,
+and the last thing that could clobber this use is above <code class="docutils literal"><span class="pre">while.cond</span></code> (e.g.
+the store to <code class="docutils literal"><span class="pre">%p3</span></code>). In heap versioning parlance, it really only depends on
+the heap version 1, and is unaffected by the new heap versions generated since
+then.</li>
+</ul>
+<p>As an aside, <code class="docutils literal"><span class="pre">MemoryAccess</span></code> is a <code class="docutils literal"><span class="pre">Value</span></code> mostly for convenience; it’s not
+meant to interact with LLVM IR.</p>
+</div>
+<div class="section" id="design-of-memoryssa">
+<h2><a class="toc-backref" href="#id3">Design of MemorySSA</a><a class="headerlink" href="#design-of-memoryssa" title="Permalink to this headline">¶</a></h2>
+<p><code class="docutils literal"><span class="pre">MemorySSA</span></code> is an analysis that can be built for any arbitrary function. When
+it’s built, it does a pass over the function’s IR in order to build up its
+mapping of <code class="docutils literal"><span class="pre">MemoryAccess</span></code>es. You can then query <code class="docutils literal"><span class="pre">MemorySSA</span></code> for things
+like the dominance relation between <code class="docutils literal"><span class="pre">MemoryAccess</span></code>es, and get the
+<code class="docutils literal"><span class="pre">MemoryAccess</span></code> for any given <code class="docutils literal"><span class="pre">Instruction</span></code> .</p>
+<p>When <code class="docutils literal"><span class="pre">MemorySSA</span></code> is done building, it also hands you a <code class="docutils literal"><span class="pre">MemorySSAWalker</span></code>
+that you can use (see below).</p>
+<div class="section" id="the-walker">
+<h3><a class="toc-backref" href="#id4">The walker</a><a class="headerlink" href="#the-walker" title="Permalink to this headline">¶</a></h3>
+<p>A structure that helps <code class="docutils literal"><span class="pre">MemorySSA</span></code> do its job is the <code class="docutils literal"><span class="pre">MemorySSAWalker</span></code>, or
+the walker, for short. The goal of the walker is to provide answers to clobber
+queries beyond what’s represented directly by <code class="docutils literal"><span class="pre">MemoryAccess</span></code>es. For example,
+given:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="nv">%a</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i8</span>
+ <span class="nv">%b</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i8</span>
+
+ <span class="c">; 1 = MemoryDef(liveOnEntry)</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%a</span>
+ <span class="c">; 2 = MemoryDef(1)</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%b</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The store to <code class="docutils literal"><span class="pre">%a</span></code> is clearly not a clobber for the store to <code class="docutils literal"><span class="pre">%b</span></code>. It would
+be the walker’s goal to figure this out, and return <code class="docutils literal"><span class="pre">liveOnEntry</span></code> when queried
+for the clobber of <code class="docutils literal"><span class="pre">MemoryAccess</span></code> <code class="docutils literal"><span class="pre">2</span></code>.</p>
+<p>By default, <code class="docutils literal"><span class="pre">MemorySSA</span></code> provides a walker that can optimize <code class="docutils literal"><span class="pre">MemoryDef</span></code>s
+and <code class="docutils literal"><span class="pre">MemoryUse</span></code>s by consulting whatever alias analysis stack you happen to
+be using. Walkers were built to be flexible, though, so it’s entirely reasonable
+(and expected) to create more specialized walkers (e.g. one that specifically
+queries <code class="docutils literal"><span class="pre">GlobalsAA</span></code>, one that always stops at <code class="docutils literal"><span class="pre">MemoryPhi</span></code> nodes, etc).</p>
+<div class="section" id="locating-clobbers-yourself">
+<h4><a class="toc-backref" href="#id5">Locating clobbers yourself</a><a class="headerlink" href="#locating-clobbers-yourself" title="Permalink to this headline">¶</a></h4>
+<p>If you choose to make your own walker, you can find the clobber for a
+<code class="docutils literal"><span class="pre">MemoryAccess</span></code> by walking every <code class="docutils literal"><span class="pre">MemoryDef</span></code> that dominates said
+<code class="docutils literal"><span class="pre">MemoryAccess</span></code>. The structure of <code class="docutils literal"><span class="pre">MemoryDef</span></code>s makes this relatively simple;
+they ultimately form a linked list of every clobber that dominates the
+<code class="docutils literal"><span class="pre">MemoryAccess</span></code> that you’re trying to optimize. In other words, the
+<code class="docutils literal"><span class="pre">definingAccess</span></code> of a <code class="docutils literal"><span class="pre">MemoryDef</span></code> is always the nearest dominating
+<code class="docutils literal"><span class="pre">MemoryDef</span></code> or <code class="docutils literal"><span class="pre">MemoryPhi</span></code> of said <code class="docutils literal"><span class="pre">MemoryDef</span></code>.</p>
+</div>
+</div>
+<div class="section" id="build-time-use-optimization">
+<h3><a class="toc-backref" href="#id6">Build-time use optimization</a><a class="headerlink" href="#build-time-use-optimization" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal"><span class="pre">MemorySSA</span></code> will optimize some <code class="docutils literal"><span class="pre">MemoryAccess</span></code>es at build-time.
+Specifically, we optimize the operand of every <code class="docutils literal"><span class="pre">MemoryUse</span></code> to point to the
+actual clobber of said <code class="docutils literal"><span class="pre">MemoryUse</span></code>. This can be seen in the above example; the
+second <code class="docutils literal"><span class="pre">MemoryUse</span></code> in <code class="docutils literal"><span class="pre">if.end</span></code> has an operand of <code class="docutils literal"><span class="pre">1</span></code>, which is a
+<code class="docutils literal"><span class="pre">MemoryDef</span></code> from the entry block. This is done to make walking,
+value numbering, etc, faster and easier.</p>
+<p>It is not possible to optimize <code class="docutils literal"><span class="pre">MemoryDef</span></code> in the same way, as we
+restrict <code class="docutils literal"><span class="pre">MemorySSA</span></code> to one heap variable and, thus, one Phi node
+per block.</p>
+</div>
+<div class="section" id="invalidation-and-updating">
+<h3><a class="toc-backref" href="#id7">Invalidation and updating</a><a class="headerlink" href="#invalidation-and-updating" title="Permalink to this headline">¶</a></h3>
+<p>Because <code class="docutils literal"><span class="pre">MemorySSA</span></code> keeps track of LLVM IR, it needs to be updated whenever
+the IR is updated. “Update”, in this case, includes the addition, deletion, and
+motion of <code class="docutils literal"><span class="pre">Instructions</span></code>. The update API is being made on an as-needed basis.
+If you’d like examples, <code class="docutils literal"><span class="pre">GVNHoist</span></code> is a user of <code class="docutils literal"><span class="pre">MemorySSA</span></code>s update API.</p>
+<div class="section" id="phi-placement">
+<h4><a class="toc-backref" href="#id8">Phi placement</a><a class="headerlink" href="#phi-placement" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal"><span class="pre">MemorySSA</span></code> only places <code class="docutils literal"><span class="pre">MemoryPhi</span></code>s where they’re actually
+needed. That is, it is a pruned SSA form, like LLVM’s SSA form. For
+example, consider:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%p1</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i8</span>
+ <span class="nv">%p2</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i8</span>
+ <span class="nv">%p3</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i8</span>
+ <span class="c">; 1 = MemoryDef(liveOnEntry)</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p3</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%while.cond</span>
+
+<span class="nl">while.cond:</span>
+ <span class="c">; 3 = MemoryPhi({%0,1},{if.end,2})</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="k">undef</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%if.then</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%if.else</span>
+
+<span class="nl">if.then:</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+
+<span class="nl">if.else:</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+
+<span class="nl">if.end:</span>
+ <span class="c">; MemoryUse(1)</span>
+ <span class="nv nv-Anonymous">%1</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i8</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p1</span>
+ <span class="c">; 2 = MemoryDef(3)</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="m">2</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p2</span>
+ <span class="c">; MemoryUse(1)</span>
+ <span class="nv nv-Anonymous">%2</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i8</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%p3</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%while.cond</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Because we removed the stores from <code class="docutils literal"><span class="pre">if.then</span></code> and <code class="docutils literal"><span class="pre">if.else</span></code>, a <code class="docutils literal"><span class="pre">MemoryPhi</span></code>
+for <code class="docutils literal"><span class="pre">if.end</span></code> would be pointless, so we don’t place one. So, if you need to
+place a <code class="docutils literal"><span class="pre">MemoryDef</span></code> in <code class="docutils literal"><span class="pre">if.then</span></code> or <code class="docutils literal"><span class="pre">if.else</span></code>, you’ll need to also create
+a <code class="docutils literal"><span class="pre">MemoryPhi</span></code> for <code class="docutils literal"><span class="pre">if.end</span></code>.</p>
+<p>If it turns out that this is a large burden, we can just place <code class="docutils literal"><span class="pre">MemoryPhi</span></code>s
+everywhere. Because we have Walkers that are capable of optimizing above said
+phis, doing so shouldn’t prohibit optimizations.</p>
+</div>
+</div>
+<div class="section" id="non-goals">
+<h3><a class="toc-backref" href="#id9">Non-Goals</a><a class="headerlink" href="#non-goals" title="Permalink to this headline">¶</a></h3>
+<p><code class="docutils literal"><span class="pre">MemorySSA</span></code> is meant to reason about the relation between memory
+operations, and enable quicker querying.
+It isn’t meant to be the single source of truth for all potential memory-related
+optimizations. Specifically, care must be taken when trying to use <code class="docutils literal"><span class="pre">MemorySSA</span></code>
+to reason about atomic or volatile operations, as in:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">i8</span> <span class="vg">@foo</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%a</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="k">undef</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%if.then</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+
+<span class="nl">if.then:</span>
+ <span class="c">; 1 = MemoryDef(liveOnEntry)</span>
+ <span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">load</span> <span class="k">volatile</span> <span class="k">i8</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%a</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+
+<span class="nl">if.end:</span>
+ <span class="nv">%av</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i8</span> <span class="p">[</span><span class="m">0</span><span class="p">,</span> <span class="nv">%entry</span><span class="p">],</span> <span class="p">[</span><span class="nv nv-Anonymous">%0</span><span class="p">,</span> <span class="nv">%if.then</span><span class="p">]</span>
+ <span class="k">ret</span> <span class="k">i8</span> <span class="nv">%av</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Going solely by <code class="docutils literal"><span class="pre">MemorySSA</span></code>‘s analysis, hoisting the <code class="docutils literal"><span class="pre">load</span></code> to <code class="docutils literal"><span class="pre">entry</span></code> may
+seem legal. Because it’s a volatile load, though, it’s not.</p>
+</div>
+<div class="section" id="design-tradeoffs">
+<h3><a class="toc-backref" href="#id10">Design tradeoffs</a><a class="headerlink" href="#design-tradeoffs" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="precision">
+<h4><a class="toc-backref" href="#id11">Precision</a><a class="headerlink" href="#precision" title="Permalink to this headline">¶</a></h4>
+<p><code class="docutils literal"><span class="pre">MemorySSA</span></code> in LLVM deliberately trades off precision for speed.
+Let us think about memory variables as if they were disjoint partitions of the
+heap (that is, if you have one variable, as above, it represents the entire
+heap, and if you have multiple variables, each one represents some
+disjoint portion of the heap)</p>
+<p>First, because alias analysis results conflict with each other, and
+each result may be what an analysis wants (IE
+TBAA may say no-alias, and something else may say must-alias), it is
+not possible to partition the heap the way every optimization wants.
+Second, some alias analysis results are not transitive (IE A noalias B,
+and B noalias C, does not mean A noalias C), so it is not possible to
+come up with a precise partitioning in all cases without variables to
+represent every pair of possible aliases. Thus, partitioning
+precisely may require introducing at least N^2 new virtual variables,
+phi nodes, etc.</p>
+<p>Each of these variables may be clobbered at multiple def sites.</p>
+<p>To give an example, if you were to split up struct fields into
+individual variables, all aliasing operations that may-def multiple struct
+fields, will may-def more than one of them. This is pretty common (calls,
+copies, field stores, etc).</p>
+<p>Experience with SSA forms for memory in other compilers has shown that
+it is simply not possible to do this precisely, and in fact, doing it
+precisely is not worth it, because now all the optimizations have to
+walk tons and tons of virtual variables and phi nodes.</p>
+<p>So we partition. At the point at which you partition, again,
+experience has shown us there is no point in partitioning to more than
+one variable. It simply generates more IR, and optimizations still
+have to query something to disambiguate further anyway.</p>
+<p>As a result, LLVM partitions to one variable.</p>
+</div>
+<div class="section" id="use-optimization">
+<h4><a class="toc-backref" href="#id12">Use Optimization</a><a class="headerlink" href="#use-optimization" title="Permalink to this headline">¶</a></h4>
+<p>Unlike other partitioned forms, LLVM’s <code class="docutils literal"><span class="pre">MemorySSA</span></code> does make one
+useful guarantee - all loads are optimized to point at the thing that
+actually clobbers them. This gives some nice properties. For example,
+for a given store, you can find all loads actually clobbered by that
+store by walking the immediate uses of the store.</p>
+</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="BitCodeFormat.html" title="LLVM Bitcode File Format"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="AliasAnalysis.html" title="LLVM Alias Analysis Infrastructure"
+ >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-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/MergeFunctions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/MergeFunctions.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/MergeFunctions.html (added)
+++ www-releases/trunk/6.0.0/docs/MergeFunctions.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,821 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>MergeFunctions pass, how it works — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="Type Metadata" href="TypeMetadata.html" />
+ <link rel="prev" title="Garbage Collection Safepoints in LLVM" href="Statepoints.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="TypeMetadata.html" title="Type Metadata"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Statepoints.html" title="Garbage Collection Safepoints in LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="mergefunctions-pass-how-it-works">
+<h1>MergeFunctions pass, how it works<a class="headerlink" href="#mergefunctions-pass-how-it-works" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a><ul>
+<li><a class="reference internal" href="#why-would-i-want-to-read-this-document" id="id2">Why would I want to read this document?</a></li>
+<li><a class="reference internal" href="#what-should-i-know-to-be-able-to-follow-along-with-this-document" id="id3">What should I know to be able to follow along with this document?</a></li>
+<li><a class="reference internal" href="#what-i-gain-by-reading-this-document" id="id4">What I gain by reading this document?</a></li>
+<li><a class="reference internal" href="#narrative-structure" id="id5">Narrative structure</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#basics" id="id6">Basics</a><ul>
+<li><a class="reference internal" href="#how-to-do-it" id="id7">How to do it?</a><ul>
+<li><a class="reference internal" href="#possible-solutions" id="id8">Possible solutions</a><ul>
+<li><a class="reference internal" href="#random-access" id="id9">Random-access</a></li>
+<li><a class="reference internal" href="#logarithmical-search" id="id10">Logarithmical search</a></li>
+<li><a class="reference internal" href="#present-state" id="id11">Present state</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#mergefunctions-main-fields-and-runonmodule" id="id12">MergeFunctions, main fields and runOnModule</a><ul>
+<li><a class="reference internal" href="#runonmodule" id="id13">runOnModule</a></li>
+<li><a class="reference internal" href="#comparison-and-logarithmical-search" id="id14">Comparison and logarithmical search</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#functions-comparison" id="id15">Functions comparison</a><ul>
+<li><a class="reference internal" href="#functioncomparator-compare-void" id="id16">FunctionComparator::compare(void)</a></li>
+<li><a class="reference internal" href="#functioncomparator-cmptype" id="id17">FunctionComparator::cmpType</a></li>
+<li><a class="reference internal" href="#cmpvalues-const-value-const-value" id="id18">cmpValues(const Value*, const Value*)</a><ul>
+<li><a class="reference internal" href="#what-we-assiciate-in-cmpvalues" id="id19">What we assiciate in cmpValues?</a></li>
+<li><a class="reference internal" href="#how-to-implement-cmpvalues" id="id20">How to implement cmpValues?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#cmpconstants" id="id21">cmpConstants</a></li>
+<li><a class="reference internal" href="#compare-const-basicblock-const-basicblock" id="id22">compare(const BasicBlock*, const BasicBlock*)</a></li>
+<li><a class="reference internal" href="#cmpgep" id="id23">cmpGEP</a></li>
+<li><a class="reference internal" href="#cmpoperation" id="id24">cmpOperation</a></li>
+<li><a class="reference internal" href="#o-log-n" id="id25">O(log(N))</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#merging-process-mergetwofunctions" id="id26">Merging process, mergeTwoFunctions</a><ul>
+<li><a class="reference internal" href="#if-f-may-be-overridden" id="id27">If âFâ may be overridden</a><ul>
+<li><a class="reference internal" href="#hasglobalaliases-removeusers" id="id28">HasGlobalAliases, removeUsers</a></li>
+<li><a class="reference internal" href="#no-global-aliases-replacedirectcallers" id="id29">No global aliases, replaceDirectCallers</a><ul>
+<li><a class="reference internal" href="#if-f-could-not-be-overridden-fix-it" id="id30">If âFâ could not be overridden, fix it!</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#that-s-it" id="id31">That’s it.</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>Sometimes code contains equal functions, or functions that does exactly the same
+thing even though they are non-equal on the IR level (e.g.: multiplication on 2
+and ‘shl 1’). It could happen due to several reasons: mainly, the usage of
+templates and automatic code generators. Though, sometimes user itself could
+write the same thing twice :-)</p>
+<p>The main purpose of this pass is to recognize such functions and merge them.</p>
+<div class="section" id="why-would-i-want-to-read-this-document">
+<h3><a class="toc-backref" href="#id2">Why would I want to read this document?</a><a class="headerlink" href="#why-would-i-want-to-read-this-document" title="Permalink to this headline">¶</a></h3>
+<p>Document is the extension to pass comments and describes the pass logic. It
+describes algorithm that is used in order to compare functions, it also
+explains how we could combine equal functions correctly, keeping module valid.</p>
+<p>Material is brought in top-down form, so reader could start learn pass from
+ideas and end up with low-level algorithm details, thus preparing him for
+reading the sources.</p>
+<p>So main goal is do describe algorithm and logic here; the concept. This document
+is good for you, if you <em>don’t want</em> to read the source code, but want to
+understand pass algorithms. Author tried not to repeat the source-code and
+cover only common cases, and thus avoid cases when after minor code changes we
+need to update this document.</p>
+</div>
+<div class="section" id="what-should-i-know-to-be-able-to-follow-along-with-this-document">
+<h3><a class="toc-backref" href="#id3">What should I know to be able to follow along with this document?</a><a class="headerlink" href="#what-should-i-know-to-be-able-to-follow-along-with-this-document" title="Permalink to this headline">¶</a></h3>
+<p>Reader should be familiar with common compile-engineering principles and LLVM
+code fundamentals. In this article we suppose reader is familiar with
+<a class="reference external" href="http://en.wikipedia.org/wiki/Static_single_assignment_form">Single Static Assingment</a>
+concepts. Understanding of
+<a class="reference external" href="http://llvm.org/docs/LangRef.html#high-level-structure">IR structure</a> is
+also important.</p>
+<p>We will use such terms as
+“<a class="reference external" href="http://llvm.org/docs/LangRef.html#high-level-structure">module</a>”,
+“<a class="reference external" href="http://llvm.org/docs/ProgrammersManual.html#the-function-class">function</a>”,
+“<a class="reference external" href="http://en.wikipedia.org/wiki/Basic_block">basic block</a>”,
+“<a class="reference external" href="http://llvm.org/docs/ProgrammersManual.html#the-user-class">user</a>”,
+“<a class="reference external" href="http://llvm.org/docs/ProgrammersManual.html#the-value-class">value</a>”,
+“<a class="reference external" href="http://llvm.org/docs/ProgrammersManual.html#the-instruction-class">instruction</a>”.</p>
+<p>As a good start point, Kaleidoscope tutorial could be used:</p>
+<p><a class="reference internal" href="tutorial/index.html"><span class="doc">LLVM Tutorial: Table of Contents</span></a></p>
+<p>Especially it’s important to understand chapter 3 of tutorial:</p>
+<p><a class="reference internal" href="tutorial/LangImpl03.html"><span class="doc">Kaleidoscope: Code generation to LLVM IR</span></a></p>
+<p>Reader also should know how passes work in LLVM, they could use next article as
+a reference and start point here:</p>
+<p><a class="reference internal" href="WritingAnLLVMPass.html"><span class="doc">Writing an LLVM Pass</span></a></p>
+<p>What else? Well perhaps reader also should have some experience in LLVM pass
+debugging and bug-fixing.</p>
+</div>
+<div class="section" id="what-i-gain-by-reading-this-document">
+<h3><a class="toc-backref" href="#id4">What I gain by reading this document?</a><a class="headerlink" href="#what-i-gain-by-reading-this-document" title="Permalink to this headline">¶</a></h3>
+<p>Main purpose is to provide reader with comfortable form of algorithms
+description, namely the human reading text. Since it could be hard to
+understand algorithm straight from the source code: pass uses some principles
+that have to be explained first.</p>
+<p>Author wishes to everybody to avoid case, when you read code from top to bottom
+again and again, and yet you don’t understand why we implemented it that way.</p>
+<p>We hope that after this article reader could easily debug and improve
+MergeFunctions pass and thus help LLVM project.</p>
+</div>
+<div class="section" id="narrative-structure">
+<h3><a class="toc-backref" href="#id5">Narrative structure</a><a class="headerlink" href="#narrative-structure" title="Permalink to this headline">¶</a></h3>
+<p>Article consists of three parts. First part explains pass functionality on the
+top-level. Second part describes the comparison procedure itself. The third
+part describes the merging process.</p>
+<p>In every part author also tried to put the contents into the top-down form.
+First, the top-level methods will be described, while the terminal ones will be
+at the end, in the tail of each part. If reader will see the reference to the
+method that wasn’t described yet, they will find its description a bit below.</p>
+</div>
+</div>
+<div class="section" id="basics">
+<h2><a class="toc-backref" href="#id6">Basics</a><a class="headerlink" href="#basics" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="how-to-do-it">
+<h3><a class="toc-backref" href="#id7">How to do it?</a><a class="headerlink" href="#how-to-do-it" title="Permalink to this headline">¶</a></h3>
+<p>Do we need to merge functions? Obvious thing is: yes that’s a quite possible
+case, since usually we <em>do</em> have duplicates. And it would be good to get rid of
+them. But how to detect such a duplicates? The idea is next: we split functions
+onto small bricks (parts), then we compare “bricks” amount, and if it equal,
+compare “bricks” themselves, and then do our conclusions about functions
+themselves.</p>
+<p>What the difference it could be? For example, on machine with 64-bit pointers
+(let’s assume we have only one address space), one function stores 64-bit
+integer, while another one stores a pointer. So if the target is a machine
+mentioned above, and if functions are identical, except the parameter type (we
+could consider it as a part of function type), then we can treat <code class="docutils literal"><span class="pre">uint64_t</span></code>
+and``void*`` as equal.</p>
+<p>It was just an example; possible details are described a bit below.</p>
+<p>As another example reader may imagine two more functions. First function
+performs multiplication on 2, while the second one performs arithmetic right
+shift on 1.</p>
+<div class="section" id="possible-solutions">
+<h4><a class="toc-backref" href="#id8">Possible solutions</a><a class="headerlink" href="#possible-solutions" title="Permalink to this headline">¶</a></h4>
+<p>Let’s briefly consider possible options about how and what we have to implement
+in order to create full-featured functions merging, and also what it would
+meant for us.</p>
+<p>Equal functions detection, obviously supposes “detector” method to be
+implemented, latter should answer the question “whether functions are equal”.
+This “detector” method consists of tiny “sub-detectors”, each of them answers
+exactly the same question, but for function parts.</p>
+<p>As the second step, we should merge equal functions. So it should be a “merger”
+method. “Merger” accepts two functions <em>F1</em> and <em>F2</em>, and produces <em>F1F2</em>
+function, the result of merging.</p>
+<p>Having such a routines in our hands, we can process whole module, and merge all
+equal functions.</p>
+<p>In this case, we have to compare every function with every another function. As
+reader could notice, this way seems to be quite expensive. Of course we could
+introduce hashing and other helpers, but it is still just an optimization, and
+thus the level of O(N*N) complexity.</p>
+<p>Can we reach another level? Could we introduce logarithmical search, or random
+access lookup? The answer is: “yes”.</p>
+<div class="section" id="random-access">
+<h5><a class="toc-backref" href="#id9">Random-access</a><a class="headerlink" href="#random-access" title="Permalink to this headline">¶</a></h5>
+<p>How it could be done? Just convert each function to number, and gather all of
+them in special hash-table. Functions with equal hash are equal. Good hashing
+means, that every function part must be taken into account. That means we have
+to convert every function part into some number, and then add it into hash.
+Lookup-up time would be small, but such approach adds some delay due to hashing
+routine.</p>
+</div>
+<div class="section" id="logarithmical-search">
+<h5><a class="toc-backref" href="#id10">Logarithmical search</a><a class="headerlink" href="#logarithmical-search" title="Permalink to this headline">¶</a></h5>
+<p>We could introduce total ordering among the functions set, once we had it we
+could then implement a logarithmical search. Lookup time still depends on N,
+but adds a little of delay (<em>log(N)</em>).</p>
+</div>
+<div class="section" id="present-state">
+<h5><a class="toc-backref" href="#id11">Present state</a><a class="headerlink" href="#present-state" title="Permalink to this headline">¶</a></h5>
+<p>Both of approaches (random-access and logarithmical) has been implemented and
+tested. And both of them gave a very good improvement. And what was most
+surprising, logarithmical search was faster; sometimes up to 15%. Hashing needs
+some extra CPU time, and it is the main reason why it works slower; in most of
+cases total “hashing” time was greater than total “logarithmical-search” time.</p>
+<p>So, preference has been granted to the “logarithmical search”.</p>
+<p>Though in the case of need, <em>logarithmical-search</em> (read “total-ordering”) could
+be used as a milestone on our way to the <em>random-access</em> implementation.</p>
+<p>Every comparison is based either on the numbers or on flags comparison. In
+<em>random-access</em> approach we could use the same comparison algorithm. During
+comparison we exit once we find the difference, but here we might have to scan
+whole function body every time (note, it could be slower). Like in
+“total-ordering”, we will track every numbers and flags, but instead of
+comparison, we should get numbers sequence and then create the hash number. So,
+once again, <em>total-ordering</em> could be considered as a milestone for even faster
+(in theory) random-access approach.</p>
+</div>
+</div>
+<div class="section" id="mergefunctions-main-fields-and-runonmodule">
+<h4><a class="toc-backref" href="#id12">MergeFunctions, main fields and runOnModule</a><a class="headerlink" href="#mergefunctions-main-fields-and-runonmodule" title="Permalink to this headline">¶</a></h4>
+<p>There are two most important fields in class:</p>
+<p><code class="docutils literal"><span class="pre">FnTree</span></code> â the set of all unique functions. It keeps items that couldn’t be
+merged with each other. It is defined as:</p>
+<p><code class="docutils literal"><span class="pre">std::set<FunctionNode></span> <span class="pre">FnTree;</span></code></p>
+<p>Here <code class="docutils literal"><span class="pre">FunctionNode</span></code> is a wrapper for <code class="docutils literal"><span class="pre">llvm::Function</span></code> class, with
+implemented â<â operator among the functions set (below we explain how it works
+exactly; this is a key point in fast functions comparison).</p>
+<p><code class="docutils literal"><span class="pre">Deferred</span></code> â merging process can affect bodies of functions that are in
+<code class="docutils literal"><span class="pre">FnTree</span></code> already. Obviously such functions should be rechecked again. In this
+case we remove them from <code class="docutils literal"><span class="pre">FnTree</span></code>, and mark them as to be rescanned, namely
+put them into <code class="docutils literal"><span class="pre">Deferred</span></code> list.</p>
+<div class="section" id="runonmodule">
+<h5><a class="toc-backref" href="#id13">runOnModule</a><a class="headerlink" href="#runonmodule" title="Permalink to this headline">¶</a></h5>
+<p>The algorithm is pretty simple:</p>
+<ol class="arabic simple">
+<li>Put all module’s functions into the <em>worklist</em>.</li>
+</ol>
+<p>2. Scan <em>worklist</em>‘s functions twice: first enumerate only strong functions and
+then only weak ones:</p>
+<blockquote>
+<div>2.1. Loop body: take function from <em>worklist</em> (call it <em>FCur</em>) and try to
+insert it into <em>FnTree</em>: check whether <em>FCur</em> is equal to one of functions
+in <em>FnTree</em>. If there <em>is</em> equal function in <em>FnTree</em> (call it <em>FExists</em>):
+merge function <em>FCur</em> with <em>FExists</em>. Otherwise add function from <em>worklist</em>
+to <em>FnTree</em>.</div></blockquote>
+<p>3. Once <em>worklist</em> scanning and merging operations is complete, check <em>Deferred</em>
+list. If it is not empty: refill <em>worklist</em> contents with <em>Deferred</em> list and
+do step 2 again, if <em>Deferred</em> is empty, then exit from method.</p>
+</div>
+<div class="section" id="comparison-and-logarithmical-search">
+<h5><a class="toc-backref" href="#id14">Comparison and logarithmical search</a><a class="headerlink" href="#comparison-and-logarithmical-search" title="Permalink to this headline">¶</a></h5>
+<p>Let’s recall our task: for every function <em>F</em> from module <em>M</em>, we have to find
+equal functions <em>F`</em> in shortest time, and merge them into the single function.</p>
+<p>Defining total ordering among the functions set allows to organize functions
+into the binary tree. The lookup procedure complexity would be estimated as
+O(log(N)) in this case. But how to define <em>total-ordering</em>?</p>
+<p>We have to introduce a single rule applicable to every pair of functions, and
+following this rule then evaluate which of them is greater. What kind of rule
+it could be? Let’s declare it as “compare” method, that returns one of 3
+possible values:</p>
+<p>-1, left is <em>less</em> than right,</p>
+<p>0, left and right are <em>equal</em>,</p>
+<p>1, left is <em>greater</em> than right.</p>
+<p>Of course it means, that we have to maintain
+<em>strict and non-strict order relation properties</em>:</p>
+<ul class="simple">
+<li>reflexivity (<code class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">a</span></code>, <code class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">a</span></code>, <code class="docutils literal"><span class="pre">a</span> <span class="pre">>=</span> <span class="pre">a</span></code>),</li>
+<li>antisymmetry (if <code class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">b</span></code> and <code class="docutils literal"><span class="pre">b</span> <span class="pre"><=</span> <span class="pre">a</span></code> then <code class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></code>),</li>
+<li>transitivity (<code class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">b</span></code> and <code class="docutils literal"><span class="pre">b</span> <span class="pre"><=</span> <span class="pre">c</span></code>, then <code class="docutils literal"><span class="pre">a</span> <span class="pre"><=</span> <span class="pre">c</span></code>)</li>
+<li>asymmetry (if <code class="docutils literal"><span class="pre">a</span> <span class="pre"><</span> <span class="pre">b</span></code>, then <code class="docutils literal"><span class="pre">a</span> <span class="pre">></span> <span class="pre">b</span></code> or <code class="docutils literal"><span class="pre">a</span> <span class="pre">==</span> <span class="pre">b</span></code>).</li>
+</ul>
+<p>As it was mentioned before, comparison routine consists of
+“sub-comparison-routines”, each of them also consists
+“sub-comparison-routines”, and so on, finally it ends up with a primitives
+comparison.</p>
+<p>Below, we will use the next operations:</p>
+<ol class="arabic simple">
+<li><code class="docutils literal"><span class="pre">cmpNumbers(number1,</span> <span class="pre">number2)</span></code> is method that returns -1 if left is less
+than right; 0, if left and right are equal; and 1 otherwise.</li>
+<li><code class="docutils literal"><span class="pre">cmpFlags(flag1,</span> <span class="pre">flag2)</span></code> is hypothetical method that compares two flags.
+The logic is the same as in <code class="docutils literal"><span class="pre">cmpNumbers</span></code>, where <code class="docutils literal"><span class="pre">true</span></code> is 1, and
+<code class="docutils literal"><span class="pre">false</span></code> is 0.</li>
+</ol>
+<p>The rest of article is based on <em>MergeFunctions.cpp</em> source code
+(<em><llvm_dir>/lib/Transforms/IPO/MergeFunctions.cpp</em>). We would like to ask
+reader to keep this file open nearby, so we could use it as a reference for
+further explanations.</p>
+<p>Now we’re ready to proceed to the next chapter and see how it works.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="functions-comparison">
+<h2><a class="toc-backref" href="#id15">Functions comparison</a><a class="headerlink" href="#functions-comparison" title="Permalink to this headline">¶</a></h2>
+<p>At first, let’s define how exactly we compare complex objects.</p>
+<p>Complex objects comparison (function, basic-block, etc) is mostly based on its
+sub-objects comparison results. So it is similar to the next “tree” objects
+comparison:</p>
+<ol class="arabic simple">
+<li>For two trees <em>T1</em> and <em>T2</em> we perform <em>depth-first-traversal</em> and have
+two sequences as a product: “<em>T1Items</em>” and “<em>T2Items</em>”.</li>
+<li>Then compare chains “<em>T1Items</em>” and “<em>T2Items</em>” in
+most-significant-item-first order. Result of items comparison would be the
+result of <em>T1</em> and <em>T2</em> comparison itself.</li>
+</ol>
+<div class="section" id="functioncomparator-compare-void">
+<h3><a class="toc-backref" href="#id16">FunctionComparator::compare(void)</a><a class="headerlink" href="#functioncomparator-compare-void" title="Permalink to this headline">¶</a></h3>
+<p>Brief look at the source code tells us, that comparison starts in
+â<code class="docutils literal"><span class="pre">int</span> <span class="pre">FunctionComparator::compare(void)</span></code>â method.</p>
+<p>1. First parts to be compared are function’s attributes and some properties that
+outsides âattributesâ term, but still could make function different without
+changing its body. This part of comparison is usually done within simple
+<em>cmpNumbers</em> or <em>cmpFlags</em> operations (e.g.
+<code class="docutils literal"><span class="pre">cmpFlags(F1->hasGC(),</span> <span class="pre">F2->hasGC())</span></code>). Below is full list of function’s
+properties to be compared on this stage:</p>
+<blockquote>
+<div><ul class="simple">
+<li><em>Attributes</em> (those are returned by <code class="docutils literal"><span class="pre">Function::getAttributes()</span></code>
+method).</li>
+<li><em>GC</em>, for equivalence, <em>RHS</em> and <em>LHS</em> should be both either without
+<em>GC</em> or with the same one.</li>
+<li><em>Section</em>, just like a <em>GC</em>: <em>RHS</em> and <em>LHS</em> should be defined in the
+same section.</li>
+<li><em>Variable arguments</em>. <em>LHS</em> and <em>RHS</em> should be both either with or
+without <em>var-args</em>.</li>
+<li><em>Calling convention</em> should be the same.</li>
+</ul>
+</div></blockquote>
+<p>2. Function type. Checked by <code class="docutils literal"><span class="pre">FunctionComparator::cmpType(Type*,</span> <span class="pre">Type*)</span></code>
+method. It checks return type and parameters type; the method itself will be
+described later.</p>
+<p>3. Associate function formal parameters with each other. Then comparing function
+bodies, if we see the usage of <em>LHS</em>‘s <em>i</em>-th argument in <em>LHS</em>‘s body, then,
+we want to see usage of <em>RHS</em>‘s <em>i</em>-th argument at the same place in <em>RHS</em>‘s
+body, otherwise functions are different. On this stage we grant the preference
+to those we met later in function body (value we met first would be <em>less</em>).
+This is done by â<code class="docutils literal"><span class="pre">FunctionComparator::cmpValues(const</span> <span class="pre">Value*,</span> <span class="pre">const</span> <span class="pre">Value*)</span></code>â
+method (will be described a bit later).</p>
+<ol class="arabic simple" start="4">
+<li>Function body comparison. As it written in method comments:</li>
+</ol>
+<p>âWe do a CFG-ordered walk since the actual ordering of the blocks in the linked
+list is immaterial. Our walk starts at the entry block for both functions, then
+takes each block from each terminator in order. As an artifact, this also means
+that unreachable blocks are ignored.â</p>
+<p>So, using this walk we get BBs from <em>left</em> and <em>right</em> in the same order, and
+compare them by â<code class="docutils literal"><span class="pre">FunctionComparator::compare(const</span> <span class="pre">BasicBlock*,</span> <span class="pre">const</span>
+<span class="pre">BasicBlock*)</span></code>â method.</p>
+<p>We also associate BBs with each other, like we did it with function formal
+arguments (see <code class="docutils literal"><span class="pre">cmpValues</span></code> method below).</p>
+</div>
+<div class="section" id="functioncomparator-cmptype">
+<h3><a class="toc-backref" href="#id17">FunctionComparator::cmpType</a><a class="headerlink" href="#functioncomparator-cmptype" title="Permalink to this headline">¶</a></h3>
+<p>Consider how types comparison works.</p>
+<p>1. Coerce pointer to integer. If left type is a pointer, try to coerce it to the
+integer type. It could be done if its address space is 0, or if address spaces
+are ignored at all. Do the same thing for the right type.</p>
+<p>2. If left and right types are equal, return 0. Otherwise we need to give
+preference to one of them. So proceed to the next step.</p>
+<p>3. If types are of different kind (different type IDs). Return result of type
+IDs comparison, treating them as a numbers (use <code class="docutils literal"><span class="pre">cmpNumbers</span></code> operation).</p>
+<p>4. If types are vectors or integers, return result of their pointers comparison,
+comparing them as numbers.</p>
+<ol class="arabic" start="5">
+<li><p class="first">Check whether type ID belongs to the next group (call it equivalent-group):</p>
+<ul class="simple">
+<li>Void</li>
+<li>Float</li>
+<li>Double</li>
+<li>X86_FP80</li>
+<li>FP128</li>
+<li>PPC_FP128</li>
+<li>Label</li>
+<li>Metadata.</li>
+</ul>
+<p>If ID belongs to group above, return 0. Since it’s enough to see that
+types has the same <code class="docutils literal"><span class="pre">TypeID</span></code>. No additional information is required.</p>
+</li>
+</ol>
+<p>6. Left and right are pointers. Return result of address space comparison
+(numbers comparison).</p>
+<p>7. Complex types (structures, arrays, etc.). Follow complex objects comparison
+technique (see the very first paragraph of this chapter). Both <em>left</em> and
+<em>right</em> are to be expanded and their element types will be checked the same
+way. If we get -1 or 1 on some stage, return it. Otherwise return 0.</p>
+<p>8. Steps 1-6 describe all the possible cases, if we passed steps 1-6 and didn’t
+get any conclusions, then invoke <code class="docutils literal"><span class="pre">llvm_unreachable</span></code>, since it’s quite
+unexpectable case.</p>
+</div>
+<div class="section" id="cmpvalues-const-value-const-value">
+<h3><a class="toc-backref" href="#id18">cmpValues(const Value*, const Value*)</a><a class="headerlink" href="#cmpvalues-const-value-const-value" title="Permalink to this headline">¶</a></h3>
+<p>Method that compares local values.</p>
+<p>This method gives us an answer on a very curious quesion: whether we could treat
+local values as equal, and which value is greater otherwise. It’s better to
+start from example:</p>
+<p>Consider situation when we’re looking at the same place in left function “<em>FL</em>”
+and in right function “<em>FR</em>”. And every part of <em>left</em> place is equal to the
+corresponding part of <em>right</em> place, and (!) both parts use <em>Value</em> instances,
+for example:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>instr0 i32 %LV ; left side, function FL
+instr0 i32 %RV ; right side, function FR
+</pre></div>
+</div>
+<p>So, now our conclusion depends on <em>Value</em> instances comparison.</p>
+<p>Main purpose of this method is to determine relation between such values.</p>
+<p>What we expect from equal functions? At the same place, in functions “<em>FL</em>” and
+“<em>FR</em>” we expect to see <em>equal</em> values, or values <em>defined</em> at the same place
+in “<em>FL</em>” and “<em>FR</em>”.</p>
+<p>Consider small example here:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>define void %f(i32 %pf0, i32 %pf1) {
+ instr0 i32 %pf0 instr1 i32 %pf1 instr2 i32 123
+}
+</pre></div>
+</div>
+<div class="highlight-text"><div class="highlight"><pre><span></span>define void %g(i32 %pg0, i32 %pg1) {
+ instr0 i32 %pg0 instr1 i32 %pg0 instr2 i32 123
+}
+</pre></div>
+</div>
+<p>In this example, <em>pf0</em> is associated with <em>pg0</em>, <em>pf1</em> is associated with <em>pg1</em>,
+and we also declare that <em>pf0</em> < <em>pf1</em>, and thus <em>pg0</em> < <em>pf1</em>.</p>
+<p>Instructions with opcode “<em>instr0</em>” would be <em>equal</em>, since their types and
+opcodes are equal, and values are <em>associated</em>.</p>
+<p>Instruction with opcode “<em>instr1</em>” from <em>f</em> is <em>greater</em> than instruction with
+opcode “<em>instr1</em>” from <em>g</em>; here we have equal types and opcodes, but “<em>pf1</em> is
+greater than “<em>pg0</em>”.</p>
+<p>And instructions with opcode “<em>instr2</em>” are equal, because their opcodes and
+types are equal, and the same constant is used as a value.</p>
+<div class="section" id="what-we-assiciate-in-cmpvalues">
+<h4><a class="toc-backref" href="#id19">What we assiciate in cmpValues?</a><a class="headerlink" href="#what-we-assiciate-in-cmpvalues" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li>Function arguments. <em>i</em>-th argument from left function associated with
+<em>i</em>-th argument from right function.</li>
+<li>BasicBlock instances. In basic-block enumeration loop we associate <em>i</em>-th
+BasicBlock from the left function with <em>i</em>-th BasicBlock from the right
+function.</li>
+<li>Instructions.</li>
+<li>Instruction operands. Note, we can meet <em>Value</em> here we have never seen
+before. In this case it is not a function argument, nor <em>BasicBlock</em>, nor
+<em>Instruction</em>. It is global value. It is constant, since its the only
+supposed global here. Method also compares:</li>
+<li>Constants that are of the same type.</li>
+<li>If right constant could be losslessly bit-casted to the left one, then we
+also compare them.</li>
+</ul>
+</div>
+<div class="section" id="how-to-implement-cmpvalues">
+<h4><a class="toc-backref" href="#id20">How to implement cmpValues?</a><a class="headerlink" href="#how-to-implement-cmpvalues" title="Permalink to this headline">¶</a></h4>
+<p><em>Association</em> is a case of equality for us. We just treat such values as equal.
+But, in general, we need to implement antisymmetric relation. As it was
+mentioned above, to understand what is <em>less</em>, we can use order in which we
+meet values. If both of values has the same order in function (met at the same
+time), then treat values as <em>associated</em>. Otherwise â it depends on who was
+first.</p>
+<p>Every time we run top-level compare method, we initialize two identical maps
+(one for the left side, another one for the right side):</p>
+<p><code class="docutils literal"><span class="pre">map<Value,</span> <span class="pre">int></span> <span class="pre">sn_mapL,</span> <span class="pre">sn_mapR;</span></code></p>
+<p>The key of the map is the <em>Value</em> itself, the <em>value</em> â is its order (call it
+<em>serial number</em>).</p>
+<p>To add value <em>V</em> we need to perform the next procedure:</p>
+<p><code class="docutils literal"><span class="pre">sn_map.insert(std::make_pair(V,</span> <span class="pre">sn_map.size()));</span></code></p>
+<p>For the first <em>Value</em>, map will return <em>0</em>, for second <em>Value</em> map will return
+<em>1</em>, and so on.</p>
+<p>Then we can check whether left and right values met at the same time with simple
+comparison:</p>
+<p><code class="docutils literal"><span class="pre">cmpNumbers(sn_mapL[Left],</span> <span class="pre">sn_mapR[Right]);</span></code></p>
+<p>Of course, we can combine insertion and comparison:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">pair</span><span class="o"><</span><span class="n">iterator</span><span class="p">,</span> <span class="kt">bool</span><span class="o">></span>
+ <span class="n">LeftRes</span> <span class="o">=</span> <span class="n">sn_mapL</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_pair</span><span class="p">(</span><span class="n">Left</span><span class="p">,</span> <span class="n">sn_mapL</span><span class="p">.</span><span class="n">size</span><span class="p">())),</span> <span class="n">RightRes</span>
+ <span class="o">=</span> <span class="n">sn_mapR</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_pair</span><span class="p">(</span><span class="n">Right</span><span class="p">,</span> <span class="n">sn_mapR</span><span class="p">.</span><span class="n">size</span><span class="p">()));</span>
+<span class="k">return</span> <span class="nf">cmpNumbers</span><span class="p">(</span><span class="n">LeftRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span><span class="p">,</span> <span class="n">RightRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Let’s look, how whole method could be implemented.</p>
+<p>1. we have to start from the bad news. Consider function self and
+cross-referencing cases:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="c1">// self-reference unsigned fact0(unsigned n) { return n > 1 ? n</span>
+<span class="o">*</span> <span class="nf">fact0</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">:</span> <span class="mi">1</span><span class="p">;</span> <span class="p">}</span> <span class="kt">unsigned</span> <span class="n">fact1</span><span class="p">(</span><span class="kt">unsigned</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">n</span> <span class="o">></span> <span class="mi">1</span> <span class="o">?</span> <span class="n">n</span> <span class="o">*</span>
+<span class="n">fact1</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">:</span> <span class="mi">1</span><span class="p">;</span> <span class="p">}</span>
+
+<span class="c1">// cross-reference unsigned ping(unsigned n) { return n!= 0 ? pong(n-1) : 0;</span>
+<span class="p">}</span> <span class="kt">unsigned</span> <span class="n">pong</span><span class="p">(</span><span class="kt">unsigned</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span> <span class="k">return</span> <span class="n">n</span><span class="o">!=</span> <span class="mi">0</span> <span class="o">?</span> <span class="n">ping</span><span class="p">(</span><span class="n">n</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">:</span> <span class="mi">0</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<blockquote>
+<div>This comparison has been implemented in initial <em>MergeFunctions</em> pass
+version. But, unfortunately, it is not transitive. And this is the only case
+we can’t convert to less-equal-greater comparison. It is a seldom case, 4-5
+functions of 10000 (checked on test-suite), and, we hope, reader would
+forgive us for such a sacrifice in order to get the O(log(N)) pass time.</div></blockquote>
+<p>2. If left/right <em>Value</em> is a constant, we have to compare them. Return 0 if it
+is the same constant, or use <code class="docutils literal"><span class="pre">cmpConstants</span></code> method otherwise.</p>
+<p>3. If left/right is <em>InlineAsm</em> instance. Return result of <em>Value</em> pointers
+comparison.</p>
+<p>4. Explicit association of <em>L</em> (left value) and <em>R</em> (right value). We need to
+find out whether values met at the same time, and thus are <em>associated</em>. Or we
+need to put the rule: when we treat <em>L</em> < <em>R</em>. Now it is easy: just return
+result of numbers comparison:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">pair</span><span class="o"><</span><span class="n">iterator</span><span class="p">,</span> <span class="kt">bool</span><span class="o">></span>
+ <span class="n">LeftRes</span> <span class="o">=</span> <span class="n">sn_mapL</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_pair</span><span class="p">(</span><span class="n">Left</span><span class="p">,</span> <span class="n">sn_mapL</span><span class="p">.</span><span class="n">size</span><span class="p">())),</span>
+ <span class="n">RightRes</span> <span class="o">=</span> <span class="n">sn_mapR</span><span class="p">.</span><span class="n">insert</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">make_pair</span><span class="p">(</span><span class="n">Right</span><span class="p">,</span> <span class="n">sn_mapR</span><span class="p">.</span><span class="n">size</span><span class="p">()));</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">LeftRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span> <span class="o">==</span> <span class="n">RightRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span><span class="p">)</span> <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">LeftRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span> <span class="o"><</span> <span class="n">RightRes</span><span class="p">.</span><span class="n">first</span><span class="o">-></span><span class="n">second</span><span class="p">)</span> <span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
+<span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Now when <em>cmpValues</em> returns 0, we can proceed comparison procedure. Otherwise,
+if we get (-1 or 1), we need to pass this result to the top level, and finish
+comparison procedure.</p>
+</div>
+</div>
+<div class="section" id="cmpconstants">
+<h3><a class="toc-backref" href="#id21">cmpConstants</a><a class="headerlink" href="#cmpconstants" title="Permalink to this headline">¶</a></h3>
+<p>Performs constants comparison as follows:</p>
+<p>1. Compare constant types using <code class="docutils literal"><span class="pre">cmpType</span></code> method. If result is -1 or 1, goto
+step 2, otherwise proceed to step 3.</p>
+<p>2. If types are different, we still can check whether constants could be
+losslessly bitcasted to each other. The further explanation is modification of
+<code class="docutils literal"><span class="pre">canLosslesslyBitCastTo</span></code> method.</p>
+<blockquote>
+<div><p>2.1 Check whether constants are of the first class types
+(<code class="docutils literal"><span class="pre">isFirstClassType</span></code> check):</p>
+<p>2.1.1. If both constants are <em>not</em> of the first class type: return result
+of <code class="docutils literal"><span class="pre">cmpType</span></code>.</p>
+<p>2.1.2. Otherwise, if left type is not of the first class, return -1. If
+right type is not of the first class, return 1.</p>
+<p>2.1.3. If both types are of the first class type, proceed to the next step
+(2.1.3.1).</p>
+<p>2.1.3.1. If types are vectors, compare their bitwidth using the
+<em>cmpNumbers</em>. If result is not 0, return it.</p>
+<p>2.1.3.2. Different types, but not a vectors:</p>
+<ul class="simple">
+<li>if both of them are pointers, good for us, we can proceed to step 3.</li>
+<li>if one of types is pointer, return result of <em>isPointer</em> flags
+comparison (<em>cmpFlags</em> operation).</li>
+<li>otherwise we have no methods to prove bitcastability, and thus return
+result of types comparison (-1 or 1).</li>
+</ul>
+</div></blockquote>
+<p>Steps below are for the case when types are equal, or case when constants are
+bitcastable:</p>
+<p>3. One of constants is a “<em>null</em>” value. Return the result of
+<code class="docutils literal"><span class="pre">cmpFlags(L->isNullValue,</span> <span class="pre">R->isNullValue)</span></code> comparison.</p>
+<ol class="arabic simple" start="4">
+<li>Compare value IDs, and return result if it is not 0:</li>
+</ol>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">(</span><span class="kt">int</span> <span class="n">Res</span> <span class="o">=</span> <span class="n">cmpNumbers</span><span class="p">(</span><span class="n">L</span><span class="o">-></span><span class="n">getValueID</span><span class="p">(),</span> <span class="n">R</span><span class="o">-></span><span class="n">getValueID</span><span class="p">()))</span>
+ <span class="k">return</span> <span class="n">Res</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>5. Compare the contents of constants. The comparison depends on kind of
+constants, but on this stage it is just a lexicographical comparison. Just see
+how it was described in the beginning of “<em>Functions comparison</em>” paragraph.
+Mathematically it is equal to the next case: we encode left constant and right
+constant (with similar way <em>bitcode-writer</em> does). Then compare left code
+sequence and right code sequence.</p>
+</div>
+<div class="section" id="compare-const-basicblock-const-basicblock">
+<h3><a class="toc-backref" href="#id22">compare(const BasicBlock*, const BasicBlock*)</a><a class="headerlink" href="#compare-const-basicblock-const-basicblock" title="Permalink to this headline">¶</a></h3>
+<p>Compares two <em>BasicBlock</em> instances.</p>
+<p>It enumerates instructions from left <em>BB</em> and right <em>BB</em>.</p>
+<p>1. It assigns serial numbers to the left and right instructions, using
+<code class="docutils literal"><span class="pre">cmpValues</span></code> method.</p>
+<p>2. If one of left or right is <em>GEP</em> (<code class="docutils literal"><span class="pre">GetElementPtr</span></code>), then treat <em>GEP</em> as
+greater than other instructions, if both instructions are <em>GEPs</em> use <code class="docutils literal"><span class="pre">cmpGEP</span></code>
+method for comparison. If result is -1 or 1, pass it to the top-level
+comparison (return it).</p>
+<blockquote>
+<div><p>3.1. Compare operations. Call <code class="docutils literal"><span class="pre">cmpOperation</span></code> method. If result is -1 or
+1, return it.</p>
+<p>3.2. Compare number of operands, if result is -1 or 1, return it.</p>
+<p>3.3. Compare operands themselves, use <code class="docutils literal"><span class="pre">cmpValues</span></code> method. Return result
+if it is -1 or 1.</p>
+<p>3.4. Compare type of operands, using <code class="docutils literal"><span class="pre">cmpType</span></code> method. Return result if
+it is -1 or 1.</p>
+<p>3.5. Proceed to the next instruction.</p>
+</div></blockquote>
+<ol class="arabic" start="4">
+<li><p class="first">We can finish instruction enumeration in 3 cases:</p>
+<p>4.1. We reached the end of both left and right basic-blocks. We didn’t
+exit on steps 1-3, so contents is equal, return 0.</p>
+<p>4.2. We have reached the end of the left basic-block. Return -1.</p>
+<p>4.3. Return 1 (the end of the right basic block).</p>
+</li>
+</ol>
+</div>
+<div class="section" id="cmpgep">
+<h3><a class="toc-backref" href="#id23">cmpGEP</a><a class="headerlink" href="#cmpgep" title="Permalink to this headline">¶</a></h3>
+<p>Compares two GEPs (<code class="docutils literal"><span class="pre">getelementptr</span></code> instructions).</p>
+<p>It differs from regular operations comparison with the only thing: possibility
+to use <code class="docutils literal"><span class="pre">accumulateConstantOffset</span></code> method.</p>
+<p>So, if we get constant offset for both left and right <em>GEPs</em>, then compare it as
+numbers, and return comparison result.</p>
+<p>Otherwise treat it like a regular operation (see previous paragraph).</p>
+</div>
+<div class="section" id="cmpoperation">
+<h3><a class="toc-backref" href="#id24">cmpOperation</a><a class="headerlink" href="#cmpoperation" title="Permalink to this headline">¶</a></h3>
+<p>Compares instruction opcodes and some important operation properties.</p>
+<ol class="arabic simple">
+<li>Compare opcodes, if it differs return the result.</li>
+<li>Compare number of operands. If it differs â return the result.</li>
+</ol>
+<p>3. Compare operation types, use <em>cmpType</em>. All the same â if types are
+different, return result.</p>
+<p>4. Compare <em>subclassOptionalData</em>, get it with <code class="docutils literal"><span class="pre">getRawSubclassOptionalData</span></code>
+method, and compare it like a numbers.</p>
+<ol class="arabic simple" start="5">
+<li>Compare operand types.</li>
+</ol>
+<p>6. For some particular instructions check equivalence (relation in our case) of
+some significant attributes. For example we have to compare alignment for
+<code class="docutils literal"><span class="pre">load</span></code> instructions.</p>
+</div>
+<div class="section" id="o-log-n">
+<h3><a class="toc-backref" href="#id25">O(log(N))</a><a class="headerlink" href="#o-log-n" title="Permalink to this headline">¶</a></h3>
+<p>Methods described above implement order relationship. And latter, could be used
+for nodes comparison in a binary tree. So we can organize functions set into
+the binary tree and reduce the cost of lookup procedure from
+O(N*N) to O(log(N)).</p>
+</div>
+</div>
+<div class="section" id="merging-process-mergetwofunctions">
+<h2><a class="toc-backref" href="#id26">Merging process, mergeTwoFunctions</a><a class="headerlink" href="#merging-process-mergetwofunctions" title="Permalink to this headline">¶</a></h2>
+<p>Once <em>MergeFunctions</em> detected that current function (<em>G</em>) is equal to one that
+were analyzed before (function <em>F</em>) it calls <code class="docutils literal"><span class="pre">mergeTwoFunctions(Function*,</span>
+<span class="pre">Function*)</span></code>.</p>
+<p>Operation affects <code class="docutils literal"><span class="pre">FnTree</span></code> contents with next way: <em>F</em> will stay in
+<code class="docutils literal"><span class="pre">FnTree</span></code>. <em>G</em> being equal to <em>F</em> will not be added to <code class="docutils literal"><span class="pre">FnTree</span></code>. Calls of
+<em>G</em> would be replaced with something else. It changes bodies of callers. So,
+functions that calls <em>G</em> would be put into <code class="docutils literal"><span class="pre">Deferred</span></code> set and removed from
+<code class="docutils literal"><span class="pre">FnTree</span></code>, and analyzed again.</p>
+<p>The approach is next:</p>
+<p>1. Most wished case: when we can use alias and both of <em>F</em> and <em>G</em> are weak. We
+make both of them with aliases to the third strong function <em>H</em>. Actually <em>H</em>
+is <em>F</em>. See below how it’s made (but it’s better to look straight into the
+source code). Well, this is a case when we can just replace <em>G</em> with <em>F</em>
+everywhere, we use <code class="docutils literal"><span class="pre">replaceAllUsesWith</span></code> operation here (<em>RAUW</em>).</p>
+<p>2. <em>F</em> could not be overridden, while <em>G</em> could. It would be good to do the
+next: after merging the places where overridable function were used, still use
+overridable stub. So try to make <em>G</em> alias to <em>F</em>, or create overridable tail
+call wrapper around <em>F</em> and replace <em>G</em> with that call.</p>
+<p>3. Neither <em>F</em> nor <em>G</em> could be overridden. We can’t use <em>RAUW</em>. We can just
+change the callers: call <em>F</em> instead of <em>G</em>. That’s what
+<code class="docutils literal"><span class="pre">replaceDirectCallers</span></code> does.</p>
+<p>Below is detailed body description.</p>
+<div class="section" id="if-f-may-be-overridden">
+<h3><a class="toc-backref" href="#id27">If âFâ may be overridden</a><a class="headerlink" href="#if-f-may-be-overridden" title="Permalink to this headline">¶</a></h3>
+<p>As follows from <code class="docutils literal"><span class="pre">mayBeOverridden</span></code> comments: âwhether the definition of this
+global may be replaced by something non-equivalent at link timeâ. If so, that’s
+ok: we can use alias to <em>F</em> instead of <em>G</em> or change call instructions itself.</p>
+<div class="section" id="hasglobalaliases-removeusers">
+<h4><a class="toc-backref" href="#id28">HasGlobalAliases, removeUsers</a><a class="headerlink" href="#hasglobalaliases-removeusers" title="Permalink to this headline">¶</a></h4>
+<p>First consider the case when we have global aliases of one function name to
+another. Our purpose is make both of them with aliases to the third strong
+function. Though if we keep <em>F</em> alive and without major changes we can leave it
+in <code class="docutils literal"><span class="pre">FnTree</span></code>. Try to combine these two goals.</p>
+<p>Do stub replacement of <em>F</em> itself with an alias to <em>F</em>.</p>
+<p>1. Create stub function <em>H</em>, with the same name and attributes like function
+<em>F</em>. It takes maximum alignment of <em>F</em> and <em>G</em>.</p>
+<p>2. Replace all uses of function <em>F</em> with uses of function <em>H</em>. It is the two
+steps procedure instead. First of all, we must take into account, all functions
+from whom <em>F</em> is called would be changed: since we change the call argument
+(from <em>F</em> to <em>H</em>). If so we must to review these caller functions again after
+this procedure. We remove callers from <code class="docutils literal"><span class="pre">FnTree</span></code>, method with name
+<code class="docutils literal"><span class="pre">removeUsers(F)</span></code> does that (don’t confuse with <code class="docutils literal"><span class="pre">replaceAllUsesWith</span></code>):</p>
+<blockquote>
+<div><p>2.1. <code class="docutils literal"><span class="pre">Inside</span> <span class="pre">removeUsers(Value*</span>
+<span class="pre">V)</span></code> we go through the all values that use value <em>V</em> (or <em>F</em> in our context).
+If value is instruction, we go to function that holds this instruction and
+mark it as to-be-analyzed-again (put to <code class="docutils literal"><span class="pre">Deferred</span></code> set), we also remove
+caller from <code class="docutils literal"><span class="pre">FnTree</span></code>.</p>
+<p>2.2. Now we can do the replacement: call <code class="docutils literal"><span class="pre">F->replaceAllUsesWith(H)</span></code>.</p>
+</div></blockquote>
+<p>3. <em>H</em> (that now “officially” plays <em>F</em>‘s role) is replaced with alias to <em>F</em>.
+Do the same with <em>G</em>: replace it with alias to <em>F</em>. So finally everywhere <em>F</em>
+was used, we use <em>H</em> and it is alias to <em>F</em>, and everywhere <em>G</em> was used we
+also have alias to <em>F</em>.</p>
+<ol class="arabic simple" start="4">
+<li>Set <em>F</em> linkage to private. Make it strong :-)</li>
+</ol>
+</div>
+<div class="section" id="no-global-aliases-replacedirectcallers">
+<h4><a class="toc-backref" href="#id29">No global aliases, replaceDirectCallers</a><a class="headerlink" href="#no-global-aliases-replacedirectcallers" title="Permalink to this headline">¶</a></h4>
+<p>If global aliases are not supported. We call <code class="docutils literal"><span class="pre">replaceDirectCallers</span></code> then. Just
+go through all calls of <em>G</em> and replace it with calls of <em>F</em>. If you look into
+method you will see that it scans all uses of <em>G</em> too, and if use is callee (if
+user is call instruction and <em>G</em> is used as what to be called), we replace it
+with use of <em>F</em>.</p>
+<div class="section" id="if-f-could-not-be-overridden-fix-it">
+<h5><a class="toc-backref" href="#id30">If âFâ could not be overridden, fix it!</a><a class="headerlink" href="#if-f-could-not-be-overridden-fix-it" title="Permalink to this headline">¶</a></h5>
+<p>We call <code class="docutils literal"><span class="pre">writeThunkOrAlias(Function</span> <span class="pre">*F,</span> <span class="pre">Function</span> <span class="pre">*G)</span></code>. Here we try to replace
+<em>G</em> with alias to <em>F</em> first. Next conditions are essential:</p>
+<ul class="simple">
+<li>target should support global aliases,</li>
+<li>the address itself of <em>G</em> should be not significant, not named and not
+referenced anywhere,</li>
+<li>function should come with external, local or weak linkage.</li>
+</ul>
+<p>Otherwise we write thunk: some wrapper that has <em>G’s</em> interface and calls <em>F</em>,
+so <em>G</em> could be replaced with this wrapper.</p>
+<p><em>writeAlias</em></p>
+<p>As follows from <em>llvm</em> reference:</p>
+<p>âAliases act as <em>second name</em> for the aliasee valueâ. So we just want to create
+second name for <em>F</em> and use it instead of <em>G</em>:</p>
+<ol class="arabic">
+<li><p class="first">create global alias itself (<em>GA</em>),</p>
+</li>
+<li><p class="first">adjust alignment of <em>F</em> so it must be maximum of current and <em>G’s</em> alignment;</p>
+</li>
+<li><p class="first">replace uses of <em>G</em>:</p>
+<p>3.1. first mark all callers of <em>G</em> as to-be-analyzed-again, using
+<code class="docutils literal"><span class="pre">removeUsers</span></code> method (see chapter above),</p>
+<p>3.2. call <code class="docutils literal"><span class="pre">G->replaceAllUsesWith(GA)</span></code>.</p>
+</li>
+<li><p class="first">Get rid of <em>G</em>.</p>
+</li>
+</ol>
+<p><em>writeThunk</em></p>
+<p>As it written in method comments:</p>
+<p>âReplace G with a simple tail call to bitcast(F). Also replace direct uses of G
+with bitcast(F). Deletes G.â</p>
+<p>In general it does the same as usual when we want to replace callee, except the
+first point:</p>
+<p>1. We generate tail call wrapper around <em>F</em>, but with interface that allows use
+it instead of <em>G</em>.</p>
+<ol class="arabic simple" start="2">
+<li>âAs-usualâ: <code class="docutils literal"><span class="pre">removeUsers</span></code> and <code class="docutils literal"><span class="pre">replaceAllUsesWith</span></code> then.</li>
+<li>Get rid of <em>G</em>.</li>
+</ol>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="that-s-it">
+<h2><a class="toc-backref" href="#id31">That’s it.</a><a class="headerlink" href="#that-s-it" title="Permalink to this headline">¶</a></h2>
+<p>We have described how to detect equal functions, and how to merge them, and in
+first chapter we have described how it works all-together. Author hopes, reader
+have some picture from now, and it helps him improve and debug Âthis pass.</p>
+<p>Reader is welcomed to send us any questions and proposals ;-)</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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="TypeMetadata.html" title="Type Metadata"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Statepoints.html" title="Garbage Collection Safepoints in LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/NVPTXUsage.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/NVPTXUsage.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/NVPTXUsage.html (added)
+++ www-releases/trunk/6.0.0/docs/NVPTXUsage.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,1062 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>User Guide for NVPTX Back-end — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="User Guide for AMDGPU Backend" href="AMDGPUUsage.html" />
+ <link rel="prev" title="How To Use Attributes" href="HowToUseAttributes.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="AMDGPUUsage.html" title="User Guide for AMDGPU Backend"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseAttributes.html" title="How To Use Attributes"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="user-guide-for-nvptx-back-end">
+<h1>User Guide for NVPTX Back-end<a class="headerlink" href="#user-guide-for-nvptx-back-end" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id11">Introduction</a></li>
+<li><a class="reference internal" href="#conventions" id="id12">Conventions</a><ul>
+<li><a class="reference internal" href="#marking-functions-as-kernels" id="id13">Marking Functions as Kernels</a></li>
+<li><a class="reference internal" href="#address-spaces" id="id14">Address Spaces</a></li>
+<li><a class="reference internal" href="#triples" id="id15">Triples</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#nvptx-intrinsics" id="id16">NVPTX Intrinsics</a><ul>
+<li><a class="reference internal" href="#address-space-conversion" id="id17">Address Space Conversion</a><ul>
+<li><a class="reference internal" href="#llvm-nvvm-ptr-to-gen-intrinsics" id="id18">‘<code class="docutils literal"><span class="pre">llvm.nvvm.ptr.*.to.gen</span></code>‘ Intrinsics</a></li>
+<li><a class="reference internal" href="#llvm-nvvm-ptr-gen-to-intrinsics" id="id19">‘<code class="docutils literal"><span class="pre">llvm.nvvm.ptr.gen.to.*</span></code>‘ Intrinsics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reading-ptx-special-registers" id="id20">Reading PTX Special Registers</a><ul>
+<li><a class="reference internal" href="#llvm-nvvm-read-ptx-sreg" id="id21">‘<code class="docutils literal"><span class="pre">llvm.nvvm.read.ptx.sreg.*</span></code>‘</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#barriers" id="id22">Barriers</a><ul>
+<li><a class="reference internal" href="#llvm-nvvm-barrier0" id="id23">‘<code class="docutils literal"><span class="pre">llvm.nvvm.barrier0</span></code>‘</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-intrinsics" id="id24">Other Intrinsics</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#linking-with-libdevice" id="id25">Linking with Libdevice</a><ul>
+<li><a class="reference internal" href="#reflection-parameters" id="id26">Reflection Parameters</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#executing-ptx" id="id27">Executing PTX</a></li>
+<li><a class="reference internal" href="#common-issues" id="id28">Common Issues</a><ul>
+<li><a class="reference internal" href="#ptxas-complains-of-undefined-function-nvvm-reflect" id="id29">ptxas complains of undefined function: __nvvm_reflect</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tutorial-a-simple-compute-kernel" id="id30">Tutorial: A Simple Compute Kernel</a><ul>
+<li><a class="reference internal" href="#the-kernel" id="id31">The Kernel</a></li>
+<li><a class="reference internal" href="#dissecting-the-kernel" id="id32">Dissecting the Kernel</a><ul>
+<li><a class="reference internal" href="#data-layout" id="id33">Data Layout</a></li>
+<li><a class="reference internal" href="#target-intrinsics" id="id34">Target Intrinsics</a></li>
+<li><a class="reference internal" href="#id10" id="id35">Address Spaces</a></li>
+<li><a class="reference internal" href="#kernel-metadata" id="id36">Kernel Metadata</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#running-the-kernel" id="id37">Running the Kernel</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#tutorial-linking-with-libdevice" id="id38">Tutorial: Linking with Libdevice</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id11">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>To support GPU programming, the NVPTX back-end supports a subset of LLVM IR
+along with a defined set of conventions used to represent GPU programming
+concepts. This document provides an overview of the general usage of the back-
+end, including a description of the conventions used and the set of accepted
+LLVM IR.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This document assumes a basic familiarity with CUDA and the PTX
+assembly language. Information about the CUDA Driver API and the PTX assembly
+language can be found in the <a class="reference external" href="http://docs.nvidia.com/cuda/index.html">CUDA documentation</a>.</p>
+</div>
+</div>
+<div class="section" id="conventions">
+<h2><a class="toc-backref" href="#id12">Conventions</a><a class="headerlink" href="#conventions" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="marking-functions-as-kernels">
+<h3><a class="toc-backref" href="#id13">Marking Functions as Kernels</a><a class="headerlink" href="#marking-functions-as-kernels" title="Permalink to this headline">¶</a></h3>
+<p>In PTX, there are two types of functions: <em>device functions</em>, which are only
+callable by device code, and <em>kernel functions</em>, which are callable by host
+code. By default, the back-end will emit device functions. Metadata is used to
+declare a function as a kernel function. This metadata is attached to the
+<code class="docutils literal"><span class="pre">nvvm.annotations</span></code> named metadata object, and has the following format:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>!0 = !{<function-ref>, metadata !"kernel", i32 1}
+</pre></div>
+</div>
+<p>The first parameter is a reference to the kernel function. The following
+example shows a kernel function calling a device function in LLVM IR. The
+function <code class="docutils literal"><span class="pre">@my_kernel</span></code> is callable from host code, but <code class="docutils literal"><span class="pre">@my_fmad</span></code> is not.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="kt">float</span> <span class="vg">@my_fmad</span><span class="p">(</span><span class="kt">float</span> <span class="nv">%x</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%y</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%z</span><span class="p">)</span> <span class="p">{</span>
+ <span class="nv">%mul</span> <span class="p">=</span> <span class="k">fmul</span> <span class="kt">float</span> <span class="nv">%x</span><span class="p">,</span> <span class="nv">%y</span>
+ <span class="nv">%add</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">float</span> <span class="nv">%mul</span><span class="p">,</span> <span class="nv">%z</span>
+ <span class="k">ret</span> <span class="kt">float</span> <span class="nv">%add</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@my_kernel</span><span class="p">(</span><span class="kt">float</span><span class="p">*</span> <span class="nv">%ptr</span><span class="p">)</span> <span class="p">{</span>
+ <span class="nv">%val</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span><span class="p">*</span> <span class="nv">%ptr</span>
+ <span class="nv">%ret</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">float</span> <span class="vg">@my_fmad</span><span class="p">(</span><span class="kt">float</span> <span class="nv">%val</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%val</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%val</span><span class="p">)</span>
+ <span class="k">store</span> <span class="kt">float</span> <span class="nv">%ret</span><span class="p">,</span> <span class="kt">float</span><span class="p">*</span> <span class="nv">%ptr</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="nv">!nvvm.annotations</span> <span class="p">=</span> <span class="p">!{</span><span class="nv nv-Anonymous">!1</span><span class="p">}</span>
+<span class="nv nv-Anonymous">!1</span> <span class="p">=</span> <span class="p">!{</span><span class="kt">void</span> <span class="p">(</span><span class="kt">float</span><span class="p">*)*</span> <span class="vg">@my_kernel</span><span class="p">,</span> <span class="nv">!"kernel"</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>When compiled, the PTX kernel functions are callable by host-side code.</p>
+</div>
+<div class="section" id="address-spaces">
+<span id="id1"></span><h3><a class="toc-backref" href="#id14">Address Spaces</a><a class="headerlink" href="#address-spaces" title="Permalink to this headline">¶</a></h3>
+<p>The NVPTX back-end uses the following address space mapping:</p>
+<blockquote>
+<div><table border="1" class="docutils">
+<colgroup>
+<col width="37%" />
+<col width="63%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Address Space</th>
+<th class="head">Memory Space</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>0</td>
+<td>Generic</td>
+</tr>
+<tr class="row-odd"><td>1</td>
+<td>Global</td>
+</tr>
+<tr class="row-even"><td>2</td>
+<td>Internal Use</td>
+</tr>
+<tr class="row-odd"><td>3</td>
+<td>Shared</td>
+</tr>
+<tr class="row-even"><td>4</td>
+<td>Constant</td>
+</tr>
+<tr class="row-odd"><td>5</td>
+<td>Local</td>
+</tr>
+</tbody>
+</table>
+</div></blockquote>
+<p>Every global variable and pointer type is assigned to one of these address
+spaces, with 0 being the default address space. Intrinsics are provided which
+can be used to convert pointers between the generic and non-generic address
+spaces.</p>
+<p>As an example, the following IR will define an array <code class="docutils literal"><span class="pre">@g</span></code> that resides in
+global device memory.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="vg">@g</span> <span class="p">=</span> <span class="k">internal</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)</span> <span class="k">global</span> <span class="p">[</span><span class="m">4</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">[</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="k">i32</span> <span class="m">3</span> <span class="p">]</span>
+</pre></div>
+</div>
+<p>LLVM IR functions can read and write to this array, and host-side code can
+copy data to it by name with the CUDA Driver API.</p>
+<p>Note that since address space 0 is the generic space, it is illegal to have
+global variables in address space 0. Address space 0 is the default address
+space in LLVM, so the <code class="docutils literal"><span class="pre">addrspace(N)</span></code> annotation is <em>required</em> for global
+variables.</p>
+</div>
+<div class="section" id="triples">
+<h3><a class="toc-backref" href="#id15">Triples</a><a class="headerlink" href="#triples" title="Permalink to this headline">¶</a></h3>
+<p>The NVPTX target uses the module triple to select between 32/64-bit code
+generation and the driver-compiler interface to use. The triple architecture
+can be one of <code class="docutils literal"><span class="pre">nvptx</span></code> (32-bit PTX) or <code class="docutils literal"><span class="pre">nvptx64</span></code> (64-bit PTX). The
+operating system should be one of <code class="docutils literal"><span class="pre">cuda</span></code> or <code class="docutils literal"><span class="pre">nvcl</span></code>, which determines the
+interface used by the generated code to communicate with the driver. Most
+users will want to use <code class="docutils literal"><span class="pre">cuda</span></code> as the operating system, which makes the
+generated PTX compatible with the CUDA Driver API.</p>
+<p>Example: 32-bit PTX for CUDA Driver API: <code class="docutils literal"><span class="pre">nvptx-nvidia-cuda</span></code></p>
+<p>Example: 64-bit PTX for CUDA Driver API: <code class="docutils literal"><span class="pre">nvptx64-nvidia-cuda</span></code></p>
+</div>
+</div>
+<div class="section" id="nvptx-intrinsics">
+<span id="id2"></span><h2><a class="toc-backref" href="#id16">NVPTX Intrinsics</a><a class="headerlink" href="#nvptx-intrinsics" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="address-space-conversion">
+<h3><a class="toc-backref" href="#id17">Address Space Conversion</a><a class="headerlink" href="#address-space-conversion" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="llvm-nvvm-ptr-to-gen-intrinsics">
+<h4><a class="toc-backref" href="#id18">‘<code class="docutils literal"><span class="pre">llvm.nvvm.ptr.*.to.gen</span></code>‘ Intrinsics</a><a class="headerlink" href="#llvm-nvvm-ptr-to-gen-intrinsics" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="syntax">
+<h5>Syntax:<a class="headerlink" href="#syntax" title="Permalink to this headline">¶</a></h5>
+<p>These are overloaded intrinsics. You can use these on any pointer types.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.global.to.gen.p0i8.p1i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*)</span>
+<span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.shared.to.gen.p0i8.p3i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">3</span><span class="p">)*)</span>
+<span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.constant.to.gen.p0i8.p4i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">4</span><span class="p">)*)</span>
+<span class="k">declare</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.nvvm.ptr.local.to.gen.p0i8.p5i8</span><span class="p">(</span><span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">5</span><span class="p">)*)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="overview">
+<h5>Overview:<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<code class="docutils literal"><span class="pre">llvm.nvvm.ptr.*.to.gen</span></code>‘ intrinsics convert a pointer in a non-generic
+address space to a generic address space pointer.</p>
+</div>
+<div class="section" id="semantics">
+<h5>Semantics:<a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h5>
+<p>These intrinsics modify the pointer value to be a valid generic address space
+pointer.</p>
+</div>
+</div>
+<div class="section" id="llvm-nvvm-ptr-gen-to-intrinsics">
+<h4><a class="toc-backref" href="#id19">‘<code class="docutils literal"><span class="pre">llvm.nvvm.ptr.gen.to.*</span></code>‘ Intrinsics</a><a class="headerlink" href="#llvm-nvvm-ptr-gen-to-intrinsics" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="id3">
+<h5>Syntax:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h5>
+<p>These are overloaded intrinsics. You can use these on any pointer types.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">declare</span> <span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="vg">@llvm.nvvm.ptr.gen.to.global.p1i8.p0i8</span><span class="p">(</span><span class="k">i8</span><span class="p">*)</span>
+<span class="k">declare</span> <span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">3</span><span class="p">)*</span> <span class="vg">@llvm.nvvm.ptr.gen.to.shared.p3i8.p0i8</span><span class="p">(</span><span class="k">i8</span><span class="p">*)</span>
+<span class="k">declare</span> <span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">4</span><span class="p">)*</span> <span class="vg">@llvm.nvvm.ptr.gen.to.constant.p4i8.p0i8</span><span class="p">(</span><span class="k">i8</span><span class="p">*)</span>
+<span class="k">declare</span> <span class="k">i8</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">5</span><span class="p">)*</span> <span class="vg">@llvm.nvvm.ptr.gen.to.local.p5i8.p0i8</span><span class="p">(</span><span class="k">i8</span><span class="p">*)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="id4">
+<h5>Overview:<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<code class="docutils literal"><span class="pre">llvm.nvvm.ptr.gen.to.*</span></code>‘ intrinsics convert a pointer in the generic
+address space to a pointer in the target address space. Note that these
+intrinsics are only useful if the address space of the target address space of
+the pointer is known. It is not legal to use address space conversion
+intrinsics to convert a pointer from one non-generic address space to another
+non-generic address space.</p>
+</div>
+<div class="section" id="id5">
+<h5>Semantics:<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h5>
+<p>These intrinsics modify the pointer value to be a valid pointer in the target
+non-generic address space.</p>
+</div>
+</div>
+</div>
+<div class="section" id="reading-ptx-special-registers">
+<h3><a class="toc-backref" href="#id20">Reading PTX Special Registers</a><a class="headerlink" href="#reading-ptx-special-registers" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="llvm-nvvm-read-ptx-sreg">
+<h4><a class="toc-backref" href="#id21">‘<code class="docutils literal"><span class="pre">llvm.nvvm.read.ptx.sreg.*</span></code>‘</a><a class="headerlink" href="#llvm-nvvm-read-ptx-sreg" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="id6">
+<h5>Syntax:<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.y</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.z</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ntid.x</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ntid.y</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ntid.z</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ctaid.x</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ctaid.y</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.ctaid.z</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.nctaid.x</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.nctaid.y</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.nctaid.z</span><span class="p">()</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.warpsize</span><span class="p">()</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="id7">
+<h5>Overview:<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<code class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.*</span></code>‘ intrinsics provide access to the PTX
+special registers, in particular the kernel launch bounds. These registers
+map in the following way to CUDA builtins:</p>
+<blockquote>
+<div><table border="1" class="docutils">
+<colgroup>
+<col width="24%" />
+<col width="76%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">CUDA Builtin</th>
+<th class="head">PTX Special Register Intrinsic</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">threadId</span></code></td>
+<td><code class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.tid.*</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">blockIdx</span></code></td>
+<td><code class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.ctaid.*</span></code></td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">blockDim</span></code></td>
+<td><code class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.ntid.*</span></code></td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">gridDim</span></code></td>
+<td><code class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.nctaid.*</span></code></td>
+</tr>
+</tbody>
+</table>
+</div></blockquote>
+</div>
+</div>
+</div>
+<div class="section" id="barriers">
+<h3><a class="toc-backref" href="#id22">Barriers</a><a class="headerlink" href="#barriers" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="llvm-nvvm-barrier0">
+<h4><a class="toc-backref" href="#id23">‘<code class="docutils literal"><span class="pre">llvm.nvvm.barrier0</span></code>‘</a><a class="headerlink" href="#llvm-nvvm-barrier0" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="id8">
+<h5>Syntax:<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">declare</span> <span class="kt">void</span> <span class="vg">@llvm.nvvm.barrier0</span><span class="p">()</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="id9">
+<h5>Overview:<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<code class="docutils literal"><span class="pre">@llvm.nvvm.barrier0()</span></code>‘ intrinsic emits a PTX <code class="docutils literal"><span class="pre">bar.sync</span> <span class="pre">0</span></code>
+instruction, equivalent to the <code class="docutils literal"><span class="pre">__syncthreads()</span></code> call in CUDA.</p>
+</div>
+</div>
+</div>
+<div class="section" id="other-intrinsics">
+<h3><a class="toc-backref" href="#id24">Other Intrinsics</a><a class="headerlink" href="#other-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>For the full set of NVPTX intrinsics, please see the
+<code class="docutils literal"><span class="pre">include/llvm/IR/IntrinsicsNVVM.td</span></code> file in the LLVM source tree.</p>
+</div>
+</div>
+<div class="section" id="linking-with-libdevice">
+<span id="libdevice"></span><h2><a class="toc-backref" href="#id25">Linking with Libdevice</a><a class="headerlink" href="#linking-with-libdevice" title="Permalink to this headline">¶</a></h2>
+<p>The CUDA Toolkit comes with an LLVM bitcode library called <code class="docutils literal"><span class="pre">libdevice</span></code> that
+implements many common mathematical functions. This library can be used as a
+high-performance math library for any compilers using the LLVM NVPTX target.
+The library can be found under <code class="docutils literal"><span class="pre">nvvm/libdevice/</span></code> in the CUDA Toolkit and
+there is a separate version for each compute architecture.</p>
+<p>For a list of all math functions implemented in libdevice, see
+<a class="reference external" href="http://docs.nvidia.com/cuda/libdevice-users-guide/index.html">libdevice Users Guide</a>.</p>
+<p>To accommodate various math-related compiler flags that can affect code
+generation of libdevice code, the library code depends on a special LLVM IR
+pass (<code class="docutils literal"><span class="pre">NVVMReflect</span></code>) to handle conditional compilation within LLVM IR. This
+pass looks for calls to the <code class="docutils literal"><span class="pre">@__nvvm_reflect</span></code> function and replaces them
+with constants based on the defined reflection parameters. Such conditional
+code often follows a pattern:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="kt">float</span> <span class="nf">my_function</span><span class="p">(</span><span class="kt">float</span> <span class="n">a</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">__nvvm_reflect</span><span class="p">(</span><span class="s">"FASTMATH"</span><span class="p">))</span>
+ <span class="k">return</span> <span class="n">my_function_fast</span><span class="p">(</span><span class="n">a</span><span class="p">);</span>
+ <span class="k">else</span>
+ <span class="k">return</span> <span class="n">my_function_precise</span><span class="p">(</span><span class="n">a</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The default value for all unspecified reflection parameters is zero.</p>
+<p>The <code class="docutils literal"><span class="pre">NVVMReflect</span></code> pass should be executed early in the optimization
+pipeline, immediately after the link stage. The <code class="docutils literal"><span class="pre">internalize</span></code> pass is also
+recommended to remove unused math functions from the resulting PTX. For an
+input IR module <code class="docutils literal"><span class="pre">module.bc</span></code>, the following compilation flow is recommended:</p>
+<ol class="arabic simple">
+<li>Save list of external functions in <code class="docutils literal"><span class="pre">module.bc</span></code></li>
+<li>Link <code class="docutils literal"><span class="pre">module.bc</span></code> with <code class="docutils literal"><span class="pre">libdevice.compute_XX.YY.bc</span></code></li>
+<li>Internalize all functions not in list from (1)</li>
+<li>Eliminate all unused internal functions</li>
+<li>Run <code class="docutils literal"><span class="pre">NVVMReflect</span></code> pass</li>
+<li>Run standard optimization pipeline</li>
+</ol>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last"><code class="docutils literal"><span class="pre">linkonce</span></code> and <code class="docutils literal"><span class="pre">linkonce_odr</span></code> linkage types are not suitable for the
+libdevice functions. It is possible to link two IR modules that have been
+linked against libdevice using different reflection variables.</p>
+</div>
+<p>Since the <code class="docutils literal"><span class="pre">NVVMReflect</span></code> pass replaces conditionals with constants, it will
+often leave behind dead code of the form:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="nl">entry:</span>
+ <span class="p">..</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="k">true</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%foo</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%bar</span>
+<span class="nl">foo:</span>
+ <span class="p">..</span>
+<span class="nl">bar:</span>
+ <span class="c">; Dead code</span>
+ <span class="p">..</span>
+</pre></div>
+</div>
+<p>Therefore, it is recommended that <code class="docutils literal"><span class="pre">NVVMReflect</span></code> is executed early in the
+optimization pipeline before dead-code elimination.</p>
+<p>The NVPTX TargetMachine knows how to schedule <code class="docutils literal"><span class="pre">NVVMReflect</span></code> at the beginning
+of your pass manager; just use the following code when setting up your pass
+manager:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">std</span><span class="o">::</span><span class="n">unique_ptr</span><span class="o"><</span><span class="n">TargetMachine</span><span class="o">></span> <span class="n">TM</span> <span class="o">=</span> <span class="p">...;</span>
+<span class="n">PassManagerBuilder</span> <span class="nf">PMBuilder</span><span class="p">(...);</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">TM</span><span class="p">)</span>
+ <span class="n">TM</span><span class="o">-></span><span class="n">adjustPassManager</span><span class="p">(</span><span class="n">PMBuilder</span><span class="p">);</span>
+</pre></div>
+</div>
+<div class="section" id="reflection-parameters">
+<h3><a class="toc-backref" href="#id26">Reflection Parameters</a><a class="headerlink" href="#reflection-parameters" title="Permalink to this headline">¶</a></h3>
+<p>The libdevice library currently uses the following reflection parameters to
+control code generation:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="27%" />
+<col width="73%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Flag</th>
+<th class="head">Description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">__CUDA_FTZ=[0,1]</span></code></td>
+<td>Use optimized code paths that flush subnormals to zero</td>
+</tr>
+</tbody>
+</table>
+<p>The value of this flag is determined by the “nvvm-reflect-ftz” module flag.
+The following sets the ftz flag to 1.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="nv">!llvm.module.flag</span> <span class="p">=</span> <span class="p">!{</span><span class="nv nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv nv-Anonymous">!0</span> <span class="p">=</span> <span class="p">!{</span><span class="k">i32</span> <span class="m">4</span><span class="p">,</span> <span class="nv">!"nvvm-reflect-ftz"</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>(<code class="docutils literal"><span class="pre">i32</span> <span class="pre">4</span></code> indicates that the value set here overrides the value in another
+module we link with. See the <cite>LangRef <LangRef.html#module-flags-metadata></cite>
+for details.)</p>
+</div>
+</div>
+<div class="section" id="executing-ptx">
+<h2><a class="toc-backref" href="#id27">Executing PTX</a><a class="headerlink" href="#executing-ptx" title="Permalink to this headline">¶</a></h2>
+<p>The most common way to execute PTX assembly on a GPU device is to use the CUDA
+Driver API. This API is a low-level interface to the GPU driver and allows for
+JIT compilation of PTX code to native GPU machine code.</p>
+<p>Initializing the Driver API:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">CUdevice</span> <span class="n">device</span><span class="p">;</span>
+<span class="n">CUcontext</span> <span class="n">context</span><span class="p">;</span>
+
+<span class="c1">// Initialize the driver API</span>
+<span class="n">cuInit</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
+<span class="c1">// Get a handle to the first compute device</span>
+<span class="n">cuDeviceGet</span><span class="p">(</span><span class="o">&</span><span class="n">device</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+<span class="c1">// Create a compute device context</span>
+<span class="n">cuCtxCreate</span><span class="p">(</span><span class="o">&</span><span class="n">context</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">device</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>JIT compiling a PTX string to a device binary:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="n">CUmodule</span> <span class="n">module</span><span class="p">;</span>
+<span class="n">CUfunction</span> <span class="n">function</span><span class="p">;</span>
+
+<span class="c1">// JIT compile a null-terminated PTX string</span>
+<span class="n">cuModuleLoadData</span><span class="p">(</span><span class="o">&</span><span class="n">module</span><span class="p">,</span> <span class="p">(</span><span class="kt">void</span><span class="o">*</span><span class="p">)</span><span class="n">PTXString</span><span class="p">);</span>
+
+<span class="c1">// Get a handle to the "myfunction" kernel function</span>
+<span class="n">cuModuleGetFunction</span><span class="p">(</span><span class="o">&</span><span class="n">function</span><span class="p">,</span> <span class="n">module</span><span class="p">,</span> <span class="s">"myfunction"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>For full examples of executing PTX assembly, please see the <a class="reference external" href="https://developer.nvidia.com/cuda-downloads">CUDA Samples</a> distribution.</p>
+</div>
+<div class="section" id="common-issues">
+<h2><a class="toc-backref" href="#id28">Common Issues</a><a class="headerlink" href="#common-issues" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="ptxas-complains-of-undefined-function-nvvm-reflect">
+<h3><a class="toc-backref" href="#id29">ptxas complains of undefined function: __nvvm_reflect</a><a class="headerlink" href="#ptxas-complains-of-undefined-function-nvvm-reflect" title="Permalink to this headline">¶</a></h3>
+<p>When linking with libdevice, the <code class="docutils literal"><span class="pre">NVVMReflect</span></code> pass must be used. See
+<a class="reference internal" href="#libdevice"><span class="std std-ref">Linking with Libdevice</span></a> for more information.</p>
+</div>
+</div>
+<div class="section" id="tutorial-a-simple-compute-kernel">
+<h2><a class="toc-backref" href="#id30">Tutorial: A Simple Compute Kernel</a><a class="headerlink" href="#tutorial-a-simple-compute-kernel" title="Permalink to this headline">¶</a></h2>
+<p>To start, let us take a look at a simple compute kernel written directly in
+LLVM IR. The kernel implements vector addition, where each thread computes one
+element of the output vector C from the input vectors A and B. To make this
+easier, we also assume that only a single CTA (thread block) will be launched,
+and that it will be one dimensional.</p>
+<div class="section" id="the-kernel">
+<h3><a class="toc-backref" href="#id31">The Kernel</a><a class="headerlink" href="#the-kernel" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">target</span> <span class="k">datalayout</span> <span class="p">=</span> <span class="s">"e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"</span>
+<span class="k">target</span> <span class="k">triple</span> <span class="p">=</span> <span class="s">"nvptx64-nvidia-cuda"</span>
+
+<span class="c">; Intrinsic to read X component of thread ID</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span> <span class="k">readnone</span> <span class="k">nounwind</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@kernel</span><span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%A</span><span class="p">,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%B</span><span class="p">,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%C</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="c">; What is my ID?</span>
+ <span class="nv">%id</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span> <span class="k">readnone</span> <span class="k">nounwind</span>
+
+ <span class="c">; Compute pointers into A, B, and C</span>
+ <span class="nv">%ptrA</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%A</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+ <span class="nv">%ptrB</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%B</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+ <span class="nv">%ptrC</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%C</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+
+ <span class="c">; Read A, B</span>
+ <span class="nv">%valA</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrA</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="nv">%valB</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrB</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+
+ <span class="c">; Compute C = A + B</span>
+ <span class="nv">%valC</span> <span class="p">=</span> <span class="k">fadd</span> <span class="kt">float</span> <span class="nv">%valA</span><span class="p">,</span> <span class="nv">%valB</span>
+
+ <span class="c">; Store back to C</span>
+ <span class="k">store</span> <span class="kt">float</span> <span class="nv">%valC</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrC</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="nv">!nvvm.annotations</span> <span class="p">=</span> <span class="p">!{</span><span class="nv nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv nv-Anonymous">!0</span> <span class="p">=</span> <span class="p">!{</span><span class="kt">void</span> <span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*)*</span> <span class="vg">@kernel</span><span class="p">,</span> <span class="nv">!"kernel"</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>We can use the LLVM <code class="docutils literal"><span class="pre">llc</span></code> tool to directly run the NVPTX code generator:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span># llc -mcpu=sm_20 kernel.ll -o kernel.ptx
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">If you want to generate 32-bit code, change <code class="docutils literal"><span class="pre">p:64:64:64</span></code> to <code class="docutils literal"><span class="pre">p:32:32:32</span></code>
+in the module data layout string and use <code class="docutils literal"><span class="pre">nvptx-nvidia-cuda</span></code> as the
+target triple.</p>
+</div>
+<p>The output we get from <code class="docutils literal"><span class="pre">llc</span></code> (as of LLVM 3.4):</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>//
+// Generated by LLVM NVPTX Back-End
+//
+
+.version 3.1
+.target sm_20
+.address_size 64
+
+ // .globl kernel
+ // @kernel
+.visible .entry kernel(
+ .param .u64 kernel_param_0,
+ .param .u64 kernel_param_1,
+ .param .u64 kernel_param_2
+)
+{
+ .reg .f32 %f<4>;
+ .reg .s32 %r<2>;
+ .reg .s64 %rl<8>;
+
+// %bb.0: // %entry
+ ld.param.u64 %rl1, [kernel_param_0];
+ mov.u32 %r1, %tid.x;
+ mul.wide.s32 %rl2, %r1, 4;
+ add.s64 %rl3, %rl1, %rl2;
+ ld.param.u64 %rl4, [kernel_param_1];
+ add.s64 %rl5, %rl4, %rl2;
+ ld.param.u64 %rl6, [kernel_param_2];
+ add.s64 %rl7, %rl6, %rl2;
+ ld.global.f32 %f1, [%rl3];
+ ld.global.f32 %f2, [%rl5];
+ add.f32 %f3, %f1, %f2;
+ st.global.f32 [%rl7], %f3;
+ ret;
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="dissecting-the-kernel">
+<h3><a class="toc-backref" href="#id32">Dissecting the Kernel</a><a class="headerlink" href="#dissecting-the-kernel" title="Permalink to this headline">¶</a></h3>
+<p>Now let us dissect the LLVM IR that makes up this kernel.</p>
+<div class="section" id="data-layout">
+<h4><a class="toc-backref" href="#id33">Data Layout</a><a class="headerlink" href="#data-layout" title="Permalink to this headline">¶</a></h4>
+<p>The data layout string determines the size in bits of common data types, their
+ABI alignment, and their storage size. For NVPTX, you should use one of the
+following:</p>
+<p>32-bit PTX:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">target</span> <span class="k">datalayout</span> <span class="p">=</span> <span class="s">"e-p:32:32:32-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"</span>
+</pre></div>
+</div>
+<p>64-bit PTX:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">target</span> <span class="k">datalayout</span> <span class="p">=</span> <span class="s">"e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="target-intrinsics">
+<h4><a class="toc-backref" href="#id34">Target Intrinsics</a><a class="headerlink" href="#target-intrinsics" title="Permalink to this headline">¶</a></h4>
+<p>In this example, we use the <code class="docutils literal"><span class="pre">@llvm.nvvm.read.ptx.sreg.tid.x</span></code> intrinsic to
+read the X component of the current thread’s ID, which corresponds to a read
+of register <code class="docutils literal"><span class="pre">%tid.x</span></code> in PTX. The NVPTX back-end supports a large set of
+intrinsics. A short list is shown below; please see
+<code class="docutils literal"><span class="pre">include/llvm/IR/IntrinsicsNVVM.td</span></code> for the full list.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="71%" />
+<col width="29%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Intrinsic</th>
+<th class="head">CUDA Equivalent</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">i32</span> <span class="pre">@llvm.nvvm.read.ptx.sreg.tid.{x,y,z}</span></code></td>
+<td>threadIdx.{x,y,z}</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">i32</span> <span class="pre">@llvm.nvvm.read.ptx.sreg.ctaid.{x,y,z}</span></code></td>
+<td>blockIdx.{x,y,z}</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">i32</span> <span class="pre">@llvm.nvvm.read.ptx.sreg.ntid.{x,y,z}</span></code></td>
+<td>blockDim.{x,y,z}</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal"><span class="pre">i32</span> <span class="pre">@llvm.nvvm.read.ptx.sreg.nctaid.{x,y,z}</span></code></td>
+<td>gridDim.{x,y,z}</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal"><span class="pre">void</span> <span class="pre">@llvm.nvvm.barrier0()</span></code></td>
+<td>__syncthreads()</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="id10">
+<h4><a class="toc-backref" href="#id35">Address Spaces</a><a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h4>
+<p>You may have noticed that all of the pointer types in the LLVM IR example had
+an explicit address space specifier. What is address space 1? NVIDIA GPU
+devices (generally) have four types of memory:</p>
+<ul class="simple">
+<li>Global: Large, off-chip memory</li>
+<li>Shared: Small, on-chip memory shared among all threads in a CTA</li>
+<li>Local: Per-thread, private memory</li>
+<li>Constant: Read-only memory shared across all threads</li>
+</ul>
+<p>These different types of memory are represented in LLVM IR as address spaces.
+There is also a fifth address space used by the NVPTX code generator that
+corresponds to the “generic” address space. This address space can represent
+addresses in any other address space (with a few exceptions). This allows
+users to write IR functions that can load/store memory using the same
+instructions. Intrinsics are provided to convert pointers between the generic
+and non-generic address spaces.</p>
+<p>See <a class="reference internal" href="#address-spaces"><span class="std std-ref">Address Spaces</span></a> and <a class="reference internal" href="#nvptx-intrinsics"><span class="std std-ref">NVPTX Intrinsics</span></a> for more information.</p>
+</div>
+<div class="section" id="kernel-metadata">
+<h4><a class="toc-backref" href="#id36">Kernel Metadata</a><a class="headerlink" href="#kernel-metadata" title="Permalink to this headline">¶</a></h4>
+<p>In PTX, a function can be either a <cite>kernel</cite> function (callable from the host
+program), or a <cite>device</cite> function (callable only from GPU code). You can think
+of <cite>kernel</cite> functions as entry-points in the GPU program. To mark an LLVM IR
+function as a <cite>kernel</cite> function, we make use of special LLVM metadata. The
+NVPTX back-end will look for a named metadata node called
+<code class="docutils literal"><span class="pre">nvvm.annotations</span></code>. This named metadata must contain a list of metadata that
+describe the IR. For our purposes, we need to declare a metadata node that
+assigns the “kernel” attribute to the LLVM IR function that should be emitted
+as a PTX <cite>kernel</cite> function. These metadata nodes take the form:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>!{<function ref>, metadata !"kernel", i32 1}
+</pre></div>
+</div>
+<p>For the previous example, we have:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="nv">!nvvm.annotations</span> <span class="p">=</span> <span class="p">!{</span><span class="nv nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv nv-Anonymous">!0</span> <span class="p">=</span> <span class="p">!{</span><span class="kt">void</span> <span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*)*</span> <span class="vg">@kernel</span><span class="p">,</span> <span class="nv">!"kernel"</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>Here, we have a single metadata declaration in <code class="docutils literal"><span class="pre">nvvm.annotations</span></code>. This
+metadata annotates our <code class="docutils literal"><span class="pre">@kernel</span></code> function with the <code class="docutils literal"><span class="pre">kernel</span></code> attribute.</p>
+</div>
+</div>
+<div class="section" id="running-the-kernel">
+<h3><a class="toc-backref" href="#id37">Running the Kernel</a><a class="headerlink" href="#running-the-kernel" title="Permalink to this headline">¶</a></h3>
+<p>Generating PTX from LLVM IR is all well and good, but how do we execute it on
+a real GPU device? The CUDA Driver API provides a convenient mechanism for
+loading and JIT compiling PTX to a native GPU device, and launching a kernel.
+The API is similar to OpenCL. A simple example showing how to load and
+execute our vector addition code is shown below. Note that for brevity this
+code does not perform much error checking!</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">You can also use the <code class="docutils literal"><span class="pre">ptxas</span></code> tool provided by the CUDA Toolkit to offline
+compile PTX to machine code (SASS) for a specific GPU architecture. Such
+binaries can be loaded by the CUDA Driver API in the same way as PTX. This
+can be useful for reducing startup time by precompiling the PTX kernels.</p>
+</div>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><iostream></span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf"><fstream></span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf"><cassert></span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf">"cuda.h"</span><span class="cp"></span>
+
+
+<span class="kt">void</span> <span class="nf">checkCudaErrors</span><span class="p">(</span><span class="n">CUresult</span> <span class="n">err</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">err</span> <span class="o">==</span> <span class="n">CUDA_SUCCESS</span><span class="p">);</span>
+<span class="p">}</span>
+
+<span class="c1">/// main - Program entry point</span>
+<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">CUdevice</span> <span class="n">device</span><span class="p">;</span>
+ <span class="n">CUmodule</span> <span class="n">cudaModule</span><span class="p">;</span>
+ <span class="n">CUcontext</span> <span class="n">context</span><span class="p">;</span>
+ <span class="n">CUfunction</span> <span class="n">function</span><span class="p">;</span>
+ <span class="n">CUlinkState</span> <span class="n">linker</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">devCount</span><span class="p">;</span>
+
+ <span class="c1">// CUDA initialization</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuInit</span><span class="p">(</span><span class="mi">0</span><span class="p">));</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuDeviceGetCount</span><span class="p">(</span><span class="o">&</span><span class="n">devCount</span><span class="p">));</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuDeviceGet</span><span class="p">(</span><span class="o">&</span><span class="n">device</span><span class="p">,</span> <span class="mi">0</span><span class="p">));</span>
+
+ <span class="kt">char</span> <span class="n">name</span><span class="p">[</span><span class="mi">128</span><span class="p">];</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuDeviceGetName</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="mi">128</span><span class="p">,</span> <span class="n">device</span><span class="p">));</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Using CUDA Device [0]: "</span> <span class="o"><<</span> <span class="n">name</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+
+ <span class="kt">int</span> <span class="n">devMajor</span><span class="p">,</span> <span class="n">devMinor</span><span class="p">;</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuDeviceComputeCapability</span><span class="p">(</span><span class="o">&</span><span class="n">devMajor</span><span class="p">,</span> <span class="o">&</span><span class="n">devMinor</span><span class="p">,</span> <span class="n">device</span><span class="p">));</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Device Compute Capability: "</span>
+ <span class="o"><<</span> <span class="n">devMajor</span> <span class="o"><<</span> <span class="s">"."</span> <span class="o"><<</span> <span class="n">devMinor</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">devMajor</span> <span class="o"><</span> <span class="mi">2</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"ERROR: Device 0 is not SM 2.0 or greater</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+ <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">std</span><span class="o">::</span><span class="n">ifstream</span> <span class="n">t</span><span class="p">(</span><span class="s">"kernel.ptx"</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">t</span><span class="p">.</span><span class="n">is_open</span><span class="p">())</span> <span class="p">{</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">cerr</span> <span class="o"><<</span> <span class="s">"kernel.ptx not found</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+ <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">str</span><span class="p">((</span><span class="n">std</span><span class="o">::</span><span class="n">istreambuf_iterator</span><span class="o"><</span><span class="kt">char</span><span class="o">></span><span class="p">(</span><span class="n">t</span><span class="p">)),</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">istreambuf_iterator</span><span class="o"><</span><span class="kt">char</span><span class="o">></span><span class="p">());</span>
+
+ <span class="c1">// Create driver context</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuCtxCreate</span><span class="p">(</span><span class="o">&</span><span class="n">context</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">device</span><span class="p">));</span>
+
+ <span class="c1">// Create module for object</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuModuleLoadDataEx</span><span class="p">(</span><span class="o">&</span><span class="n">cudaModule</span><span class="p">,</span> <span class="n">str</span><span class="p">.</span><span class="n">c_str</span><span class="p">(),</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">));</span>
+
+ <span class="c1">// Get kernel function</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuModuleGetFunction</span><span class="p">(</span><span class="o">&</span><span class="n">function</span><span class="p">,</span> <span class="n">cudaModule</span><span class="p">,</span> <span class="s">"kernel"</span><span class="p">));</span>
+
+ <span class="c1">// Device data</span>
+ <span class="n">CUdeviceptr</span> <span class="n">devBufferA</span><span class="p">;</span>
+ <span class="n">CUdeviceptr</span> <span class="n">devBufferB</span><span class="p">;</span>
+ <span class="n">CUdeviceptr</span> <span class="n">devBufferC</span><span class="p">;</span>
+
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemAlloc</span><span class="p">(</span><span class="o">&</span><span class="n">devBufferA</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemAlloc</span><span class="p">(</span><span class="o">&</span><span class="n">devBufferB</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemAlloc</span><span class="p">(</span><span class="o">&</span><span class="n">devBufferC</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+
+ <span class="kt">float</span><span class="o">*</span> <span class="n">hostA</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">float</span><span class="p">[</span><span class="mi">16</span><span class="p">];</span>
+ <span class="kt">float</span><span class="o">*</span> <span class="n">hostB</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">float</span><span class="p">[</span><span class="mi">16</span><span class="p">];</span>
+ <span class="kt">float</span><span class="o">*</span> <span class="n">hostC</span> <span class="o">=</span> <span class="k">new</span> <span class="kt">float</span><span class="p">[</span><span class="mi">16</span><span class="p">];</span>
+
+ <span class="c1">// Populate input</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="mi">16</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">hostA</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="n">i</span><span class="p">;</span>
+ <span class="n">hostB</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="kt">float</span><span class="p">)(</span><span class="mi">2</span><span class="o">*</span><span class="n">i</span><span class="p">);</span>
+ <span class="n">hostC</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="mf">0.0f</span><span class="p">;</span>
+ <span class="p">}</span>
+
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemcpyHtoD</span><span class="p">(</span><span class="n">devBufferA</span><span class="p">,</span> <span class="o">&</span><span class="n">hostA</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemcpyHtoD</span><span class="p">(</span><span class="n">devBufferB</span><span class="p">,</span> <span class="o">&</span><span class="n">hostB</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+
+
+ <span class="kt">unsigned</span> <span class="n">blockSizeX</span> <span class="o">=</span> <span class="mi">16</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">blockSizeY</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">blockSizeZ</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">gridSizeX</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">gridSizeY</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">gridSizeZ</span> <span class="o">=</span> <span class="mi">1</span><span class="p">;</span>
+
+ <span class="c1">// Kernel parameters</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">KernelParams</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span> <span class="o">&</span><span class="n">devBufferA</span><span class="p">,</span> <span class="o">&</span><span class="n">devBufferB</span><span class="p">,</span> <span class="o">&</span><span class="n">devBufferC</span> <span class="p">};</span>
+
+ <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Launching kernel</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+
+ <span class="c1">// Kernel launch</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuLaunchKernel</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">gridSizeX</span><span class="p">,</span> <span class="n">gridSizeY</span><span class="p">,</span> <span class="n">gridSizeZ</span><span class="p">,</span>
+ <span class="n">blockSizeX</span><span class="p">,</span> <span class="n">blockSizeY</span><span class="p">,</span> <span class="n">blockSizeZ</span><span class="p">,</span>
+ <span class="mi">0</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">,</span> <span class="n">KernelParams</span><span class="p">,</span> <span class="nb">NULL</span><span class="p">));</span>
+
+ <span class="c1">// Retrieve device data</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemcpyDtoH</span><span class="p">(</span><span class="o">&</span><span class="n">hostC</span><span class="p">[</span><span class="mi">0</span><span class="p">],</span> <span class="n">devBufferC</span><span class="p">,</span> <span class="k">sizeof</span><span class="p">(</span><span class="kt">float</span><span class="p">)</span><span class="o">*</span><span class="mi">16</span><span class="p">));</span>
+
+
+ <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="s">"Results:</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="mi">16</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o"><<</span> <span class="n">hostA</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o"><<</span> <span class="s">" + "</span> <span class="o"><<</span> <span class="n">hostB</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o"><<</span> <span class="s">" = "</span> <span class="o"><<</span> <span class="n">hostC</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o"><<</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">;</span>
+ <span class="p">}</span>
+
+
+ <span class="c1">// Clean up after ourselves</span>
+ <span class="k">delete</span> <span class="p">[]</span> <span class="n">hostA</span><span class="p">;</span>
+ <span class="k">delete</span> <span class="p">[]</span> <span class="n">hostB</span><span class="p">;</span>
+ <span class="k">delete</span> <span class="p">[]</span> <span class="n">hostC</span><span class="p">;</span>
+
+ <span class="c1">// Clean-up</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemFree</span><span class="p">(</span><span class="n">devBufferA</span><span class="p">));</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemFree</span><span class="p">(</span><span class="n">devBufferB</span><span class="p">));</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuMemFree</span><span class="p">(</span><span class="n">devBufferC</span><span class="p">));</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuModuleUnload</span><span class="p">(</span><span class="n">cudaModule</span><span class="p">));</span>
+ <span class="n">checkCudaErrors</span><span class="p">(</span><span class="n">cuCtxDestroy</span><span class="p">(</span><span class="n">context</span><span class="p">));</span>
+
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>You will need to link with the CUDA driver and specify the path to cuda.h.</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span># clang++ sample.cpp -o sample -O2 -g -I/usr/local/cuda-5.5/include -lcuda
+</pre></div>
+</div>
+<p>We don’t need to specify a path to <code class="docutils literal"><span class="pre">libcuda.so</span></code> since this is installed in a
+system location by the driver, not the CUDA toolkit.</p>
+<p>If everything goes as planned, you should see the following output when
+running the compiled program:</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>Using CUDA Device [0]: GeForce GTX 680
+Device Compute Capability: 3.0
+Launching kernel
+Results:
+0 + 0 = 0
+1 + 2 = 3
+2 + 4 = 6
+3 + 6 = 9
+4 + 8 = 12
+5 + 10 = 15
+6 + 12 = 18
+7 + 14 = 21
+8 + 16 = 24
+9 + 18 = 27
+10 + 20 = 30
+11 + 22 = 33
+12 + 24 = 36
+13 + 26 = 39
+14 + 28 = 42
+15 + 30 = 45
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">You will likely see a different device identifier based on your hardware</p>
+</div>
+</div>
+</div>
+<div class="section" id="tutorial-linking-with-libdevice">
+<h2><a class="toc-backref" href="#id38">Tutorial: Linking with Libdevice</a><a class="headerlink" href="#tutorial-linking-with-libdevice" title="Permalink to this headline">¶</a></h2>
+<p>In this tutorial, we show a simple example of linking LLVM IR with the
+libdevice library. We will use the same kernel as the previous tutorial,
+except that we will compute <code class="docutils literal"><span class="pre">C</span> <span class="pre">=</span> <span class="pre">pow(A,</span> <span class="pre">B)</span></code> instead of <code class="docutils literal"><span class="pre">C</span> <span class="pre">=</span> <span class="pre">A</span> <span class="pre">+</span> <span class="pre">B</span></code>.
+Libdevice provides an <code class="docutils literal"><span class="pre">__nv_powf</span></code> function that we will use.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">target</span> <span class="k">datalayout</span> <span class="p">=</span> <span class="s">"e-p:64:64:64-i1:8:8-i8:8:8-i16:16:16-i32:32:32-i64:64:64-f32:32:32-f64:64:64-v16:16:16-v32:32:32-v64:64:64-v128:128:128-n16:32:64"</span>
+<span class="k">target</span> <span class="k">triple</span> <span class="p">=</span> <span class="s">"nvptx64-nvidia-cuda"</span>
+
+<span class="c">; Intrinsic to read X component of thread ID</span>
+<span class="k">declare</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span> <span class="k">readnone</span> <span class="k">nounwind</span>
+<span class="c">; libdevice function</span>
+<span class="k">declare</span> <span class="kt">float</span> <span class="vg">@__nv_powf</span><span class="p">(</span><span class="kt">float</span><span class="p">,</span> <span class="kt">float</span><span class="p">)</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@kernel</span><span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%A</span><span class="p">,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%B</span><span class="p">,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%C</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="c">; What is my ID?</span>
+ <span class="nv">%id</span> <span class="p">=</span> <span class="k">tail</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.nvvm.read.ptx.sreg.tid.x</span><span class="p">()</span> <span class="k">readnone</span> <span class="k">nounwind</span>
+
+ <span class="c">; Compute pointers into A, B, and C</span>
+ <span class="nv">%ptrA</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%A</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+ <span class="nv">%ptrB</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%B</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+ <span class="nv">%ptrC</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%C</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%id</span>
+
+ <span class="c">; Read A, B</span>
+ <span class="nv">%valA</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrA</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="nv">%valB</span> <span class="p">=</span> <span class="k">load</span> <span class="kt">float</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrB</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+
+ <span class="c">; Compute C = pow(A, B)</span>
+ <span class="nv">%valC</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">float</span> <span class="vg">@__nv_powf</span><span class="p">(</span><span class="kt">float</span> <span class="nv">%valA</span><span class="p">,</span> <span class="kt">float</span> <span class="nv">%valB</span><span class="p">)</span>
+
+ <span class="c">; Store back to C</span>
+ <span class="k">store</span> <span class="kt">float</span> <span class="nv">%valC</span><span class="p">,</span> <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*</span> <span class="nv">%ptrC</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="nv">!nvvm.annotations</span> <span class="p">=</span> <span class="p">!{</span><span class="nv nv-Anonymous">!0</span><span class="p">}</span>
+<span class="nv nv-Anonymous">!0</span> <span class="p">=</span> <span class="p">!{</span><span class="kt">void</span> <span class="p">(</span><span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*,</span>
+ <span class="kt">float</span> <span class="k">addrspace</span><span class="p">(</span><span class="m">1</span><span class="p">)*)*</span> <span class="vg">@kernel</span><span class="p">,</span> <span class="nv">!"kernel"</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span><span class="p">}</span>
+</pre></div>
+</div>
+<p>To compile this kernel, we perform the following steps:</p>
+<ol class="arabic simple">
+<li>Link with libdevice</li>
+<li>Internalize all but the public kernel function</li>
+<li>Run <code class="docutils literal"><span class="pre">NVVMReflect</span></code> and set <code class="docutils literal"><span class="pre">__CUDA_FTZ</span></code> to 0</li>
+<li>Optimize the linked module</li>
+<li>Codegen the module</li>
+</ol>
+<p>These steps can be performed by the LLVM <code class="docutils literal"><span class="pre">llvm-link</span></code>, <code class="docutils literal"><span class="pre">opt</span></code>, and <code class="docutils literal"><span class="pre">llc</span></code>
+tools. In a complete compiler, these steps can also be performed entirely
+programmatically by setting up an appropriate pass configuration (see
+<a class="reference internal" href="#libdevice"><span class="std std-ref">Linking with Libdevice</span></a>).</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span># llvm-link t2.bc libdevice.compute_20.10.bc -o t2.linked.bc
+# opt -internalize -internalize-public-api-list=kernel -nvvm-reflect-list=__CUDA_FTZ=0 -nvvm-reflect -O3 t2.linked.bc -o t2.opt.bc
+# llc -mcpu=sm_20 t2.opt.bc -o t2.ptx
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The <code class="docutils literal"><span class="pre">-nvvm-reflect-list=_CUDA_FTZ=0</span></code> is not strictly required, as any
+undefined variables will default to zero. It is shown here for evaluation
+purposes.</p>
+</div>
+<p>This gives us the following PTX (excerpt):</p>
+<div class="highlight-text"><div class="highlight"><pre><span></span>//
+// Generated by LLVM NVPTX Back-End
+//
+
+.version 3.1
+.target sm_20
+.address_size 64
+
+ // .globl kernel
+ // @kernel
+.visible .entry kernel(
+ .param .u64 kernel_param_0,
+ .param .u64 kernel_param_1,
+ .param .u64 kernel_param_2
+)
+{
+ .reg .pred %p<30>;
+ .reg .f32 %f<111>;
+ .reg .s32 %r<21>;
+ .reg .s64 %rl<8>;
+
+// %bb.0: // %entry
+ ld.param.u64 %rl2, [kernel_param_0];
+ mov.u32 %r3, %tid.x;
+ ld.param.u64 %rl3, [kernel_param_1];
+ mul.wide.s32 %rl4, %r3, 4;
+ add.s64 %rl5, %rl2, %rl4;
+ ld.param.u64 %rl6, [kernel_param_2];
+ add.s64 %rl7, %rl3, %rl4;
+ add.s64 %rl1, %rl6, %rl4;
+ ld.global.f32 %f1, [%rl5];
+ ld.global.f32 %f2, [%rl7];
+ setp.eq.f32 %p1, %f1, 0f3F800000;
+ setp.eq.f32 %p2, %f2, 0f00000000;
+ or.pred %p3, %p1, %p2;
+ @%p3 bra BB0_1;
+ bra.uni BB0_2;
+BB0_1:
+ mov.f32 %f110, 0f3F800000;
+ st.global.f32 [%rl1], %f110;
+ ret;
+BB0_2: // %__nv_isnanf.exit.i
+ abs.f32 %f4, %f1;
+ setp.gtu.f32 %p4, %f4, 0f7F800000;
+ @%p4 bra BB0_4;
+// %bb.3: // %__nv_isnanf.exit5.i
+ abs.f32 %f5, %f2;
+ setp.le.f32 %p5, %f5, 0f7F800000;
+ @%p5 bra BB0_5;
+BB0_4: // %.critedge1.i
+ add.f32 %f110, %f1, %f2;
+ st.global.f32 [%rl1], %f110;
+ ret;
+BB0_5: // %__nv_isinff.exit.i
+
+ ...
+
+BB0_26: // %__nv_truncf.exit.i.i.i.i.i
+ mul.f32 %f90, %f107, 0f3FB8AA3B;
+ cvt.rzi.f32.f32 %f91, %f90;
+ mov.f32 %f92, 0fBF317200;
+ fma.rn.f32 %f93, %f91, %f92, %f107;
+ mov.f32 %f94, 0fB5BFBE8E;
+ fma.rn.f32 %f95, %f91, %f94, %f93;
+ mul.f32 %f89, %f95, 0f3FB8AA3B;
+ // inline asm
+ ex2.approx.ftz.f32 %f88,%f89;
+ // inline asm
+ add.f32 %f96, %f91, 0f00000000;
+ ex2.approx.f32 %f97, %f96;
+ mul.f32 %f98, %f88, %f97;
+ setp.lt.f32 %p15, %f107, 0fC2D20000;
+ selp.f32 %f99, 0f00000000, %f98, %p15;
+ setp.gt.f32 %p16, %f107, 0f42D20000;
+ selp.f32 %f110, 0f7F800000, %f99, %p16;
+ setp.eq.f32 %p17, %f110, 0f7F800000;
+ @%p17 bra BB0_28;
+// %bb.27:
+ fma.rn.f32 %f110, %f110, %f108, %f110;
+BB0_28: // %__internal_accurate_powf.exit.i
+ setp.lt.f32 %p18, %f1, 0f00000000;
+ setp.eq.f32 %p19, %f3, 0f3F800000;
+ and.pred %p20, %p18, %p19;
+ @!%p20 bra BB0_30;
+ bra.uni BB0_29;
+BB0_29:
+ mov.b32 %r9, %f110;
+ xor.b32 %r10, %r9, -2147483648;
+ mov.b32 %f110, %r10;
+BB0_30: // %__nv_powf.exit
+ st.global.f32 [%rl1], %f110;
+ ret;
+}
+</pre></div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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="AMDGPUUsage.html" title="User Guide for AMDGPU Backend"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseAttributes.html" title="How To Use Attributes"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/OptBisect.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/OptBisect.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/OptBisect.html (added)
+++ www-releases/trunk/6.0.0/docs/OptBisect.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,267 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Using -opt-bisect-limit to debug optimization errors — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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 Alias Analysis Infrastructure" href="AliasAnalysis.html" />
+ <link rel="prev" title="Scudo Hardened Allocator" href="ScudoHardenedAllocator.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="AliasAnalysis.html" title="LLVM Alias Analysis Infrastructure"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ScudoHardenedAllocator.html" title="Scudo Hardened Allocator"
+ 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="using-opt-bisect-limit-to-debug-optimization-errors">
+<h1>Using -opt-bisect-limit to debug optimization errors<a class="headerlink" href="#using-opt-bisect-limit-to-debug-optimization-errors" 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="#getting-started" id="id2">Getting Started</a></li>
+<li><a class="reference internal" href="#bisection-index-values" id="id3">Bisection Index Values</a></li>
+<li><a class="reference internal" href="#example-usage" id="id4">Example Usage</a></li>
+<li><a class="reference internal" href="#pass-skipping-implementation" id="id5">Pass Skipping Implementation</a></li>
+<li><a class="reference internal" href="#adding-finer-granularity" id="id6">Adding Finer Granularity</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 -opt-bisect-limit option provides a way to disable all optimization passes
+above a specified limit without modifying the way in which the Pass Managers
+are populated. The intention of this option is to assist in tracking down
+problems where incorrect transformations during optimization result in incorrect
+run-time behavior.</p>
+<p>This feature is implemented on an opt-in basis. Passes which can be safely
+skipped while still allowing correct code generation call a function to
+check the opt-bisect limit before performing optimizations. Passes which
+either must be run or do not modify the IR do not perform this check and are
+therefore never skipped. Generally, this means analysis passes, passes
+that are run at CodeGenOpt::None and passes which are required for register
+allocation.</p>
+<p>The -opt-bisect-limit option can be used with any tool, including front ends
+such as clang, that uses the core LLVM library for optimization and code
+generation. The exact syntax for invoking the option is discussed below.</p>
+<p>This feature is not intended to replace other debugging tools such as bugpoint.
+Rather it provides an alternate course of action when reproducing the problem
+requires a complex build infrastructure that would make using bugpoint
+impractical or when reproducing the failure requires a sequence of
+transformations that is difficult to replicate with tools like opt and llc.</p>
+</div>
+<div class="section" id="getting-started">
+<h2><a class="toc-backref" href="#id2">Getting Started</a><a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h2>
+<p>The -opt-bisect-limit command line option can be passed directly to tools such
+as opt, llc and lli. The syntax is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">tool</span> <span class="n">name</span><span class="o">></span> <span class="p">[</span><span class="n">other</span> <span class="n">options</span><span class="p">]</span> <span class="o">-</span><span class="n">opt</span><span class="o">-</span><span class="n">bisect</span><span class="o">-</span><span class="n">limit</span><span class="o">=<</span><span class="n">limit</span><span class="o">></span>
+</pre></div>
+</div>
+<p>If a value of -1 is used the tool will perform all optimizations but a message
+will be printed to stderr for each optimization that could be skipped
+indicating the index value that is associated with that optimization. To skip
+optimizations, pass the value of the last optimization to be performed as the
+opt-bisect-limit. All optimizations with a higher index value will be skipped.</p>
+<p>In order to use the -opt-bisect-limit option with a driver that provides a
+wrapper around the LLVM core library, an additional prefix option may be
+required, as defined by the driver. For example, to use this option with
+clang, the “-mllvm” prefix must be used. A typical clang invocation would look
+like this:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">clang</span> <span class="o">-</span><span class="n">O2</span> <span class="o">-</span><span class="n">mllvm</span> <span class="o">-</span><span class="n">opt</span><span class="o">-</span><span class="n">bisect</span><span class="o">-</span><span class="n">limit</span><span class="o">=</span><span class="mi">256</span> <span class="n">my_file</span><span class="o">.</span><span class="n">c</span>
+</pre></div>
+</div>
+<p>The -opt-bisect-limit option may also be applied to link-time optimizations by
+using a prefix to indicate that this is a plug-in option for the linker. The
+following syntax will set a bisect limit for LTO transformations:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># When using lld, or ld64 (macOS)</span>
+<span class="n">clang</span> <span class="o">-</span><span class="n">flto</span> <span class="o">-</span><span class="n">Wl</span><span class="p">,</span><span class="o">-</span><span class="n">mllvm</span><span class="p">,</span><span class="o">-</span><span class="n">opt</span><span class="o">-</span><span class="n">bisect</span><span class="o">-</span><span class="n">limit</span><span class="o">=</span><span class="mi">256</span> <span class="n">my_file</span><span class="o">.</span><span class="n">o</span> <span class="n">my_other_file</span><span class="o">.</span><span class="n">o</span>
+<span class="c1"># When using Gold</span>
+<span class="n">clang</span> <span class="o">-</span><span class="n">flto</span> <span class="o">-</span><span class="n">Wl</span><span class="p">,</span><span class="o">-</span><span class="n">plugin</span><span class="o">-</span><span class="n">opt</span><span class="p">,</span><span class="o">-</span><span class="n">opt</span><span class="o">-</span><span class="n">bisect</span><span class="o">-</span><span class="n">limit</span><span class="o">=</span><span class="mi">256</span> <span class="n">my_file</span><span class="o">.</span><span class="n">o</span> <span class="n">my_other_file</span><span class="o">.</span><span class="n">o</span>
+</pre></div>
+</div>
+<p>LTO passes are run by a library instance invoked by the linker. Therefore any
+passes run in the primary driver compilation phase are not affected by options
+passed via ‘-Wl,-plugin-opt’ and LTO passes are not affected by options
+passed to the driver-invoked LLVM invocation via ‘-mllvm’.</p>
+</div>
+<div class="section" id="bisection-index-values">
+<h2><a class="toc-backref" href="#id3">Bisection Index Values</a><a class="headerlink" href="#bisection-index-values" title="Permalink to this headline">¶</a></h2>
+<p>The granularity of the optimizations associated with a single index value is
+variable. Depending on how the optimization pass has been instrumented the
+value may be associated with as much as all transformations that would have
+been performed by an optimization pass on an IR unit for which it is invoked
+(for instance, during a single call of runOnFunction for a FunctionPass) or as
+little as a single transformation. The index values may also be nested so that
+if an invocation of the pass is not skipped individual transformations within
+that invocation may still be skipped.</p>
+<p>The order of the values assigned is guaranteed to remain stable and consistent
+from one run to the next up to and including the value specified as the limit.
+Above the limit value skipping of optimizations can cause a change in the
+numbering, but because all optimizations above the limit are skipped this
+is not a problem.</p>
+<p>When an opt-bisect index value refers to an entire invocation of the run
+function for a pass, the pass will query whether or not it should be skipped
+each time it is invoked and each invocation will be assigned a unique value.
+For example, if a FunctionPass is used with a module containing three functions
+a different index value will be assigned to the pass for each of the functions
+as the pass is run. The pass may be run on two functions but skipped for the
+third.</p>
+<p>If the pass internally performs operations on a smaller IR unit the pass must be
+specifically instrumented to enable bisection at this finer level of granularity
+(see below for details).</p>
+</div>
+<div class="section" id="example-usage">
+<h2><a class="toc-backref" href="#id4">Example Usage</a><a class="headerlink" href="#example-usage" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-console"><div class="highlight"><pre><span></span><span class="gp">$</span> opt -O2 -o test-opt.bc -opt-bisect-limit<span class="o">=</span><span class="m">16</span> test.ll
+
+<span class="go">BISECT: running pass (1) Simplify the CFG on function (g)</span>
+<span class="go">BISECT: running pass (2) SROA on function (g)</span>
+<span class="go">BISECT: running pass (3) Early CSE on function (g)</span>
+<span class="go">BISECT: running pass (4) Infer set function attributes on module (test.ll)</span>
+<span class="go">BISECT: running pass (5) Interprocedural Sparse Conditional Constant Propagation on module (test.ll)</span>
+<span class="go">BISECT: running pass (6) Global Variable Optimizer on module (test.ll)</span>
+<span class="go">BISECT: running pass (7) Promote Memory to Register on function (g)</span>
+<span class="go">BISECT: running pass (8) Dead Argument Elimination on module (test.ll)</span>
+<span class="go">BISECT: running pass (9) Combine redundant instructions on function (g)</span>
+<span class="go">BISECT: running pass (10) Simplify the CFG on function (g)</span>
+<span class="go">BISECT: running pass (11) Remove unused exception handling info on SCC (<<null function>>)</span>
+<span class="go">BISECT: running pass (12) Function Integration/Inlining on SCC (<<null function>>)</span>
+<span class="go">BISECT: running pass (13) Deduce function attributes on SCC (<<null function>>)</span>
+<span class="go">BISECT: running pass (14) Remove unused exception handling info on SCC (f)</span>
+<span class="go">BISECT: running pass (15) Function Integration/Inlining on SCC (f)</span>
+<span class="go">BISECT: running pass (16) Deduce function attributes on SCC (f)</span>
+<span class="go">BISECT: NOT running pass (17) Remove unused exception handling info on SCC (g)</span>
+<span class="go">BISECT: NOT running pass (18) Function Integration/Inlining on SCC (g)</span>
+<span class="go">BISECT: NOT running pass (19) Deduce function attributes on SCC (g)</span>
+<span class="go">BISECT: NOT running pass (20) SROA on function (g)</span>
+<span class="go">BISECT: NOT running pass (21) Early CSE on function (g)</span>
+<span class="go">BISECT: NOT running pass (22) Speculatively execute instructions if target has divergent branches on function (g)</span>
+<span class="go">... etc. ...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="pass-skipping-implementation">
+<h2><a class="toc-backref" href="#id5">Pass Skipping Implementation</a><a class="headerlink" href="#pass-skipping-implementation" title="Permalink to this headline">¶</a></h2>
+<p>The -opt-bisect-limit implementation depends on individual passes opting in to
+the opt-bisect process. The OptBisect object that manages the process is
+entirely passive and has no knowledge of how any pass is implemented. When a
+pass is run if the pass may be skipped, it should call the OptBisect object to
+see if it should be skipped.</p>
+<p>The OptBisect object is intended to be accessed through LLVMContext and each
+Pass base class contains a helper function that abstracts the details in order
+to make this check uniform across all passes. These helper functions are:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="kt">bool</span> <span class="n">ModulePass</span><span class="o">::</span><span class="n">skipModule</span><span class="p">(</span><span class="n">Module</span> <span class="o">&</span><span class="n">M</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="n">CallGraphSCCPass</span><span class="o">::</span><span class="n">skipSCC</span><span class="p">(</span><span class="n">CallGraphSCC</span> <span class="o">&</span><span class="n">SCC</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="n">FunctionPass</span><span class="o">::</span><span class="n">skipFunction</span><span class="p">(</span><span class="k">const</span> <span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="n">BasicBlockPass</span><span class="o">::</span><span class="n">skipBasicBlock</span><span class="p">(</span><span class="k">const</span> <span class="n">BasicBlock</span> <span class="o">&</span><span class="n">BB</span><span class="p">);</span>
+<span class="kt">bool</span> <span class="n">LoopPass</span><span class="o">::</span><span class="n">skipLoop</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>
+</pre></div>
+</div>
+<p>A MachineFunctionPass should use FunctionPass::skipFunction() as such:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="kt">bool</span> <span class="n">MyMachineFunctionPass</span><span class="o">::</span><span class="n">runOnMachineFunction</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">MF</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">skipFunction</span><span class="p">(</span><span class="o">*</span><span class="n">MF</span><span class="p">.</span><span class="n">getFunction</span><span class="p">())</span>
+ <span class="k">return</span> <span class="nb">false</span><span class="p">;</span>
+ <span class="c1">// Otherwise, run the pass normally.</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In addition to checking with the OptBisect class to see if the pass should be
+skipped, the skipFunction(), skipLoop() and skipBasicBlock() helper functions
+also look for the presence of the “optnone” function attribute. The calling
+pass will be unable to determine whether it is being skipped because the
+“optnone” attribute is present or because the opt-bisect-limit has been
+reached. This is desirable because the behavior should be the same in either
+case.</p>
+<p>The majority of LLVM passes which can be skipped have already been instrumented
+in the manner described above. If you are adding a new pass or believe you
+have found a pass which is not being included in the opt-bisect process but
+should be, you can add it as described above.</p>
+</div>
+<div class="section" id="adding-finer-granularity">
+<h2><a class="toc-backref" href="#id6">Adding Finer Granularity</a><a class="headerlink" href="#adding-finer-granularity" title="Permalink to this headline">¶</a></h2>
+<p>Once the pass in which an incorrect transformation is performed has been
+determined, it may be useful to perform further analysis in order to determine
+which specific transformation is causing the problem. Debug counters
+can be used for this purpose.</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="AliasAnalysis.html" title="LLVM Alias Analysis Infrastructure"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ScudoHardenedAllocator.html" title="Scudo Hardened Allocator"
+ >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-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/CodeViewSymbols.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/CodeViewSymbols.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/CodeViewSymbols.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/CodeViewSymbols.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,102 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>CodeView Symbol Records — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="CodeView Type Records" href="CodeViewTypes.html" />
+ <link rel="prev" title="The TPI & IPI Hash Streams" href="HashStream.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="CodeViewTypes.html" title="CodeView Type Records"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HashStream.html" title="The TPI & IPI Hash Streams"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="codeview-symbol-records">
+<h1>CodeView Symbol Records<a class="headerlink" href="#codeview-symbol-records" title="Permalink to this headline">¶</a></h1>
+</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="CodeViewTypes.html" title="CodeView Type Records"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HashStream.html" title="The TPI & IPI Hash Streams"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/CodeViewTypes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/CodeViewTypes.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/CodeViewTypes.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/CodeViewTypes.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,102 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>CodeView Type Records — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="Control Flow Verification Tool Design Document" href="../CFIVerify.html" />
+ <link rel="prev" title="CodeView Symbol Records" href="CodeViewSymbols.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="../CFIVerify.html" title="Control Flow Verification Tool Design Document"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CodeViewSymbols.html" title="CodeView Symbol Records"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="codeview-type-records">
+<h1>CodeView Type Records<a class="headerlink" href="#codeview-type-records" title="Permalink to this headline">¶</a></h1>
+</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="../CFIVerify.html" title="Control Flow Verification Tool Design Document"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CodeViewSymbols.html" title="CodeView Symbol Records"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/DbiStream.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/DbiStream.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/DbiStream.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/DbiStream.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,479 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The PDB DBI (Debug Info) Stream — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="The Module Information Stream" href="ModiStream.html" />
+ <link rel="prev" title="The PDB TPI Stream" href="TpiStream.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="ModiStream.html" title="The Module Information Stream"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TpiStream.html" title="The PDB TPI Stream"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-pdb-dbi-debug-info-stream">
+<h1>The PDB DBI (Debug Info) Stream<a class="headerlink" href="#the-pdb-dbi-debug-info-stream" 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="#stream-header" id="id2">Stream Header</a></li>
+<li><a class="reference internal" href="#substreams" id="id3">Substreams</a><ul>
+<li><a class="reference internal" href="#module-info-substream" id="id4">Module Info Substream</a></li>
+<li><a class="reference internal" href="#section-contribution-substream" id="id5">Section Contribution Substream</a></li>
+<li><a class="reference internal" href="#section-map-substream" id="id6">Section Map Substream</a></li>
+<li><a class="reference internal" href="#file-info-substream" id="id7">File Info Substream</a></li>
+<li><a class="reference internal" href="#type-server-substream" id="id8">Type Server Substream</a></li>
+<li><a class="reference internal" href="#ec-substream" id="id9">EC Substream</a></li>
+<li><a class="reference internal" href="#optional-debug-header-stream" id="id10">Optional Debug Header Stream</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<span id="dbi-intro"></span><h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The PDB DBI Stream (Index 3) is one of the largest and most important streams
+in a PDB file. It contains information about how the program was compiled,
+(e.g. compilation flags, etc), the compilands (e.g. object files) that
+were used to link together the program, the source files which were used
+to build the program, as well as references to other streams that contain more
+detailed information about each compiland, such as the CodeView symbol records
+contained within each compiland and the source and line information for
+functions and other symbols within each compiland.</p>
+</div>
+<div class="section" id="stream-header">
+<span id="dbi-header"></span><h2><a class="toc-backref" href="#id2">Stream Header</a><a class="headerlink" href="#stream-header" title="Permalink to this headline">¶</a></h2>
+<p>At offset 0 of the DBI Stream is a header with the following layout:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">DbiStreamHeader</span> <span class="p">{</span>
+ <span class="kt">int32_t</span> <span class="n">VersionSignature</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">VersionHeader</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">Age</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">GlobalStreamIndex</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">BuildNumber</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">PublicStreamIndex</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">PdbDllVersion</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">SymRecordStream</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">PdbDllRbld</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">ModInfoSize</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">SectionContributionSize</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">SectionMapSize</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">SourceInfoSize</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">TypeServerSize</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">MFCTypeServerIndex</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">OptionalDbgHeaderSize</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">ECSubstreamSize</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">Flags</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">Machine</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">Padding</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><strong>VersionSignature</strong> - Unknown meaning. Appears to always be <code class="docutils literal"><span class="pre">-1</span></code>.</li>
+<li><strong>VersionHeader</strong> - A value from the following enum.</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="k">class</span> <span class="nc">DbiStreamVersion</span> <span class="o">:</span> <span class="kt">uint32_t</span> <span class="p">{</span>
+ <span class="n">VC41</span> <span class="o">=</span> <span class="mi">930803</span><span class="p">,</span>
+ <span class="n">V50</span> <span class="o">=</span> <span class="mi">19960307</span><span class="p">,</span>
+ <span class="n">V60</span> <span class="o">=</span> <span class="mi">19970606</span><span class="p">,</span>
+ <span class="n">V70</span> <span class="o">=</span> <span class="mi">19990903</span><span class="p">,</span>
+ <span class="n">V110</span> <span class="o">=</span> <span class="mi">20091201</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Similar to the <a class="reference internal" href="PdbStream.html"><span class="doc">PDB Stream</span></a>, this value always appears to be
+<code class="docutils literal"><span class="pre">V70</span></code>, and it is not clear what the other values are for.</p>
+<ul class="simple">
+<li><strong>Age</strong> - The number of times the PDB has been written. Equal to the same
+field from the <a class="reference internal" href="PdbStream.html#pdb-stream-header"><span class="std std-ref">PDB Stream header</span></a>.</li>
+<li><strong>GlobalStreamIndex</strong> - The index of the <a class="reference internal" href="GlobalStream.html"><span class="doc">Global Symbol Stream</span></a>,
+which contains CodeView symbol records for all global symbols. Actual records
+are stored in the symbol record stream, and are referenced from this stream.</li>
+<li><strong>BuildNumber</strong> - A bitfield containing values representing the major and minor
+version number of the toolchain (e.g. 12.0 for MSVC 2013) used to build the
+program, with the following layout:</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="kt">uint16_t</span> <span class="nl">MinorVersion</span> <span class="p">:</span> <span class="mi">8</span><span class="p">;</span>
+<span class="kt">uint16_t</span> <span class="nl">MajorVersion</span> <span class="p">:</span> <span class="mi">7</span><span class="p">;</span>
+<span class="kt">uint16_t</span> <span class="nl">NewVersionFormat</span> <span class="p">:</span> <span class="mi">1</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>For the purposes of LLVM, we assume <code class="docutils literal"><span class="pre">NewVersionFormat</span></code> to be always <code class="docutils literal"><span class="pre">true</span></code>.
+If it is <code class="docutils literal"><span class="pre">false</span></code>, the layout above does not apply and the reader should consult
+the <a class="reference external" href="https://github.com/Microsoft/microsoft-pdb">Microsoft Source Code</a> for
+further guidance.</p>
+<ul class="simple">
+<li><strong>PublicStreamIndex</strong> - The index of the <a class="reference internal" href="PublicStream.html"><span class="doc">Public Symbol Stream</span></a>,
+which contains CodeView symbol records for all public symbols. Actual records
+are stored in the symbol record stream, and are referenced from this stream.</li>
+<li><strong>PdbDllVersion</strong> - The version number of <code class="docutils literal"><span class="pre">mspdbXXXX.dll</span></code> used to produce this
+PDB. Note this obviously does not apply for LLVM as LLVM does not use <code class="docutils literal"><span class="pre">mspdb.dll</span></code>.</li>
+<li><strong>SymRecordStream</strong> - The stream containing all CodeView symbol records used
+by the program. This is used for deduplication, so that many different
+compilands can refer to the same symbols without having to include the full record
+content inside of each module stream.</li>
+<li><strong>PdbDllRbld</strong> - Unknown</li>
+<li><strong>MFCTypeServerIndex</strong> - The length of the :ref:dbi_mfc_type_server_substream</li>
+<li><strong>Flags</strong> - A bitfield with the following layout, containing various
+information about how the program was built:</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="kt">uint16_t</span> <span class="nl">WasIncrementallyLinked</span> <span class="p">:</span> <span class="mi">1</span><span class="p">;</span>
+<span class="kt">uint16_t</span> <span class="nl">ArePrivateSymbolsStripped</span> <span class="p">:</span> <span class="mi">1</span><span class="p">;</span>
+<span class="kt">uint16_t</span> <span class="nl">HasConflictingTypes</span> <span class="p">:</span> <span class="mi">1</span><span class="p">;</span>
+<span class="kt">uint16_t</span> <span class="nl">Reserved</span> <span class="p">:</span> <span class="mi">13</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>The only one of these that is not self-explanatory is <code class="docutils literal"><span class="pre">HasConflictingTypes</span></code>.
+Although undocumented, <code class="docutils literal"><span class="pre">link.exe</span></code> contains a hidden flag <code class="docutils literal"><span class="pre">/DEBUG:CTYPES</span></code>.
+If it is passed to <code class="docutils literal"><span class="pre">link.exe</span></code>, this field will be set. Otherwise it will
+not be set. It is unclear what this flag does, although it seems to have
+subtle implications on the algorithm used to look up type records.</p>
+<ul class="simple">
+<li><strong>Machine</strong> - A value from the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/b2fc64ek.aspx">CV_CPU_TYPE_e</a>
+enumeration. Common values are <code class="docutils literal"><span class="pre">0x8664</span></code> (x86-64) and <code class="docutils literal"><span class="pre">0x14C</span></code> (x86).</li>
+</ul>
+<p>Immediately after the fixed-size DBI Stream header are <code class="docutils literal"><span class="pre">7</span></code> variable-length
+<cite>substreams</cite>. The following <code class="docutils literal"><span class="pre">7</span></code> fields of the DBI Stream header specify the
+number of bytes of the corresponding substream. Each substream’s contents will
+be described in detail <a class="reference internal" href="#dbi-substreams"><span class="std std-ref">below</span></a>. The length of the entire
+DBI Stream should equal <code class="docutils literal"><span class="pre">64</span></code> (the length of the header above) plus the value
+of each of the following <code class="docutils literal"><span class="pre">7</span></code> fields.</p>
+<ul class="simple">
+<li><strong>ModInfoSize</strong> - The length of the <a class="reference internal" href="#dbi-mod-info-substream"><span class="std std-ref">Module Info Substream</span></a>.</li>
+<li><strong>SectionContributionSize</strong> - The length of the <a class="reference internal" href="#dbi-sec-contr-substream"><span class="std std-ref">Section Contribution Substream</span></a>.</li>
+<li><strong>SectionMapSize</strong> - The length of the <a class="reference internal" href="#dbi-section-map-substream"><span class="std std-ref">Section Map Substream</span></a>.</li>
+<li><strong>SourceInfoSize</strong> - The length of the <a class="reference internal" href="#dbi-file-info-substream"><span class="std std-ref">File Info Substream</span></a>.</li>
+<li><strong>TypeServerSize</strong> - The length of the <a class="reference internal" href="#dbi-type-server-substream"><span class="std std-ref">Type Server Substream</span></a>.</li>
+<li><strong>OptionalDbgHeaderSize</strong> - The length of the <a class="reference internal" href="#dbi-optional-dbg-stream"><span class="std std-ref">Optional Debug Header Stream</span></a>.</li>
+<li><strong>ECSubstreamSize</strong> - The length of the <a class="reference internal" href="#dbi-ec-substream"><span class="std std-ref">EC Substream</span></a>.</li>
+</ul>
+</div>
+<div class="section" id="substreams">
+<span id="dbi-substreams"></span><h2><a class="toc-backref" href="#id3">Substreams</a><a class="headerlink" href="#substreams" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="module-info-substream">
+<span id="dbi-mod-info-substream"></span><h3><a class="toc-backref" href="#id4">Module Info Substream</a><a class="headerlink" href="#module-info-substream" title="Permalink to this headline">¶</a></h3>
+<p>Begins at offset <code class="docutils literal"><span class="pre">0</span></code> immediately after the <a class="reference internal" href="#dbi-header"><span class="std std-ref">header</span></a>. The
+module info substream is an array of variable-length records, each one
+describing a single module (e.g. object file) linked into the program. Each
+record in the array has the format:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">SectionContribEntry</span> <span class="p">{</span>
+ <span class="kt">uint16_t</span> <span class="n">Section</span><span class="p">;</span>
+ <span class="kt">char</span> <span class="n">Padding1</span><span class="p">[</span><span class="mi">2</span><span class="p">];</span>
+ <span class="kt">int32_t</span> <span class="n">Offset</span><span class="p">;</span>
+ <span class="kt">int32_t</span> <span class="n">Size</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">Characteristics</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">ModuleIndex</span><span class="p">;</span>
+ <span class="kt">char</span> <span class="n">Padding2</span><span class="p">[</span><span class="mi">2</span><span class="p">];</span>
+ <span class="kt">uint32_t</span> <span class="n">DataCrc</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">RelocCrc</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>While most of these are self-explanatory, the <code class="docutils literal"><span class="pre">Characteristics</span></code> field
+warrants some elaboration. It corresponds to the <code class="docutils literal"><span class="pre">Characteristics</span></code>
+field of the <a class="reference external" href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms680341(v=vs.85).aspx">IMAGE_SECTION_HEADER</a>
+structure.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">ModInfo</span> <span class="p">{</span>
+ <span class="kt">uint32_t</span> <span class="n">Unused1</span><span class="p">;</span>
+ <span class="n">SectionContribEntry</span> <span class="n">SectionContr</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">Flags</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">ModuleSymStream</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">SymByteSize</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">C11ByteSize</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">C13ByteSize</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">SourceFileCount</span><span class="p">;</span>
+ <span class="kt">char</span> <span class="n">Padding</span><span class="p">[</span><span class="mi">2</span><span class="p">];</span>
+ <span class="kt">uint32_t</span> <span class="n">Unused2</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">SourceFileNameIndex</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">PdbFilePathNameIndex</span><span class="p">;</span>
+ <span class="kt">char</span> <span class="n">ModuleName</span><span class="p">[];</span>
+ <span class="kt">char</span> <span class="n">ObjFileName</span><span class="p">[];</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><strong>SectionContr</strong> - Describes the properties of the section in the final binary
+which contain the code and data from this module.</li>
+<li><strong>Flags</strong> - A bitfield with the following format:</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="kt">uint16_t</span> <span class="nl">Dirty</span> <span class="p">:</span> <span class="mi">1</span><span class="p">;</span> <span class="c1">// ``true`` if this ModInfo has been written since reading the PDB.</span>
+<span class="kt">uint16_t</span> <span class="nl">EC</span> <span class="p">:</span> <span class="mi">1</span><span class="p">;</span> <span class="c1">// ``true`` if EC information is present for this module. It is unknown what EC actually is.</span>
+<span class="kt">uint16_t</span> <span class="nl">Unused</span> <span class="p">:</span> <span class="mi">6</span><span class="p">;</span>
+<span class="kt">uint16_t</span> <span class="nl">TSM</span> <span class="p">:</span> <span class="mi">8</span><span class="p">;</span> <span class="c1">// Type Server Index for this module. It is unknown what this is used for, but it is not used by LLVM.</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><strong>ModuleSymStream</strong> - The index of the stream that contains symbol information
+for this module. This includes CodeView symbol information as well as source
+and line information.</li>
+<li><strong>SymByteSize</strong> - The number of bytes of data from the stream identified by
+<code class="docutils literal"><span class="pre">ModuleSymStream</span></code> that represent CodeView symbol records.</li>
+<li><strong>C11ByteSize</strong> - The number of bytes of data from the stream identified by
+<code class="docutils literal"><span class="pre">ModuleSymStream</span></code> that represent C11-style CodeView line information.</li>
+<li><strong>C13ByteSize</strong> - The number of bytes of data from the stream identified by
+<code class="docutils literal"><span class="pre">ModuleSymStream</span></code> that represent C13-style CodeView line information. At
+most one of <code class="docutils literal"><span class="pre">C11ByteSize</span></code> and <code class="docutils literal"><span class="pre">C13ByteSize</span></code> will be non-zero.</li>
+<li><strong>SourceFileCount</strong> - The number of source files that contributed to this
+module during compilation.</li>
+<li><strong>SourceFileNameIndex</strong> - The offset in the names buffer of the primary
+translation unit used to build this module. All PDB files observed to date
+always have this value equal to 0.</li>
+<li><strong>PdbFilePathNameIndex</strong> - The offset in the names buffer of the PDB file
+containing this module’s symbol information. This has only been observed
+to be non-zero for the special <code class="docutils literal"><span class="pre">*</span> <span class="pre">Linker</span> <span class="pre">*</span></code> module.</li>
+<li><strong>ModuleName</strong> - The module name. This is usually either a full path to an
+object file (either directly passed to <code class="docutils literal"><span class="pre">link.exe</span></code> or from an archive) or
+a string of the form <code class="docutils literal"><span class="pre">Import:<dll</span> <span class="pre">name></span></code>.</li>
+<li><strong>ObjFileName</strong> - The object file name. In the case of an module that is
+linked directly passed to <code class="docutils literal"><span class="pre">link.exe</span></code>, this is the same as <strong>ModuleName</strong>.
+In the case of a module that comes from an archive, this is usually the full
+path to the archive.</li>
+</ul>
+</div>
+<div class="section" id="section-contribution-substream">
+<span id="dbi-sec-contr-substream"></span><h3><a class="toc-backref" href="#id5">Section Contribution Substream</a><a class="headerlink" href="#section-contribution-substream" title="Permalink to this headline">¶</a></h3>
+<p>Begins at offset <code class="docutils literal"><span class="pre">0</span></code> immediately after the <a class="reference internal" href="#dbi-mod-info-substream"><span class="std std-ref">Module Info Substream</span></a> ends,
+and consumes <code class="docutils literal"><span class="pre">Header->SectionContributionSize</span></code> bytes. This substream begins
+with a single <code class="docutils literal"><span class="pre">uint32_t</span></code> which will be one of the following values:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="k">class</span> <span class="nc">SectionContrSubstreamVersion</span> <span class="o">:</span> <span class="kt">uint32_t</span> <span class="p">{</span>
+ <span class="n">Ver60</span> <span class="o">=</span> <span class="mh">0xeffe0000</span> <span class="o">+</span> <span class="mi">19970605</span><span class="p">,</span>
+ <span class="n">V2</span> <span class="o">=</span> <span class="mh">0xeffe0000</span> <span class="o">+</span> <span class="mi">20140516</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p><code class="docutils literal"><span class="pre">Ver60</span></code> is the only value which has been observed in a PDB so far. Following
+this <code class="docutils literal"><span class="pre">4</span></code> byte field is an array of fixed-length structures. If the version
+is <code class="docutils literal"><span class="pre">Ver60</span></code>, it is an array of <code class="docutils literal"><span class="pre">SectionContribEntry</span></code> structures. If the
+version is <code class="docutils literal"><span class="pre">V2</span></code>, it is an array of <code class="docutils literal"><span class="pre">SectionContribEntry2</span></code> structures,
+defined as follows:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">SectionContribEntry2</span> <span class="p">{</span>
+ <span class="n">SectionContribEntry</span> <span class="n">SC</span><span class="p">;</span>
+ <span class="kt">uint32_t</span> <span class="n">ISectCoff</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>The purpose of the second field is not well understood.</p>
+</div>
+<div class="section" id="section-map-substream">
+<span id="dbi-section-map-substream"></span><h3><a class="toc-backref" href="#id6">Section Map Substream</a><a class="headerlink" href="#section-map-substream" title="Permalink to this headline">¶</a></h3>
+<p>Begins at offset <code class="docutils literal"><span class="pre">0</span></code> immediately after the <a class="reference internal" href="#dbi-sec-contr-substream"><span class="std std-ref">Section Contribution Substream</span></a> ends,
+and consumes <code class="docutils literal"><span class="pre">Header->SectionMapSize</span></code> bytes. This substream begins with an <code class="docutils literal"><span class="pre">8</span></code>
+byte header followed by an array of fixed-length records. The header and records
+have the following layout:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">SectionMapHeader</span> <span class="p">{</span>
+ <span class="kt">uint16_t</span> <span class="n">Count</span><span class="p">;</span> <span class="c1">// Number of segment descriptors</span>
+ <span class="kt">uint16_t</span> <span class="n">LogCount</span><span class="p">;</span> <span class="c1">// Number of logical segment descriptors</span>
+<span class="p">};</span>
+
+<span class="k">struct</span> <span class="n">SectionMapEntry</span> <span class="p">{</span>
+ <span class="kt">uint16_t</span> <span class="n">Flags</span><span class="p">;</span> <span class="c1">// See the SectionMapEntryFlags enum below.</span>
+ <span class="kt">uint16_t</span> <span class="n">Ovl</span><span class="p">;</span> <span class="c1">// Logical overlay number</span>
+ <span class="kt">uint16_t</span> <span class="n">Group</span><span class="p">;</span> <span class="c1">// Group index into descriptor array.</span>
+ <span class="kt">uint16_t</span> <span class="n">Frame</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">SectionName</span><span class="p">;</span> <span class="c1">// Byte index of segment / group name in string table, or 0xFFFF.</span>
+ <span class="kt">uint16_t</span> <span class="n">ClassName</span><span class="p">;</span> <span class="c1">// Byte index of class in string table, or 0xFFFF.</span>
+ <span class="kt">uint32_t</span> <span class="n">Offset</span><span class="p">;</span> <span class="c1">// Byte offset of the logical segment within physical segment. If group is set in flags, this is the offset of the group.</span>
+ <span class="kt">uint32_t</span> <span class="n">SectionLength</span><span class="p">;</span> <span class="c1">// Byte count of the segment or group.</span>
+<span class="p">};</span>
+
+<span class="k">enum</span> <span class="k">class</span> <span class="nc">SectionMapEntryFlags</span> <span class="o">:</span> <span class="kt">uint16_t</span> <span class="p">{</span>
+ <span class="n">Read</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">0</span><span class="p">,</span> <span class="c1">// Segment is readable.</span>
+ <span class="n">Write</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">1</span><span class="p">,</span> <span class="c1">// Segment is writable.</span>
+ <span class="n">Execute</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">2</span><span class="p">,</span> <span class="c1">// Segment is executable.</span>
+ <span class="n">AddressIs32Bit</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">3</span><span class="p">,</span> <span class="c1">// Descriptor describes a 32-bit linear address.</span>
+ <span class="n">IsSelector</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">8</span><span class="p">,</span> <span class="c1">// Frame represents a selector.</span>
+ <span class="n">IsAbsoluteAddress</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">9</span><span class="p">,</span> <span class="c1">// Frame represents an absolute address.</span>
+ <span class="n">IsGroup</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="mi">10</span> <span class="c1">// If set, descriptor represents a group.</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Many of these fields are not well understood, so will not be discussed further.</p>
+</div>
+<div class="section" id="file-info-substream">
+<span id="dbi-file-info-substream"></span><h3><a class="toc-backref" href="#id7">File Info Substream</a><a class="headerlink" href="#file-info-substream" title="Permalink to this headline">¶</a></h3>
+<p>Begins at offset <code class="docutils literal"><span class="pre">0</span></code> immediately after the <a class="reference internal" href="#dbi-section-map-substream"><span class="std std-ref">Section Map Substream</span></a> ends,
+and consumes <code class="docutils literal"><span class="pre">Header->SourceInfoSize</span></code> bytes. This substream defines the mapping
+from module to the source files that contribute to that module. Since multiple
+modules can use the same source file (for example, a header file), this substream
+uses a string table to store each unique file name only once, and then have each
+module use offsets into the string table rather than embedding the string’s value
+directly. The format of this substream is as follows:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">FileInfoSubstream</span> <span class="p">{</span>
+ <span class="kt">uint16_t</span> <span class="n">NumModules</span><span class="p">;</span>
+ <span class="kt">uint16_t</span> <span class="n">NumSourceFiles</span><span class="p">;</span>
+
+ <span class="kt">uint16_t</span> <span class="n">ModIndices</span><span class="p">[</span><span class="n">NumModules</span><span class="p">];</span>
+ <span class="kt">uint16_t</span> <span class="n">ModFileCounts</span><span class="p">[</span><span class="n">NumModules</span><span class="p">];</span>
+ <span class="kt">uint32_t</span> <span class="n">FileNameOffsets</span><span class="p">[</span><span class="n">NumSourceFiles</span><span class="p">];</span>
+ <span class="kt">char</span> <span class="n">NamesBuffer</span><span class="p">[][</span><span class="n">NumSourceFiles</span><span class="p">];</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p><strong>NumModules</strong> - The number of modules for which source file information is
+contained within this substream. Should match the corresponding value from the
+ref:<cite>dbi_header</cite>.</p>
+<p><strong>NumSourceFiles</strong>: In theory this is supposed to contain the number of source
+files for which this substream contains information. But that would present a
+problem in that the width of this field being <code class="docutils literal"><span class="pre">16</span></code>-bits would prevent one from
+having more than 64K source files in a program. In early versions of the file
+format, this seems to have been the case. In order to support more than this, this
+field of the is simply ignored, and computed dynamically by summing up the values of
+the <code class="docutils literal"><span class="pre">ModFileCounts</span></code> array (discussed below). In short, this value should be
+ignored.</p>
+<p><strong>ModIndices</strong> - This array is present, but does not appear to be useful.</p>
+<p><strong>ModFileCountArray</strong> - An array of <code class="docutils literal"><span class="pre">NumModules</span></code> integers, each one containing
+the number of source files which contribute to the module at the specified index.
+While each individual module is limited to 64K contributing source files, the
+union of all modules’ source files may be greater than 64K. The real number of
+source files is thus computed by summing this array. Note that summing this array
+does not give the number of <cite>unique</cite> source files, only the total number of source
+file contributions to modules.</p>
+<p><strong>FileNameOffsets</strong> - An array of <strong>NumSourceFiles</strong> integers (where <strong>NumSourceFiles</strong>
+here refers to the 32-bit value obtained from summing <strong>ModFileCountArray</strong>), where
+each integer is an offset into <strong>NamesBuffer</strong> pointing to a null terminated string.</p>
+<p><strong>NamesBuffer</strong> - An array of null terminated strings containing the actual source
+file names.</p>
+</div>
+<div class="section" id="type-server-substream">
+<span id="dbi-type-server-substream"></span><h3><a class="toc-backref" href="#id8">Type Server Substream</a><a class="headerlink" href="#type-server-substream" title="Permalink to this headline">¶</a></h3>
+<p>Begins at offset <code class="docutils literal"><span class="pre">0</span></code> immediately after the <a class="reference internal" href="#dbi-file-info-substream"><span class="std std-ref">File Info Substream</span></a> ends,
+and consumes <code class="docutils literal"><span class="pre">Header->TypeServerSize</span></code> bytes. Neither the purpose nor the layout
+of this substream is understood, although it is assumed to related somehow to the
+usage of <code class="docutils literal"><span class="pre">/Zi</span></code> and <code class="docutils literal"><span class="pre">mspdbsrv.exe</span></code>. This substream will not be discussed further.</p>
+</div>
+<div class="section" id="ec-substream">
+<span id="dbi-ec-substream"></span><h3><a class="toc-backref" href="#id9">EC Substream</a><a class="headerlink" href="#ec-substream" title="Permalink to this headline">¶</a></h3>
+<p>Begins at offset <code class="docutils literal"><span class="pre">0</span></code> immediately after the <a class="reference internal" href="#dbi-type-server-substream"><span class="std std-ref">Type Server Substream</span></a> ends,
+and consumes <code class="docutils literal"><span class="pre">Header->ECSubstreamSize</span></code> bytes. Neither the purpose nor the layout
+of this substream is understood, and it will not be discussed further.</p>
+</div>
+<div class="section" id="optional-debug-header-stream">
+<span id="dbi-optional-dbg-stream"></span><h3><a class="toc-backref" href="#id10">Optional Debug Header Stream</a><a class="headerlink" href="#optional-debug-header-stream" title="Permalink to this headline">¶</a></h3>
+<p>Begins at offset <code class="docutils literal"><span class="pre">0</span></code> immediately after the <a class="reference internal" href="#dbi-ec-substream"><span class="std std-ref">EC Substream</span></a> ends, and
+consumes <code class="docutils literal"><span class="pre">Header->OptionalDbgHeaderSize</span></code> bytes. This field is an array of
+stream indices (e.g. <code class="docutils literal"><span class="pre">uint16_t</span></code>‘s), each of which identifies a stream
+index in the larger MSF file which contains some additional debug information.
+Each position of this array has a special meaning, allowing one to determine
+what kind of debug information is at the referenced stream. <code class="docutils literal"><span class="pre">11</span></code> indices
+are currently understood, although it’s possible there may be more. The
+layout of each stream generally corresponds exactly to a particular type
+of debug data directory from the PE/COFF file. The format of these fields
+can be found in the <a class="reference external" href="https://www.microsoft.com/en-us/download/details.aspx?id=19509">Microsoft PE/COFF Specification</a>.</p>
+<p><strong>FPO Data</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[0]</span></code>. The data in the referenced stream is a
+debug data directory of type <code class="docutils literal"><span class="pre">IMAGE_DEBUG_TYPE_FPO</span></code></p>
+<p><strong>Exception Data</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[1]</span></code>. The data in the referenced stream
+is a debug data directory of type <code class="docutils literal"><span class="pre">IMAGE_DEBUG_TYPE_EXCEPTION</span></code>.</p>
+<p><strong>Fixup Data</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[2]</span></code>. The data in the referenced stream is a
+debug data directory of type <code class="docutils literal"><span class="pre">IMAGE_DEBUG_TYPE_FIXUP</span></code>.</p>
+<p><strong>Omap To Src Data</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[3]</span></code>. The data in the referenced stream
+is a debug data directory of type <code class="docutils literal"><span class="pre">IMAGE_DEBUG_TYPE_OMAP_TO_SRC</span></code>. This
+is used for mapping addresses between instrumented and uninstrumented code.</p>
+<p><strong>Omap From Src Data</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[4]</span></code>. The data in the referenced stream
+is a debug data directory of type <code class="docutils literal"><span class="pre">IMAGE_DEBUG_TYPE_OMAP_FROM_SRC</span></code>. This
+is used for mapping addresses between instrumented and uninstrumented code.</p>
+<p><strong>Section Header Data</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[5]</span></code>. A dump of all section headers from
+the original executable.</p>
+<p><strong>Token / RID Map</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[6]</span></code>. The layout of this stream is not
+understood, but it is assumed to be a mapping from <code class="docutils literal"><span class="pre">CLR</span> <span class="pre">Token</span></code> to
+<code class="docutils literal"><span class="pre">CLR</span> <span class="pre">Record</span> <span class="pre">ID</span></code>. Refer to <a class="reference external" href="http://www.ecma-international.org/publications/standards/Ecma-335.htm">ECMA 335</a>
+for more information.</p>
+<p><strong>Xdata</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[7]</span></code>. A copy of the <code class="docutils literal"><span class="pre">.xdata</span></code> section from the
+executable.</p>
+<p><strong>Pdata</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[8]</span></code>. This is assumed to be a copy of the <code class="docutils literal"><span class="pre">.pdata</span></code>
+section from the executable, but that would make it identical to
+<code class="docutils literal"><span class="pre">DbgStreamArray[1]</span></code>. The difference between these two indices is not well
+understood.</p>
+<p><strong>New FPO Data</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[9]</span></code>. The data in the referenced stream is a
+debug data directory of type <code class="docutils literal"><span class="pre">IMAGE_DEBUG_TYPE_FPO</span></code>. It is not clear how this
+differs from <code class="docutils literal"><span class="pre">DbgStreamArray[0]</span></code>, but in practice all observed PDB files have
+used the “new” format rather than the “old” format.</p>
+<p><strong>Original Section Header Data</strong> - <code class="docutils literal"><span class="pre">DbgStreamArray[10]</span></code>. Assumed to be similar
+to <code class="docutils literal"><span class="pre">DbgStreamArray[5]</span></code>, but has not been observed in practice.</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="ModiStream.html" title="The Module Information Stream"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TpiStream.html" title="The PDB TPI Stream"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/GlobalStream.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/GlobalStream.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/GlobalStream.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/GlobalStream.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,102 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The PDB Global Symbol Stream — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="The TPI & IPI Hash Streams" href="HashStream.html" />
+ <link rel="prev" title="The PDB Public Symbol Stream" href="PublicStream.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="HashStream.html" title="The TPI & IPI Hash Streams"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="PublicStream.html" title="The PDB Public Symbol Stream"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-pdb-global-symbol-stream">
+<h1>The PDB Global Symbol Stream<a class="headerlink" href="#the-pdb-global-symbol-stream" title="Permalink to this headline">¶</a></h1>
+</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="HashStream.html" title="The TPI & IPI Hash Streams"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="PublicStream.html" title="The PDB Public Symbol Stream"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/HashStream.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/HashStream.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/HashStream.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/HashStream.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,102 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The TPI & IPI Hash Streams — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="CodeView Symbol Records" href="CodeViewSymbols.html" />
+ <link rel="prev" title="The PDB Global Symbol Stream" href="GlobalStream.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="CodeViewSymbols.html" title="CodeView Symbol Records"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GlobalStream.html" title="The PDB Global Symbol Stream"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-tpi-ipi-hash-streams">
+<h1>The TPI & IPI Hash Streams<a class="headerlink" href="#the-tpi-ipi-hash-streams" title="Permalink to this headline">¶</a></h1>
+</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="CodeViewSymbols.html" title="CodeView Symbol Records"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GlobalStream.html" title="The PDB Global Symbol Stream"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/ModiStream.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/ModiStream.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/ModiStream.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/ModiStream.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,169 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The Module Information Stream — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="The PDB Public Symbol Stream" href="PublicStream.html" />
+ <link rel="prev" title="The PDB DBI (Debug Info) Stream" href="DbiStream.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="PublicStream.html" title="The PDB Public Symbol Stream"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="DbiStream.html" title="The PDB DBI (Debug Info) Stream"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-module-information-stream">
+<h1>The Module Information Stream<a class="headerlink" href="#the-module-information-stream" 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="#stream-layout" id="id2">Stream Layout</a></li>
+<li><a class="reference internal" href="#the-codeview-symbol-substream" id="id3">The CodeView Symbol Substream</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<span id="modi-stream-intro"></span><h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The Module Info Stream (henceforth referred to as the Modi stream) contains
+information about a single module (object file, import library, etc that
+contributes to the binary this PDB contains debug information about. There
+is one modi stream for each module, and the mapping between modi stream index
+and module is contained in the <a class="reference internal" href="DbiStream.html"><span class="doc">DBI Stream</span></a>. The modi stream
+for a single module contains line information for the compiland, as well as
+all CodeView information for the symbols defined in the compiland. Finally,
+there is a “global refs” substream which is not well understood.</p>
+</div>
+<div class="section" id="stream-layout">
+<span id="modi-stream-layout"></span><h2><a class="toc-backref" href="#id2">Stream Layout</a><a class="headerlink" href="#stream-layout" title="Permalink to this headline">¶</a></h2>
+<p>A modi stream is laid out as follows:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">ModiStream</span> <span class="p">{</span>
+ <span class="kt">uint32_t</span> <span class="n">Signature</span><span class="p">;</span>
+ <span class="kt">uint8_t</span> <span class="n">Symbols</span><span class="p">[</span><span class="n">SymbolSize</span><span class="o">-</span><span class="mi">4</span><span class="p">];</span>
+ <span class="kt">uint8_t</span> <span class="n">C11LineInfo</span><span class="p">[</span><span class="n">C11Size</span><span class="p">];</span>
+ <span class="kt">uint8_t</span> <span class="n">C13LineInfo</span><span class="p">[</span><span class="n">C13Size</span><span class="p">];</span>
+
+ <span class="kt">uint32_t</span> <span class="n">GlobalRefsSize</span><span class="p">;</span>
+ <span class="kt">uint8_t</span> <span class="n">GlobalRefs</span><span class="p">[</span><span class="n">GlobalRefsSize</span><span class="p">];</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><strong>Signature</strong> - Unknown. In practice only the value of <code class="docutils literal"><span class="pre">4</span></code> has been
+observed. It is hypothesized that this value corresponds to the set of
+<code class="docutils literal"><span class="pre">CV_SIGNATURE_xx</span></code> defines in <code class="docutils literal"><span class="pre">cvinfo.h</span></code>, with the value of <code class="docutils literal"><span class="pre">4</span></code>
+meaning that this module has C13 line information (as opposed to C11 line
+information). A corollary of this is that we expect to only ever see
+C13 line info, and that we do not understand the format of C11 line info.</li>
+<li><strong>Symbols</strong> - The <a class="reference internal" href="#modi-symbol-substream"><span class="std std-ref">CodeView Symbol Substream</span></a>.
+<code class="docutils literal"><span class="pre">SymbolSize</span></code> is equal to the value of <code class="docutils literal"><span class="pre">SymByteSize</span></code> for the
+corresponding module’s entry in the <a class="reference internal" href="DbiStream.html#dbi-mod-info-substream"><span class="std std-ref">Module Info Substream</span></a>
+of the <a class="reference internal" href="DbiStream.html"><span class="doc">DBI Stream</span></a>.</li>
+<li><strong>C11LineInfo</strong> - A block containing CodeView line information in C11
+format. <code class="docutils literal"><span class="pre">C11Size</span></code> is equal to the value of <code class="docutils literal"><span class="pre">C11ByteSize</span></code> from the
+<a class="reference internal" href="DbiStream.html#dbi-mod-info-substream"><span class="std std-ref">Module Info Substream</span></a> of the
+<a class="reference internal" href="DbiStream.html"><span class="doc">DBI Stream</span></a>. If this value is <code class="docutils literal"><span class="pre">0</span></code>, then C11 line
+information is not present. As mentioned previously, the format of
+C11 line info is not understood and we assume all line in modern PDBs
+to be in C13 format.</li>
+<li><strong>C13LineInfo</strong> - A block containing CodeView line information in C13
+format. <code class="docutils literal"><span class="pre">C13Size</span></code> is equal to the value of <code class="docutils literal"><span class="pre">C13ByteSize</span></code> from the
+<a class="reference internal" href="DbiStream.html#dbi-mod-info-substream"><span class="std std-ref">Module Info Substream</span></a> of the
+<a class="reference internal" href="DbiStream.html"><span class="doc">DBI Stream</span></a>. If this value is <code class="docutils literal"><span class="pre">0</span></code>, then C13 line
+information is not present.</li>
+<li><strong>GlobalRefs</strong> - The meaning of this substream is not understood.</li>
+</ul>
+</div>
+<div class="section" id="the-codeview-symbol-substream">
+<span id="modi-symbol-substream"></span><h2><a class="toc-backref" href="#id3">The CodeView Symbol Substream</a><a class="headerlink" href="#the-codeview-symbol-substream" title="Permalink to this headline">¶</a></h2>
+<p>The CodeView Symbol Substream. This is an array of variable length
+records describing the functions, variables, inlining information,
+and other symbols defined in the compiland. The entire array consumes
+<code class="docutils literal"><span class="pre">SymbolSize-4</span></code> bytes. The format of a CodeView Symbol Record (and
+thusly, an array of CodeView Symbol Records) is described in
+<a class="reference internal" href="CodeViewSymbols.html"><span class="doc">CodeView Symbol Records</span></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="PublicStream.html" title="The PDB Public Symbol Stream"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="DbiStream.html" title="The PDB DBI (Debug Info) Stream"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/MsfFile.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/MsfFile.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/MsfFile.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/MsfFile.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,211 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The MSF File Format — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="The PDB Info Stream (aka the PDB Stream)" href="PdbStream.html" />
+ <link rel="prev" title="The PDB File Format" href="index.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="PdbStream.html" title="The PDB Info Stream (aka the PDB Stream)"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="The PDB File Format"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-msf-file-format">
+<h1>The MSF File Format<a class="headerlink" href="#the-msf-file-format" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#the-superblock" id="id1">The Superblock</a></li>
+<li><a class="reference internal" href="#the-stream-directory" id="id2">The Stream Directory</a></li>
+<li><a class="reference internal" href="#alignment-and-block-boundaries" id="id3">Alignment and Block Boundaries</a></li>
+</ul>
+</div>
+<div class="section" id="the-superblock">
+<span id="msf-superblock"></span><h2><a class="toc-backref" href="#id1">The Superblock</a><a class="headerlink" href="#the-superblock" title="Permalink to this headline">¶</a></h2>
+<p>At file offset 0 in an MSF file is the MSF <em>SuperBlock</em>, which is laid out as
+follows:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">SuperBlock</span> <span class="p">{</span>
+ <span class="kt">char</span> <span class="n">FileMagic</span><span class="p">[</span><span class="k">sizeof</span><span class="p">(</span><span class="n">Magic</span><span class="p">)];</span>
+ <span class="n">ulittle32_t</span> <span class="n">BlockSize</span><span class="p">;</span>
+ <span class="n">ulittle32_t</span> <span class="n">FreeBlockMapBlock</span><span class="p">;</span>
+ <span class="n">ulittle32_t</span> <span class="n">NumBlocks</span><span class="p">;</span>
+ <span class="n">ulittle32_t</span> <span class="n">NumDirectoryBytes</span><span class="p">;</span>
+ <span class="n">ulittle32_t</span> <span class="n">Unknown</span><span class="p">;</span>
+ <span class="n">ulittle32_t</span> <span class="n">BlockMapAddr</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><strong>FileMagic</strong> - Must be equal to <code class="docutils literal"><span class="pre">"Microsoft</span> <span class="pre">C</span> <span class="pre">/</span> <span class="pre">C++</span> <span class="pre">MSF</span> <span class="pre">7.00\\r\\n"</span></code>
+followed by the bytes <code class="docutils literal"><span class="pre">1A</span> <span class="pre">44</span> <span class="pre">53</span> <span class="pre">00</span> <span class="pre">00</span> <span class="pre">00</span></code>.</li>
+<li><strong>BlockSize</strong> - The block size of the internal file system. Valid values are
+512, 1024, 2048, and 4096 bytes. Certain aspects of the MSF file layout vary
+depending on the block sizes. For the purposes of LLVM, we handle only block
+sizes of 4KiB, and all further discussion assumes a block size of 4KiB.</li>
+<li><strong>FreeBlockMapBlock</strong> - The index of a block within the file, at which begins
+a bitfield representing the set of all blocks within the file which are “free”
+(i.e. the data within that block is not used). This bitfield is spread across
+the MSF file at <code class="docutils literal"><span class="pre">BlockSize</span></code> intervals.
+<strong>Important</strong>: <code class="docutils literal"><span class="pre">FreeBlockMapBlock</span></code> can only be <code class="docutils literal"><span class="pre">1</span></code> or <code class="docutils literal"><span class="pre">2</span></code>! This field
+is designed to support incremental and atomic updates of the underlying MSF
+file. While writing to an MSF file, if the value of this field is <cite>1</cite>, you
+can write your new modified bitfield to page 2, and vice versa. Only when
+you commit the file to disk do you need to swap the value in the SuperBlock
+to point to the new <code class="docutils literal"><span class="pre">FreeBlockMapBlock</span></code>.</li>
+<li><strong>NumBlocks</strong> - The total number of blocks in the file. <code class="docutils literal"><span class="pre">NumBlocks</span> <span class="pre">*</span> <span class="pre">BlockSize</span></code>
+should equal the size of the file on disk.</li>
+<li><strong>NumDirectoryBytes</strong> - The size of the stream directory, in bytes. The stream
+directory contains information about each stream’s size and the set of blocks
+that it occupies. It will be described in more detail later.</li>
+<li><strong>BlockMapAddr</strong> - The index of a block within the MSF file. At this block is
+an array of <code class="docutils literal"><span class="pre">ulittle32_t</span></code>‘s listing the blocks that the stream directory
+resides on. For large MSF files, the stream directory (which describes the
+block layout of each stream) may not fit entirely on a single block. As a
+result, this extra layer of indirection is introduced, whereby this block
+contains the list of blocks that the stream directory occupies, and the stream
+directory itself can be stitched together accordingly. The number of
+<code class="docutils literal"><span class="pre">ulittle32_t</span></code>‘s in this array is given by <code class="docutils literal"><span class="pre">ceil(NumDirectoryBytes</span> <span class="pre">/</span> <span class="pre">BlockSize)</span></code>.</li>
+</ul>
+</div>
+<div class="section" id="the-stream-directory">
+<h2><a class="toc-backref" href="#id2">The Stream Directory</a><a class="headerlink" href="#the-stream-directory" title="Permalink to this headline">¶</a></h2>
+<p>The Stream Directory is the root of all access to the other streams in an MSF
+file. Beginning at byte 0 of the stream directory is the following structure:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">StreamDirectory</span> <span class="p">{</span>
+ <span class="n">ulittle32_t</span> <span class="n">NumStreams</span><span class="p">;</span>
+ <span class="n">ulittle32_t</span> <span class="n">StreamSizes</span><span class="p">[</span><span class="n">NumStreams</span><span class="p">];</span>
+ <span class="n">ulittle32_t</span> <span class="n">StreamBlocks</span><span class="p">[</span><span class="n">NumStreams</span><span class="p">][];</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>And this structure occupies exactly <code class="docutils literal"><span class="pre">SuperBlock->NumDirectoryBytes</span></code> bytes.
+Note that each of the last two arrays is of variable length, and in particular
+that the second array is jagged.</p>
+<p><strong>Example:</strong> Suppose a hypothetical PDB file with a 4KiB block size, and 4
+streams of lengths {1000 bytes, 8000 bytes, 16000 bytes, 9000 bytes}.</p>
+<p>Stream 0: ceil(1000 / 4096) = 1 block</p>
+<p>Stream 1: ceil(8000 / 4096) = 2 blocks</p>
+<p>Stream 2: ceil(16000 / 4096) = 4 blocks</p>
+<p>Stream 3: ceil(9000 / 4096) = 3 blocks</p>
+<p>In total, 10 blocks are used. Let’s see what the stream directory might look
+like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">StreamDirectory</span> <span class="p">{</span>
+ <span class="n">ulittle32_t</span> <span class="n">NumStreams</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span>
+ <span class="n">ulittle32_t</span> <span class="n">StreamSizes</span><span class="p">[]</span> <span class="o">=</span> <span class="p">{</span><span class="mi">1000</span><span class="p">,</span> <span class="mi">8000</span><span class="p">,</span> <span class="mi">16000</span><span class="p">,</span> <span class="mi">9000</span><span class="p">};</span>
+ <span class="n">ulittle32_t</span> <span class="n">StreamBlocks</span><span class="p">[][]</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="p">{</span><span class="mi">4</span><span class="p">},</span>
+ <span class="p">{</span><span class="mi">5</span><span class="p">,</span> <span class="mi">6</span><span class="p">},</span>
+ <span class="p">{</span><span class="mi">11</span><span class="p">,</span> <span class="mi">9</span><span class="p">,</span> <span class="mi">7</span><span class="p">,</span> <span class="mi">8</span><span class="p">},</span>
+ <span class="p">{</span><span class="mi">10</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="mi">12</span><span class="p">}</span>
+ <span class="p">};</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>In total, this occupies <code class="docutils literal"><span class="pre">15</span> <span class="pre">*</span> <span class="pre">4</span> <span class="pre">=</span> <span class="pre">60</span></code> bytes, so <code class="docutils literal"><span class="pre">SuperBlock->NumDirectoryBytes</span></code>
+would equal <code class="docutils literal"><span class="pre">60</span></code>, and <code class="docutils literal"><span class="pre">SuperBlock->BlockMapAddr</span></code> would be an array of one
+<code class="docutils literal"><span class="pre">ulittle32_t</span></code>, since <code class="docutils literal"><span class="pre">60</span> <span class="pre"><=</span> <span class="pre">SuperBlock->BlockSize</span></code>.</p>
+<p>Note also that the streams are discontiguous, and that part of stream 3 is in the
+middle of part of stream 2. You cannot assume anything about the layout of the
+blocks!</p>
+</div>
+<div class="section" id="alignment-and-block-boundaries">
+<h2><a class="toc-backref" href="#id3">Alignment and Block Boundaries</a><a class="headerlink" href="#alignment-and-block-boundaries" title="Permalink to this headline">¶</a></h2>
+<p>As may be clear by now, it is possible for a single field (whether it be a high
+level record, a long string field, or even a single <code class="docutils literal"><span class="pre">uint16</span></code>) to begin and
+end in separate blocks. For example, if the block size is 4096 bytes, and a
+<code class="docutils literal"><span class="pre">uint16</span></code> field begins at the last byte of the current block, then it would
+need to end on the first byte of the next block. Since blocks are not
+necessarily contiguously laid out in the file, this means that both the consumer
+and the producer of an MSF file must be prepared to split data apart
+accordingly. In the aforementioned example, the high byte of the <code class="docutils literal"><span class="pre">uint16</span></code>
+would be written to the last byte of block N, and the low byte would be written
+to the first byte of block N+1, which could be tens of thousands of bytes later
+(or even earlier!) in the file, depending on what the stream directory says.</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="PdbStream.html" title="The PDB Info Stream (aka the PDB Stream)"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="The PDB File Format"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/PdbStream.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/PdbStream.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/PdbStream.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/PdbStream.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,174 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The PDB Info Stream (aka the PDB Stream) — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="The PDB TPI Stream" href="TpiStream.html" />
+ <link rel="prev" title="The MSF File Format" href="MsfFile.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="TpiStream.html" title="The PDB TPI Stream"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="MsfFile.html" title="The MSF File Format"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-pdb-info-stream-aka-the-pdb-stream">
+<h1>The PDB Info Stream (aka the PDB Stream)<a class="headerlink" href="#the-pdb-info-stream-aka-the-pdb-stream" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#stream-header" id="id1">Stream Header</a></li>
+<li><a class="reference internal" href="#matching-a-pdb-to-its-executable" id="id2">Matching a PDB to its executable</a></li>
+</ul>
+</div>
+<div class="section" id="stream-header">
+<span id="pdb-stream-header"></span><h2><a class="toc-backref" href="#id1">Stream Header</a><a class="headerlink" href="#stream-header" title="Permalink to this headline">¶</a></h2>
+<p>At offset 0 of the PDB Stream is a header with the following layout:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="n">PdbStreamHeader</span> <span class="p">{</span>
+ <span class="n">ulittle32_t</span> <span class="n">Version</span><span class="p">;</span>
+ <span class="n">ulittle32_t</span> <span class="n">Signature</span><span class="p">;</span>
+ <span class="n">ulittle32_t</span> <span class="n">Age</span><span class="p">;</span>
+ <span class="n">Guid</span> <span class="n">UniqueId</span><span class="p">;</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<ul class="simple">
+<li><strong>Version</strong> - A Value from the following enum:</li>
+</ul>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">enum</span> <span class="k">class</span> <span class="nc">PdbStreamVersion</span> <span class="o">:</span> <span class="kt">uint32_t</span> <span class="p">{</span>
+ <span class="n">VC2</span> <span class="o">=</span> <span class="mi">19941610</span><span class="p">,</span>
+ <span class="n">VC4</span> <span class="o">=</span> <span class="mi">19950623</span><span class="p">,</span>
+ <span class="n">VC41</span> <span class="o">=</span> <span class="mi">19950814</span><span class="p">,</span>
+ <span class="n">VC50</span> <span class="o">=</span> <span class="mi">19960307</span><span class="p">,</span>
+ <span class="n">VC98</span> <span class="o">=</span> <span class="mi">19970604</span><span class="p">,</span>
+ <span class="n">VC70Dep</span> <span class="o">=</span> <span class="mi">19990604</span><span class="p">,</span>
+ <span class="n">VC70</span> <span class="o">=</span> <span class="mi">20000404</span><span class="p">,</span>
+ <span class="n">VC80</span> <span class="o">=</span> <span class="mi">20030901</span><span class="p">,</span>
+ <span class="n">VC110</span> <span class="o">=</span> <span class="mi">20091201</span><span class="p">,</span>
+ <span class="n">VC140</span> <span class="o">=</span> <span class="mi">20140508</span><span class="p">,</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>While the meaning of this field appears to be obvious, in practice we have
+never observed a value other than <code class="docutils literal"><span class="pre">VC70</span></code>, even with modern versions of
+the toolchain, and it is unclear why the other values exist. It is assumed
+that certain aspects of the PDB stream’s layout, and perhaps even that of
+the other streams, will change if the value is something other than <code class="docutils literal"><span class="pre">VC70</span></code>.</p>
+<ul class="simple">
+<li><strong>Signature</strong> - A 32-bit time-stamp generated with a call to <code class="docutils literal"><span class="pre">time()</span></code> at
+the time the PDB file is written. Note that due to the inherent uniqueness
+problems of using a timestamp with 1-second granularity, this field does not
+really serve its intended purpose, and as such is typically ignored in favor
+of the <code class="docutils literal"><span class="pre">Guid</span></code> field, described below.</li>
+<li><strong>Age</strong> - The number of times the PDB file has been written. This can be used
+along with <code class="docutils literal"><span class="pre">Guid</span></code> to match the PDB to its corresponding executable.</li>
+<li><strong>Guid</strong> - A 128-bit identifier guaranteed to be unique across space and time.
+In general, this can be thought of as the result of calling the Win32 API
+<a class="reference external" href="https://msdn.microsoft.com/en-us/library/windows/desktop/aa379205(v=vs.85).aspx">UuidCreate</a>,
+although LLVM cannot rely on that, as it must work on non-Windows platforms.</li>
+</ul>
+</div>
+<div class="section" id="matching-a-pdb-to-its-executable">
+<h2><a class="toc-backref" href="#id2">Matching a PDB to its executable</a><a class="headerlink" href="#matching-a-pdb-to-its-executable" title="Permalink to this headline">¶</a></h2>
+<p>The linker is responsible for writing both the PDB and the final executable, and
+as a result is the only entity capable of writing the information necessary to
+match the PDB to the executable.</p>
+<p>In order to accomplish this, the linker generates a guid for the PDB (or
+re-uses the existing guid if it is linking incrementally) and increments the Age
+field.</p>
+<p>The executable is a PE/COFF file, and part of a PE/COFF file is the presence of
+number of “directories”. For our purposes here, we are interested in the “debug
+directory”. The exact format of a debug directory is described by the
+<a class="reference external" href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms680307(v=vs.85).aspx">IMAGE_DEBUG_DIRECTORY structure</a>.
+For this particular case, the linker emits a debug directory of type
+<code class="docutils literal"><span class="pre">IMAGE_DEBUG_TYPE_CODEVIEW</span></code>. The format of this record is defined in
+<code class="docutils literal"><span class="pre">llvm/DebugInfo/CodeView/CVDebugRecord.h</span></code>, but it suffices to say here only
+that it includes the same <code class="docutils literal"><span class="pre">Guid</span></code> and <code class="docutils literal"><span class="pre">Age</span></code> fields. At runtime, a
+debugger or tool can scan the COFF executable image for the presence of
+a debug directory of the correct type and verify that the Guid and Age match.</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="TpiStream.html" title="The PDB TPI Stream"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="MsfFile.html" title="The MSF File Format"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/PublicStream.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/PublicStream.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/PublicStream.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/PublicStream.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,102 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The PDB Public Symbol Stream — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="The PDB Global Symbol Stream" href="GlobalStream.html" />
+ <link rel="prev" title="The Module Information Stream" href="ModiStream.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="GlobalStream.html" title="The PDB Global Symbol Stream"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ModiStream.html" title="The Module Information Stream"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-pdb-public-symbol-stream">
+<h1>The PDB Public Symbol Stream<a class="headerlink" href="#the-pdb-public-symbol-stream" title="Permalink to this headline">¶</a></h1>
+</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="GlobalStream.html" title="The PDB Global Symbol Stream"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ModiStream.html" title="The Module Information Stream"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/TpiStream.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/TpiStream.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/TpiStream.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/TpiStream.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,102 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The PDB TPI Stream — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="The PDB DBI (Debug Info) Stream" href="DbiStream.html" />
+ <link rel="prev" title="The PDB Info Stream (aka the PDB Stream)" href="PdbStream.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="DbiStream.html" title="The PDB DBI (Debug Info) Stream"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="PdbStream.html" title="The PDB Info Stream (aka the PDB Stream)"
+ 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="index.html" accesskey="U">The PDB File Format</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-pdb-tpi-stream">
+<h1>The PDB TPI Stream<a class="headerlink" href="#the-pdb-tpi-stream" title="Permalink to this headline">¶</a></h1>
+</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="DbiStream.html" title="The PDB DBI (Debug Info) Stream"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="PdbStream.html" title="The PDB Info Stream (aka the PDB Stream)"
+ >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="index.html" >The PDB File Format</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/PDB/index.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/PDB/index.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/PDB/index.html (added)
+++ www-releases/trunk/6.0.0/docs/PDB/index.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,359 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>The PDB File Format — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="The MSF File Format" href="MsfFile.html" />
+ <link rel="prev" title="XRay Flight Data Recorder Trace Format" href="../XRayFDRFormat.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="MsfFile.html" title="The MSF File Format"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../XRayFDRFormat.html" title="XRay Flight Data Recorder Trace Format"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="the-pdb-file-format">
+<h1>The PDB File Format<a class="headerlink" href="#the-pdb-file-format" 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="#file-layout" id="id3">File Layout</a><ul>
+<li><a class="reference internal" href="#the-msf-container" id="id4">The MSF Container</a></li>
+<li><a class="reference internal" href="#streams" id="id5">Streams</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#codeview" id="id6">CodeView</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<span id="pdb-intro"></span><h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>PDB (Program Database) is a file format invented by Microsoft and which contains
+debug information that can be consumed by debuggers and other tools. Since
+officially supported APIs exist on Windows for querying debug information from
+PDBs even without the user understanding the internals of the file format, a
+large ecosystem of tools has been built for Windows to consume this format. In
+order for Clang to be able to generate programs that can interoperate with these
+tools, it is necessary for us to generate PDB files ourselves.</p>
+<p>At the same time, LLVM has a long history of being able to cross-compile from
+any platform to any platform, and we wish for the same to be true here. So it
+is necessary for us to understand the PDB file format at the byte-level so that
+we can generate PDB files entirely on our own.</p>
+<p>This manual describes what we know about the PDB file format today. The layout
+of the file, the various streams contained within, the format of individual
+records within, and more.</p>
+<p>We would like to extend our heartfelt gratitude to Microsoft, without whom we
+would not be where we are today. Much of the knowledge contained within this
+manual was learned through reading code published by Microsoft on their <a class="reference external" href="https://github.com/Microsoft/microsoft-pdb">GitHub
+repo</a>.</p>
+</div>
+<div class="section" id="file-layout">
+<span id="pdb-layout"></span><h2><a class="toc-backref" href="#id3">File Layout</a><a class="headerlink" href="#file-layout" title="Permalink to this headline">¶</a></h2>
+<div class="admonition important">
+<p class="first admonition-title">Important</p>
+<p class="last">Unless otherwise specified, all numeric values are encoded in little endian.
+If you see a type such as <code class="docutils literal"><span class="pre">uint16_t</span></code> or <code class="docutils literal"><span class="pre">uint64_t</span></code> going forward, always
+assume it is little endian!</p>
+</div>
+<div class="toctree-wrapper compound">
+</div>
+<div class="section" id="the-msf-container">
+<span id="msf"></span><h3><a class="toc-backref" href="#id4">The MSF Container</a><a class="headerlink" href="#the-msf-container" title="Permalink to this headline">¶</a></h3>
+<p>A PDB file is really just a special case of an MSF (Multi-Stream Format) file.
+An MSF file is actually a miniature “file system within a file”. It contains
+multiple streams (aka files) which can represent arbitrary data, and these
+streams are divided into blocks which may not necessarily be contiguously
+laid out within the file (aka fragmented). Additionally, the MSF contains a
+stream directory (aka MFT) which describes how the streams (files) are laid
+out within the MSF.</p>
+<p>For more information about the MSF container format, stream directory, and
+block layout, see <a class="reference internal" href="MsfFile.html"><span class="doc">The MSF File Format</span></a>.</p>
+</div>
+<div class="section" id="streams">
+<span id="id1"></span><h3><a class="toc-backref" href="#id5">Streams</a><a class="headerlink" href="#streams" title="Permalink to this headline">¶</a></h3>
+<p>The PDB format contains a number of streams which describe various information
+such as the types, symbols, source files, and compilands (e.g. object files)
+of a program, as well as some additional streams containing hash tables that are
+used by debuggers and other tools to provide fast lookup of records and types
+by name, and various other information about how the program was compiled such
+as the specific toolchain used, and more. A summary of streams contained in a
+PDB file is as follows:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="22%" />
+<col width="32%" />
+<col width="46%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Name</th>
+<th class="head">Stream Index</th>
+<th class="head">Contents</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>Old Directory</td>
+<td><ul class="first last simple">
+<li>Fixed Stream Index 0</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>Previous MSF Stream Directory</li>
+</ul>
+</td>
+</tr>
+<tr class="row-odd"><td>PDB Stream</td>
+<td><ul class="first last simple">
+<li>Fixed Stream Index 1</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>Basic File Information</li>
+<li>Fields to match EXE to this PDB</li>
+<li>Map of named streams to stream indices</li>
+</ul>
+</td>
+</tr>
+<tr class="row-even"><td>TPI Stream</td>
+<td><ul class="first last simple">
+<li>Fixed Stream Index 2</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>CodeView Type Records</li>
+<li>Index of TPI Hash Stream</li>
+</ul>
+</td>
+</tr>
+<tr class="row-odd"><td>DBI Stream</td>
+<td><ul class="first last simple">
+<li>Fixed Stream Index 3</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>Module/Compiland Information</li>
+<li>Indices of individual module streams</li>
+<li>Indices of public / global streams</li>
+<li>Section Contribution Information</li>
+<li>Source File Information</li>
+<li>FPO / PGO Data</li>
+</ul>
+</td>
+</tr>
+<tr class="row-even"><td>IPI Stream</td>
+<td><ul class="first last simple">
+<li>Fixed Stream Index 4</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>CodeView Type Records</li>
+<li>Index of IPI Hash Stream</li>
+</ul>
+</td>
+</tr>
+<tr class="row-odd"><td>/LinkInfo</td>
+<td><ul class="first last simple">
+<li>Contained in PDB Stream
+Named Stream map</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>Unknown</li>
+</ul>
+</td>
+</tr>
+<tr class="row-even"><td>/src/headerblock</td>
+<td><ul class="first last simple">
+<li>Contained in PDB Stream
+Named Stream map</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>Unknown</li>
+</ul>
+</td>
+</tr>
+<tr class="row-odd"><td>/names</td>
+<td><ul class="first last simple">
+<li>Contained in PDB Stream
+Named Stream map</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>PDB-wide global string table used for
+string de-duplication</li>
+</ul>
+</td>
+</tr>
+<tr class="row-even"><td>Module Info Stream</td>
+<td><ul class="first last simple">
+<li>Contained in DBI Stream</li>
+<li>One for each compiland</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>CodeView Symbol Records for this module</li>
+<li>Line Number Information</li>
+</ul>
+</td>
+</tr>
+<tr class="row-odd"><td>Public Stream</td>
+<td><ul class="first last simple">
+<li>Contained in DBI Stream</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>Public (Exported) Symbol Records</li>
+<li>Index of Public Hash Stream</li>
+</ul>
+</td>
+</tr>
+<tr class="row-even"><td>Global Stream</td>
+<td><ul class="first last simple">
+<li>Contained in DBI Stream</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>Global Symbol Records</li>
+<li>Index of Global Hash Stream</li>
+</ul>
+</td>
+</tr>
+<tr class="row-odd"><td>TPI Hash Stream</td>
+<td><ul class="first last simple">
+<li>Contained in TPI Stream</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>Hash table for looking up TPI records
+by name</li>
+</ul>
+</td>
+</tr>
+<tr class="row-even"><td>IPI Hash Stream</td>
+<td><ul class="first last simple">
+<li>Contained in IPI Stream</li>
+</ul>
+</td>
+<td><ul class="first last simple">
+<li>Hash table for looking up IPI records
+by name</li>
+</ul>
+</td>
+</tr>
+</tbody>
+</table>
+<p>More information about the structure of each of these can be found on the
+following pages:</p>
+<dl class="docutils">
+<dt><a class="reference internal" href="PdbStream.html"><span class="doc">The PDB Info Stream (aka the PDB Stream)</span></a></dt>
+<dd>Information about the PDB Info Stream and how it is used to match PDBs to EXEs.</dd>
+<dt><a class="reference internal" href="TpiStream.html"><span class="doc">The PDB TPI Stream</span></a></dt>
+<dd>Information about the TPI stream and the CodeView records contained within.</dd>
+<dt><a class="reference internal" href="DbiStream.html"><span class="doc">The PDB DBI (Debug Info) Stream</span></a></dt>
+<dd>Information about the DBI stream and relevant substreams including the Module Substreams,
+source file information, and CodeView symbol records contained within.</dd>
+<dt><a class="reference internal" href="ModiStream.html"><span class="doc">The Module Information Stream</span></a></dt>
+<dd>Information about the Module Information Stream, of which there is one for each compilation
+unit and the format of symbols contained within.</dd>
+<dt><a class="reference internal" href="PublicStream.html"><span class="doc">The PDB Public Symbol Stream</span></a></dt>
+<dd>Information about the Public Symbol Stream.</dd>
+<dt><a class="reference internal" href="GlobalStream.html"><span class="doc">The PDB Global Symbol Stream</span></a></dt>
+<dd>Information about the Global Symbol Stream.</dd>
+<dt><a class="reference internal" href="HashStream.html"><span class="doc">The TPI & IPI Hash Streams</span></a></dt>
+<dd>Information about the Hash Table stream, and how it can be used to quickly look up records
+by name.</dd>
+</dl>
+</div>
+</div>
+<div class="section" id="codeview">
+<h2><a class="toc-backref" href="#id6">CodeView</a><a class="headerlink" href="#codeview" title="Permalink to this headline">¶</a></h2>
+<p>CodeView is another format which comes into the picture. While MSF defines
+the structure of the overall file, and PDB defines the set of streams that
+appear within the MSF file and the format of those streams, CodeView defines
+the format of <strong>symbol and type records</strong> that appear within specific streams.
+Refer to the pages on <a class="reference internal" href="CodeViewSymbols.html"><span class="doc">CodeView Symbol Records</span></a> and <a class="reference internal" href="CodeViewTypes.html"><span class="doc">CodeView Type Records</span></a> for
+more information about the CodeView format.</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="MsfFile.html" title="The MSF File Format"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../XRayFDRFormat.html" title="XRay Flight Data Recorder Trace Format"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/Packaging.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/Packaging.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/Packaging.html (added)
+++ www-releases/trunk/6.0.0/docs/Packaging.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,171 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Advice on Packaging LLVM — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="How To Validate a New Release" href="ReleaseProcess.html" />
+ <link rel="prev" title="How To Release LLVM To The Public" href="HowToReleaseLLVM.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="ReleaseProcess.html" title="How To Validate a New Release"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToReleaseLLVM.html" title="How To Release LLVM To The Public"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="advice-on-packaging-llvm">
+<h1>Advice on Packaging LLVM<a class="headerlink" href="#advice-on-packaging-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#overview" id="id1">Overview</a></li>
+<li><a class="reference internal" href="#compile-flags" id="id2">Compile Flags</a></li>
+<li><a class="reference internal" href="#c-features" id="id3">C++ Features</a></li>
+<li><a class="reference internal" href="#shared-library" id="id4">Shared Library</a></li>
+<li><a class="reference internal" href="#dependencies" id="id5">Dependencies</a></li>
+</ul>
+</div>
+<div class="section" id="overview">
+<h2><a class="toc-backref" href="#id1">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>LLVM sets certain default configure options to make sure our developers don’t
+break things for constrained platforms. These settings are not optimal for most
+desktop systems, and we hope that packagers (e.g., Redhat, Debian, MacPorts,
+etc.) will tweak them. This document lists settings we suggest you tweak.</p>
+<p>LLVM’s API changes with each release, so users are likely to want, for example,
+both LLVM-2.6 and LLVM-2.7 installed at the same time to support apps developed
+against each.</p>
+</div>
+<div class="section" id="compile-flags">
+<h2><a class="toc-backref" href="#id2">Compile Flags</a><a class="headerlink" href="#compile-flags" title="Permalink to this headline">¶</a></h2>
+<p>LLVM runs much more quickly when it’s optimized and assertions are removed.
+However, such a build is currently incompatible with users who build without
+defining <code class="docutils literal"><span class="pre">NDEBUG</span></code>, and the lack of assertions makes it hard to debug problems
+in user code. We recommend allowing users to install both optimized and debug
+versions of LLVM in parallel. The following configure flags are relevant:</p>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">--disable-assertions</span></code></dt>
+<dd>Builds LLVM with <code class="docutils literal"><span class="pre">NDEBUG</span></code> defined. Changes the LLVM ABI. Also available
+by setting <code class="docutils literal"><span class="pre">DISABLE_ASSERTIONS=0|1</span></code> in <code class="docutils literal"><span class="pre">make</span></code>‘s environment. This
+defaults to enabled regardless of the optimization setting, but it slows
+things down.</dd>
+<dt><code class="docutils literal"><span class="pre">--enable-debug-symbols</span></code></dt>
+<dd>Builds LLVM with <code class="docutils literal"><span class="pre">-g</span></code>. Also available by setting <code class="docutils literal"><span class="pre">DEBUG_SYMBOLS=0|1</span></code> in
+<code class="docutils literal"><span class="pre">make</span></code>‘s environment. This defaults to disabled when optimizing, so you
+should turn it back on to let users debug their programs.</dd>
+<dt><code class="docutils literal"><span class="pre">--enable-optimized</span></code></dt>
+<dd>(For svn checkouts) Builds LLVM with <code class="docutils literal"><span class="pre">-O2</span></code> and, by default, turns off
+debug symbols. Also available by setting <code class="docutils literal"><span class="pre">ENABLE_OPTIMIZED=0|1</span></code> in
+<code class="docutils literal"><span class="pre">make</span></code>‘s environment. This defaults to enabled when not in a
+checkout.</dd>
+</dl>
+</div>
+<div class="section" id="c-features">
+<h2><a class="toc-backref" href="#id3">C++ Features</a><a class="headerlink" href="#c-features" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt>RTTI</dt>
+<dd>LLVM disables RTTI by default. Add <code class="docutils literal"><span class="pre">REQUIRES_RTTI=1</span></code> to your environment
+while running <code class="docutils literal"><span class="pre">make</span></code> to re-enable it. This will allow users to build with
+RTTI enabled and still inherit from LLVM classes.</dd>
+</dl>
+</div>
+<div class="section" id="shared-library">
+<h2><a class="toc-backref" href="#id4">Shared Library</a><a class="headerlink" href="#shared-library" title="Permalink to this headline">¶</a></h2>
+<p>Configure with <code class="docutils literal"><span class="pre">--enable-shared</span></code> to build
+<code class="docutils literal"><span class="pre">libLLVM-<major>.<minor>.(so|dylib)</span></code> and link the tools against it. This
+saves lots of binary size at the cost of some startup time.</p>
+</div>
+<div class="section" id="dependencies">
+<h2><a class="toc-backref" href="#id5">Dependencies</a><a class="headerlink" href="#dependencies" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">--enable-libffi</span></code></dt>
+<dd>Depend on <a class="reference external" href="http://sources.redhat.com/libffi/">libffi</a> to allow the LLVM
+interpreter to call external functions.</dd>
+</dl>
+<p><code class="docutils literal"><span class="pre">--with-oprofile</span></code></p>
+<blockquote>
+<div>Depend on <a class="reference external" href="http://oprofile.sourceforge.net/doc/devel/index.html">libopagent</a> (>=version 0.9.4)
+to let the LLVM JIT tell oprofile about function addresses and line
+numbers.</div></blockquote>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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="ReleaseProcess.html" title="How To Validate a New Release"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToReleaseLLVM.html" title="How To Release LLVM To The Public"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/Passes.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/Passes.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/Passes.html (added)
+++ www-releases/trunk/6.0.0/docs/Passes.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,1173 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>LLVMâs Analysis and Transform Passes — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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="YAML I/O" href="YamlIO.html" />
+ <link rel="prev" title="LLVM 6.0.0 Release Notes" href="ReleaseNotes.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="YamlIO.html" title="YAML I/O"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ReleaseNotes.html" title="LLVM 6.0.0 Release Notes"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-s-analysis-and-transform-passes">
+<h1>LLVM’s Analysis and Transform Passes<a class="headerlink" href="#llvm-s-analysis-and-transform-passes" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
+<li><a class="reference internal" href="#analysis-passes" id="id2">Analysis Passes</a><ul>
+<li><a class="reference internal" href="#aa-eval-exhaustive-alias-analysis-precision-evaluator" id="id3"><code class="docutils literal"><span class="pre">-aa-eval</span></code>: Exhaustive Alias Analysis Precision Evaluator</a></li>
+<li><a class="reference internal" href="#basicaa-basic-alias-analysis-stateless-aa-impl" id="id4"><code class="docutils literal"><span class="pre">-basicaa</span></code>: Basic Alias Analysis (stateless AA impl)</a></li>
+<li><a class="reference internal" href="#basiccg-basic-callgraph-construction" id="id5"><code class="docutils literal"><span class="pre">-basiccg</span></code>: Basic CallGraph Construction</a></li>
+<li><a class="reference internal" href="#count-aa-count-alias-analysis-query-responses" id="id6"><code class="docutils literal"><span class="pre">-count-aa</span></code>: Count Alias Analysis Query Responses</a></li>
+<li><a class="reference internal" href="#da-dependence-analysis" id="id7"><code class="docutils literal"><span class="pre">-da</span></code>: Dependence Analysis</a></li>
+<li><a class="reference internal" href="#debug-aa-aa-use-debugger" id="id8"><code class="docutils literal"><span class="pre">-debug-aa</span></code>: AA use debugger</a></li>
+<li><a class="reference internal" href="#domfrontier-dominance-frontier-construction" id="id9"><code class="docutils literal"><span class="pre">-domfrontier</span></code>: Dominance Frontier Construction</a></li>
+<li><a class="reference internal" href="#domtree-dominator-tree-construction" id="id10"><code class="docutils literal"><span class="pre">-domtree</span></code>: Dominator Tree Construction</a></li>
+<li><a class="reference internal" href="#dot-callgraph-print-call-graph-to-dot-file" id="id11"><code class="docutils literal"><span class="pre">-dot-callgraph</span></code>: Print Call Graph to “dot” file</a></li>
+<li><a class="reference internal" href="#dot-cfg-print-cfg-of-function-to-dot-file" id="id12"><code class="docutils literal"><span class="pre">-dot-cfg</span></code>: Print CFG of function to “dot” file</a></li>
+<li><a class="reference internal" href="#dot-cfg-only-print-cfg-of-function-to-dot-file-with-no-function-bodies" id="id13"><code class="docutils literal"><span class="pre">-dot-cfg-only</span></code>: Print CFG of function to “dot” file (with no function bodies)</a></li>
+<li><a class="reference internal" href="#dot-dom-print-dominance-tree-of-function-to-dot-file" id="id14"><code class="docutils literal"><span class="pre">-dot-dom</span></code>: Print dominance tree of function to “dot” file</a></li>
+<li><a class="reference internal" href="#dot-dom-only-print-dominance-tree-of-function-to-dot-file-with-no-function-bodies" id="id15"><code class="docutils literal"><span class="pre">-dot-dom-only</span></code>: Print dominance tree of function to “dot” file (with no function bodies)</a></li>
+<li><a class="reference internal" href="#dot-postdom-print-postdominance-tree-of-function-to-dot-file" id="id16"><code class="docutils literal"><span class="pre">-dot-postdom</span></code>: Print postdominance tree of function to “dot” file</a></li>
+<li><a class="reference internal" href="#dot-postdom-only-print-postdominance-tree-of-function-to-dot-file-with-no-function-bodies" id="id17"><code class="docutils literal"><span class="pre">-dot-postdom-only</span></code>: Print postdominance tree of function to “dot” file (with no function bodies)</a></li>
+<li><a class="reference internal" href="#globalsmodref-aa-simple-mod-ref-analysis-for-globals" id="id18"><code class="docutils literal"><span class="pre">-globalsmodref-aa</span></code>: Simple mod/ref analysis for globals</a></li>
+<li><a class="reference internal" href="#instcount-counts-the-various-types-of-instructions" id="id19"><code class="docutils literal"><span class="pre">-instcount</span></code>: Counts the various types of <code class="docutils literal"><span class="pre">Instruction</span></code>s</a></li>
+<li><a class="reference internal" href="#intervals-interval-partition-construction" id="id20"><code class="docutils literal"><span class="pre">-intervals</span></code>: Interval Partition Construction</a></li>
+<li><a class="reference internal" href="#iv-users-induction-variable-users" id="id21"><code class="docutils literal"><span class="pre">-iv-users</span></code>: Induction Variable Users</a></li>
+<li><a class="reference internal" href="#lazy-value-info-lazy-value-information-analysis" id="id22"><code class="docutils literal"><span class="pre">-lazy-value-info</span></code>: Lazy Value Information Analysis</a></li>
+<li><a class="reference internal" href="#libcall-aa-libcall-alias-analysis" id="id23"><code class="docutils literal"><span class="pre">-libcall-aa</span></code>: LibCall Alias Analysis</a></li>
+<li><a class="reference internal" href="#lint-statically-lint-checks-llvm-ir" id="id24"><code class="docutils literal"><span class="pre">-lint</span></code>: Statically lint-checks LLVM IR</a></li>
+<li><a class="reference internal" href="#loops-natural-loop-information" id="id25"><code class="docutils literal"><span class="pre">-loops</span></code>: Natural Loop Information</a></li>
+<li><a class="reference internal" href="#memdep-memory-dependence-analysis" id="id26"><code class="docutils literal"><span class="pre">-memdep</span></code>: Memory Dependence Analysis</a></li>
+<li><a class="reference internal" href="#module-debuginfo-decodes-module-level-debug-info" id="id27"><code class="docutils literal"><span class="pre">-module-debuginfo</span></code>: Decodes module-level debug info</a></li>
+<li><a class="reference internal" href="#postdomfrontier-post-dominance-frontier-construction" id="id28"><code class="docutils literal"><span class="pre">-postdomfrontier</span></code>: Post-Dominance Frontier Construction</a></li>
+<li><a class="reference internal" href="#postdomtree-post-dominator-tree-construction" id="id29"><code class="docutils literal"><span class="pre">-postdomtree</span></code>: Post-Dominator Tree Construction</a></li>
+<li><a class="reference internal" href="#print-alias-sets-alias-set-printer" id="id30"><code class="docutils literal"><span class="pre">-print-alias-sets</span></code>: Alias Set Printer</a></li>
+<li><a class="reference internal" href="#print-callgraph-print-a-call-graph" id="id31"><code class="docutils literal"><span class="pre">-print-callgraph</span></code>: Print a call graph</a></li>
+<li><a class="reference internal" href="#print-callgraph-sccs-print-sccs-of-the-call-graph" id="id32"><code class="docutils literal"><span class="pre">-print-callgraph-sccs</span></code>: Print SCCs of the Call Graph</a></li>
+<li><a class="reference internal" href="#print-cfg-sccs-print-sccs-of-each-function-cfg" id="id33"><code class="docutils literal"><span class="pre">-print-cfg-sccs</span></code>: Print SCCs of each function CFG</a></li>
+<li><a class="reference internal" href="#print-dom-info-dominator-info-printer" id="id34"><code class="docutils literal"><span class="pre">-print-dom-info</span></code>: Dominator Info Printer</a></li>
+<li><a class="reference internal" href="#print-externalfnconstants-print-external-fn-callsites-passed-constants" id="id35"><code class="docutils literal"><span class="pre">-print-externalfnconstants</span></code>: Print external fn callsites passed constants</a></li>
+<li><a class="reference internal" href="#print-function-print-function-to-stderr" id="id36"><code class="docutils literal"><span class="pre">-print-function</span></code>: Print function to stderr</a></li>
+<li><a class="reference internal" href="#print-module-print-module-to-stderr" id="id37"><code class="docutils literal"><span class="pre">-print-module</span></code>: Print module to stderr</a></li>
+<li><a class="reference internal" href="#print-used-types-find-used-types" id="id38"><code class="docutils literal"><span class="pre">-print-used-types</span></code>: Find Used Types</a></li>
+<li><a class="reference internal" href="#regions-detect-single-entry-single-exit-regions" id="id39"><code class="docutils literal"><span class="pre">-regions</span></code>: Detect single entry single exit regions</a></li>
+<li><a class="reference internal" href="#scalar-evolution-scalar-evolution-analysis" id="id40"><code class="docutils literal"><span class="pre">-scalar-evolution</span></code>: Scalar Evolution Analysis</a></li>
+<li><a class="reference internal" href="#scev-aa-scalarevolution-based-alias-analysis" id="id41"><code class="docutils literal"><span class="pre">-scev-aa</span></code>: ScalarEvolution-based Alias Analysis</a></li>
+<li><a class="reference internal" href="#targetdata-target-data-layout" id="id42"><code class="docutils literal"><span class="pre">-targetdata</span></code>: Target Data Layout</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#transform-passes" id="id43">Transform Passes</a><ul>
+<li><a class="reference internal" href="#adce-aggressive-dead-code-elimination" id="id44"><code class="docutils literal"><span class="pre">-adce</span></code>: Aggressive Dead Code Elimination</a></li>
+<li><a class="reference internal" href="#always-inline-inliner-for-always-inline-functions" id="id45"><code class="docutils literal"><span class="pre">-always-inline</span></code>: Inliner for <code class="docutils literal"><span class="pre">always_inline</span></code> functions</a></li>
+<li><a class="reference internal" href="#argpromotion-promote-by-reference-arguments-to-scalars" id="id46"><code class="docutils literal"><span class="pre">-argpromotion</span></code>: Promote ‘by reference’ arguments to scalars</a></li>
+<li><a class="reference internal" href="#bb-vectorize-basic-block-vectorization" id="id47"><code class="docutils literal"><span class="pre">-bb-vectorize</span></code>: Basic-Block Vectorization</a></li>
+<li><a class="reference internal" href="#block-placement-profile-guided-basic-block-placement" id="id48"><code class="docutils literal"><span class="pre">-block-placement</span></code>: Profile Guided Basic Block Placement</a></li>
+<li><a class="reference internal" href="#break-crit-edges-break-critical-edges-in-cfg" id="id49"><code class="docutils literal"><span class="pre">-break-crit-edges</span></code>: Break critical edges in CFG</a></li>
+<li><a class="reference internal" href="#codegenprepare-optimize-for-code-generation" id="id50"><code class="docutils literal"><span class="pre">-codegenprepare</span></code>: Optimize for code generation</a></li>
+<li><a class="reference internal" href="#constmerge-merge-duplicate-global-constants" id="id51"><code class="docutils literal"><span class="pre">-constmerge</span></code>: Merge Duplicate Global Constants</a></li>
+<li><a class="reference internal" href="#constprop-simple-constant-propagation" id="id52"><code class="docutils literal"><span class="pre">-constprop</span></code>: Simple constant propagation</a></li>
+<li><a class="reference internal" href="#dce-dead-code-elimination" id="id53"><code class="docutils literal"><span class="pre">-dce</span></code>: Dead Code Elimination</a></li>
+<li><a class="reference internal" href="#deadargelim-dead-argument-elimination" id="id54"><code class="docutils literal"><span class="pre">-deadargelim</span></code>: Dead Argument Elimination</a></li>
+<li><a class="reference internal" href="#deadtypeelim-dead-type-elimination" id="id55"><code class="docutils literal"><span class="pre">-deadtypeelim</span></code>: Dead Type Elimination</a></li>
+<li><a class="reference internal" href="#die-dead-instruction-elimination" id="id56"><code class="docutils literal"><span class="pre">-die</span></code>: Dead Instruction Elimination</a></li>
+<li><a class="reference internal" href="#dse-dead-store-elimination" id="id57"><code class="docutils literal"><span class="pre">-dse</span></code>: Dead Store Elimination</a></li>
+<li><a class="reference internal" href="#functionattrs-deduce-function-attributes" id="id58"><code class="docutils literal"><span class="pre">-functionattrs</span></code>: Deduce function attributes</a></li>
+<li><a class="reference internal" href="#globaldce-dead-global-elimination" id="id59"><code class="docutils literal"><span class="pre">-globaldce</span></code>: Dead Global Elimination</a></li>
+<li><a class="reference internal" href="#globalopt-global-variable-optimizer" id="id60"><code class="docutils literal"><span class="pre">-globalopt</span></code>: Global Variable Optimizer</a></li>
+<li><a class="reference internal" href="#gvn-global-value-numbering" id="id61"><code class="docutils literal"><span class="pre">-gvn</span></code>: Global Value Numbering</a></li>
+<li><a class="reference internal" href="#indvars-canonicalize-induction-variables" id="id62"><code class="docutils literal"><span class="pre">-indvars</span></code>: Canonicalize Induction Variables</a></li>
+<li><a class="reference internal" href="#inline-function-integration-inlining" id="id63"><code class="docutils literal"><span class="pre">-inline</span></code>: Function Integration/Inlining</a></li>
+<li><a class="reference internal" href="#instcombine-combine-redundant-instructions" id="id64"><code class="docutils literal"><span class="pre">-instcombine</span></code>: Combine redundant instructions</a></li>
+<li><a class="reference internal" href="#internalize-internalize-global-symbols" id="id65"><code class="docutils literal"><span class="pre">-internalize</span></code>: Internalize Global Symbols</a></li>
+<li><a class="reference internal" href="#ipconstprop-interprocedural-constant-propagation" id="id66"><code class="docutils literal"><span class="pre">-ipconstprop</span></code>: Interprocedural constant propagation</a></li>
+<li><a class="reference internal" href="#ipsccp-interprocedural-sparse-conditional-constant-propagation" id="id67"><code class="docutils literal"><span class="pre">-ipsccp</span></code>: Interprocedural Sparse Conditional Constant Propagation</a></li>
+<li><a class="reference internal" href="#jump-threading-jump-threading" id="id68"><code class="docutils literal"><span class="pre">-jump-threading</span></code>: Jump Threading</a></li>
+<li><a class="reference internal" href="#lcssa-loop-closed-ssa-form-pass" id="id69"><code class="docutils literal"><span class="pre">-lcssa</span></code>: Loop-Closed SSA Form Pass</a></li>
+<li><a class="reference internal" href="#licm-loop-invariant-code-motion" id="id70"><code class="docutils literal"><span class="pre">-licm</span></code>: Loop Invariant Code Motion</a></li>
+<li><a class="reference internal" href="#loop-deletion-delete-dead-loops" id="id71"><code class="docutils literal"><span class="pre">-loop-deletion</span></code>: Delete dead loops</a></li>
+<li><a class="reference internal" href="#loop-extract-extract-loops-into-new-functions" id="id72"><code class="docutils literal"><span class="pre">-loop-extract</span></code>: Extract loops into new functions</a></li>
+<li><a class="reference internal" href="#loop-extract-single-extract-at-most-one-loop-into-a-new-function" id="id73"><code class="docutils literal"><span class="pre">-loop-extract-single</span></code>: Extract at most one loop into a new function</a></li>
+<li><a class="reference internal" href="#loop-reduce-loop-strength-reduction" id="id74"><code class="docutils literal"><span class="pre">-loop-reduce</span></code>: Loop Strength Reduction</a></li>
+<li><a class="reference internal" href="#loop-rotate-rotate-loops" id="id75"><code class="docutils literal"><span class="pre">-loop-rotate</span></code>: Rotate Loops</a></li>
+<li><a class="reference internal" href="#loop-simplify-canonicalize-natural-loops" id="id76"><code class="docutils literal"><span class="pre">-loop-simplify</span></code>: Canonicalize natural loops</a></li>
+<li><a class="reference internal" href="#loop-unroll-unroll-loops" id="id77"><code class="docutils literal"><span class="pre">-loop-unroll</span></code>: Unroll loops</a></li>
+<li><a class="reference internal" href="#loop-unswitch-unswitch-loops" id="id78"><code class="docutils literal"><span class="pre">-loop-unswitch</span></code>: Unswitch loops</a></li>
+<li><a class="reference internal" href="#loweratomic-lower-atomic-intrinsics-to-non-atomic-form" id="id79"><code class="docutils literal"><span class="pre">-loweratomic</span></code>: Lower atomic intrinsics to non-atomic form</a></li>
+<li><a class="reference internal" href="#lowerinvoke-lower-invokes-to-calls-for-unwindless-code-generators" id="id80"><code class="docutils literal"><span class="pre">-lowerinvoke</span></code>: Lower invokes to calls, for unwindless code generators</a></li>
+<li><a class="reference internal" href="#lowerswitch-lower-switchinsts-to-branches" id="id81"><code class="docutils literal"><span class="pre">-lowerswitch</span></code>: Lower <code class="docutils literal"><span class="pre">SwitchInst</span></code>s to branches</a></li>
+<li><a class="reference internal" href="#mem2reg-promote-memory-to-register" id="id82"><code class="docutils literal"><span class="pre">-mem2reg</span></code>: Promote Memory to Register</a></li>
+<li><a class="reference internal" href="#memcpyopt-memcpy-optimization" id="id83"><code class="docutils literal"><span class="pre">-memcpyopt</span></code>: MemCpy Optimization</a></li>
+<li><a class="reference internal" href="#mergefunc-merge-functions" id="id84"><code class="docutils literal"><span class="pre">-mergefunc</span></code>: Merge Functions</a></li>
+<li><a class="reference internal" href="#mergereturn-unify-function-exit-nodes" id="id85"><code class="docutils literal"><span class="pre">-mergereturn</span></code>: Unify function exit nodes</a></li>
+<li><a class="reference internal" href="#partial-inliner-partial-inliner" id="id86"><code class="docutils literal"><span class="pre">-partial-inliner</span></code>: Partial Inliner</a></li>
+<li><a class="reference internal" href="#prune-eh-remove-unused-exception-handling-info" id="id87"><code class="docutils literal"><span class="pre">-prune-eh</span></code>: Remove unused exception handling info</a></li>
+<li><a class="reference internal" href="#reassociate-reassociate-expressions" id="id88"><code class="docutils literal"><span class="pre">-reassociate</span></code>: Reassociate expressions</a></li>
+<li><a class="reference internal" href="#reg2mem-demote-all-values-to-stack-slots" id="id89"><code class="docutils literal"><span class="pre">-reg2mem</span></code>: Demote all values to stack slots</a></li>
+<li><a class="reference internal" href="#sroa-scalar-replacement-of-aggregates" id="id90"><code class="docutils literal"><span class="pre">-sroa</span></code>: Scalar Replacement of Aggregates</a></li>
+<li><a class="reference internal" href="#sccp-sparse-conditional-constant-propagation" id="id91"><code class="docutils literal"><span class="pre">-sccp</span></code>: Sparse Conditional Constant Propagation</a></li>
+<li><a class="reference internal" href="#simplifycfg-simplify-the-cfg" id="id92"><code class="docutils literal"><span class="pre">-simplifycfg</span></code>: Simplify the CFG</a></li>
+<li><a class="reference internal" href="#sink-code-sinking" id="id93"><code class="docutils literal"><span class="pre">-sink</span></code>: Code sinking</a></li>
+<li><a class="reference internal" href="#strip-strip-all-symbols-from-a-module" id="id94"><code class="docutils literal"><span class="pre">-strip</span></code>: Strip all symbols from a module</a></li>
+<li><a class="reference internal" href="#strip-dead-debug-info-strip-debug-info-for-unused-symbols" id="id95"><code class="docutils literal"><span class="pre">-strip-dead-debug-info</span></code>: Strip debug info for unused symbols</a></li>
+<li><a class="reference internal" href="#strip-dead-prototypes-strip-unused-function-prototypes" id="id96"><code class="docutils literal"><span class="pre">-strip-dead-prototypes</span></code>: Strip Unused Function Prototypes</a></li>
+<li><a class="reference internal" href="#strip-debug-declare-strip-all-llvm-dbg-declare-intrinsics" id="id97"><code class="docutils literal"><span class="pre">-strip-debug-declare</span></code>: Strip all <code class="docutils literal"><span class="pre">llvm.dbg.declare</span></code> intrinsics</a></li>
+<li><a class="reference internal" href="#strip-nondebug-strip-all-symbols-except-dbg-symbols-from-a-module" id="id98"><code class="docutils literal"><span class="pre">-strip-nondebug</span></code>: Strip all symbols, except dbg symbols, from a module</a></li>
+<li><a class="reference internal" href="#tailcallelim-tail-call-elimination" id="id99"><code class="docutils literal"><span class="pre">-tailcallelim</span></code>: Tail Call Elimination</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#utility-passes" id="id100">Utility Passes</a><ul>
+<li><a class="reference internal" href="#deadarghax0r-dead-argument-hacking-bugpoint-use-only-do-not-use" id="id101"><code class="docutils literal"><span class="pre">-deadarghaX0r</span></code>: Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)</a></li>
+<li><a class="reference internal" href="#extract-blocks-extract-basic-blocks-from-module-for-bugpoint-use" id="id102"><code class="docutils literal"><span class="pre">-extract-blocks</span></code>: Extract Basic Blocks From Module (for bugpoint use)</a></li>
+<li><a class="reference internal" href="#instnamer-assign-names-to-anonymous-instructions" id="id103"><code class="docutils literal"><span class="pre">-instnamer</span></code>: Assign names to anonymous instructions</a></li>
+<li><a class="reference internal" href="#verify-module-verifier" id="id104"><code class="docutils literal"><span class="pre">-verify</span></code>: Module Verifier</a></li>
+<li><a class="reference internal" href="#view-cfg-view-cfg-of-function" id="id105"><code class="docutils literal"><span class="pre">-view-cfg</span></code>: View CFG of function</a></li>
+<li><a class="reference internal" href="#view-cfg-only-view-cfg-of-function-with-no-function-bodies" id="id106"><code class="docutils literal"><span class="pre">-view-cfg-only</span></code>: View CFG of function (with no function bodies)</a></li>
+<li><a class="reference internal" href="#view-dom-view-dominance-tree-of-function" id="id107"><code class="docutils literal"><span class="pre">-view-dom</span></code>: View dominance tree of function</a></li>
+<li><a class="reference internal" href="#view-dom-only-view-dominance-tree-of-function-with-no-function-bodies" id="id108"><code class="docutils literal"><span class="pre">-view-dom-only</span></code>: View dominance tree of function (with no function bodies)</a></li>
+<li><a class="reference internal" href="#view-postdom-view-postdominance-tree-of-function" id="id109"><code class="docutils literal"><span class="pre">-view-postdom</span></code>: View postdominance tree of function</a></li>
+<li><a class="reference internal" href="#view-postdom-only-view-postdominance-tree-of-function-with-no-function-bodies" id="id110"><code class="docutils literal"><span class="pre">-view-postdom-only</span></code>: View postdominance tree of function (with no function bodies)</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document serves as a high level summary of the optimization features that
+LLVM provides. Optimizations are implemented as Passes that traverse some
+portion of a program to either collect information or transform the program.
+The table below divides the passes that LLVM provides into three categories.
+Analysis passes compute information that other passes can use or for debugging
+or program visualization purposes. Transform passes can use (or invalidate)
+the analysis passes. Transform passes all mutate the program in some way.
+Utility passes provides some utility but don’t otherwise fit categorization.
+For example passes to extract functions to bitcode or write a module to bitcode
+are neither analysis nor transform passes. The table of contents above
+provides a quick summary of each pass and links to the more complete pass
+description later in the document.</p>
+</div>
+<div class="section" id="analysis-passes">
+<h2><a class="toc-backref" href="#id2">Analysis Passes</a><a class="headerlink" href="#analysis-passes" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the LLVM Analysis Passes.</p>
+<div class="section" id="aa-eval-exhaustive-alias-analysis-precision-evaluator">
+<h3><a class="toc-backref" href="#id3"><code class="docutils literal"><span class="pre">-aa-eval</span></code>: Exhaustive Alias Analysis Precision Evaluator</a><a class="headerlink" href="#aa-eval-exhaustive-alias-analysis-precision-evaluator" title="Permalink to this headline">¶</a></h3>
+<p>This is a simple N^2 alias analysis accuracy evaluator. Basically, for each
+function in the program, it simply queries to see how the alias analysis
+implementation answers alias queries between each pair of pointers in the
+function.</p>
+<p>This is inspired and adapted from code by: Naveen Neelakantam, Francesco
+Spadini, and Wojciech Stryjewski.</p>
+</div>
+<div class="section" id="basicaa-basic-alias-analysis-stateless-aa-impl">
+<h3><a class="toc-backref" href="#id4"><code class="docutils literal"><span class="pre">-basicaa</span></code>: Basic Alias Analysis (stateless AA impl)</a><a class="headerlink" href="#basicaa-basic-alias-analysis-stateless-aa-impl" title="Permalink to this headline">¶</a></h3>
+<p>A basic alias analysis pass that implements identities (two different globals
+cannot alias, etc), but does no stateful analysis.</p>
+</div>
+<div class="section" id="basiccg-basic-callgraph-construction">
+<h3><a class="toc-backref" href="#id5"><code class="docutils literal"><span class="pre">-basiccg</span></code>: Basic CallGraph Construction</a><a class="headerlink" href="#basiccg-basic-callgraph-construction" title="Permalink to this headline">¶</a></h3>
+<p>Yet to be written.</p>
+</div>
+<div class="section" id="count-aa-count-alias-analysis-query-responses">
+<h3><a class="toc-backref" href="#id6"><code class="docutils literal"><span class="pre">-count-aa</span></code>: Count Alias Analysis Query Responses</a><a class="headerlink" href="#count-aa-count-alias-analysis-query-responses" title="Permalink to this headline">¶</a></h3>
+<p>A pass which can be used to count how many alias queries are being made and how
+the alias analysis implementation being used responds.</p>
+</div>
+<div class="section" id="da-dependence-analysis">
+<h3><a class="toc-backref" href="#id7"><code class="docutils literal"><span class="pre">-da</span></code>: Dependence Analysis</a><a class="headerlink" href="#da-dependence-analysis" title="Permalink to this headline">¶</a></h3>
+<p>Dependence analysis framework, which is used to detect dependences in memory
+accesses.</p>
+</div>
+<div class="section" id="debug-aa-aa-use-debugger">
+<h3><a class="toc-backref" href="#id8"><code class="docutils literal"><span class="pre">-debug-aa</span></code>: AA use debugger</a><a class="headerlink" href="#debug-aa-aa-use-debugger" title="Permalink to this headline">¶</a></h3>
+<p>This simple pass checks alias analysis users to ensure that if they create a
+new value, they do not query AA without informing it of the value. It acts as
+a shim over any other AA pass you want.</p>
+<p>Yes keeping track of every value in the program is expensive, but this is a
+debugging pass.</p>
+</div>
+<div class="section" id="domfrontier-dominance-frontier-construction">
+<h3><a class="toc-backref" href="#id9"><code class="docutils literal"><span class="pre">-domfrontier</span></code>: Dominance Frontier Construction</a><a class="headerlink" href="#domfrontier-dominance-frontier-construction" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a simple dominator construction algorithm for finding forward
+dominator frontiers.</p>
+</div>
+<div class="section" id="domtree-dominator-tree-construction">
+<h3><a class="toc-backref" href="#id10"><code class="docutils literal"><span class="pre">-domtree</span></code>: Dominator Tree Construction</a><a class="headerlink" href="#domtree-dominator-tree-construction" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a simple dominator construction algorithm for finding forward
+dominators.</p>
+</div>
+<div class="section" id="dot-callgraph-print-call-graph-to-dot-file">
+<h3><a class="toc-backref" href="#id11"><code class="docutils literal"><span class="pre">-dot-callgraph</span></code>: Print Call Graph to “dot” file</a><a class="headerlink" href="#dot-callgraph-print-call-graph-to-dot-file" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints the call graph into a <code class="docutils literal"><span class="pre">.dot</span></code>
+graph. This graph can then be processed with the “dot” tool to convert it to
+postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-cfg-print-cfg-of-function-to-dot-file">
+<h3><a class="toc-backref" href="#id12"><code class="docutils literal"><span class="pre">-dot-cfg</span></code>: Print CFG of function to “dot” file</a><a class="headerlink" href="#dot-cfg-print-cfg-of-function-to-dot-file" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints the control flow graph into a
+<code class="docutils literal"><span class="pre">.dot</span></code> graph. This graph can then be processed with the <strong class="program">dot</strong> tool
+to convert it to postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-cfg-only-print-cfg-of-function-to-dot-file-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id13"><code class="docutils literal"><span class="pre">-dot-cfg-only</span></code>: Print CFG of function to “dot” file (with no function bodies)</a><a class="headerlink" href="#dot-cfg-only-print-cfg-of-function-to-dot-file-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints the control flow graph into a
+<code class="docutils literal"><span class="pre">.dot</span></code> graph, omitting the function bodies. This graph can then be processed
+with the <strong class="program">dot</strong> tool to convert it to postscript or some other suitable
+format.</p>
+</div>
+<div class="section" id="dot-dom-print-dominance-tree-of-function-to-dot-file">
+<h3><a class="toc-backref" href="#id14"><code class="docutils literal"><span class="pre">-dot-dom</span></code>: Print dominance tree of function to “dot” file</a><a class="headerlink" href="#dot-dom-print-dominance-tree-of-function-to-dot-file" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints the dominator tree into a <code class="docutils literal"><span class="pre">.dot</span></code>
+graph. This graph can then be processed with the <strong class="program">dot</strong> tool to
+convert it to postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-dom-only-print-dominance-tree-of-function-to-dot-file-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id15"><code class="docutils literal"><span class="pre">-dot-dom-only</span></code>: Print dominance tree of function to “dot” file (with no function bodies)</a><a class="headerlink" href="#dot-dom-only-print-dominance-tree-of-function-to-dot-file-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints the dominator tree into a <code class="docutils literal"><span class="pre">.dot</span></code>
+graph, omitting the function bodies. This graph can then be processed with the
+<strong class="program">dot</strong> tool to convert it to postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-postdom-print-postdominance-tree-of-function-to-dot-file">
+<h3><a class="toc-backref" href="#id16"><code class="docutils literal"><span class="pre">-dot-postdom</span></code>: Print postdominance tree of function to “dot” file</a><a class="headerlink" href="#dot-postdom-print-postdominance-tree-of-function-to-dot-file" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints the post dominator tree into a
+<code class="docutils literal"><span class="pre">.dot</span></code> graph. This graph can then be processed with the <strong class="program">dot</strong> tool
+to convert it to postscript or some other suitable format.</p>
+</div>
+<div class="section" id="dot-postdom-only-print-postdominance-tree-of-function-to-dot-file-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id17"><code class="docutils literal"><span class="pre">-dot-postdom-only</span></code>: Print postdominance tree of function to “dot” file (with no function bodies)</a><a class="headerlink" href="#dot-postdom-only-print-postdominance-tree-of-function-to-dot-file-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints the post dominator tree into a
+<code class="docutils literal"><span class="pre">.dot</span></code> graph, omitting the function bodies. This graph can then be processed
+with the <strong class="program">dot</strong> tool to convert it to postscript or some other suitable
+format.</p>
+</div>
+<div class="section" id="globalsmodref-aa-simple-mod-ref-analysis-for-globals">
+<h3><a class="toc-backref" href="#id18"><code class="docutils literal"><span class="pre">-globalsmodref-aa</span></code>: Simple mod/ref analysis for globals</a><a class="headerlink" href="#globalsmodref-aa-simple-mod-ref-analysis-for-globals" title="Permalink to this headline">¶</a></h3>
+<p>This simple pass provides alias and mod/ref information for global values that
+do not have their address taken, and keeps track of whether functions read or
+write memory (are “pure”). For this simple (but very common) case, we can
+provide pretty accurate and useful information.</p>
+</div>
+<div class="section" id="instcount-counts-the-various-types-of-instructions">
+<h3><a class="toc-backref" href="#id19"><code class="docutils literal"><span class="pre">-instcount</span></code>: Counts the various types of <code class="docutils literal"><span class="pre">Instruction</span></code>s</a><a class="headerlink" href="#instcount-counts-the-various-types-of-instructions" title="Permalink to this headline">¶</a></h3>
+<p>This pass collects the count of all instructions and reports them.</p>
+</div>
+<div class="section" id="intervals-interval-partition-construction">
+<h3><a class="toc-backref" href="#id20"><code class="docutils literal"><span class="pre">-intervals</span></code>: Interval Partition Construction</a><a class="headerlink" href="#intervals-interval-partition-construction" title="Permalink to this headline">¶</a></h3>
+<p>This analysis calculates and represents the interval partition of a function,
+or a preexisting interval partition.</p>
+<p>In this way, the interval partition may be used to reduce a flow graph down to
+its degenerate single node interval partition (unless it is irreducible).</p>
+</div>
+<div class="section" id="iv-users-induction-variable-users">
+<h3><a class="toc-backref" href="#id21"><code class="docutils literal"><span class="pre">-iv-users</span></code>: Induction Variable Users</a><a class="headerlink" href="#iv-users-induction-variable-users" title="Permalink to this headline">¶</a></h3>
+<p>Bookkeeping for “interesting” users of expressions computed from induction
+variables.</p>
+</div>
+<div class="section" id="lazy-value-info-lazy-value-information-analysis">
+<h3><a class="toc-backref" href="#id22"><code class="docutils literal"><span class="pre">-lazy-value-info</span></code>: Lazy Value Information Analysis</a><a class="headerlink" href="#lazy-value-info-lazy-value-information-analysis" title="Permalink to this headline">¶</a></h3>
+<p>Interface for lazy computation of value constraint information.</p>
+</div>
+<div class="section" id="libcall-aa-libcall-alias-analysis">
+<h3><a class="toc-backref" href="#id23"><code class="docutils literal"><span class="pre">-libcall-aa</span></code>: LibCall Alias Analysis</a><a class="headerlink" href="#libcall-aa-libcall-alias-analysis" title="Permalink to this headline">¶</a></h3>
+<p>LibCall Alias Analysis.</p>
+</div>
+<div class="section" id="lint-statically-lint-checks-llvm-ir">
+<h3><a class="toc-backref" href="#id24"><code class="docutils literal"><span class="pre">-lint</span></code>: Statically lint-checks LLVM IR</a><a class="headerlink" href="#lint-statically-lint-checks-llvm-ir" title="Permalink to this headline">¶</a></h3>
+<p>This pass statically checks for common and easily-identified constructs which
+produce undefined or likely unintended behavior in LLVM IR.</p>
+<p>It is not a guarantee of correctness, in two ways. First, it isn’t
+comprehensive. There are checks which could be done statically which are not
+yet implemented. Some of these are indicated by TODO comments, but those
+aren’t comprehensive either. Second, many conditions cannot be checked
+statically. This pass does no dynamic instrumentation, so it can’t check for
+all possible problems.</p>
+<p>Another limitation is that it assumes all code will be executed. A store
+through a null pointer in a basic block which is never reached is harmless, but
+this pass will warn about it anyway.</p>
+<p>Optimization passes may make conditions that this pass checks for more or less
+obvious. If an optimization pass appears to be introducing a warning, it may
+be that the optimization pass is merely exposing an existing condition in the
+code.</p>
+<p>This code may be run before <a class="reference internal" href="#passes-instcombine"><span class="std std-ref">instcombine</span></a>. In many
+cases, instcombine checks for the same kinds of things and turns instructions
+with undefined behavior into unreachable (or equivalent). Because of this,
+this pass makes some effort to look through bitcasts and so on.</p>
+</div>
+<div class="section" id="loops-natural-loop-information">
+<h3><a class="toc-backref" href="#id25"><code class="docutils literal"><span class="pre">-loops</span></code>: Natural Loop Information</a><a class="headerlink" href="#loops-natural-loop-information" title="Permalink to this headline">¶</a></h3>
+<p>This analysis is used to identify natural loops and determine the loop depth of
+various nodes of the CFG. Note that the loops identified may actually be
+several natural loops that share the same header node... not just a single
+natural loop.</p>
+</div>
+<div class="section" id="memdep-memory-dependence-analysis">
+<h3><a class="toc-backref" href="#id26"><code class="docutils literal"><span class="pre">-memdep</span></code>: Memory Dependence Analysis</a><a class="headerlink" href="#memdep-memory-dependence-analysis" title="Permalink to this headline">¶</a></h3>
+<p>An analysis that determines, for a given memory operation, what preceding
+memory operations it depends on. It builds on alias analysis information, and
+tries to provide a lazy, caching interface to a common kind of alias
+information query.</p>
+</div>
+<div class="section" id="module-debuginfo-decodes-module-level-debug-info">
+<h3><a class="toc-backref" href="#id27"><code class="docutils literal"><span class="pre">-module-debuginfo</span></code>: Decodes module-level debug info</a><a class="headerlink" href="#module-debuginfo-decodes-module-level-debug-info" title="Permalink to this headline">¶</a></h3>
+<p>This pass decodes the debug info metadata in a module and prints in a
+(sufficiently-prepared-) human-readable form.</p>
+<p>For example, run this pass from <code class="docutils literal"><span class="pre">opt</span></code> along with the <code class="docutils literal"><span class="pre">-analyze</span></code> option, and
+it’ll print to standard output.</p>
+</div>
+<div class="section" id="postdomfrontier-post-dominance-frontier-construction">
+<h3><a class="toc-backref" href="#id28"><code class="docutils literal"><span class="pre">-postdomfrontier</span></code>: Post-Dominance Frontier Construction</a><a class="headerlink" href="#postdomfrontier-post-dominance-frontier-construction" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a simple post-dominator construction algorithm for finding
+post-dominator frontiers.</p>
+</div>
+<div class="section" id="postdomtree-post-dominator-tree-construction">
+<h3><a class="toc-backref" href="#id29"><code class="docutils literal"><span class="pre">-postdomtree</span></code>: Post-Dominator Tree Construction</a><a class="headerlink" href="#postdomtree-post-dominator-tree-construction" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a simple post-dominator construction algorithm for finding
+post-dominators.</p>
+</div>
+<div class="section" id="print-alias-sets-alias-set-printer">
+<h3><a class="toc-backref" href="#id30"><code class="docutils literal"><span class="pre">-print-alias-sets</span></code>: Alias Set Printer</a><a class="headerlink" href="#print-alias-sets-alias-set-printer" title="Permalink to this headline">¶</a></h3>
+<p>Yet to be written.</p>
+</div>
+<div class="section" id="print-callgraph-print-a-call-graph">
+<h3><a class="toc-backref" href="#id31"><code class="docutils literal"><span class="pre">-print-callgraph</span></code>: Print a call graph</a><a class="headerlink" href="#print-callgraph-print-a-call-graph" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints the call graph to standard error
+in a human-readable form.</p>
+</div>
+<div class="section" id="print-callgraph-sccs-print-sccs-of-the-call-graph">
+<h3><a class="toc-backref" href="#id32"><code class="docutils literal"><span class="pre">-print-callgraph-sccs</span></code>: Print SCCs of the Call Graph</a><a class="headerlink" href="#print-callgraph-sccs-print-sccs-of-the-call-graph" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints the SCCs of the call graph to
+standard error in a human-readable form.</p>
+</div>
+<div class="section" id="print-cfg-sccs-print-sccs-of-each-function-cfg">
+<h3><a class="toc-backref" href="#id33"><code class="docutils literal"><span class="pre">-print-cfg-sccs</span></code>: Print SCCs of each function CFG</a><a class="headerlink" href="#print-cfg-sccs-print-sccs-of-each-function-cfg" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, printsthe SCCs of each function CFG to
+standard error in a human-readable fom.</p>
+</div>
+<div class="section" id="print-dom-info-dominator-info-printer">
+<h3><a class="toc-backref" href="#id34"><code class="docutils literal"><span class="pre">-print-dom-info</span></code>: Dominator Info Printer</a><a class="headerlink" href="#print-dom-info-dominator-info-printer" title="Permalink to this headline">¶</a></h3>
+<p>Dominator Info Printer.</p>
+</div>
+<div class="section" id="print-externalfnconstants-print-external-fn-callsites-passed-constants">
+<h3><a class="toc-backref" href="#id35"><code class="docutils literal"><span class="pre">-print-externalfnconstants</span></code>: Print external fn callsites passed constants</a><a class="headerlink" href="#print-externalfnconstants-print-external-fn-callsites-passed-constants" title="Permalink to this headline">¶</a></h3>
+<p>This pass, only available in <code class="docutils literal"><span class="pre">opt</span></code>, prints out call sites to external
+functions that are called with constant arguments. This can be useful when
+looking for standard library functions we should constant fold or handle in
+alias analyses.</p>
+</div>
+<div class="section" id="print-function-print-function-to-stderr">
+<h3><a class="toc-backref" href="#id36"><code class="docutils literal"><span class="pre">-print-function</span></code>: Print function to stderr</a><a class="headerlink" href="#print-function-print-function-to-stderr" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal"><span class="pre">PrintFunctionPass</span></code> class is designed to be pipelined with other
+<code class="docutils literal"><span class="pre">FunctionPasses</span></code>, and prints out the functions of the module as they are
+processed.</p>
+</div>
+<div class="section" id="print-module-print-module-to-stderr">
+<h3><a class="toc-backref" href="#id37"><code class="docutils literal"><span class="pre">-print-module</span></code>: Print module to stderr</a><a class="headerlink" href="#print-module-print-module-to-stderr" title="Permalink to this headline">¶</a></h3>
+<p>This pass simply prints out the entire module when it is executed.</p>
+</div>
+<div class="section" id="print-used-types-find-used-types">
+<span id="passes-print-used-types"></span><h3><a class="toc-backref" href="#id38"><code class="docutils literal"><span class="pre">-print-used-types</span></code>: Find Used Types</a><a class="headerlink" href="#print-used-types-find-used-types" title="Permalink to this headline">¶</a></h3>
+<p>This pass is used to seek out all of the types in use by the program. Note
+that this analysis explicitly does not include types only used by the symbol
+table.</p>
+</div>
+<div class="section" id="regions-detect-single-entry-single-exit-regions">
+<h3><a class="toc-backref" href="#id39"><code class="docutils literal"><span class="pre">-regions</span></code>: Detect single entry single exit regions</a><a class="headerlink" href="#regions-detect-single-entry-single-exit-regions" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal"><span class="pre">RegionInfo</span></code> pass detects single entry single exit regions in a function,
+where a region is defined as any subgraph that is connected to the remaining
+graph at only two spots. Furthermore, an hierarchical region tree is built.</p>
+</div>
+<div class="section" id="scalar-evolution-scalar-evolution-analysis">
+<h3><a class="toc-backref" href="#id40"><code class="docutils literal"><span class="pre">-scalar-evolution</span></code>: Scalar Evolution Analysis</a><a class="headerlink" href="#scalar-evolution-scalar-evolution-analysis" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal"><span class="pre">ScalarEvolution</span></code> analysis can be used to analyze and catagorize scalar
+expressions in loops. It specializes in recognizing general induction
+variables, representing them with the abstract and opaque <code class="docutils literal"><span class="pre">SCEV</span></code> class.
+Given this analysis, trip counts of loops and other important properties can be
+obtained.</p>
+<p>This analysis is primarily useful for induction variable substitution and
+strength reduction.</p>
+</div>
+<div class="section" id="scev-aa-scalarevolution-based-alias-analysis">
+<h3><a class="toc-backref" href="#id41"><code class="docutils literal"><span class="pre">-scev-aa</span></code>: ScalarEvolution-based Alias Analysis</a><a class="headerlink" href="#scev-aa-scalarevolution-based-alias-analysis" title="Permalink to this headline">¶</a></h3>
+<p>Simple alias analysis implemented in terms of <code class="docutils literal"><span class="pre">ScalarEvolution</span></code> queries.</p>
+<p>This differs from traditional loop dependence analysis in that it tests for
+dependencies within a single iteration of a loop, rather than dependencies
+between different iterations.</p>
+<p><code class="docutils literal"><span class="pre">ScalarEvolution</span></code> has a more complete understanding of pointer arithmetic
+than <code class="docutils literal"><span class="pre">BasicAliasAnalysis</span></code>‘ collection of ad-hoc analyses.</p>
+</div>
+<div class="section" id="targetdata-target-data-layout">
+<h3><a class="toc-backref" href="#id42"><code class="docutils literal"><span class="pre">-targetdata</span></code>: Target Data Layout</a><a class="headerlink" href="#targetdata-target-data-layout" title="Permalink to this headline">¶</a></h3>
+<p>Provides other passes access to information on how the size and alignment
+required by the target ABI for various data types.</p>
+</div>
+</div>
+<div class="section" id="transform-passes">
+<h2><a class="toc-backref" href="#id43">Transform Passes</a><a class="headerlink" href="#transform-passes" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the LLVM Transform Passes.</p>
+<div class="section" id="adce-aggressive-dead-code-elimination">
+<h3><a class="toc-backref" href="#id44"><code class="docutils literal"><span class="pre">-adce</span></code>: Aggressive Dead Code Elimination</a><a class="headerlink" href="#adce-aggressive-dead-code-elimination" title="Permalink to this headline">¶</a></h3>
+<p>ADCE aggressively tries to eliminate code. This pass is similar to <a class="reference internal" href="#passes-dce"><span class="std std-ref">DCE</span></a> but it assumes that values are dead until proven otherwise. This
+is similar to <a class="reference internal" href="#passes-sccp"><span class="std std-ref">SCCP</span></a>, except applied to the liveness of
+values.</p>
+</div>
+<div class="section" id="always-inline-inliner-for-always-inline-functions">
+<h3><a class="toc-backref" href="#id45"><code class="docutils literal"><span class="pre">-always-inline</span></code>: Inliner for <code class="docutils literal"><span class="pre">always_inline</span></code> functions</a><a class="headerlink" href="#always-inline-inliner-for-always-inline-functions" title="Permalink to this headline">¶</a></h3>
+<p>A custom inliner that handles only functions that are marked as “always
+inline”.</p>
+</div>
+<div class="section" id="argpromotion-promote-by-reference-arguments-to-scalars">
+<h3><a class="toc-backref" href="#id46"><code class="docutils literal"><span class="pre">-argpromotion</span></code>: Promote ‘by reference’ arguments to scalars</a><a class="headerlink" href="#argpromotion-promote-by-reference-arguments-to-scalars" title="Permalink to this headline">¶</a></h3>
+<p>This pass promotes “by reference” arguments to be “by value” arguments. In
+practice, this means looking for internal functions that have pointer
+arguments. If it can prove, through the use of alias analysis, that an
+argument is <em>only</em> loaded, then it can pass the value into the function instead
+of the address of the value. This can cause recursive simplification of code
+and lead to the elimination of allocas (especially in C++ template code like
+the STL).</p>
+<p>This pass also handles aggregate arguments that are passed into a function,
+scalarizing them if the elements of the aggregate are only loaded. Note that
+it refuses to scalarize aggregates which would require passing in more than
+three operands to the function, because passing thousands of operands for a
+large array or structure is unprofitable!</p>
+<p>Note that this transformation could also be done for arguments that are only
+stored to (returning the value instead), but does not currently. This case
+would be best handled when and if LLVM starts supporting multiple return values
+from functions.</p>
+</div>
+<div class="section" id="bb-vectorize-basic-block-vectorization">
+<h3><a class="toc-backref" href="#id47"><code class="docutils literal"><span class="pre">-bb-vectorize</span></code>: Basic-Block Vectorization</a><a class="headerlink" href="#bb-vectorize-basic-block-vectorization" title="Permalink to this headline">¶</a></h3>
+<p>This pass combines instructions inside basic blocks to form vector
+instructions. It iterates over each basic block, attempting to pair compatible
+instructions, repeating this process until no additional pairs are selected for
+vectorization. When the outputs of some pair of compatible instructions are
+used as inputs by some other pair of compatible instructions, those pairs are
+part of a potential vectorization chain. Instruction pairs are only fused into
+vector instructions when they are part of a chain longer than some threshold
+length. Moreover, the pass attempts to find the best possible chain for each
+pair of compatible instructions. These heuristics are intended to prevent
+vectorization in cases where it would not yield a performance increase of the
+resulting code.</p>
+</div>
+<div class="section" id="block-placement-profile-guided-basic-block-placement">
+<h3><a class="toc-backref" href="#id48"><code class="docutils literal"><span class="pre">-block-placement</span></code>: Profile Guided Basic Block Placement</a><a class="headerlink" href="#block-placement-profile-guided-basic-block-placement" title="Permalink to this headline">¶</a></h3>
+<p>This pass is a very simple profile guided basic block placement algorithm. The
+idea is to put frequently executed blocks together at the start of the function
+and hopefully increase the number of fall-through conditional branches. If
+there is no profile information for a particular function, this pass basically
+orders blocks in depth-first order.</p>
+</div>
+<div class="section" id="break-crit-edges-break-critical-edges-in-cfg">
+<h3><a class="toc-backref" href="#id49"><code class="docutils literal"><span class="pre">-break-crit-edges</span></code>: Break critical edges in CFG</a><a class="headerlink" href="#break-crit-edges-break-critical-edges-in-cfg" title="Permalink to this headline">¶</a></h3>
+<p>Break all of the critical edges in the CFG by inserting a dummy basic block.
+It may be “required” by passes that cannot deal with critical edges. This
+transformation obviously invalidates the CFG, but can update forward dominator
+(set, immediate dominators, tree, and frontier) information.</p>
+</div>
+<div class="section" id="codegenprepare-optimize-for-code-generation">
+<h3><a class="toc-backref" href="#id50"><code class="docutils literal"><span class="pre">-codegenprepare</span></code>: Optimize for code generation</a><a class="headerlink" href="#codegenprepare-optimize-for-code-generation" title="Permalink to this headline">¶</a></h3>
+<p>This pass munges the code in the input function to better prepare it for
+SelectionDAG-based code generation. This works around limitations in its
+basic-block-at-a-time approach. It should eventually be removed.</p>
+</div>
+<div class="section" id="constmerge-merge-duplicate-global-constants">
+<h3><a class="toc-backref" href="#id51"><code class="docutils literal"><span class="pre">-constmerge</span></code>: Merge Duplicate Global Constants</a><a class="headerlink" href="#constmerge-merge-duplicate-global-constants" title="Permalink to this headline">¶</a></h3>
+<p>Merges duplicate global constants together into a single constant that is
+shared. This is useful because some passes (i.e., TraceValues) insert a lot of
+string constants into the program, regardless of whether or not an existing
+string is available.</p>
+</div>
+<div class="section" id="constprop-simple-constant-propagation">
+<h3><a class="toc-backref" href="#id52"><code class="docutils literal"><span class="pre">-constprop</span></code>: Simple constant propagation</a><a class="headerlink" href="#constprop-simple-constant-propagation" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements constant propagation and merging. It looks for
+instructions involving only constant operands and replaces them with a constant
+value instead of an instruction. For example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></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>becomes</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="k">i32</span> <span class="m">3</span>
+</pre></div>
+</div>
+<p>NOTE: this pass has a habit of making definitions be dead. It is a good idea
+to run a <a class="reference internal" href="#passes-die"><span class="std std-ref">Dead Instruction Elimination</span></a> pass sometime after
+running this pass.</p>
+</div>
+<div class="section" id="dce-dead-code-elimination">
+<span id="passes-dce"></span><h3><a class="toc-backref" href="#id53"><code class="docutils literal"><span class="pre">-dce</span></code>: Dead Code Elimination</a><a class="headerlink" href="#dce-dead-code-elimination" title="Permalink to this headline">¶</a></h3>
+<p>Dead code elimination is similar to <a class="reference internal" href="#passes-die"><span class="std std-ref">dead instruction elimination</span></a>, but it rechecks instructions that were used by removed
+instructions to see if they are newly dead.</p>
+</div>
+<div class="section" id="deadargelim-dead-argument-elimination">
+<h3><a class="toc-backref" href="#id54"><code class="docutils literal"><span class="pre">-deadargelim</span></code>: Dead Argument Elimination</a><a class="headerlink" href="#deadargelim-dead-argument-elimination" title="Permalink to this headline">¶</a></h3>
+<p>This pass deletes dead arguments from internal functions. Dead argument
+elimination removes arguments which are directly dead, as well as arguments
+only passed into function calls as dead arguments of other functions. This
+pass also deletes dead arguments in a similar way.</p>
+<p>This pass is often useful as a cleanup pass to run after aggressive
+interprocedural passes, which add possibly-dead arguments.</p>
+</div>
+<div class="section" id="deadtypeelim-dead-type-elimination">
+<h3><a class="toc-backref" href="#id55"><code class="docutils literal"><span class="pre">-deadtypeelim</span></code>: Dead Type Elimination</a><a class="headerlink" href="#deadtypeelim-dead-type-elimination" title="Permalink to this headline">¶</a></h3>
+<p>This pass is used to cleanup the output of GCC. It eliminate names for types
+that are unused in the entire translation unit, using the <a class="reference internal" href="#passes-print-used-types"><span class="std std-ref">find used types</span></a> pass.</p>
+</div>
+<div class="section" id="die-dead-instruction-elimination">
+<span id="passes-die"></span><h3><a class="toc-backref" href="#id56"><code class="docutils literal"><span class="pre">-die</span></code>: Dead Instruction Elimination</a><a class="headerlink" href="#die-dead-instruction-elimination" title="Permalink to this headline">¶</a></h3>
+<p>Dead instruction elimination performs a single pass over the function, removing
+instructions that are obviously dead.</p>
+</div>
+<div class="section" id="dse-dead-store-elimination">
+<h3><a class="toc-backref" href="#id57"><code class="docutils literal"><span class="pre">-dse</span></code>: Dead Store Elimination</a><a class="headerlink" href="#dse-dead-store-elimination" title="Permalink to this headline">¶</a></h3>
+<p>A trivial dead store elimination that only considers basic-block local
+redundant stores.</p>
+</div>
+<div class="section" id="functionattrs-deduce-function-attributes">
+<span id="passes-functionattrs"></span><h3><a class="toc-backref" href="#id58"><code class="docutils literal"><span class="pre">-functionattrs</span></code>: Deduce function attributes</a><a class="headerlink" href="#functionattrs-deduce-function-attributes" title="Permalink to this headline">¶</a></h3>
+<p>A simple interprocedural pass which walks the call-graph, looking for functions
+which do not access or only read non-local memory, and marking them
+<code class="docutils literal"><span class="pre">readnone</span></code>/<code class="docutils literal"><span class="pre">readonly</span></code>. In addition, it marks function arguments (of
+pointer type) “<code class="docutils literal"><span class="pre">nocapture</span></code>” if a call to the function does not create any
+copies of the pointer value that outlive the call. This more or less means
+that the pointer is only dereferenced, and not returned from the function or
+stored in a global. This pass is implemented as a bottom-up traversal of the
+call-graph.</p>
+</div>
+<div class="section" id="globaldce-dead-global-elimination">
+<h3><a class="toc-backref" href="#id59"><code class="docutils literal"><span class="pre">-globaldce</span></code>: Dead Global Elimination</a><a class="headerlink" href="#globaldce-dead-global-elimination" title="Permalink to this headline">¶</a></h3>
+<p>This transform is designed to eliminate unreachable internal globals from the
+program. It uses an aggressive algorithm, searching out globals that are known
+to be alive. After it finds all of the globals which are needed, it deletes
+whatever is left over. This allows it to delete recursive chunks of the
+program which are unreachable.</p>
+</div>
+<div class="section" id="globalopt-global-variable-optimizer">
+<h3><a class="toc-backref" href="#id60"><code class="docutils literal"><span class="pre">-globalopt</span></code>: Global Variable Optimizer</a><a class="headerlink" href="#globalopt-global-variable-optimizer" title="Permalink to this headline">¶</a></h3>
+<p>This pass transforms simple global variables that never have their address
+taken. If obviously true, it marks read/write globals as constant, deletes
+variables only stored to, etc.</p>
+</div>
+<div class="section" id="gvn-global-value-numbering">
+<h3><a class="toc-backref" href="#id61"><code class="docutils literal"><span class="pre">-gvn</span></code>: Global Value Numbering</a><a class="headerlink" href="#gvn-global-value-numbering" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs global value numbering to eliminate fully and partially
+redundant instructions. It also performs redundant load elimination.</p>
+</div>
+<div class="section" id="indvars-canonicalize-induction-variables">
+<span id="passes-indvars"></span><h3><a class="toc-backref" href="#id62"><code class="docutils literal"><span class="pre">-indvars</span></code>: Canonicalize Induction Variables</a><a class="headerlink" href="#indvars-canonicalize-induction-variables" title="Permalink to this headline">¶</a></h3>
+<p>This transformation analyzes and transforms the induction variables (and
+computations derived from them) into simpler forms suitable for subsequent
+analysis and transformation.</p>
+<p>This transformation makes the following changes to each loop with an
+identifiable induction variable:</p>
+<ul class="simple">
+<li>All loops are transformed to have a <em>single</em> canonical induction variable
+which starts at zero and steps by one.</li>
+<li>The canonical induction variable is guaranteed to be the first PHI node in
+the loop header block.</li>
+<li>Any pointer arithmetic recurrences are raised to use array subscripts.</li>
+</ul>
+<p>If the trip count of a loop is computable, this pass also makes the following
+changes:</p>
+<ul>
+<li><p class="first">The exit condition for the loop is canonicalized to compare the induction
+value against the exit value. This turns loops like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">7</span><span class="p">;</span> <span class="n">i</span><span class="o">*</span><span class="n">i</span> <span class="o"><</span> <span class="mi">1000</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+
+<span class="n">into</span>
+</pre></div>
+</div>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="mi">25</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">Any use outside of the loop of an expression derived from the indvar is
+changed to compute the derived value outside of the loop, eliminating the
+dependence on the exit value of the induction variable. If the only purpose
+of the loop is to compute the exit value of some derived expression, this
+transformation will make the loop dead.</p>
+</li>
+</ul>
+<p>This transformation should be followed by strength reduction after all of the
+desired loop transformations have been performed. Additionally, on targets
+where it is profitable, the loop could be transformed to count down to zero
+(the “do loop” optimization).</p>
+</div>
+<div class="section" id="inline-function-integration-inlining">
+<h3><a class="toc-backref" href="#id63"><code class="docutils literal"><span class="pre">-inline</span></code>: Function Integration/Inlining</a><a class="headerlink" href="#inline-function-integration-inlining" title="Permalink to this headline">¶</a></h3>
+<p>Bottom-up inlining of functions into callees.</p>
+</div>
+<div class="section" id="instcombine-combine-redundant-instructions">
+<span id="passes-instcombine"></span><h3><a class="toc-backref" href="#id64"><code class="docutils literal"><span class="pre">-instcombine</span></code>: Combine redundant instructions</a><a class="headerlink" href="#instcombine-combine-redundant-instructions" title="Permalink to this headline">¶</a></h3>
+<p>Combine instructions to form fewer, simple instructions. This pass does not
+modify the CFG. This pass is where algebraic simplification happens.</p>
+<p>This pass combines things like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="nv">%Y</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%X</span><span class="p">,</span> <span class="m">1</span>
+<span class="nv">%Z</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%Y</span><span class="p">,</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>into:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span></span><span class="nv">%Z</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%X</span><span class="p">,</span> <span class="m">2</span>
+</pre></div>
+</div>
+<p>This is a simple worklist driven algorithm.</p>
+<p>This pass guarantees that the following canonicalizations are performed on the
+program:</p>
+<ol class="arabic simple">
+<li>If a binary operator has a constant operand, it is moved to the right-hand
+side.</li>
+<li>Bitwise operators with constant operands are always grouped so that shifts
+are performed first, then <code class="docutils literal"><span class="pre">or</span></code>s, then <code class="docutils literal"><span class="pre">and</span></code>s, then <code class="docutils literal"><span class="pre">xor</span></code>s.</li>
+<li>Compare instructions are converted from <code class="docutils literal"><span class="pre"><</span></code>, <code class="docutils literal"><span class="pre">></span></code>, <code class="docutils literal"><span class="pre">â¤</span></code>, or <code class="docutils literal"><span class="pre">â¥</span></code> to
+<code class="docutils literal"><span class="pre">=</span></code> or <code class="docutils literal"><span class="pre">â </span></code> if possible.</li>
+<li>All <code class="docutils literal"><span class="pre">cmp</span></code> instructions on boolean values are replaced with logical
+operations.</li>
+<li><code class="docutils literal"><span class="pre">add</span> <span class="pre">X,</span> <span class="pre">X</span></code> is represented as <code class="docutils literal"><span class="pre">mul</span> <span class="pre">X,</span> <span class="pre">2</span></code> â <code class="docutils literal"><span class="pre">shl</span> <span class="pre">X,</span> <span class="pre">1</span></code></li>
+<li>Multiplies with a constant power-of-two argument are transformed into
+shifts.</li>
+<li>⦠etc.</li>
+</ol>
+<p>This pass can also simplify calls to specific well-known function calls (e.g.
+runtime library functions). For example, a call <code class="docutils literal"><span class="pre">exit(3)</span></code> that occurs within
+the <code class="docutils literal"><span class="pre">main()</span></code> function can be transformed into simply <code class="docutils literal"><span class="pre">return</span> <span class="pre">3</span></code>. Whether or
+not library calls are simplified is controlled by the
+<a class="reference internal" href="#passes-functionattrs"><span class="std std-ref">-functionattrs</span></a> pass and LLVM’s knowledge of
+library calls on different targets.</p>
+</div>
+<div class="section" id="internalize-internalize-global-symbols">
+<h3><a class="toc-backref" href="#id65"><code class="docutils literal"><span class="pre">-internalize</span></code>: Internalize Global Symbols</a><a class="headerlink" href="#internalize-internalize-global-symbols" title="Permalink to this headline">¶</a></h3>
+<p>This pass loops over all of the functions in the input module, looking for a
+main function. If a main function is found, all other functions and all global
+variables with initializers are marked as internal.</p>
+</div>
+<div class="section" id="ipconstprop-interprocedural-constant-propagation">
+<h3><a class="toc-backref" href="#id66"><code class="docutils literal"><span class="pre">-ipconstprop</span></code>: Interprocedural constant propagation</a><a class="headerlink" href="#ipconstprop-interprocedural-constant-propagation" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements an <em>extremely</em> simple interprocedural constant propagation
+pass. It could certainly be improved in many different ways, like using a
+worklist. This pass makes arguments dead, but does not remove them. The
+existing dead argument elimination pass should be run after this to clean up
+the mess.</p>
+</div>
+<div class="section" id="ipsccp-interprocedural-sparse-conditional-constant-propagation">
+<h3><a class="toc-backref" href="#id67"><code class="docutils literal"><span class="pre">-ipsccp</span></code>: Interprocedural Sparse Conditional Constant Propagation</a><a class="headerlink" href="#ipsccp-interprocedural-sparse-conditional-constant-propagation" title="Permalink to this headline">¶</a></h3>
+<p>An interprocedural variant of <a class="reference internal" href="#passes-sccp"><span class="std std-ref">Sparse Conditional Constant Propagation</span></a>.</p>
+</div>
+<div class="section" id="jump-threading-jump-threading">
+<h3><a class="toc-backref" href="#id68"><code class="docutils literal"><span class="pre">-jump-threading</span></code>: Jump Threading</a><a class="headerlink" href="#jump-threading-jump-threading" title="Permalink to this headline">¶</a></h3>
+<p>Jump threading tries to find distinct threads of control flow running through a
+basic block. This pass looks at blocks that have multiple predecessors and
+multiple successors. If one or more of the predecessors of the block can be
+proven to always cause a jump to one of the successors, we forward the edge
+from the predecessor to the successor by duplicating the contents of this
+block.</p>
+<p>An example of when this can occur is code like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="p">()</span> <span class="p">{</span> <span class="p">...</span>
+ <span class="n">X</span> <span class="o">=</span> <span class="mi">4</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">X</span> <span class="o"><</span> <span class="mi">3</span><span class="p">)</span> <span class="p">{</span>
+</pre></div>
+</div>
+<p>In this case, the unconditional branch at the end of the first if can be
+revectored to the false side of the second if.</p>
+</div>
+<div class="section" id="lcssa-loop-closed-ssa-form-pass">
+<h3><a class="toc-backref" href="#id69"><code class="docutils literal"><span class="pre">-lcssa</span></code>: Loop-Closed SSA Form Pass</a><a class="headerlink" href="#lcssa-loop-closed-ssa-form-pass" title="Permalink to this headline">¶</a></h3>
+<p>This pass transforms loops by placing phi nodes at the end of the loops for all
+values that are live across the loop boundary. For example, it turns the left
+into the right code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(...)</span> <span class="k">for</span> <span class="p">(...)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">c</span><span class="p">)</span> <span class="k">if</span> <span class="p">(</span><span class="n">c</span><span class="p">)</span>
+ <span class="n">X1</span> <span class="o">=</span> <span class="p">...</span> <span class="n">X1</span> <span class="o">=</span> <span class="p">...</span>
+ <span class="k">else</span> <span class="k">else</span>
+ <span class="n">X2</span> <span class="o">=</span> <span class="p">...</span> <span class="n">X2</span> <span class="o">=</span> <span class="p">...</span>
+ <span class="n">X3</span> <span class="o">=</span> <span class="n">phi</span><span class="p">(</span><span class="n">X1</span><span class="p">,</span> <span class="n">X2</span><span class="p">)</span> <span class="n">X3</span> <span class="o">=</span> <span class="n">phi</span><span class="p">(</span><span class="n">X1</span><span class="p">,</span> <span class="n">X2</span><span class="p">)</span>
+<span class="p">...</span> <span class="o">=</span> <span class="n">X3</span> <span class="o">+</span> <span class="mi">4</span> <span class="n">X4</span> <span class="o">=</span> <span class="n">phi</span><span class="p">(</span><span class="n">X3</span><span class="p">)</span>
+ <span class="p">...</span> <span class="o">=</span> <span class="n">X4</span> <span class="o">+</span> <span class="mi">4</span>
+</pre></div>
+</div>
+<p>This is still valid LLVM; the extra phi nodes are purely redundant, and will be
+trivially eliminated by <code class="docutils literal"><span class="pre">InstCombine</span></code>. The major benefit of this
+transformation is that it makes many other loop optimizations, such as
+<code class="docutils literal"><span class="pre">LoopUnswitch</span></code>ing, simpler.</p>
+</div>
+<div class="section" id="licm-loop-invariant-code-motion">
+<span id="passes-licm"></span><h3><a class="toc-backref" href="#id70"><code class="docutils literal"><span class="pre">-licm</span></code>: Loop Invariant Code Motion</a><a class="headerlink" href="#licm-loop-invariant-code-motion" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs loop invariant code motion, attempting to remove as much
+code from the body of a loop as possible. It does this by either hoisting code
+into the preheader block, or by sinking code to the exit blocks if it is safe.
+This pass also promotes must-aliased memory locations in the loop to live in
+registers, thus hoisting and sinking “invariant” loads and stores.</p>
+<p>This pass uses alias analysis for two purposes:</p>
+<ol class="arabic">
+<li><p class="first">Moving loop invariant loads and calls out of loops. If we can determine
+that a load or call inside of a loop never aliases anything stored to, we
+can hoist it or sink it like any other instruction.</p>
+</li>
+<li><p class="first">Scalar Promotion of Memory. If there is a store instruction inside of the
+loop, we try to move the store to happen AFTER the loop instead of inside of
+the loop. This can only happen if a few conditions are true:</p>
+<ol class="arabic simple">
+<li>The pointer stored through is loop invariant.</li>
+<li>There are no stores or loads in the loop which <em>may</em> alias the pointer.
+There are no calls in the loop which mod/ref the pointer.</li>
+</ol>
+<p>If these conditions are true, we can promote the loads and stores in the
+loop of the pointer to use a temporary alloca’d variable. We then use the
+<a class="reference internal" href="#passes-mem2reg"><span class="std std-ref">mem2reg</span></a> functionality to construct the appropriate
+SSA form for the variable.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="loop-deletion-delete-dead-loops">
+<h3><a class="toc-backref" href="#id71"><code class="docutils literal"><span class="pre">-loop-deletion</span></code>: Delete dead loops</a><a class="headerlink" href="#loop-deletion-delete-dead-loops" title="Permalink to this headline">¶</a></h3>
+<p>This file implements the Dead Loop Deletion Pass. This pass is responsible for
+eliminating loops with non-infinite computable trip counts that have no side
+effects or volatile instructions, and do not contribute to the computation of
+the function’s return value.</p>
+</div>
+<div class="section" id="loop-extract-extract-loops-into-new-functions">
+<span id="passes-loop-extract"></span><h3><a class="toc-backref" href="#id72"><code class="docutils literal"><span class="pre">-loop-extract</span></code>: Extract loops into new functions</a><a class="headerlink" href="#loop-extract-extract-loops-into-new-functions" title="Permalink to this headline">¶</a></h3>
+<p>A pass wrapper around the <code class="docutils literal"><span class="pre">ExtractLoop()</span></code> scalar transformation to extract
+each top-level loop into its own new function. If the loop is the <em>only</em> loop
+in a given function, it is not touched. This is a pass most useful for
+debugging via bugpoint.</p>
+</div>
+<div class="section" id="loop-extract-single-extract-at-most-one-loop-into-a-new-function">
+<h3><a class="toc-backref" href="#id73"><code class="docutils literal"><span class="pre">-loop-extract-single</span></code>: Extract at most one loop into a new function</a><a class="headerlink" href="#loop-extract-single-extract-at-most-one-loop-into-a-new-function" title="Permalink to this headline">¶</a></h3>
+<p>Similar to <a class="reference internal" href="#passes-loop-extract"><span class="std std-ref">Extract loops into new functions</span></a>, this
+pass extracts one natural loop from the program into a function if it can.
+This is used by <strong class="program">bugpoint</strong>.</p>
+</div>
+<div class="section" id="loop-reduce-loop-strength-reduction">
+<h3><a class="toc-backref" href="#id74"><code class="docutils literal"><span class="pre">-loop-reduce</span></code>: Loop Strength Reduction</a><a class="headerlink" href="#loop-reduce-loop-strength-reduction" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs a strength reduction on array references inside loops that
+have as one or more of their components the loop induction variable. This is
+accomplished by creating a new value to hold the initial value of the array
+access for the first iteration, and then creating a new GEP instruction in the
+loop to increment the value by the appropriate amount.</p>
+</div>
+<div class="section" id="loop-rotate-rotate-loops">
+<h3><a class="toc-backref" href="#id75"><code class="docutils literal"><span class="pre">-loop-rotate</span></code>: Rotate Loops</a><a class="headerlink" href="#loop-rotate-rotate-loops" title="Permalink to this headline">¶</a></h3>
+<p>A simple loop rotation transformation.</p>
+</div>
+<div class="section" id="loop-simplify-canonicalize-natural-loops">
+<h3><a class="toc-backref" href="#id76"><code class="docutils literal"><span class="pre">-loop-simplify</span></code>: Canonicalize natural loops</a><a class="headerlink" href="#loop-simplify-canonicalize-natural-loops" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs several transformations to transform natural loops into a
+simpler form, which makes subsequent analyses and transformations simpler and
+more effective.</p>
+<p>Loop pre-header insertion guarantees that there is a single, non-critical entry
+edge from outside of the loop to the loop header. This simplifies a number of
+analyses and transformations, such as <a class="reference internal" href="#passes-licm"><span class="std std-ref">LICM</span></a>.</p>
+<p>Loop exit-block insertion guarantees that all exit blocks from the loop (blocks
+which are outside of the loop that have predecessors inside of the loop) only
+have predecessors from inside of the loop (and are thus dominated by the loop
+header). This simplifies transformations such as store-sinking that are built
+into LICM.</p>
+<p>This pass also guarantees that loops will have exactly one backedge.</p>
+<p>Note that the <a class="reference internal" href="#passes-simplifycfg"><span class="std std-ref">simplifycfg</span></a> pass will clean up blocks
+which are split out but end up being unnecessary, so usage of this pass should
+not pessimize generated code.</p>
+<p>This pass obviously modifies the CFG, but updates loop information and
+dominator information.</p>
+</div>
+<div class="section" id="loop-unroll-unroll-loops">
+<h3><a class="toc-backref" href="#id77"><code class="docutils literal"><span class="pre">-loop-unroll</span></code>: Unroll loops</a><a class="headerlink" href="#loop-unroll-unroll-loops" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements a simple loop unroller. It works best when loops have
+been canonicalized by the <a class="reference internal" href="#passes-indvars"><span class="std std-ref">indvars</span></a> pass, allowing it to
+determine the trip counts of loops easily.</p>
+</div>
+<div class="section" id="loop-unswitch-unswitch-loops">
+<h3><a class="toc-backref" href="#id78"><code class="docutils literal"><span class="pre">-loop-unswitch</span></code>: Unswitch loops</a><a class="headerlink" href="#loop-unswitch-unswitch-loops" title="Permalink to this headline">¶</a></h3>
+<p>This pass transforms loops that contain branches on loop-invariant conditions
+to have multiple loops. For example, it turns the left into the right code:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(...)</span> <span class="k">if</span> <span class="p">(</span><span class="n">lic</span><span class="p">)</span>
+ <span class="n">A</span> <span class="k">for</span> <span class="p">(...)</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">lic</span><span class="p">)</span> <span class="n">A</span><span class="p">;</span> <span class="n">B</span><span class="p">;</span> <span class="n">C</span>
+ <span class="n">B</span> <span class="k">else</span>
+ <span class="n">C</span> <span class="nf">for</span> <span class="p">(...)</span>
+ <span class="n">A</span><span class="p">;</span> <span class="n">C</span>
+</pre></div>
+</div>
+<p>This can increase the size of the code exponentially (doubling it every time a
+loop is unswitched) so we only unswitch if the resultant code will be smaller
+than a threshold.</p>
+<p>This pass expects <a class="reference internal" href="#passes-licm"><span class="std std-ref">LICM</span></a> to be run before it to hoist
+invariant conditions out of the loop, to make the unswitching opportunity
+obvious.</p>
+</div>
+<div class="section" id="loweratomic-lower-atomic-intrinsics-to-non-atomic-form">
+<h3><a class="toc-backref" href="#id79"><code class="docutils literal"><span class="pre">-loweratomic</span></code>: Lower atomic intrinsics to non-atomic form</a><a class="headerlink" href="#loweratomic-lower-atomic-intrinsics-to-non-atomic-form" title="Permalink to this headline">¶</a></h3>
+<p>This pass lowers atomic intrinsics to non-atomic form for use in a known
+non-preemptible environment.</p>
+<p>The pass does not verify that the environment is non-preemptible (in general
+this would require knowledge of the entire call graph of the program including
+any libraries which may not be available in bitcode form); it simply lowers
+every atomic intrinsic.</p>
+</div>
+<div class="section" id="lowerinvoke-lower-invokes-to-calls-for-unwindless-code-generators">
+<h3><a class="toc-backref" href="#id80"><code class="docutils literal"><span class="pre">-lowerinvoke</span></code>: Lower invokes to calls, for unwindless code generators</a><a class="headerlink" href="#lowerinvoke-lower-invokes-to-calls-for-unwindless-code-generators" title="Permalink to this headline">¶</a></h3>
+<p>This transformation is designed for use by code generators which do not yet
+support stack unwinding. This pass converts <code class="docutils literal"><span class="pre">invoke</span></code> instructions to
+<code class="docutils literal"><span class="pre">call</span></code> instructions, so that any exception-handling <code class="docutils literal"><span class="pre">landingpad</span></code> blocks
+become dead code (which can be removed by running the <code class="docutils literal"><span class="pre">-simplifycfg</span></code> pass
+afterwards).</p>
+</div>
+<div class="section" id="lowerswitch-lower-switchinsts-to-branches">
+<h3><a class="toc-backref" href="#id81"><code class="docutils literal"><span class="pre">-lowerswitch</span></code>: Lower <code class="docutils literal"><span class="pre">SwitchInst</span></code>s to branches</a><a class="headerlink" href="#lowerswitch-lower-switchinsts-to-branches" title="Permalink to this headline">¶</a></h3>
+<p>Rewrites switch instructions with a sequence of branches, which allows targets
+to get away with not implementing the switch instruction until it is
+convenient.</p>
+</div>
+<div class="section" id="mem2reg-promote-memory-to-register">
+<span id="passes-mem2reg"></span><h3><a class="toc-backref" href="#id82"><code class="docutils literal"><span class="pre">-mem2reg</span></code>: Promote Memory to Register</a><a class="headerlink" href="#mem2reg-promote-memory-to-register" title="Permalink to this headline">¶</a></h3>
+<p>This file promotes memory references to be register references. It promotes
+alloca instructions which only have loads and stores as uses. An <code class="docutils literal"><span class="pre">alloca</span></code> is
+transformed by using dominator frontiers to place phi nodes, then traversing
+the function in depth-first order to rewrite loads and stores as appropriate.
+This is just the standard SSA construction algorithm to construct “pruned” SSA
+form.</p>
+</div>
+<div class="section" id="memcpyopt-memcpy-optimization">
+<h3><a class="toc-backref" href="#id83"><code class="docutils literal"><span class="pre">-memcpyopt</span></code>: MemCpy Optimization</a><a class="headerlink" href="#memcpyopt-memcpy-optimization" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs various transformations related to eliminating <code class="docutils literal"><span class="pre">memcpy</span></code>
+calls, or transforming sets of stores into <code class="docutils literal"><span class="pre">memset</span></code>s.</p>
+</div>
+<div class="section" id="mergefunc-merge-functions">
+<h3><a class="toc-backref" href="#id84"><code class="docutils literal"><span class="pre">-mergefunc</span></code>: Merge Functions</a><a class="headerlink" href="#mergefunc-merge-functions" title="Permalink to this headline">¶</a></h3>
+<p>This pass looks for equivalent functions that are mergable and folds them.</p>
+<p>Total-ordering is introduced among the functions set: we define comparison
+that answers for every two functions which of them is greater. It allows to
+arrange functions into the binary tree.</p>
+<p>For every new function we check for equivalent in tree.</p>
+<p>If equivalent exists we fold such functions. If both functions are overridable,
+we move the functionality into a new internal function and leave two
+overridable thunks to it.</p>
+<p>If there is no equivalent, then we add this function to tree.</p>
+<p>Lookup routine has O(log(n)) complexity, while whole merging process has
+complexity of O(n*log(n)).</p>
+<p>Read
+<a class="reference internal" href="MergeFunctions.html"><span class="doc">this</span></a>
+article for more details.</p>
+</div>
+<div class="section" id="mergereturn-unify-function-exit-nodes">
+<h3><a class="toc-backref" href="#id85"><code class="docutils literal"><span class="pre">-mergereturn</span></code>: Unify function exit nodes</a><a class="headerlink" href="#mergereturn-unify-function-exit-nodes" title="Permalink to this headline">¶</a></h3>
+<p>Ensure that functions have at most one <code class="docutils literal"><span class="pre">ret</span></code> instruction in them.
+Additionally, it keeps track of which node is the new exit node of the CFG.</p>
+</div>
+<div class="section" id="partial-inliner-partial-inliner">
+<h3><a class="toc-backref" href="#id86"><code class="docutils literal"><span class="pre">-partial-inliner</span></code>: Partial Inliner</a><a class="headerlink" href="#partial-inliner-partial-inliner" title="Permalink to this headline">¶</a></h3>
+<p>This pass performs partial inlining, typically by inlining an <code class="docutils literal"><span class="pre">if</span></code> statement
+that surrounds the body of the function.</p>
+</div>
+<div class="section" id="prune-eh-remove-unused-exception-handling-info">
+<h3><a class="toc-backref" href="#id87"><code class="docutils literal"><span class="pre">-prune-eh</span></code>: Remove unused exception handling info</a><a class="headerlink" href="#prune-eh-remove-unused-exception-handling-info" title="Permalink to this headline">¶</a></h3>
+<p>This file implements a simple interprocedural pass which walks the call-graph,
+turning invoke instructions into call instructions if and only if the callee
+cannot throw an exception. It implements this as a bottom-up traversal of the
+call-graph.</p>
+</div>
+<div class="section" id="reassociate-reassociate-expressions">
+<h3><a class="toc-backref" href="#id88"><code class="docutils literal"><span class="pre">-reassociate</span></code>: Reassociate expressions</a><a class="headerlink" href="#reassociate-reassociate-expressions" title="Permalink to this headline">¶</a></h3>
+<p>This pass reassociates commutative expressions in an order that is designed to
+promote better constant propagation, GCSE, <a class="reference internal" href="#passes-licm"><span class="std std-ref">LICM</span></a>, PRE, etc.</p>
+<p>For example: 4 + (x + 5) â x + (4 + 5)</p>
+<p>In the implementation of this algorithm, constants are assigned rank = 0,
+function arguments are rank = 1, and other values are assigned ranks
+corresponding to the reverse post order traversal of current function (starting
+at 2), which effectively gives values in deep loops higher rank than values not
+in loops.</p>
+</div>
+<div class="section" id="reg2mem-demote-all-values-to-stack-slots">
+<h3><a class="toc-backref" href="#id89"><code class="docutils literal"><span class="pre">-reg2mem</span></code>: Demote all values to stack slots</a><a class="headerlink" href="#reg2mem-demote-all-values-to-stack-slots" title="Permalink to this headline">¶</a></h3>
+<p>This file demotes all registers to memory references. It is intended to be the
+inverse of <a class="reference internal" href="#passes-mem2reg"><span class="std std-ref">mem2reg</span></a>. By converting to <code class="docutils literal"><span class="pre">load</span></code>
+instructions, the only values live across basic blocks are <code class="docutils literal"><span class="pre">alloca</span></code>
+instructions and <code class="docutils literal"><span class="pre">load</span></code> instructions before <code class="docutils literal"><span class="pre">phi</span></code> nodes. It is intended
+that this should make CFG hacking much easier. To make later hacking easier,
+the entry block is split into two, such that all introduced <code class="docutils literal"><span class="pre">alloca</span></code>
+instructions (and nothing else) are in the entry block.</p>
+</div>
+<div class="section" id="sroa-scalar-replacement-of-aggregates">
+<h3><a class="toc-backref" href="#id90"><code class="docutils literal"><span class="pre">-sroa</span></code>: Scalar Replacement of Aggregates</a><a class="headerlink" href="#sroa-scalar-replacement-of-aggregates" title="Permalink to this headline">¶</a></h3>
+<p>The well-known scalar replacement of aggregates transformation. This transform
+breaks up <code class="docutils literal"><span class="pre">alloca</span></code> instructions of aggregate type (structure or array) into
+individual <code class="docutils literal"><span class="pre">alloca</span></code> instructions for each member if possible. Then, if
+possible, it transforms the individual <code class="docutils literal"><span class="pre">alloca</span></code> instructions into nice clean
+scalar SSA form.</p>
+</div>
+<div class="section" id="sccp-sparse-conditional-constant-propagation">
+<span id="passes-sccp"></span><h3><a class="toc-backref" href="#id91"><code class="docutils literal"><span class="pre">-sccp</span></code>: Sparse Conditional Constant Propagation</a><a class="headerlink" href="#sccp-sparse-conditional-constant-propagation" title="Permalink to this headline">¶</a></h3>
+<p>Sparse conditional constant propagation and merging, which can be summarized
+as:</p>
+<ul class="simple">
+<li>Assumes values are constant unless proven otherwise</li>
+<li>Assumes BasicBlocks are dead unless proven otherwise</li>
+<li>Proves values to be constant, and replaces them with constants</li>
+<li>Proves conditional branches to be unconditional</li>
+</ul>
+<p>Note that this pass has a habit of making definitions be dead. It is a good
+idea to run a <a class="reference internal" href="#passes-dce"><span class="std std-ref">DCE</span></a> pass sometime after running this pass.</p>
+</div>
+<div class="section" id="simplifycfg-simplify-the-cfg">
+<span id="passes-simplifycfg"></span><h3><a class="toc-backref" href="#id92"><code class="docutils literal"><span class="pre">-simplifycfg</span></code>: Simplify the CFG</a><a class="headerlink" href="#simplifycfg-simplify-the-cfg" title="Permalink to this headline">¶</a></h3>
+<p>Performs dead code elimination and basic block merging. Specifically:</p>
+<ul class="simple">
+<li>Removes basic blocks with no predecessors.</li>
+<li>Merges a basic block into its predecessor if there is only one and the
+predecessor only has one successor.</li>
+<li>Eliminates PHI nodes for basic blocks with a single predecessor.</li>
+<li>Eliminates a basic block that only contains an unconditional branch.</li>
+</ul>
+</div>
+<div class="section" id="sink-code-sinking">
+<h3><a class="toc-backref" href="#id93"><code class="docutils literal"><span class="pre">-sink</span></code>: Code sinking</a><a class="headerlink" href="#sink-code-sinking" title="Permalink to this headline">¶</a></h3>
+<p>This pass moves instructions into successor blocks, when possible, so that they
+aren’t executed on paths where their results aren’t needed.</p>
+</div>
+<div class="section" id="strip-strip-all-symbols-from-a-module">
+<h3><a class="toc-backref" href="#id94"><code class="docutils literal"><span class="pre">-strip</span></code>: Strip all symbols from a module</a><a class="headerlink" href="#strip-strip-all-symbols-from-a-module" title="Permalink to this headline">¶</a></h3>
+<p>Performs code stripping. This transformation can delete:</p>
+<ul class="simple">
+<li>names for virtual registers</li>
+<li>symbols for internal globals and functions</li>
+<li>debug information</li>
+</ul>
+<p>Note that this transformation makes code much less readable, so it should only
+be used in situations where the strip utility would be used, such as reducing
+code size or making it harder to reverse engineer code.</p>
+</div>
+<div class="section" id="strip-dead-debug-info-strip-debug-info-for-unused-symbols">
+<h3><a class="toc-backref" href="#id95"><code class="docutils literal"><span class="pre">-strip-dead-debug-info</span></code>: Strip debug info for unused symbols</a><a class="headerlink" href="#strip-dead-debug-info-strip-debug-info-for-unused-symbols" title="Permalink to this headline">¶</a></h3>
+<p>performs code stripping. this transformation can delete:</p>
+<ul class="simple">
+<li>names for virtual registers</li>
+<li>symbols for internal globals and functions</li>
+<li>debug information</li>
+</ul>
+<p>note that this transformation makes code much less readable, so it should only
+be used in situations where the strip utility would be used, such as reducing
+code size or making it harder to reverse engineer code.</p>
+</div>
+<div class="section" id="strip-dead-prototypes-strip-unused-function-prototypes">
+<h3><a class="toc-backref" href="#id96"><code class="docutils literal"><span class="pre">-strip-dead-prototypes</span></code>: Strip Unused Function Prototypes</a><a class="headerlink" href="#strip-dead-prototypes-strip-unused-function-prototypes" title="Permalink to this headline">¶</a></h3>
+<p>This pass loops over all of the functions in the input module, looking for dead
+declarations and removes them. Dead declarations are declarations of functions
+for which no implementation is available (i.e., declarations for unused library
+functions).</p>
+</div>
+<div class="section" id="strip-debug-declare-strip-all-llvm-dbg-declare-intrinsics">
+<h3><a class="toc-backref" href="#id97"><code class="docutils literal"><span class="pre">-strip-debug-declare</span></code>: Strip all <code class="docutils literal"><span class="pre">llvm.dbg.declare</span></code> intrinsics</a><a class="headerlink" href="#strip-debug-declare-strip-all-llvm-dbg-declare-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements code stripping. Specifically, it can delete:</p>
+<ol class="arabic simple">
+<li>names for virtual registers</li>
+<li>symbols for internal globals and functions</li>
+<li>debug information</li>
+</ol>
+<p>Note that this transformation makes code much less readable, so it should only
+be used in situations where the ‘strip’ utility would be used, such as reducing
+code size or making it harder to reverse engineer code.</p>
+</div>
+<div class="section" id="strip-nondebug-strip-all-symbols-except-dbg-symbols-from-a-module">
+<h3><a class="toc-backref" href="#id98"><code class="docutils literal"><span class="pre">-strip-nondebug</span></code>: Strip all symbols, except dbg symbols, from a module</a><a class="headerlink" href="#strip-nondebug-strip-all-symbols-except-dbg-symbols-from-a-module" title="Permalink to this headline">¶</a></h3>
+<p>This pass implements code stripping. Specifically, it can delete:</p>
+<ol class="arabic simple">
+<li>names for virtual registers</li>
+<li>symbols for internal globals and functions</li>
+<li>debug information</li>
+</ol>
+<p>Note that this transformation makes code much less readable, so it should only
+be used in situations where the ‘strip’ utility would be used, such as reducing
+code size or making it harder to reverse engineer code.</p>
+</div>
+<div class="section" id="tailcallelim-tail-call-elimination">
+<h3><a class="toc-backref" href="#id99"><code class="docutils literal"><span class="pre">-tailcallelim</span></code>: Tail Call Elimination</a><a class="headerlink" href="#tailcallelim-tail-call-elimination" title="Permalink to this headline">¶</a></h3>
+<p>This file transforms calls of the current function (self recursion) followed by
+a return instruction with a branch to the entry of the function, creating a
+loop. This pass also implements the following extensions to the basic
+algorithm:</p>
+<ol class="arabic simple">
+<li>Trivial instructions between the call and return do not prevent the
+transformation from taking place, though currently the analysis cannot
+support moving any really useful instructions (only dead ones).</li>
+<li>This pass transforms functions that are prevented from being tail recursive
+by an associative expression to use an accumulator variable, thus compiling
+the typical naive factorial or fib implementation into efficient code.</li>
+<li>TRE is performed if the function returns void, if the return returns the
+result returned by the call, or if the function returns a run-time constant
+on all exits from the function. It is possible, though unlikely, that the
+return returns something else (like constant 0), and can still be TRE’d. It
+can be TRE’d if <em>all other</em> return instructions in the function return the
+exact same value.</li>
+<li>If it can prove that callees do not access theier caller stack frame, they
+are marked as eligible for tail call elimination (by the code generator).</li>
+</ol>
+</div>
+</div>
+<div class="section" id="utility-passes">
+<h2><a class="toc-backref" href="#id100">Utility Passes</a><a class="headerlink" href="#utility-passes" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the LLVM Utility Passes.</p>
+<div class="section" id="deadarghax0r-dead-argument-hacking-bugpoint-use-only-do-not-use">
+<h3><a class="toc-backref" href="#id101"><code class="docutils literal"><span class="pre">-deadarghaX0r</span></code>: Dead Argument Hacking (BUGPOINT USE ONLY; DO NOT USE)</a><a class="headerlink" href="#deadarghax0r-dead-argument-hacking-bugpoint-use-only-do-not-use" title="Permalink to this headline">¶</a></h3>
+<p>Same as dead argument elimination, but deletes arguments to functions which are
+external. This is only for use by <a class="reference internal" href="Bugpoint.html"><span class="doc">bugpoint</span></a>.</p>
+</div>
+<div class="section" id="extract-blocks-extract-basic-blocks-from-module-for-bugpoint-use">
+<h3><a class="toc-backref" href="#id102"><code class="docutils literal"><span class="pre">-extract-blocks</span></code>: Extract Basic Blocks From Module (for bugpoint use)</a><a class="headerlink" href="#extract-blocks-extract-basic-blocks-from-module-for-bugpoint-use" title="Permalink to this headline">¶</a></h3>
+<p>This pass is used by bugpoint to extract all blocks from the module into their
+own functions.</p>
+</div>
+<div class="section" id="instnamer-assign-names-to-anonymous-instructions">
+<h3><a class="toc-backref" href="#id103"><code class="docutils literal"><span class="pre">-instnamer</span></code>: Assign names to anonymous instructions</a><a class="headerlink" href="#instnamer-assign-names-to-anonymous-instructions" title="Permalink to this headline">¶</a></h3>
+<p>This is a little utility pass that gives instructions names, this is mostly
+useful when diffing the effect of an optimization because deleting an unnamed
+instruction can change all other instruction numbering, making the diff very
+noisy.</p>
+</div>
+<div class="section" id="verify-module-verifier">
+<span id="passes-verify"></span><h3><a class="toc-backref" href="#id104"><code class="docutils literal"><span class="pre">-verify</span></code>: Module Verifier</a><a class="headerlink" href="#verify-module-verifier" title="Permalink to this headline">¶</a></h3>
+<p>Verifies an LLVM IR code. This is useful to run after an optimization which is
+undergoing testing. Note that llvm-as verifies its input before emitting
+bitcode, and also that malformed bitcode is likely to make LLVM crash. All
+language front-ends are therefore encouraged to verify their output before
+performing optimizing transformations.</p>
+<ol class="arabic simple">
+<li>Both of a binary operator’s parameters are of the same type.</li>
+<li>Verify that the indices of mem access instructions match other operands.</li>
+<li>Verify that arithmetic and other things are only performed on first-class
+types. Verify that shifts and logicals only happen on integrals f.e.</li>
+<li>All of the constants in a switch statement are of the correct type.</li>
+<li>The code is in valid SSA form.</li>
+<li>It is illegal to put a label into any other type (like a structure) or to
+return one.</li>
+<li>Only phi nodes can be self referential: <code class="docutils literal"><span class="pre">%x</span> <span class="pre">=</span> <span class="pre">add</span> <span class="pre">i32</span> <span class="pre">%x</span></code>, <code class="docutils literal"><span class="pre">%x</span></code> is
+invalid.</li>
+<li>PHI nodes must have an entry for each predecessor, with no extras.</li>
+<li>PHI nodes must be the first thing in a basic block, all grouped together.</li>
+<li>PHI nodes must have at least one entry.</li>
+<li>All basic blocks should only end with terminator insts, not contain them.</li>
+<li>The entry node to a function must not have predecessors.</li>
+<li>All Instructions must be embedded into a basic block.</li>
+<li>Functions cannot take a void-typed parameter.</li>
+<li>Verify that a function’s argument list agrees with its declared type.</li>
+<li>It is illegal to specify a name for a void value.</li>
+<li>It is illegal to have an internal global value with no initializer.</li>
+<li>It is illegal to have a <code class="docutils literal"><span class="pre">ret</span></code> instruction that returns a value that does
+not agree with the function return value type.</li>
+<li>Function call argument types match the function prototype.</li>
+<li>All other things that are tested by asserts spread about the code.</li>
+</ol>
+<p>Note that this does not provide full security verification (like Java), but
+instead just tries to ensure that code is well-formed.</p>
+</div>
+<div class="section" id="view-cfg-view-cfg-of-function">
+<h3><a class="toc-backref" href="#id105"><code class="docutils literal"><span class="pre">-view-cfg</span></code>: View CFG of function</a><a class="headerlink" href="#view-cfg-view-cfg-of-function" title="Permalink to this headline">¶</a></h3>
+<p>Displays the control flow graph using the GraphViz tool.</p>
+</div>
+<div class="section" id="view-cfg-only-view-cfg-of-function-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id106"><code class="docutils literal"><span class="pre">-view-cfg-only</span></code>: View CFG of function (with no function bodies)</a><a class="headerlink" href="#view-cfg-only-view-cfg-of-function-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>Displays the control flow graph using the GraphViz tool, but omitting function
+bodies.</p>
+</div>
+<div class="section" id="view-dom-view-dominance-tree-of-function">
+<h3><a class="toc-backref" href="#id107"><code class="docutils literal"><span class="pre">-view-dom</span></code>: View dominance tree of function</a><a class="headerlink" href="#view-dom-view-dominance-tree-of-function" title="Permalink to this headline">¶</a></h3>
+<p>Displays the dominator tree using the GraphViz tool.</p>
+</div>
+<div class="section" id="view-dom-only-view-dominance-tree-of-function-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id108"><code class="docutils literal"><span class="pre">-view-dom-only</span></code>: View dominance tree of function (with no function bodies)</a><a class="headerlink" href="#view-dom-only-view-dominance-tree-of-function-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>Displays the dominator tree using the GraphViz tool, but omitting function
+bodies.</p>
+</div>
+<div class="section" id="view-postdom-view-postdominance-tree-of-function">
+<h3><a class="toc-backref" href="#id109"><code class="docutils literal"><span class="pre">-view-postdom</span></code>: View postdominance tree of function</a><a class="headerlink" href="#view-postdom-view-postdominance-tree-of-function" title="Permalink to this headline">¶</a></h3>
+<p>Displays the post dominator tree using the GraphViz tool.</p>
+</div>
+<div class="section" id="view-postdom-only-view-postdominance-tree-of-function-with-no-function-bodies">
+<h3><a class="toc-backref" href="#id110"><code class="docutils literal"><span class="pre">-view-postdom-only</span></code>: View postdominance tree of function (with no function bodies)</a><a class="headerlink" href="#view-postdom-only-view-postdominance-tree-of-function-with-no-function-bodies" title="Permalink to this headline">¶</a></h3>
+<p>Displays the post dominator tree using the GraphViz tool, but omitting function
+bodies.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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="YamlIO.html" title="YAML I/O"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ReleaseNotes.html" title="LLVM 6.0.0 Release Notes"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/6.0.0/docs/Phabricator.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/6.0.0/docs/Phabricator.html?rev=326992&view=auto
==============================================================================
--- www-releases/trunk/6.0.0/docs/Phabricator.html (added)
+++ www-releases/trunk/6.0.0/docs/Phabricator.html Thu Mar 8 02:24:44 2018
@@ -0,0 +1,305 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Code Reviews with Phabricator — LLVM 6 documentation</title>
+
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: './',
+ VERSION: '6',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </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 Testing Infrastructure Guide" href="TestingGuide.html" />
+ <link rel="prev" title="Sphinx Quickstart Template" href="SphinxQuickstartTemplate.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body role="document">
+<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="TestingGuide.html" title="LLVM Testing Infrastructure Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
+ 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="code-reviews-with-phabricator">
+<h1>Code Reviews with Phabricator<a class="headerlink" href="#code-reviews-with-phabricator" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#sign-up" id="id1">Sign up</a></li>
+<li><a class="reference internal" href="#requesting-a-review-via-the-command-line" id="id2">Requesting a review via the command line</a></li>
+<li><a class="reference internal" href="#requesting-a-review-via-the-web-interface" id="id3">Requesting a review via the web interface</a></li>
+<li><a class="reference internal" href="#reviewing-code-with-phabricator" id="id4">Reviewing code with Phabricator</a></li>
+<li><a class="reference internal" href="#committing-a-change" id="id5">Committing a change</a><ul>
+<li><a class="reference internal" href="#subversion-and-arcanist" id="id6">Subversion and Arcanist</a></li>
+<li><a class="reference internal" href="#git-svn-and-arcanist" id="id7">git-svn and Arcanist</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#abandoning-a-change" id="id8">Abandoning a change</a></li>
+<li><a class="reference internal" href="#status" id="id9">Status</a></li>
+</ul>
+</div>
+<p>If you prefer to use a web user interface for code reviews, you can now submit
+your patches for Clang and LLVM at <a class="reference external" href="http://reviews.llvm.org">LLVM’s Phabricator</a> instance.</p>
+<p>While Phabricator is a useful tool for some, the relevant -commits mailing list
+is the system of record for all LLVM code review. The mailing list should be
+added as a subscriber on all reviews, and Phabricator users should be prepared
+to respond to free-form comments in mail sent to the commits list.</p>
+<div class="section" id="sign-up">
+<h2><a class="toc-backref" href="#id1">Sign up</a><a class="headerlink" href="#sign-up" title="Permalink to this headline">¶</a></h2>
+<p>To get started with Phabricator, navigate to <a class="reference external" href="http://reviews.llvm.org">http://reviews.llvm.org</a> and
+click the power icon in the top right. You can register with a GitHub account,
+a Google account, or you can create your own profile.</p>
+<p>Make <em>sure</em> that the email address registered with Phabricator is subscribed
+to the relevant -commits mailing list. If you are not subscribed to the commit
+list, all mail sent by Phabricator on your behalf will be held for moderation.</p>
+<p>Note that if you use your Subversion user name as Phabricator user name,
+Phabricator will automatically connect your submits to your Phabricator user in
+the <a class="reference external" href="http://reviews.llvm.org/diffusion/">Code Repository Browser</a>.</p>
+</div>
+<div class="section" id="requesting-a-review-via-the-command-line">
+<h2><a class="toc-backref" href="#id2">Requesting a review via the command line</a><a class="headerlink" href="#requesting-a-review-via-the-command-line" title="Permalink to this headline">¶</a></h2>
+<p>Phabricator has a tool called <em>Arcanist</em> to upload patches from
+the command line. To get you set up, follow the
+<a class="reference external" href="https://secure.phabricator.com/book/phabricator/article/arcanist_quick_start/">Arcanist Quick Start</a> instructions.</p>
+<p>You can learn more about how to use arc to interact with
+Phabricator in the <a class="reference external" href="https://secure.phabricator.com/book/phabricator/article/arcanist/">Arcanist User Guide</a>.</p>
+</div>
+<div class="section" id="requesting-a-review-via-the-web-interface">
+<h2><a class="toc-backref" href="#id3">Requesting a review via the web interface</a><a class="headerlink" href="#requesting-a-review-via-the-web-interface" title="Permalink to this headline">¶</a></h2>
+<p>The tool to create and review patches in Phabricator is called
+<em>Differential</em>.</p>
+<p>Note that you can upload patches created through various diff tools,
+including git and svn. To make reviews easier, please always include
+<strong>as much context as possible</strong> with your diff! Don’t worry, Phabricator
+will automatically send a diff with a smaller context in the review
+email, but having the full file in the web interface will help the
+reviewer understand your code.</p>
+<p>To get a full diff, use one of the following commands (or just use Arcanist
+to upload your patch):</p>
+<ul class="simple">
+<li><code class="docutils literal"><span class="pre">git</span> <span class="pre">show</span> <span class="pre">HEAD</span> <span class="pre">-U999999</span> <span class="pre">></span> <span class="pre">mypatch.patch</span></code></li>
+<li><code class="docutils literal"><span class="pre">git</span> <span class="pre">format-patch</span> <span class="pre">-U999999</span> <span class="pre">@{u}</span></code></li>
+<li><code class="docutils literal"><span class="pre">svn</span> <span class="pre">diff</span> <span class="pre">--diff-cmd=diff</span> <span class="pre">-x</span> <span class="pre">-U999999</span></code></li>
+</ul>
+<p>To upload a new patch:</p>
+<ul class="simple">
+<li>Click <em>Differential</em>.</li>
+<li>Click <em>+ Create Diff</em>.</li>
+<li>Paste the text diff or browse to the patch file. Click <em>Create Diff</em>.</li>
+<li>Leave the Repository field blank.</li>
+<li>Leave the drop down on <em>Create a new Revision...</em> and click <em>Continue</em>.</li>
+<li>Enter a descriptive title and summary. The title and summary are usually
+in the form of a <a class="reference internal" href="DeveloperPolicy.html#commit-messages"><span class="std std-ref">commit message</span></a>.</li>
+<li>Add reviewers (see below for advice) and subscribe mailing
+lists that you want to be included in the review. If your patch is
+for LLVM, add llvm-commits as a Subscriber; if your patch is for Clang,
+add cfe-commits.</li>
+<li>Leave the Repository and Project fields blank.</li>
+<li>Click <em>Save</em>.</li>
+</ul>
+<p>To submit an updated patch:</p>
+<ul class="simple">
+<li>Click <em>Differential</em>.</li>
+<li>Click <em>+ Create Diff</em>.</li>
+<li>Paste the updated diff or browse to the updated patch file. Click <em>Create Diff</em>.</li>
+<li>Select the review you want to from the <em>Attach To</em> dropdown and click
+<em>Continue</em>.</li>
+<li>Leave the Repository and Project fields blank.</li>
+<li>Add comments about the changes in the new diff. Click <em>Save</em>.</li>
+</ul>
+<p>Choosing reviewers: You typically pick one or two people as initial reviewers.
+This choice is not crucial, because you are merely suggesting and not requiring
+them to participate. Many people will see the email notification on cfe-commits
+or llvm-commits, and if the subject line suggests the patch is something they
+should look at, they will.</p>
+<p>Here are a couple of ways to pick the initial reviewer(s):</p>
+<ul class="simple">
+<li>Use <code class="docutils literal"><span class="pre">svn</span> <span class="pre">blame</span></code> and the commit log to find names of people who have
+recently modified the same area of code that you are modifying.</li>
+<li>Look in CODE_OWNERS.TXT to see who might be responsible for that area.</li>
+<li>If you’ve discussed the change on a dev list, the people who participated
+might be appropriate reviewers.</li>
+</ul>
+<p>Even if you think the code owner is the busiest person in the world, it’s still
+okay to put them as a reviewer. Being the code owner means they have accepted
+responsibility for making sure the review happens.</p>
+</div>
+<div class="section" id="reviewing-code-with-phabricator">
+<h2><a class="toc-backref" href="#id4">Reviewing code with Phabricator</a><a class="headerlink" href="#reviewing-code-with-phabricator" title="Permalink to this headline">¶</a></h2>
+<p>Phabricator allows you to add inline comments as well as overall comments
+to a revision. To add an inline comment, select the lines of code you want
+to comment on by clicking and dragging the line numbers in the diff pane.
+When you have added all your comments, scroll to the bottom of the page and
+click the Submit button.</p>
+<p>You can add overall comments in the text box at the bottom of the page.
+When you’re done, click the Submit button.</p>
+<p>Phabricator has many useful features, for example allowing you to select
+diffs between different versions of the patch as it was reviewed in the
+<em>Revision Update History</em>. Most features are self descriptive - explore, and
+if you have a question, drop by on #llvm in IRC to get help.</p>
+<p>Note that as e-mail is the system of reference for code reviews, and some
+people prefer it over a web interface, we do not generate automated mail
+when a review changes state, for example by clicking “Accept Revision” in
+the web interface. Thus, please type LGTM into the comment box to accept
+a change from Phabricator.</p>
+</div>
+<div class="section" id="committing-a-change">
+<h2><a class="toc-backref" href="#id5">Committing a change</a><a class="headerlink" href="#committing-a-change" title="Permalink to this headline">¶</a></h2>
+<p>Once a patch has been reviewed and approved on Phabricator it can then be
+committed to trunk. If you do not have commit access, someone has to
+commit the change for you (with attribution). It is sufficient to add
+a comment to the approved review indicating you cannot commit the patch
+yourself. If you have commit access, there are multiple workflows to commit the
+change. Whichever method you follow it is recommended that your commit message
+ends with the line:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Differential</span> <span class="n">Revision</span><span class="p">:</span> <span class="o"><</span><span class="n">URL</span><span class="o">></span>
+</pre></div>
+</div>
+<p>where <code class="docutils literal"><span class="pre"><URL></span></code> is the URL for the code review, starting with
+<code class="docutils literal"><span class="pre">http://reviews.llvm.org/</span></code>.</p>
+<p>This allows people reading the version history to see the review for
+context. This also allows Phabricator to detect the commit, close the
+review, and add a link from the review to the commit.</p>
+<p>Note that if you use the Arcanist tool the <code class="docutils literal"><span class="pre">Differential</span> <span class="pre">Revision</span></code> line will
+be added automatically. If you don’t want to use Arcanist, you can add the
+<code class="docutils literal"><span class="pre">Differential</span> <span class="pre">Revision</span></code> line (as the last line) to the commit message
+yourself.</p>
+<p>Using the Arcanist tool can simplify the process of committing reviewed code
+as it will retrieve reviewers, the <code class="docutils literal"><span class="pre">Differential</span> <span class="pre">Revision</span></code>, etc from the review
+and place it in the commit message. Several methods of using Arcanist to commit
+code are given below. If you do not wish to use Arcanist then simply commit
+the reviewed patch as you would normally.</p>
+<p>Note that if you commit the change without using Arcanist and forget to add the
+<code class="docutils literal"><span class="pre">Differential</span> <span class="pre">Revision</span></code> line to your commit message then it is recommended
+that you close the review manually. In the web UI, under “Leap Into Action” put
+the SVN revision number in the Comment, set the Action to “Close Revision” and
+click Submit. Note the review must have been Accepted first.</p>
+<div class="section" id="subversion-and-arcanist">
+<h3><a class="toc-backref" href="#id6">Subversion and Arcanist</a><a class="headerlink" href="#subversion-and-arcanist" title="Permalink to this headline">¶</a></h3>
+<p>On a clean Subversion working copy run the following (where <code class="docutils literal"><span class="pre"><Revision></span></code> is
+the Phabricator review number):</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">arc</span> <span class="n">patch</span> <span class="n">D</span><span class="o"><</span><span class="n">Revision</span><span class="o">></span>
+<span class="n">arc</span> <span class="n">commit</span> <span class="o">--</span><span class="n">revision</span> <span class="n">D</span><span class="o"><</span><span class="n">Revision</span><span class="o">></span>
+</pre></div>
+</div>
+<p>The first command will take the latest version of the reviewed patch and apply it to the working
+copy. The second command will commit this revision to trunk.</p>
+</div>
+<div class="section" id="git-svn-and-arcanist">
+<h3><a class="toc-backref" href="#id7">git-svn and Arcanist</a><a class="headerlink" href="#git-svn-and-arcanist" title="Permalink to this headline">¶</a></h3>
+<p>This presumes that the git repository has been configured as described in <a class="reference internal" href="GettingStarted.html#developers-work-with-git-svn"><span class="std std-ref">For developers to work with git-svn</span></a>.</p>
+<p>On a clean Git repository on an up to date <code class="docutils literal"><span class="pre">master</span></code> branch run the
+following (where <code class="docutils literal"><span class="pre"><Revision></span></code> is the Phabricator review number):</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">arc</span> <span class="n">patch</span> <span class="n">D</span><span class="o"><</span><span class="n">Revision</span><span class="o">></span>
+</pre></div>
+</div>
+<p>This will create a new branch called <code class="docutils literal"><span class="pre">arcpatch-D<Revision></span></code> based on the
+current <code class="docutils literal"><span class="pre">master</span></code> and will create a commit corresponding to <code class="docutils literal"><span class="pre">D<Revision></span></code> with a
+commit message derived from information in the Phabricator review.</p>
+<p>Check you are happy with the commit message and amend it if necessary. Now switch to
+the <code class="docutils literal"><span class="pre">master</span></code> branch and add the new commit to it and commit it to trunk. This
+can be done by running the following:</p>
+<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
+<span class="n">git</span> <span class="n">merge</span> <span class="o">--</span><span class="n">ff</span><span class="o">-</span><span class="n">only</span> <span class="n">arcpatch</span><span class="o">-</span><span class="n">D</span><span class="o"><</span><span class="n">Revision</span><span class="o">></span>
+<span class="n">git</span> <span class="n">svn</span> <span class="n">dcommit</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="abandoning-a-change">
+<h2><a class="toc-backref" href="#id8">Abandoning a change</a><a class="headerlink" href="#abandoning-a-change" title="Permalink to this headline">¶</a></h2>
+<p>If you decide you should not commit the patch, you should explicitly abandon
+the review so that reviewers don’t think it is still open. In the web UI,
+scroll to the bottom of the page where normally you would enter an overall
+comment. In the drop-down Action list, which defaults to “Comment,” you should
+select “Abandon Revision” and then enter a comment explaining why. Click the
+Submit button to finish closing the review.</p>
+</div>
+<div class="section" id="status">
+<h2><a class="toc-backref" href="#id9">Status</a><a class="headerlink" href="#status" title="Permalink to this headline">¶</a></h2>
+<p>Please let us know whether you like it and what could be improved! We’re still
+working on setting up a bug tracker, but you can email klimek-at-google-dot-com
+and chandlerc-at-gmail-dot-com and CC the llvm-dev mailing list with questions
+until then. We also could use help implementing improvements. This sadly is
+really painful and hard because the Phabricator codebase is in PHP and not as
+testable as you might like. However, we’ve put exactly what we’re deploying up
+on an <a class="reference external" href="https://github.com/r4nt/llvm-reviews/">llvm-reviews GitHub project</a> where folks can hack on it and post pull
+requests. We’re looking into what the right long-term hosting for this is, but
+note that it is a derivative of an existing open source project, and so not
+trivially a good fit for an official LLVM project.</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="TestingGuide.html" title="LLVM Testing Infrastructure Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
+ >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-2018, LLVM Project.
+ Last updated on 2018-03-02.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.5.6.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list