[www-releases] r349965 - Add 7.0.1 docs for clang, llvm, and lld
Tom Stellard via llvm-commits
llvm-commits at lists.llvm.org
Fri Dec 21 13:53:04 PST 2018
Added: www-releases/trunk/7.0.1/docs/CommandGuide/llvm-pdbutil.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CommandGuide/llvm-pdbutil.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CommandGuide/llvm-pdbutil.html (added)
+++ www-releases/trunk/7.0.1/docs/CommandGuide/llvm-pdbutil.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,861 @@
+
+
+<!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-pdbutil - PDB File forensics and diagnostics — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-readobj - LLVM Object Reader" href="llvm-readobj.html" />
+ <link rel="prev" title="llvm-exegesis - LLVM Machine Instruction Benchmark" href="llvm-exegesis.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-exegesis.html" title="llvm-exegesis - LLVM Machine Instruction Benchmark"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-pdbutil-pdb-file-forensics-and-diagnostics">
+<h1>llvm-pdbutil - PDB File forensics and diagnostics<a class="headerlink" href="#llvm-pdbutil-pdb-file-forensics-and-diagnostics" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#synopsis" id="id12">Synopsis</a></li>
+<li><a class="reference internal" href="#description" id="id13">Description</a></li>
+<li><a class="reference internal" href="#subcommands" id="id14">Subcommands</a><ul>
+<li><a class="reference internal" href="#pretty" id="id15">pretty</a><ul>
+<li><a class="reference internal" href="#summary" id="id16">Summary</a></li>
+<li><a class="reference internal" href="#options" id="id17">Options</a><ul>
+<li><a class="reference internal" href="#filtering-and-sorting-options" id="id18">Filtering and Sorting Options</a></li>
+<li><a class="reference internal" href="#symbol-type-options" id="id19">Symbol Type Options</a></li>
+<li><a class="reference internal" href="#other-options" id="id20">Other Options</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#dump" id="id21">dump</a><ul>
+<li><a class="reference internal" href="#id1" id="id22">Summary</a></li>
+<li><a class="reference internal" href="#id2" id="id23">Options</a><ul>
+<li><a class="reference internal" href="#msf-container-options" id="id24">MSF Container Options</a></li>
+<li><a class="reference internal" href="#module-file-options" id="id25">Module & File Options</a></li>
+<li><a class="reference internal" href="#symbol-options" id="id26">Symbol Options</a></li>
+<li><a class="reference internal" href="#type-record-options" id="id27">Type Record Options</a></li>
+<li><a class="reference internal" href="#miscellaneous-options" id="id28">Miscellaneous Options</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#bytes" id="id29">bytes</a><ul>
+<li><a class="reference internal" href="#id3" id="id30">Summary</a></li>
+<li><a class="reference internal" href="#id4" id="id31">Options</a><ul>
+<li><a class="reference internal" href="#msf-file-options" id="id32">MSF File Options</a></li>
+<li><a class="reference internal" href="#pdb-stream-options" id="id33">PDB Stream Options</a></li>
+<li><a class="reference internal" href="#dbi-stream-options" id="id34">DBI Stream Options</a></li>
+<li><a class="reference internal" href="#module-options" id="id35">Module Options</a></li>
+<li><a class="reference internal" href="#id5" id="id36">Type Record Options</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#pdb2yaml" id="id37">pdb2yaml</a><ul>
+<li><a class="reference internal" href="#id6" id="id38">Summary</a></li>
+<li><a class="reference internal" href="#id7" id="id39">Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#yaml2pdb" id="id40">yaml2pdb</a><ul>
+<li><a class="reference internal" href="#id8" id="id41">Summary</a></li>
+<li><a class="reference internal" href="#id9" id="id42">Options</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#merge" id="id43">merge</a><ul>
+<li><a class="reference internal" href="#id10" id="id44">Summary</a></li>
+<li><a class="reference internal" href="#id11" id="id45">Options</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="synopsis">
+<h2><a class="toc-backref" href="#id12">Synopsis</a><a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-pdbutil</strong> [<em>subcommand</em>] [<em>options</em>]</p>
+</div>
+<div class="section" id="description">
+<h2><a class="toc-backref" href="#id13">Description</a><a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>Display types, symbols, CodeView records, and other information from a
+PDB file, as well as manipulate and create PDB files. <strong class="program">llvm-pdbutil</strong>
+is normally used by FileCheck-based tests to test LLVM’s PDB reading and
+writing functionality, but can also be used for general PDB file investigation
+and forensics, or as a replacement for cvdump.</p>
+</div>
+<div class="section" id="subcommands">
+<h2><a class="toc-backref" href="#id14">Subcommands</a><a class="headerlink" href="#subcommands" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-pdbutil</strong> is separated into several subcommands each tailored to
+a different purpose. A brief summary of each command follows, with more detail
+in the sections that follow.</p>
+<blockquote>
+<div><ul class="simple">
+<li><a class="reference internal" href="#pretty-subcommand"><em>pretty</em></a> - Dump symbol and type information in a format that
+tries to look as much like the original source code as possible.</li>
+<li><a class="reference internal" href="#dump-subcommand"><em>dump</em></a> - Dump low level types and structures from the PDB
+file, including CodeView records, hash tables, PDB streams, etc.</li>
+<li><a class="reference internal" href="#bytes-subcommand"><em>bytes</em></a> - Dump data from the PDB file’s streams, records,
+types, symbols, etc as raw bytes.</li>
+<li><a class="reference internal" href="#yaml2pdb-subcommand"><em>yaml2pdb</em></a> - Given a yaml description of a PDB file, produce
+a valid PDB file that matches that description.</li>
+<li><a class="reference internal" href="#pdb2yaml-subcommand"><em>pdb2yaml</em></a> - For a given PDB file, produce a YAML
+description of some or all of the file in a way that the PDB can be
+reconstructed.</li>
+<li><a class="reference internal" href="#merge-subcommand"><em>merge</em></a> - Given two PDBs, produce a third PDB that is the
+result of merging the two input PDBs.</li>
+</ul>
+</div></blockquote>
+<div class="section" id="pretty">
+<span id="pretty-subcommand"></span><h3><a class="toc-backref" href="#id15">pretty</a><a class="headerlink" href="#pretty" title="Permalink to this headline">¶</a></h3>
+<div class="admonition important">
+<p class="first admonition-title">Important</p>
+<p class="last">The <strong>pretty</strong> subcommand is built on the Windows DIA SDK, and as such is not
+supported on non-Windows platforms.</p>
+</div>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> pretty [<em>options</em>] <input PDB file></p>
+<div class="section" id="summary">
+<h4><a class="toc-backref" href="#id16">Summary</a><a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h4>
+<p>The <em>pretty</em> subcommand displays a very high level representation of your
+program’s debug info. Since it is built on the Windows DIA SDK which is the
+standard API that Windows tools and debuggers query debug information, it
+presents a more authoritative view of how a debugger is going to interpret your
+debug information than a mode which displays low-level CodeView records.</p>
+</div>
+<div class="section" id="options">
+<h4><a class="toc-backref" href="#id17">Options</a><a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="filtering-and-sorting-options">
+<h5><a class="toc-backref" href="#id18">Filtering and Sorting Options</a><a class="headerlink" href="#filtering-and-sorting-options" title="Permalink to this headline">¶</a></h5>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last"><em>exclude</em> filters take priority over <em>include</em> filters. So if a filter
+matches both an include and an exclude rule, then it is excluded.</p>
+</div>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-exclude-compilands">
+<tt class="descname">-exclude-compilands</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-exclude-compilands" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping compilands, compiland source-file contributions, or per-compiland
+symbols, this option instructs <strong>llvm-pdbutil</strong> to omit any compilands that
+match the specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-exclude-symbols">
+<tt class="descname">-exclude-symbols</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-exclude-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping global, public, or per-compiland symbols, this option instructs
+<strong>llvm-pdbutil</strong> to omit any symbols that match the specified regular
+expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-exclude-types">
+<tt class="descname">-exclude-types</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-exclude-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping types, this option instructs <strong>llvm-pdbutil</strong> to omit any types
+that match the specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-include-compilands">
+<tt class="descname">-include-compilands</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-include-compilands" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping compilands, compiland source-file contributions, or per-compiland
+symbols, limit the initial search to only those compilands that match the
+specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-include-symbols">
+<tt class="descname">-include-symbols</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-include-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping global, public, or per-compiland symbols, limit the initial
+search to only those symbols that match the specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-include-types">
+<tt class="descname">-include-types</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-include-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping types, limit the initial search to only those types that match
+the specified regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-min-class-padding">
+<tt class="descname">-min-class-padding</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-min-class-padding" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only display types that have at least the specified amount of alignment
+padding, accounting for padding in base classes and aggregate field members.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-min-class-padding-imm">
+<tt class="descname">-min-class-padding-imm</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-min-class-padding-imm" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only display types that have at least the specified amount of alignment
+padding, ignoring padding in base classes and aggregate field members.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-min-type-size">
+<tt class="descname">-min-type-size</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-min-type-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only display types T where sizeof(T) is greater than or equal to the specified
+amount.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-no-compiler-generated">
+<tt class="descname">-no-compiler-generated</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-no-compiler-generated" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t show compiler generated types and symbols</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-no-enum-definitions">
+<tt class="descname">-no-enum-definitions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-no-enum-definitions" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping an enum, don’t show the full enum (e.g. the individual enumerator
+values).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-no-system-libs">
+<tt class="descname">-no-system-libs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-no-system-libs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Don’t show symbols from system libraries</p>
+</dd></dl>
+
+</div>
+<div class="section" id="symbol-type-options">
+<h5><a class="toc-backref" href="#id19">Symbol Type Options</a><a class="headerlink" href="#symbol-type-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-all">
+<tt class="descname">-all</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>Implies all other options in this category.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-class-definitions">
+<tt class="descname">-class-definitions</tt><tt class="descclassname">=<format></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-class-definitions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Displays class definitions in the specified format.</p>
+<div class="highlight-text"><div class="highlight"><pre>=all - Display all class members including data, constants, typedefs, functions, etc (default)
+=layout - Only display members that contribute to class size.
+=none - Don't display class definitions (e.g. only display the name and base list)
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-class-order">
+<tt class="descname">-class-order</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-class-order" title="Permalink to this definition">¶</a></dt>
+<dd><p>Displays classes in the specified order.</p>
+<div class="highlight-text"><div class="highlight"><pre>=none - Undefined / no particular sort order (default)
+=name - Sort classes by name
+=size - Sort classes by size
+=padding - Sort classes by amount of padding
+=padding-pct - Sort classes by percentage of space consumed by padding
+=padding-imm - Sort classes by amount of immediate padding
+=padding-pct-imm - Sort classes by percentage of space consumed by immediate padding
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-class-recurse-depth">
+<tt class="descname">-class-recurse-depth</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-class-recurse-depth" title="Permalink to this definition">¶</a></dt>
+<dd><p>When dumping class definitions, stop after recursing the specified number of times. The
+default is 0, which is no limit.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-classes">
+<tt class="descname">-classes</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-classes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display classes</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-compilands">
+<tt class="descname">-compilands</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-compilands" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display compilands (e.g. object files)</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-enums">
+<tt class="descname">-enums</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-enums" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display enums</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-externals">
+<tt class="descname">-externals</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-externals" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump external (e.g. exported) symbols</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-globals">
+<tt class="descname">-globals</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-globals" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump global symbols</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-lines">
+<tt class="descname">-lines</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-lines" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the mappings between source lines and code addresses.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-module-syms">
+<tt class="descname">-module-syms</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-module-syms" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display symbols (variables, functions, etc) for each compiland</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-sym-types">
+<tt class="descname">-sym-types</tt><tt class="descclassname">=<types></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-sym-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>Type of symbols to dump when -globals, -externals, or -module-syms is
+specified. (default all)</p>
+<div class="highlight-text"><div class="highlight"><pre>=thunks - Display thunk symbols
+=data - Display data symbols
+=funcs - Display function symbols
+=all - Display all symbols (default)
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-symbol-order">
+<tt class="descname">-symbol-order</tt><tt class="descclassname">=<order></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-symbol-order" title="Permalink to this definition">¶</a></dt>
+<dd><p>For symbols dumped via the -module-syms, -globals, or -externals options, sort
+the results in specified order.</p>
+<div class="highlight-text"><div class="highlight"><pre>=none - Undefined / no particular sort order
+=name - Sort symbols by name
+=size - Sort symbols by size
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-typedefs">
+<tt class="descname">-typedefs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-typedefs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display typedef types</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-types">
+<tt class="descname">-types</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all types (implies -classes, -enums, -typedefs)</p>
+</dd></dl>
+
+</div>
+<div class="section" id="other-options">
+<h5><a class="toc-backref" href="#id20">Other Options</a><a class="headerlink" href="#other-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-color-output">
+<tt class="descname">-color-output</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-color-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Force color output on or off. By default, color if used if outputting to a
+terminal.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-pretty-load-address">
+<tt class="descname">-load-address</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-pretty-load-address" title="Permalink to this definition">¶</a></dt>
+<dd><p>When displaying relative virtual addresses, assume the process is loaded at the
+given address and display what would be the absolute address.</p>
+</dd></dl>
+
+</div>
+</div>
+</div>
+<div class="section" id="dump">
+<span id="dump-subcommand"></span><h3><a class="toc-backref" href="#id21">dump</a><a class="headerlink" href="#dump" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> dump [<em>options</em>] <input PDB file></p>
+<div class="section" id="id1">
+<h4><a class="toc-backref" href="#id22">Summary</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>The <strong>dump</strong> subcommand displays low level information about the structure of a
+PDB file. It is used heavily by LLVM’s testing infrastructure, but can also be
+used for PDB forensics. It serves a role similar to that of Microsoft’s
+<cite>cvdump</cite> tool.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The <strong>dump</strong> subcommand exposes internal details of the file format. As
+such, the reader should be familiar with <a class="reference internal" href="../PDB/index.html"><em>The PDB File Format</em></a> before using this
+command.</p>
+</div>
+</div>
+<div class="section" id="id2">
+<h4><a class="toc-backref" href="#id23">Options</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="msf-container-options">
+<h5><a class="toc-backref" href="#id24">MSF Container Options</a><a class="headerlink" href="#msf-container-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-streams">
+<tt class="descname">-streams</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-streams" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump a summary of all of the streams in the PDB file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-stream-blocks">
+<tt class="descname">-stream-blocks</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-stream-blocks" title="Permalink to this definition">¶</a></dt>
+<dd><p>In conjunction with <a class="reference internal" href="#cmdoption-llvm-pdbutil-dump-streams"><em class="xref std std-option">-streams</em></a>, add information to the output about
+what blocks the specified stream occupies.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-summary">
+<tt class="descname">-summary</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-summary" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump MSF and PDB header information.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="module-file-options">
+<h5><a class="toc-backref" href="#id25">Module & File Options</a><a class="headerlink" href="#module-file-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-modi">
+<tt class="descname">-modi</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-modi" title="Permalink to this definition">¶</a></dt>
+<dd><p>For all options that dump information from each module/compiland, limit to
+the specified module.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-files">
+<tt class="descname">-files</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-files" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the source files that contribute to each displayed module.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-il">
+<tt class="descname">-il</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-il" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump inlinee line information (DEBUG_S_INLINEELINES CodeView subsection)</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-l">
+<tt class="descname">-l</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-l" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump line information (DEBUG_S_LINES CodeView subsection)</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-modules">
+<tt class="descname">-modules</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-modules" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump compiland information</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-xme">
+<tt class="descname">-xme</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-xme" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump cross module exports (DEBUG_S_CROSSSCOPEEXPORTS CodeView subsection)</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-xmi">
+<tt class="descname">-xmi</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-xmi" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump cross module imports (DEBUG_S_CROSSSCOPEIMPORTS CodeView subsection)</p>
+</dd></dl>
+
+</div>
+<div class="section" id="symbol-options">
+<h5><a class="toc-backref" href="#id26">Symbol Options</a><a class="headerlink" href="#symbol-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-globals">
+<tt class="descname">-globals</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-globals" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump global symbol records</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-global-extras">
+<tt class="descname">-global-extras</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-global-extras" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump additional information about the globals, such as hash buckets and hash
+values.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-publics">
+<tt class="descname">-publics</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-publics" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump public symbol records</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-public-extras">
+<tt class="descname">-public-extras</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-public-extras" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump additional information about the publics, such as hash buckets and hash
+values.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-symbols">
+<tt class="descname">-symbols</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>dump symbols (functions, variables, etc) for each module dumped.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-sym-data">
+<tt class="descname">-sym-data</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-sym-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>For each symbol record dumped as a result of the <a class="reference internal" href="#cmdoption-llvm-pdbutil-dump-symbols"><em class="xref std std-option">-symbols</em></a> option,
+display the full bytes of the record in binary as well.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="type-record-options">
+<h5><a class="toc-backref" href="#id27">Type Record Options</a><a class="headerlink" href="#type-record-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-types">
+<tt class="descname">-types</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump CodeView type records from TPI stream</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-type-extras">
+<tt class="descname">-type-extras</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-type-extras" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump additional information from the TPI stream, such as hashes and the type
+index offsets array.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-type-data">
+<tt class="descname">-type-data</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-type-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>For each type record dumped, display the full bytes of the record in binary as
+well.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-type-index">
+<tt class="descname">-type-index</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-type-index" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only dump types with the specified type index.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-ids">
+<tt class="descname">-ids</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-ids" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump CodeView type records from IPI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-id-extras">
+<tt class="descname">-id-extras</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-id-extras" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump additional information from the IPI stream, such as hashes and the type
+index offsets array.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-id-data">
+<tt class="descname">-id-data</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-id-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>For each ID record dumped, display the full bytes of the record in binary as
+well.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-id-index">
+<tt class="descname">-id-index</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-id-index" title="Permalink to this definition">¶</a></dt>
+<dd><p>only dump ID records with the specified hexadecimal type index.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-dependents">
+<tt class="descname">-dependents</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-dependents" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used in conjunction with <a class="reference internal" href="#cmdoption-llvm-pdbutil-dump-type-index"><em class="xref std std-option">-type-index</em></a> or <a class="reference internal" href="#cmdoption-llvm-pdbutil-dump-id-index"><em class="xref std std-option">-id-index</em></a>,
+dumps the entire dependency graph for the specified index instead of just the
+single record with the specified index. For example, if type index 0x4000 is
+a function whose return type has index 0x3000, and you specify
+<cite>-dependents=0x4000</cite>, then this would dump both records (as well as any other
+dependents in the tree).</p>
+</dd></dl>
+
+</div>
+<div class="section" id="miscellaneous-options">
+<h5><a class="toc-backref" href="#id28">Miscellaneous Options</a><a class="headerlink" href="#miscellaneous-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-all">
+<tt class="descname">-all</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>Implies most other options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-section-contribs">
+<tt class="descname">-section-contribs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-section-contribs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump section contributions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-section-headers">
+<tt class="descname">-section-headers</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-section-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump image section headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-section-map">
+<tt class="descname">-section-map</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-section-map" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump section map.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-dump-string-table">
+<tt class="descname">-string-table</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-dump-string-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump PDB string table.</p>
+</dd></dl>
+
+</div>
+</div>
+</div>
+<div class="section" id="bytes">
+<span id="bytes-subcommand"></span><h3><a class="toc-backref" href="#id29">bytes</a><a class="headerlink" href="#bytes" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> bytes [<em>options</em>] <input PDB file></p>
+<div class="section" id="id3">
+<h4><a class="toc-backref" href="#id30">Summary</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p>Like the <strong>dump</strong> subcommand, the <strong>bytes</strong> subcommand displays low level
+information about the structure of a PDB file, but it is used for even deeper
+forensics. The <strong>bytes</strong> subcommand finds various structures in a PDB file
+based on the command line options specified, and dumps them in hex. Someone
+working on support for emitting PDBs would use this heavily, for example, to
+compare one PDB against another PDB to ensure byte-for-byte compatibility. It
+is not enough to simply compare the bytes of an entire file, or an entire stream
+because it’s perfectly fine for the same structure to exist at different
+locations in two different PDBs, and “finding” the structure is half the battle.</p>
+</div>
+<div class="section" id="id4">
+<h4><a class="toc-backref" href="#id31">Options</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<div class="section" id="msf-file-options">
+<h5><a class="toc-backref" href="#id32">MSF File Options</a><a class="headerlink" href="#msf-file-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-block-range">
+<tt class="descname">-block-range</tt><tt class="descclassname">=<start[-end]></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-block-range" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump binary data from specified range of MSF file blocks.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-byte-range">
+<tt class="descname">-byte-range</tt><tt class="descclassname">=<start[-end]></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-byte-range" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump binary data from specified range of bytes in the file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-fpm">
+<tt class="descname">-fpm</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-fpm" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the MSF free page map.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-stream-data">
+<tt class="descname">-stream-data</tt><tt class="descclassname">=<string></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-stream-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump binary data from the specified streams. Format is SN[:Start][@Size].
+For example, <cite>-stream-data=7:3@12</cite> dumps 12 bytes from stream 7, starting
+at offset 3 in the stream.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="pdb-stream-options">
+<h5><a class="toc-backref" href="#id33">PDB Stream Options</a><a class="headerlink" href="#pdb-stream-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-name-map">
+<tt class="descname">-name-map</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-name-map" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump bytes of PDB Name Map</p>
+</dd></dl>
+
+</div>
+<div class="section" id="dbi-stream-options">
+<h5><a class="toc-backref" href="#id34">DBI Stream Options</a><a class="headerlink" href="#dbi-stream-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-ec">
+<tt class="descname">-ec</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-ec" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the edit and continue map substream of the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-files">
+<tt class="descname">-files</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-files" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the file info substream of the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-modi">
+<tt class="descname">-modi</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-modi" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the modi substream of the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-sc">
+<tt class="descname">-sc</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-sc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump section contributions substream of the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-sm">
+<tt class="descname">-sm</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-sm" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the section map from the DBI stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-type-server">
+<tt class="descname">-type-server</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-type-server" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the type server map from the DBI stream.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="module-options">
+<h5><a class="toc-backref" href="#id35">Module Options</a><a class="headerlink" href="#module-options" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-mod">
+<tt class="descname">-mod</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-mod" title="Permalink to this definition">¶</a></dt>
+<dd><p>Limit all options in this category to the specified module index. By default,
+options in this category will dump bytes from all modules.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-chunks">
+<tt class="descname">-chunks</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-chunks" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the bytes of each module’s C13 debug subsection.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-split-chunks">
+<tt class="descname">-split-chunks</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-split-chunks" title="Permalink to this definition">¶</a></dt>
+<dd><p>When specified with <a class="reference internal" href="#cmdoption-llvm-pdbutil-bytes-chunks"><em class="xref std std-option">-chunks</em></a>, split the C13 debug subsection into a
+separate chunk for each subsection type, and dump them separately.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-syms">
+<tt class="descname">-syms</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-syms" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the symbol record substream from each module.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="id5">
+<h5><a class="toc-backref" href="#id36">Type Record Options</a><a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h5>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-id">
+<tt class="descname">-id</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-id" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the record from the IPI stream with the given type index.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-bytes-type">
+<tt class="descname">-type</tt><tt class="descclassname">=<uint></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-bytes-type" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the record from the TPI stream with the given type index.</p>
+</dd></dl>
+
+</div>
+</div>
+</div>
+<div class="section" id="pdb2yaml">
+<span id="pdb2yaml-subcommand"></span><h3><a class="toc-backref" href="#id37">pdb2yaml</a><a class="headerlink" href="#pdb2yaml" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> pdb2yaml [<em>options</em>] <input PDB file></p>
+<div class="section" id="id6">
+<h4><a class="toc-backref" href="#id38">Summary</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
+</div>
+<div class="section" id="id7">
+<h4><a class="toc-backref" href="#id39">Options</a><a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h4>
+</div>
+</div>
+<div class="section" id="yaml2pdb">
+<span id="yaml2pdb-subcommand"></span><h3><a class="toc-backref" href="#id40">yaml2pdb</a><a class="headerlink" href="#yaml2pdb" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> yaml2pdb [<em>options</em>] <input YAML file></p>
+<div class="section" id="id8">
+<h4><a class="toc-backref" href="#id41">Summary</a><a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h4>
+<p>Generate a PDB file from a YAML description. The YAML syntax is not described
+here. Instead, use <a class="reference internal" href="#pdb2yaml-subcommand"><em>llvm-pdbutil pdb2yaml</em></a> and
+examine the output for an example starting point.</p>
+</div>
+<div class="section" id="id9">
+<h4><a class="toc-backref" href="#id42">Options</a><a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h4>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-yaml2pdb-pdb">
+<tt class="descname">-pdb</tt><tt class="descclassname">=<file-name></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-yaml2pdb-pdb" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Write the resulting PDB to the specified file.</p>
+</div>
+</div>
+<div class="section" id="merge">
+<span id="merge-subcommand"></span><h3><a class="toc-backref" href="#id43">merge</a><a class="headerlink" href="#merge" title="Permalink to this headline">¶</a></h3>
+<p>USAGE: <strong class="program">llvm-pdbutil</strong> merge [<em>options</em>] <input PDB file 1> <input PDB file 2></p>
+<div class="section" id="id10">
+<h4><a class="toc-backref" href="#id44">Summary</a><a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h4>
+<p>Merge two PDB files into a single file.</p>
+</div>
+<div class="section" id="id11">
+<h4><a class="toc-backref" href="#id45">Options</a><a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h4>
+<dl class="option">
+<dt id="cmdoption-llvm-pdbutil-merge-pdb">
+<tt class="descname">-pdb</tt><tt class="descclassname">=<file-name></tt><a class="headerlink" href="#cmdoption-llvm-pdbutil-merge-pdb" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Write the resulting PDB to the specified file.</p>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-exegesis.html" title="llvm-exegesis - LLVM Machine Instruction Benchmark"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CommandGuide/llvm-profdata.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CommandGuide/llvm-profdata.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CommandGuide/llvm-profdata.html (added)
+++ www-releases/trunk/7.0.1/docs/CommandGuide/llvm-profdata.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,330 @@
+
+
+<!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-profdata - Profile data tool — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-stress - generate random .ll files" href="llvm-stress.html" />
+ <link rel="prev" title="llvm-cov - emit coverage information" href="llvm-cov.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-stress.html" title="llvm-stress - generate random .ll files"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-cov.html" title="llvm-cov - emit coverage information"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-profdata-profile-data-tool">
+<h1>llvm-profdata - Profile data tool<a class="headerlink" href="#llvm-profdata-profile-data-tool" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-profdata</strong> <em>command</em> [<em>args...</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-profdata</strong> tool is a small utility for working with profile
+data files.</p>
+</div>
+<div class="section" id="commands">
+<h2>COMMANDS<a class="headerlink" href="#commands" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference internal" href="#profdata-merge"><em>merge</em></a></li>
+<li><a class="reference internal" href="#profdata-show"><em>show</em></a></li>
+</ul>
+</div>
+<div class="section" id="merge">
+<span id="profdata-merge"></span><h2>MERGE<a class="headerlink" href="#merge" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id1">
+<h3>SYNOPSIS<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata merge</strong> [<em>options</em>] [<em>filename...</em>]</p>
+</div>
+<div class="section" id="id2">
+<h3>DESCRIPTION<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata merge</strong> takes several profile data files
+generated by PGO instrumentation and merges them together into a single
+indexed profile data file.</p>
+<p>By default profile data is merged without modification. This means that the
+relative importance of each input file is proportional to the number of samples
+or counts it contains. In general, the input from a longer training run will be
+interpreted as relatively more important than a shorter run. Depending on the
+nature of the training runs it may be useful to adjust the weight given to each
+input file by using the <tt class="docutils literal"><span class="pre">-weighted-input</span></tt> option.</p>
+<p>Profiles passed in via <tt class="docutils literal"><span class="pre">-weighted-input</span></tt>, <tt class="docutils literal"><span class="pre">-input-files</span></tt>, or via positional
+arguments are processed once for each time they are seen.</p>
+</div>
+<div class="section" id="options">
+<h3>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-output">
+<tt class="descname">-output</tt><tt class="descclassname">=output</tt><tt class="descclassname">, </tt><tt class="descname">-o</tt><tt class="descclassname">=output</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output file name. <em>Output</em> cannot be <tt class="docutils literal"><span class="pre">-</span></tt> as the resulting
+indexed profile data can’t be written to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-weighted-input">
+<tt class="descname">-weighted-input</tt><tt class="descclassname">=weight,filename</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-weighted-input" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify an input file name along with a weight. The profile counts of the
+supplied <tt class="docutils literal"><span class="pre">filename</span></tt> will be scaled (multiplied) by the supplied
+<tt class="docutils literal"><span class="pre">weight</span></tt>, where where <tt class="docutils literal"><span class="pre">weight</span></tt> is a decimal integer >= 1.
+Input files specified without using this option are assigned a default
+weight of 1. Examples are shown below.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-input-files">
+<tt class="descname">-input-files</tt><tt class="descclassname">=path</tt><tt class="descclassname">, </tt><tt class="descname">-f</tt><tt class="descclassname">=path</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-input-files" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a file which contains a list of files to merge. The entries in this
+file are newline-separated. Lines starting with ‘#’ are skipped. Entries may
+be of the form <filename> or <weight>,<filename>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-instr">
+<tt class="descname">-instr</tt><tt class="descclassname"> (default)</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-instr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify that the input profile is an instrumentation-based profile.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-sample">
+<tt class="descname">-sample</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-sample" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify that the input profile is a sample-based profile.</p>
+<p>The format of the generated file can be generated in one of three ways:</p>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-binary">
+<tt class="descname">-binary</tt><tt class="descclassname"> (default)</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-binary" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Emit the profile using a binary encoding. For instrumentation-based profile
+the output format is the indexed binary format.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-text">
+<tt class="descname">-text</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-text" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Emit the profile in text mode. This option can also be used with both
+sample-based and instrumentation-based profile. When this option is used
+the profile will be dumped in the text format that is parsable by the profile
+reader.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-gcc">
+<tt class="descname">-gcc</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-gcc" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<p>Emit the profile using GCC’s gcov format (Not yet supported).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-sparse">
+<tt class="descname">-sparse</tt><tt class="descclassname">[=true|false]</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-sparse" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not emit function records with 0 execution count. Can only be used in
+conjunction with -instr. Defaults to false, since it can inhibit compiler
+optimization during PGO.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-num-threads">
+<tt class="descname">-num-threads</tt><tt class="descclassname">=N</tt><tt class="descclassname">, </tt><tt class="descname">-j</tt><tt class="descclassname">=N</tt><a class="headerlink" href="#cmdoption-llvm-profdata-merge-num-threads" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use N threads to perform profile merging. When N=0, llvm-profdata auto-detects
+an appropriate number of threads to use. This is the default.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="examples">
+<h3>EXAMPLES<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="basic-usage">
+<h4>Basic Usage<a class="headerlink" href="#basic-usage" title="Permalink to this headline">¶</a></h4>
+<p>Merge three profiles:</p>
+<div class="highlight-python"><pre>llvm-profdata merge foo.profdata bar.profdata baz.profdata -output merged.profdata</pre>
+</div>
+</div>
+<div class="section" id="weighted-input">
+<h4>Weighted Input<a class="headerlink" href="#weighted-input" title="Permalink to this headline">¶</a></h4>
+<p>The input file <cite>foo.profdata</cite> is especially important, multiply its counts by 10:</p>
+<div class="highlight-python"><pre>llvm-profdata merge -weighted-input=10,foo.profdata bar.profdata baz.profdata -output merged.profdata</pre>
+</div>
+<p>Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):</p>
+<div class="highlight-python"><pre>llvm-profdata merge -weighted-input=10,foo.profdata -weighted-input=1,bar.profdata -weighted-input=1,baz.profdata -output merged.profdata</pre>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="show">
+<span id="profdata-show"></span><h2>SHOW<a class="headerlink" href="#show" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id3">
+<h3>SYNOPSIS<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata show</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="id4">
+<h3>DESCRIPTION<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata show</strong> takes a profile data file and displays the
+information about the profile counters for this file and
+for any of the specified function(s).</p>
+<p>If <em>filename</em> is omitted or is <tt class="docutils literal"><span class="pre">-</span></tt>, then <strong>llvm-profdata show</strong> reads its
+input from standard input.</p>
+</div>
+<div class="section" id="id5">
+<h3>OPTIONS<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-all-functions">
+<tt class="descname">-all-functions</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-all-functions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print details for every function.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-counts">
+<tt class="descname">-counts</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-counts" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the counter values for the displayed functions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-function">
+<tt class="descname">-function</tt><tt class="descclassname">=string</tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-function" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print details for a function if the function’s name contains the given string.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-output">
+<tt class="descname">-output</tt><tt class="descclassname">=output</tt><tt class="descclassname">, </tt><tt class="descname">-o</tt><tt class="descclassname">=output</tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output file name. If <em>output</em> is <tt class="docutils literal"><span class="pre">-</span></tt> or it isn’t specified,
+then the output is sent to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-instr">
+<tt class="descname">-instr</tt><tt class="descclassname"> (default)</tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-instr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify that the input profile is an instrumentation-based profile.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-text">
+<tt class="descname">-text</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-text" title="Permalink to this definition">¶</a></dt>
+<dd><p>Instruct the profile dumper to show profile counts in the text format of the
+instrumentation-based profile data representation. By default, the profile
+information is dumped in a more human readable form (also in text) with
+annotations.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-topn">
+<tt class="descname">-topn</tt><tt class="descclassname">=n</tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-topn" title="Permalink to this definition">¶</a></dt>
+<dd><p>Instruct the profile dumper to show the top <tt class="docutils literal"><span class="pre">n</span></tt> functions with the
+hottest basic blocks in the summary section. By default, the topn functions
+are not dumped.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-sample">
+<tt class="descname">-sample</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-sample" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify that the input profile is a sample-based profile.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-memop-sizes">
+<tt class="descname">-memop-sizes</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-llvm-profdata-show-memop-sizes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the profiled sizes of the memory intrinsic calls for shown functions.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-profdata</strong> returns 1 if the command is omitted or is invalid,
+if it cannot read input files, or if there is a mismatch between their data.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-stress.html" title="llvm-stress - generate random .ll files"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-cov.html" title="llvm-cov - emit coverage information"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CommandGuide/llvm-readobj.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CommandGuide/llvm-readobj.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CommandGuide/llvm-readobj.html (added)
+++ www-releases/trunk/7.0.1/docs/CommandGuide/llvm-readobj.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,218 @@
+
+
+<!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-readobj - LLVM Object Reader — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="Getting Started with the LLVM System" href="../GettingStarted.html" />
+ <link rel="prev" title="llvm-pdbutil - PDB File forensics and diagnostics" href="llvm-pdbutil.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../GettingStarted.html" title="Getting Started with the LLVM System"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-readobj-llvm-object-reader">
+<h1>llvm-readobj - LLVM Object Reader<a class="headerlink" href="#llvm-readobj-llvm-object-reader" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-readobj</strong> [<em>options</em>] [<em>input...</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-readobj</strong> tool displays low-level format-specific information
+about one or more object files. The tool and its output is primarily designed
+for use in FileCheck-based tests.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p>If <tt class="docutils literal"><span class="pre">input</span></tt> is “<tt class="docutils literal"><span class="pre">-</span></tt>” or omitted, <strong class="program">llvm-readobj</strong> reads from standard
+input. Otherwise, it will read from the specified <tt class="docutils literal"><span class="pre">filenames</span></tt>.</p>
+<dl class="option">
+<dt id="cmdoption-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-version">
+<tt class="descname">-version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of this program</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-file-headers">
+<tt class="descname">-file-headers</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-h</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-file-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display file headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-sections">
+<tt class="descname">-sections</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-s</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-sections" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-section-data">
+<tt class="descname">-section-data</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-sd</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-section-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <tt class="docutils literal"><span class="pre">-sections</span></tt>, display section data for each section shown.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-section-relocations">
+<tt class="descname">-section-relocations</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-sr</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-section-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <tt class="docutils literal"><span class="pre">-sections</span></tt>, display relocations for each section shown.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-section-symbols">
+<tt class="descname">-section-symbols</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-st</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-section-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <tt class="docutils literal"><span class="pre">-sections</span></tt>, display symbols for each section shown.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-relocations">
+<tt class="descname">-relocations</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-r</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the relocation entries in the file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-symbols">
+<tt class="descname">-symbols</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-t</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dyn-symbols">
+<tt class="descname">-dyn-symbols</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-dyn-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic symbol table (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-unwind">
+<tt class="descname">-unwind</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-u</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-unwind" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display unwind information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-expand-relocs">
+<tt class="descname">-expand-relocs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-expand-relocs" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <tt class="docutils literal"><span class="pre">-relocations</span></tt>, display each relocation in an expanded
+multi-line format.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dynamic-table">
+<tt class="descname">-dynamic-table</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-dynamic-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the ELF .dynamic section table (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-needed-libs">
+<tt class="descname">-needed-libs</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-needed-libs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the needed libraries (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-program-headers">
+<tt class="descname">-program-headers</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-program-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the ELF program headers (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-elf-section-groups">
+<tt class="descname">-elf-section-groups</tt><tt class="descclassname"></tt><tt class="descclassname">, </tt><tt class="descname">-g</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-elf-section-groups" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display section groups (only for ELF object files).</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-readobj</strong> returns 0.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../GettingStarted.html" title="Getting Started with the LLVM System"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CommandGuide/llvm-stress.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CommandGuide/llvm-stress.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CommandGuide/llvm-stress.html (added)
+++ www-releases/trunk/7.0.1/docs/CommandGuide/llvm-stress.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,136 @@
+
+
+<!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-stress - generate random .ll files — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-symbolizer - convert addresses into source code locations" href="llvm-symbolizer.html" />
+ <link rel="prev" title="llvm-profdata - Profile data tool" href="llvm-profdata.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-symbolizer.html" title="llvm-symbolizer - convert addresses into source code locations"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-profdata.html" title="llvm-profdata - Profile data tool"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-stress-generate-random-ll-files">
+<h1>llvm-stress - generate random .ll files<a class="headerlink" href="#llvm-stress-generate-random-ll-files" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-stress</strong> [-size=filesize] [-seed=initialseed] [-o=outfile]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">llvm-stress</strong> tool is used to generate random <tt class="docutils literal"><span class="pre">.ll</span></tt> files that
+can be used to test different components of LLVM.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-o">
+<tt class="descname">-o</tt><tt class="descclassname"> filename</tt><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output filename.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-size">
+<tt class="descname">-size</tt><tt class="descclassname"> size</tt><a class="headerlink" href="#cmdoption-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the size of the generated <tt class="docutils literal"><span class="pre">.ll</span></tt> file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-seed">
+<tt class="descname">-seed</tt><tt class="descclassname"> seed</tt><a class="headerlink" href="#cmdoption-seed" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the seed to be used for the randomly generated instructions.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-stress</strong> returns 0.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-symbolizer.html" title="llvm-symbolizer - convert addresses into source code locations"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-profdata.html" title="llvm-profdata - Profile data tool"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CommandGuide/llvm-symbolizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CommandGuide/llvm-symbolizer.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CommandGuide/llvm-symbolizer.html (added)
+++ www-releases/trunk/7.0.1/docs/CommandGuide/llvm-symbolizer.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,235 @@
+
+
+<!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-symbolizer - convert addresses into source code locations — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llvm-dwarfdump - dump and verify DWARF debug information" href="llvm-dwarfdump.html" />
+ <link rel="prev" title="llvm-stress - generate random .ll files" href="llvm-stress.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-dwarfdump.html" title="llvm-dwarfdump - dump and verify DWARF debug information"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-stress.html" title="llvm-stress - generate random .ll files"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-symbolizer-convert-addresses-into-source-code-locations">
+<h1>llvm-symbolizer - convert addresses into source code locations<a class="headerlink" href="#llvm-symbolizer-convert-addresses-into-source-code-locations" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-symbolizer</strong> [options]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-symbolizer</strong> reads object file names and addresses from standard
+input and prints corresponding source code locations to standard output.
+If object file is specified in command line, <strong class="program">llvm-symbolizer</strong>
+processes only addresses from standard input, the rest is output verbatim.
+This program uses debug info sections and symbol table in the object files.</p>
+</div>
+<div class="section" id="example">
+<h2>EXAMPLE<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> cat addr.txt
+<span class="go">a.out 0x4004f4</span>
+<span class="go">/tmp/b.out 0x400528</span>
+<span class="go">/tmp/c.so 0x710</span>
+<span class="go">/tmp/mach_universal_binary:i386 0x1f84</span>
+<span class="go">/tmp/mach_universal_binary:x86_64 0x100000f24</span>
+<span class="gp">$</span> llvm-symbolizer < addr.txt
+<span class="go">main</span>
+<span class="go">/tmp/a.cc:4</span>
+
+<span class="go">f(int, int)</span>
+<span class="go">/tmp/b.cc:11</span>
+
+<span class="go">h_inlined_into_g</span>
+<span class="go">/tmp/header.h:2</span>
+<span class="go">g_inlined_into_f</span>
+<span class="go">/tmp/header.h:7</span>
+<span class="go">f_inlined_into_main</span>
+<span class="go">/tmp/source.cc:3</span>
+<span class="go">main</span>
+<span class="go">/tmp/source.cc:8</span>
+
+<span class="go">_main</span>
+<span class="go">/tmp/source_i386.cc:8</span>
+
+<span class="go">_main</span>
+<span class="go">/tmp/source_x86_64.cc:8</span>
+<span class="gp">$</span> cat addr2.txt
+<span class="go">0x4004f4</span>
+<span class="go">0x401000</span>
+<span class="gp">$</span> llvm-symbolizer -obj<span class="o">=</span>a.out < addr2.txt
+<span class="go">main</span>
+<span class="go">/tmp/a.cc:4</span>
+
+<span class="go">foo(int)</span>
+<span class="go">/tmp/a.cc:12</span>
+<span class="gp">$</span>cat addr.txt
+<span class="go">0x40054d</span>
+<span class="gp">$</span>llvm-symbolizer -inlining -print-address -pretty-print -obj<span class="o">=</span>addr.exe < addr.txt
+<span class="go">0x40054d: inc at /tmp/x.c:3:3</span>
+<span class="go"> (inlined by) main at /tmp/x.c:9:0</span>
+<span class="gp">$</span>llvm-symbolizer -inlining -pretty-print -obj<span class="o">=</span>addr.exe < addr.txt
+<span class="go">inc at /tmp/x.c:3:3</span>
+<span class="go"> (inlined by) main at /tmp/x.c:9:0</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-obj">
+<tt class="descname">-obj</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-obj" title="Permalink to this definition">¶</a></dt>
+<dd><p>Path to object file to be symbolized.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-functions">
+<tt class="descname">-functions</tt><tt class="descclassname">=[none|short|linkage]</tt><a class="headerlink" href="#cmdoption-functions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the way function names are printed (omit function name,
+print short function name, or print full linkage name, respectively).
+Defaults to <tt class="docutils literal"><span class="pre">linkage</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-use-symbol-table">
+<tt class="descname">-use-symbol-table</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-use-symbol-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Prefer function names stored in symbol table to function names
+in debug info sections. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-demangle">
+<tt class="descname">-demangle</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-demangle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print demangled function names. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-inlining">
+<tt class="descname">-inlining</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-inlining" title="Permalink to this definition">¶</a></dt>
+<dd><p>If a source code location is in an inlined function, prints all the
+inlnied frames. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-default-arch">
+<tt class="descname">-default-arch</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-default-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>If a binary contains object files for multiple architectures (e.g. it is a
+Mach-O universal binary), symbolize the object file for a given architecture.
+You can also specify architecture by writing <tt class="docutils literal"><span class="pre">binary_name:arch_name</span></tt> in the
+input (see example above). If architecture is not specified in either way,
+address will not be symbolized. Defaults to empty string.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dsym-hint">
+<tt class="descname">-dsym-hint</tt><tt class="descclassname">=<path/to/file.dSYM></tt><a class="headerlink" href="#cmdoption-dsym-hint" title="Permalink to this definition">¶</a></dt>
+<dd><p>(Darwin-only flag). If the debug info for a binary isn’t present in the default
+location, look for the debug info at the .dSYM path provided via the
+<tt class="docutils literal"><span class="pre">-dsym-hint</span></tt> flag. This flag can be used multiple times.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-print-address">
+<tt class="descname">-print-address</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-print-address" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print address before the source code location. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pretty-print">
+<tt class="descname">-pretty-print</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-pretty-print" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print human readable output. If <tt class="docutils literal"><span class="pre">-inlining</span></tt> is specified, enclosing scope is
+prefixed by (inlined by). Refer to listed examples.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-symbolizer</strong> returns 0. Other exit codes imply internal program error.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-dwarfdump.html" title="llvm-dwarfdump - dump and verify DWARF debug information"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-stress.html" title="llvm-stress - generate random .ll files"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CommandGuide/opt.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CommandGuide/opt.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CommandGuide/opt.html (added)
+++ www-releases/trunk/7.0.1/docs/CommandGuide/opt.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,241 @@
+
+
+<!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>opt - LLVM optimizer — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="llc - LLVM static compiler" href="llc.html" />
+ <link rel="prev" title="llvm-dis - LLVM disassembler" href="llvm-dis.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llc.html" title="llc - LLVM static compiler"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-dis.html" title="llvm-dis - LLVM disassembler"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="opt-llvm-optimizer">
+<h1>opt - LLVM optimizer<a class="headerlink" href="#opt-llvm-optimizer" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">opt</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong class="program">opt</strong> command is the modular LLVM optimizer and analyzer. It
+takes LLVM source files as input, runs the specified optimizations or analyses
+on it, and then outputs the optimized file or the analysis results. The
+function of <strong class="program">opt</strong> depends on whether the <cite>-analyze</cite> option is
+given.</p>
+<p>When <cite>-analyze</cite> is specified, <strong class="program">opt</strong> performs various analyses
+of the input source. It will usually print the results on standard output, but
+in a few cases, it will print output to standard error or generate a file with
+the analysis output, which is usually done when the output is meant for another
+program.</p>
+<p>While <cite>-analyze</cite> is <em>not</em> given, <strong class="program">opt</strong> attempts to produce an
+optimized output file. The optimizations available via <strong class="program">opt</strong> depend
+upon what libraries were linked into it as well as any additional libraries
+that have been loaded with the <a class="reference internal" href="#cmdoption-load"><em class="xref std std-option">-load</em></a> option. Use the <a class="reference internal" href="#cmdoption-help"><em class="xref std std-option">-help</em></a>
+option to determine what optimizations you can use.</p>
+<p>If <tt class="docutils literal"><span class="pre">filename</span></tt> is omitted from the command line or is “<tt class="docutils literal"><span class="pre">-</span></tt>”, <strong class="program">opt</strong>
+reads its input from standard input. Inputs can be in either the LLVM assembly
+language format (<tt class="docutils literal"><span class="pre">.ll</span></tt>) or the LLVM bitcode format (<tt class="docutils literal"><span class="pre">.bc</span></tt>).</p>
+<p>If an output filename is not specified with the <a class="reference internal" href="#cmdoption-o"><em class="xref std std-option">-o</em></a> option,
+<strong class="program">opt</strong> writes its output to the standard output.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-f">
+<tt class="descname">-f</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable binary output on terminals. Normally, <strong class="program">opt</strong> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+<strong class="program">opt</strong> will write raw bitcode regardless of the output device.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-o">
+<tt class="descname">-o</tt><tt class="descclassname"> <filename></tt><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output filename.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-S">
+<tt class="descname">-S</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-S" title="Permalink to this definition">¶</a></dt>
+<dd><p>Write output in LLVM intermediate language (instead of bitcode).</p>
+</dd></dl>
+
+<dl class="option">
+<dt>
+<tt class="descname">-{passname}</tt></dt>
+<dd><p><strong class="program">opt</strong> provides the ability to run any of LLVM’s optimization or
+analysis passes in any order. The <a class="reference internal" href="#cmdoption-help"><em class="xref std std-option">-help</em></a> option lists all the passes
+available. The order in which the options occur on the command line are the
+order in which they are executed (within pass constraints).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-disable-inlining">
+<tt class="descname">-disable-inlining</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-disable-inlining" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option simply removes the inlining pass from the standard list.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-disable-opt">
+<tt class="descname">-disable-opt</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-disable-opt" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option is only meaningful when <cite>-std-link-opts</cite> is given. It
+disables most passes.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-strip-debug">
+<tt class="descname">-strip-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-strip-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option causes opt to strip debug information from the module before
+applying other optimizations. It is essentially the same as <cite>-strip</cite>
+but it ensures that stripping of debug information is done first.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-verify-each">
+<tt class="descname">-verify-each</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-verify-each" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option causes opt to add a verify pass after every pass otherwise
+specified on the command line (including <cite>-verify</cite>). This is useful
+for cases where it is suspected that a pass is creating an invalid module but
+it is not clear which pass is doing it.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-stats">
+<tt class="descname">-stats</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print statistics.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-time-passes">
+<tt class="descname">-time-passes</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-time-passes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Record the amount of time needed for each pass and print it to standard
+error.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-debug">
+<tt class="descname">-debug</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>If this is a debug build, this option will enable debug printouts from passes
+which use the <tt class="docutils literal"><span class="pre">LLVM_DEBUG()</span></tt> macro. See the <a class="reference external" href="../ProgrammersManual.html">LLVM Programmer’s Manual</a>, section <tt class="docutils literal"><span class="pre">#DEBUG</span></tt> for more information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-load">
+<tt class="descname">-load</tt><tt class="descclassname">=<plugin></tt><a class="headerlink" href="#cmdoption-load" title="Permalink to this definition">¶</a></dt>
+<dd><p>Load the dynamic object <tt class="docutils literal"><span class="pre">plugin</span></tt>. This object should register new
+optimization or analysis passes. Once loaded, the object will add new command
+line options to enable various optimizations or analyses. To see the new
+complete list of optimizations, use the <a class="reference internal" href="#cmdoption-help"><em class="xref std std-option">-help</em></a> and <a class="reference internal" href="#cmdoption-load"><em class="xref std std-option">-load</em></a>
+options together. For example:</p>
+<div class="highlight-sh"><div class="highlight"><pre>opt -load<span class="o">=</span>plugin.so -help
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-p">
+<tt class="descname">-p</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-p" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print module after each transformation.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">opt</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llc.html" title="llc - LLVM static compiler"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-dis.html" title="llvm-dis - LLVM disassembler"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CommandGuide/tblgen.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CommandGuide/tblgen.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CommandGuide/tblgen.html (added)
+++ www-releases/trunk/7.0.1/docs/CommandGuide/tblgen.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,285 @@
+
+
+<!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>tblgen - Target Description To C++ Code Generator — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="../index.html" />
+ <link rel="up" title="LLVM Command Guide" href="index.html" />
+ <link rel="next" title="lit - LLVM Integrated Tester" href="lit.html" />
+ <link rel="prev" title="FileCheck - Flexible pattern matching file verifier" href="FileCheck.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="lit.html" title="lit - LLVM Integrated Tester"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="FileCheck.html" title="FileCheck - Flexible pattern matching file verifier"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="tblgen-target-description-to-c-code-generator">
+<h1>tblgen - Target Description To C++ Code Generator<a class="headerlink" href="#tblgen-target-description-to-c-code-generator" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">tblgen</strong> [<em>options</em>] [<em>filename</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">tblgen</strong> translates from target description (<tt class="docutils literal"><span class="pre">.td</span></tt>) files into C++
+code that can be included in the definition of an LLVM target library. Most
+users of LLVM will not need to use this program. It is only for assisting with
+writing an LLVM target backend.</p>
+<p>The input and output of <strong class="program">tblgen</strong> is beyond the scope of this short
+introduction; please see the <a class="reference internal" href="../TableGen/index.html"><em>introduction to TableGen</em></a>.</p>
+<p>The <em>filename</em> argument specifies the name of a Target Description (<tt class="docutils literal"><span class="pre">.td</span></tt>)
+file to read as input.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-tblgen-help">
+<tt class="descname">-help</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-o">
+<tt class="descname">-o</tt><tt class="descclassname"> filename</tt><a class="headerlink" href="#cmdoption-tblgen-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output file name. If <tt class="docutils literal"><span class="pre">filename</span></tt> is <tt class="docutils literal"><span class="pre">-</span></tt>, then
+<strong class="program">tblgen</strong> sends its output to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-I">
+<tt class="descname">-I</tt><tt class="descclassname"> directory</tt><a class="headerlink" href="#cmdoption-tblgen-I" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify where to find other target description files for inclusion. The
+<tt class="docutils literal"><span class="pre">directory</span></tt> value should be a full or partial path to a directory that
+contains target description files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-asmparsernum">
+<tt class="descname">-asmparsernum</tt><tt class="descclassname"> N</tt><a class="headerlink" href="#cmdoption-tblgen-asmparsernum" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make -gen-asm-parser emit assembly writer number <tt class="docutils literal"><span class="pre">N</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-asmwriternum">
+<tt class="descname">-asmwriternum</tt><tt class="descclassname"> N</tt><a class="headerlink" href="#cmdoption-tblgen-asmwriternum" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make -gen-asm-writer emit assembly writer number <tt class="docutils literal"><span class="pre">N</span></tt>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-class">
+<tt class="descname">-class</tt><tt class="descclassname"> className</tt><a class="headerlink" href="#cmdoption-tblgen-class" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the enumeration list for this class.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-print-records">
+<tt class="descname">-print-records</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-print-records" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print all records to standard output (default).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-dump-json">
+<tt class="descname">-dump-json</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-dump-json" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a JSON representation of all records, suitable for further
+automated processing.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-print-enums">
+<tt class="descname">-print-enums</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-print-enums" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print enumeration values for a class.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-print-sets">
+<tt class="descname">-print-sets</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-print-sets" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print expanded sets for testing DAG exprs.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-emitter">
+<tt class="descname">-gen-emitter</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-emitter" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate machine code emitter.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-register-info">
+<tt class="descname">-gen-register-info</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-register-info" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate registers and register classes info.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-instr-info">
+<tt class="descname">-gen-instr-info</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-instr-info" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate instruction descriptions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-asm-writer">
+<tt class="descname">-gen-asm-writer</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-asm-writer" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate the assembly writer.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-disassembler">
+<tt class="descname">-gen-disassembler</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-disassembler" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate disassembler.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-pseudo-lowering">
+<tt class="descname">-gen-pseudo-lowering</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-pseudo-lowering" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate pseudo instruction lowering.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-dag-isel">
+<tt class="descname">-gen-dag-isel</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-dag-isel" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate a DAG (Directed Acycle Graph) instruction selector.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-asm-matcher">
+<tt class="descname">-gen-asm-matcher</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-asm-matcher" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate assembly instruction matcher.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-dfa-packetizer">
+<tt class="descname">-gen-dfa-packetizer</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-dfa-packetizer" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate DFA Packetizer for VLIW targets.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-fast-isel">
+<tt class="descname">-gen-fast-isel</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-fast-isel" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate a “fast” instruction selector.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-subtarget">
+<tt class="descname">-gen-subtarget</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-subtarget" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate subtarget enumerations.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-intrinsic-enums">
+<tt class="descname">-gen-intrinsic-enums</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-intrinsic-enums" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate intrinsic enums.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-intrinsic-impl">
+<tt class="descname">-gen-intrinsic-impl</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-intrinsic-impl" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate intrinsic implementation.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-tgt-intrinsic">
+<tt class="descname">-gen-tgt-intrinsic</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-tgt-intrinsic" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate target intrinsic information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-gen-enhanced-disassembly-info">
+<tt class="descname">-gen-enhanced-disassembly-info</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-gen-enhanced-disassembly-info" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate enhanced disassembly info.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-version">
+<tt class="descname">-version</tt><tt class="descclassname"></tt><a class="headerlink" href="#cmdoption-tblgen-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the version number of this program.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">tblgen</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="lit.html" title="lit - LLVM Integrated Tester"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="FileCheck.html" title="FileCheck - Flexible pattern matching file verifier"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CommandLine.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CommandLine.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CommandLine.html (added)
+++ www-releases/trunk/7.0.1/docs/CommandLine.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,1553 @@
+
+
+<!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>CommandLine 2.0 Library Manual — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Architecture & Platform Information for Compiler Writers" href="CompilerWriterInfo.html" />
+ <link rel="prev" title="LLVM Coding Standards" href="CodingStandards.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CodingStandards.html" title="LLVM Coding Standards"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="commandline-2-0-library-manual">
+<h1>CommandLine 2.0 Library Manual<a class="headerlink" href="#commandline-2-0-library-manual" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id8">Introduction</a></li>
+<li><a class="reference internal" href="#quick-start-guide" id="id9">Quick Start Guide</a><ul>
+<li><a class="reference internal" href="#boolean-arguments" id="id10">Boolean Arguments</a></li>
+<li><a class="reference internal" href="#argument-aliases" id="id11">Argument Aliases</a></li>
+<li><a class="reference internal" href="#selecting-an-alternative-from-a-set-of-possibilities" id="id12">Selecting an alternative from a set of possibilities</a></li>
+<li><a class="reference internal" href="#named-alternatives" id="id13">Named Alternatives</a></li>
+<li><a class="reference internal" href="#parsing-a-list-of-options" id="id14">Parsing a list of options</a></li>
+<li><a class="reference internal" href="#collecting-options-as-a-set-of-flags" id="id15">Collecting options as a set of flags</a></li>
+<li><a class="reference internal" href="#adding-freeform-text-to-help-output" id="id16">Adding freeform text to help output</a></li>
+<li><a class="reference internal" href="#grouping-options-into-categories" id="id17">Grouping options into categories</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reference-guide" id="id18">Reference Guide</a><ul>
+<li><a class="reference internal" href="#positional-options" id="id19">Positional Arguments</a><ul>
+<li><a class="reference internal" href="#specifying-positional-options-with-hyphens" id="id20">Specifying positional options with hyphens</a></li>
+<li><a class="reference internal" href="#determining-absolute-position-with-getposition" id="id21">Determining absolute position with getPosition()</a></li>
+<li><a class="reference internal" href="#the-cl-consumeafter-modifier" id="id22">The <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> modifier</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#internal-vs-external-storage" id="id23">Internal vs External Storage</a></li>
+<li><a class="reference internal" href="#option-attributes" id="id24">Option Attributes</a></li>
+<li><a class="reference internal" href="#option-modifiers" id="id25">Option Modifiers</a><ul>
+<li><a class="reference internal" href="#hiding-an-option-from-help-output" id="id26">Hiding an option from <tt class="docutils literal"><span class="pre">-help</span></tt> output</a></li>
+<li><a class="reference internal" href="#controlling-the-number-of-occurrences-required-and-allowed" id="id27">Controlling the number of occurrences required and allowed</a></li>
+<li><a class="reference internal" href="#controlling-whether-or-not-a-value-must-be-specified" id="id28">Controlling whether or not a value must be specified</a></li>
+<li><a class="reference internal" href="#controlling-other-formatting-options" id="id29">Controlling other formatting options</a></li>
+<li><a class="reference internal" href="#miscellaneous-option-modifiers" id="id30">Miscellaneous option modifiers</a></li>
+<li><a class="reference internal" href="#response-files" id="id31">Response files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#top-level-classes-and-functions" id="id32">Top-Level Classes and Functions</a><ul>
+<li><a class="reference internal" href="#the-cl-getregisteredoptions-function" id="id33">The <tt class="docutils literal"><span class="pre">cl::getRegisteredOptions</span></tt> function</a></li>
+<li><a class="reference internal" href="#the-cl-parsecommandlineoptions-function" id="id34">The <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt> function</a></li>
+<li><a class="reference internal" href="#the-cl-parseenvironmentoptions-function" id="id35">The <tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> function</a></li>
+<li><a class="reference internal" href="#the-cl-setversionprinter-function" id="id36">The <tt class="docutils literal"><span class="pre">cl::SetVersionPrinter</span></tt> function</a></li>
+<li><a class="reference internal" href="#the-cl-opt-class" id="id37">The <tt class="docutils literal"><span class="pre">cl::opt</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-list-class" id="id38">The <tt class="docutils literal"><span class="pre">cl::list</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-bits-class" id="id39">The <tt class="docutils literal"><span class="pre">cl::bits</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-alias-class" id="id40">The <tt class="docutils literal"><span class="pre">cl::alias</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-extrahelp-class" id="id41">The <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt> class</a></li>
+<li><a class="reference internal" href="#the-cl-optioncategory-class" id="id42">The <tt class="docutils literal"><span class="pre">cl::OptionCategory</span></tt> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#builtin-parsers" id="id43">Builtin parsers</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#extending-the-library" id="id44">Extension Guide</a><ul>
+<li><a class="reference internal" href="#writing-a-custom-parser" id="id45">Writing a custom parser</a></li>
+<li><a class="reference internal" href="#exploiting-external-storage" id="id46">Exploiting external storage</a></li>
+<li><a class="reference internal" href="#dynamically-adding-command-line-options" id="id47">Dynamically adding command line options</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id8">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the CommandLine argument processing library. It will
+show you how to use it, and what it can do. The CommandLine library uses a
+declarative approach to specifying the command line options that your program
+takes. By default, these options declarations implicitly hold the value parsed
+for the option declared (of course this <a class="reference internal" href="#can-be-changed">can be changed</a>).</p>
+<p>Although there are a <strong>lot</strong> of command line argument parsing libraries out
+there in many different languages, none of them fit well with what I needed. By
+looking at the features and problems of other libraries, I designed the
+CommandLine library to have the following features:</p>
+<ol class="arabic simple">
+<li>Speed: The CommandLine library is very quick and uses little resources. The
+parsing time of the library is directly proportional to the number of
+arguments parsed, not the number of options recognized. Additionally,
+command line argument values are captured transparently into user defined
+global variables, which can be accessed like any other variable (and with the
+same performance).</li>
+<li>Type Safe: As a user of CommandLine, you don’t have to worry about
+remembering the type of arguments that you want (is it an int? a string? a
+bool? an enum?) and keep casting it around. Not only does this help prevent
+error prone constructs, it also leads to dramatically cleaner source code.</li>
+<li>No subclasses required: To use CommandLine, you instantiate variables that
+correspond to the arguments that you would like to capture, you don’t
+subclass a parser. This means that you don’t have to write <strong>any</strong>
+boilerplate code.</li>
+<li>Globally accessible: Libraries can specify command line arguments that are
+automatically enabled in any tool that links to the library. This is
+possible because the application doesn’t have to keep a list of arguments to
+pass to the parser. This also makes supporting <a class="reference internal" href="#dynamically-loaded-options">dynamically loaded options</a>
+trivial.</li>
+<li>Cleaner: CommandLine supports enum and other types directly, meaning that
+there is less error and more security built into the library. You don’t have
+to worry about whether your integral command line argument accidentally got
+assigned a value that is not valid for your enum type.</li>
+<li>Powerful: The CommandLine library supports many different types of arguments,
+from simple <a class="reference internal" href="#boolean-flags">boolean flags</a> to <a class="reference internal" href="#scalars-arguments">scalars arguments</a> (<a class="reference internal" href="#strings">strings</a>,
+<a class="reference internal" href="#integers">integers</a>, <a class="reference internal" href="#enums">enums</a>, <a class="reference internal" href="#doubles">doubles</a>), to <a class="reference internal" href="#lists-of-arguments">lists of arguments</a>. This is
+possible because CommandLine is...</li>
+<li>Extensible: It is very simple to add a new argument type to CommandLine.
+Simply specify the parser that you want to use with the command line option
+when you declare it. <a class="reference internal" href="#custom-parsers">Custom parsers</a> are no problem.</li>
+<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
+that you, the user, have to do. For example, it automatically provides a
+<tt class="docutils literal"><span class="pre">-help</span></tt> option that shows the available command line options for your tool.
+Additionally, it does most of the basic correctness checking for you.</li>
+<li>Capable: The CommandLine library can handle lots of different forms of
+options often found in real programs. For example, <a class="reference internal" href="#positional">positional</a> arguments,
+<tt class="docutils literal"><span class="pre">ls</span></tt> style <a class="reference internal" href="#grouping">grouping</a> options (to allow processing ‘<tt class="docutils literal"><span class="pre">ls</span> <span class="pre">-lad</span></tt>‘
+naturally), <tt class="docutils literal"><span class="pre">ld</span></tt> style <a class="reference internal" href="#prefix">prefix</a> options (to parse ‘<tt class="docutils literal"><span class="pre">-lmalloc</span>
+<span class="pre">-L/usr/lib</span></tt>‘), and interpreter style options.</li>
+</ol>
+<p>This document will hopefully let you jump in and start using CommandLine in your
+utility quickly and painlessly. Additionally it should be a simple reference
+manual to figure out how stuff works.</p>
+</div>
+<div class="section" id="quick-start-guide">
+<h2><a class="toc-backref" href="#id9">Quick Start Guide</a><a class="headerlink" href="#quick-start-guide" title="Permalink to this headline">¶</a></h2>
+<p>This section of the manual runs through a simple CommandLine’ification of a
+basic compiler tool. This is intended to show you how to jump into using the
+CommandLine library in your own program, and show you some of the cool things it
+can do.</p>
+<p>To start out, you need to include the CommandLine header file into your program:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/Support/CommandLine.h"</span>
+</pre></div>
+</div>
+<p>Additionally, you need to add this as the first line of your main program:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">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">cl</span><span class="o">::</span><span class="n">ParseCommandLineOptions</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="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>... which actually parses the arguments and fills in the variable declarations.</p>
+<p>Now that you are ready to support command line arguments, we need to tell the
+system which ones we want, and what type of arguments they are. The CommandLine
+library uses a declarative syntax to model command line arguments with the
+global variable declarations that capture the parsed values. This means that
+for every command line option that you would like to support, there should be a
+global variable declaration to capture the result. For example, in a compiler,
+we would like to support the Unix-standard ‘<tt class="docutils literal"><span class="pre">-o</span> <span class="pre"><filename></span></tt>‘ option to specify
+where to put the output. With the CommandLine library, this is represented like
+this:</p>
+<div class="highlight-c++" id="here"><span id="scalars-arguments"></span><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">OutputFilename</span><span class="p">(</span><span class="s">"o"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Specify output filename"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">value_desc</span><span class="p">(</span><span class="s">"filename"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This declares a global variable “<tt class="docutils literal"><span class="pre">OutputFilename</span></tt>” that is used to capture the
+result of the “<tt class="docutils literal"><span class="pre">o</span></tt>” argument (first parameter). We specify that this is a
+simple scalar option by using the “<tt class="docutils literal"><span class="pre">cl::opt</span></tt>” template (as opposed to the
+“<tt class="docutils literal"><span class="pre">cl::list</span></tt>” template), and tell the CommandLine library that the data
+type that we are parsing is a string.</p>
+<p>The second and third parameters (which are optional) are used to specify what to
+output for the “<tt class="docutils literal"><span class="pre">-help</span></tt>” option. In this case, we get a line that looks like
+this:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options]
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename</pre>
+</div>
+<p>Because we specified that the command line option should parse using the
+<tt class="docutils literal"><span class="pre">string</span></tt> data type, the variable declared is automatically usable as a real
+string in all contexts that a normal C++ string object may be used. For
+example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">...</span>
+<span class="n">std</span><span class="o">::</span><span class="n">ofstream</span> <span class="n">Output</span><span class="p">(</span><span class="n">OutputFilename</span><span class="p">.</span><span class="n">c_str</span><span class="p">());</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">Output</span><span class="p">.</span><span class="n">good</span><span class="p">())</span> <span class="p">...</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>There are many different options that you can use to customize the command line
+option handling library, but the above example shows the general interface to
+these options. The options can be specified in any order, and are specified
+with helper functions like <a class="reference internal" href="#cl-desc">cl::desc(...)</a>, so there are no positional
+dependencies to remember. The available options are discussed in detail in the
+<a class="reference internal" href="#reference-guide">Reference Guide</a>.</p>
+<p>Continuing the example, we would like to have our compiler take an input
+filename as well as an output filename, but we do not want the input filename to
+be specified with a hyphen (ie, not <tt class="docutils literal"><span class="pre">-filename.c</span></tt>). To support this style of
+argument, the CommandLine library allows for <a class="reference internal" href="#positional">positional</a> arguments to be
+specified for the program. These positional arguments are filled with command
+line parameters that are not in option form. We use this feature like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">InputFilename</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input file>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">init</span><span class="p">(</span><span class="s">"-"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>This declaration indicates that the first positional argument should be treated
+as the input filename. Here we use the <a class="reference internal" href="#cl-init">cl::init</a> option to specify an initial
+value for the command line option, which is used if the option is not specified
+(if you do not specify a <a class="reference internal" href="#cl-init">cl::init</a> modifier for an option, then the default
+constructor for the data type is used to initialize the value). Command line
+options default to being optional, so if we would like to require that the user
+always specify an input filename, we would add the <a class="reference internal" href="#cl-required">cl::Required</a> flag, and we
+could eliminate the <a class="reference internal" href="#cl-init">cl::init</a> modifier, like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">InputFilename</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input file>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">Required</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Again, the CommandLine library does not require the options to be specified in
+any particular order, so the above declaration is equivalent to:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">InputFilename</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">Required</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input file>"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>By simply adding the <a class="reference internal" href="#cl-required">cl::Required</a> flag, the CommandLine library will
+automatically issue an error if the argument is not specified, which shifts all
+of the command line option verification code out of your application into the
+library. This is just one example of how using flags can alter the default
+behaviour of the library, on a per-option basis. By adding one of the
+declarations above, the <tt class="docutils literal"><span class="pre">-help</span></tt> option synopsis is now extended to:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename</pre>
+</div>
+<p>... indicating that an input filename is expected.</p>
+<div class="section" id="boolean-arguments">
+<h3><a class="toc-backref" href="#id10">Boolean Arguments</a><a class="headerlink" href="#boolean-arguments" title="Permalink to this headline">¶</a></h3>
+<p>In addition to input and output filenames, we would like the compiler example to
+support three boolean flags: “<tt class="docutils literal"><span class="pre">-f</span></tt>” to force writing binary output to a
+terminal, “<tt class="docutils literal"><span class="pre">--quiet</span></tt>” to enable quiet mode, and “<tt class="docutils literal"><span class="pre">-q</span></tt>” for backwards
+compatibility with some of our users. We can support these by declaring options
+of boolean type like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Force</span> <span class="p">(</span><span class="s">"f"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Enable binary output on terminals"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Quiet</span> <span class="p">(</span><span class="s">"quiet"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Don't print informational messages"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Quiet2</span><span class="p">(</span><span class="s">"q"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Don't print informational messages"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">Hidden</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This does what you would expect: it declares three boolean variables
+(“<tt class="docutils literal"><span class="pre">Force</span></tt>”, “<tt class="docutils literal"><span class="pre">Quiet</span></tt>”, and “<tt class="docutils literal"><span class="pre">Quiet2</span></tt>”) to recognize these options. Note
+that the “<tt class="docutils literal"><span class="pre">-q</span></tt>” option is specified with the “<a class="reference internal" href="#cl-hidden">cl::Hidden</a>” flag. This
+modifier prevents it from being shown by the standard “<tt class="docutils literal"><span class="pre">-help</span></tt>” output (note
+that it is still shown in the “<tt class="docutils literal"><span class="pre">-help-hidden</span></tt>” output).</p>
+<p>The CommandLine library uses a <a class="reference internal" href="#different-parser">different parser</a> for different data types.
+For example, in the string case, the argument passed to the option is copied
+literally into the content of the string variable... we obviously cannot do that
+in the boolean case, however, so we must use a smarter parser. In the case of
+the boolean parser, it allows no options (in which case it assigns the value of
+true to the variable), or it allows the values “<tt class="docutils literal"><span class="pre">true</span></tt>” or “<tt class="docutils literal"><span class="pre">false</span></tt>” to be
+specified, allowing any of the following inputs:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">compiler</span> <span class="o">-</span><span class="n">f</span> <span class="c"># No value, 'Force' == true</span>
+<span class="n">compiler</span> <span class="o">-</span><span class="n">f</span><span class="o">=</span><span class="n">true</span> <span class="c"># Value specified, 'Force' == true</span>
+<span class="n">compiler</span> <span class="o">-</span><span class="n">f</span><span class="o">=</span><span class="n">TRUE</span> <span class="c"># Value specified, 'Force' == true</span>
+<span class="n">compiler</span> <span class="o">-</span><span class="n">f</span><span class="o">=</span><span class="n">FALSE</span> <span class="c"># Value specified, 'Force' == false</span>
+</pre></div>
+</div>
+<p>... you get the idea. The <a class="reference internal" href="#bool-parser">bool parser</a> just turns the string values into
+boolean values, and rejects things like ‘<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-f=foo</span></tt>‘. Similarly, the
+<a class="reference internal" href="#float">float</a>, <a class="reference internal" href="#double">double</a>, and <a class="reference internal" href="#int">int</a> parsers work like you would expect, using the
+‘<tt class="docutils literal"><span class="pre">strtol</span></tt>‘ and ‘<tt class="docutils literal"><span class="pre">strtod</span></tt>‘ C library calls to parse the string value into the
+specified data type.</p>
+<p>With the declarations above, “<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-help</span></tt>” emits this:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ -f - Enable binary output on terminals
+ -o - Override output filename
+ -quiet - Don't print informational messages
+ -help - display available options (-help-hidden for more)</pre>
+</div>
+<p>and “<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-help-hidden</span></tt>” prints this:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ -f - Enable binary output on terminals
+ -o - Override output filename
+ -q - Don't print informational messages
+ -quiet - Don't print informational messages
+ -help - display available options (-help-hidden for more)</pre>
+</div>
+<p>This brief example has shown you how to use the ‘<a class="reference internal" href="#cl-opt">cl::opt</a>‘ class to parse
+simple scalar command line arguments. In addition to simple scalar arguments,
+the CommandLine library also provides primitives to support CommandLine option
+<a class="reference internal" href="#aliases">aliases</a>, and <a class="reference internal" href="#lists">lists</a> of options.</p>
+</div>
+<div class="section" id="argument-aliases">
+<span id="aliases"></span><h3><a class="toc-backref" href="#id11">Argument Aliases</a><a class="headerlink" href="#argument-aliases" title="Permalink to this headline">¶</a></h3>
+<p>So far, the example works well, except for the fact that we need to check the
+quiet condition like this now:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">Quiet</span> <span class="o">&&</span> <span class="o">!</span><span class="n">Quiet2</span><span class="p">)</span> <span class="n">printInformationalMessage</span><span class="p">(...);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>... which is a real pain! Instead of defining two values for the same
+condition, we can use the “<a class="reference internal" href="#cl-alias">cl::alias</a>” class to make the “<tt class="docutils literal"><span class="pre">-q</span></tt>” option an
+<strong>alias</strong> for the “<tt class="docutils literal"><span class="pre">-quiet</span></tt>” option, instead of providing a value itself:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Force</span> <span class="p">(</span><span class="s">"f"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Overwrite output files"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Quiet</span> <span class="p">(</span><span class="s">"quiet"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Don't print informational messages"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">alias</span> <span class="n">QuietA</span><span class="p">(</span><span class="s">"q"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Alias for -quiet"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">aliasopt</span><span class="p">(</span><span class="n">Quiet</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>The third line (which is the only one we modified from above) defines a “<tt class="docutils literal"><span class="pre">-q</span></tt>”
+alias that updates the “<tt class="docutils literal"><span class="pre">Quiet</span></tt>” variable (as specified by the <a class="reference internal" href="#cl-aliasopt">cl::aliasopt</a>
+modifier) whenever it is specified. Because aliases do not hold state, the only
+thing the program has to query is the <tt class="docutils literal"><span class="pre">Quiet</span></tt> variable now. Another nice
+feature of aliases is that they automatically hide themselves from the <tt class="docutils literal"><span class="pre">-help</span></tt>
+output (although, again, they are still visible in the <tt class="docutils literal"><span class="pre">-help-hidden</span> <span class="pre">output</span></tt>).</p>
+<p>Now the application code can simply use:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">Quiet</span><span class="p">)</span> <span class="n">printInformationalMessage</span><span class="p">(...);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>... which is much nicer! The “<a class="reference internal" href="#cl-alias">cl::alias</a>” can be used to specify an
+alternative name for any variable type, and has many uses.</p>
+</div>
+<div class="section" id="selecting-an-alternative-from-a-set-of-possibilities">
+<span id="unnamed-alternatives-using-the-generic-parser"></span><h3><a class="toc-backref" href="#id12">Selecting an alternative from a set of possibilities</a><a class="headerlink" href="#selecting-an-alternative-from-a-set-of-possibilities" title="Permalink to this headline">¶</a></h3>
+<p>So far we have seen how the CommandLine library handles builtin types like
+<tt class="docutils literal"><span class="pre">std::string</span></tt>, <tt class="docutils literal"><span class="pre">bool</span></tt> and <tt class="docutils literal"><span class="pre">int</span></tt>, but how does it handle things it doesn’t
+know about, like enums or ‘<tt class="docutils literal"><span class="pre">int*</span></tt>‘s?</p>
+<p>The answer is that it uses a table-driven generic parser (unless you specify
+your own parser, as described in the <a class="reference internal" href="#extension-guide">Extension Guide</a>). This parser maps
+literal strings to whatever type is required, and requires you to tell it what
+this mapping should be.</p>
+<p>Let’s say that we would like to add four optimization levels to our optimizer,
+using the standard flags “<tt class="docutils literal"><span class="pre">-g</span></tt>”, “<tt class="docutils literal"><span class="pre">-O0</span></tt>”, “<tt class="docutils literal"><span class="pre">-O1</span></tt>”, and “<tt class="docutils literal"><span class="pre">-O2</span></tt>”. We
+could easily implement this with boolean options like above, but there are
+several problems with this strategy:</p>
+<ol class="arabic simple">
+<li>A user could specify more than one of the options at a time, for example,
+“<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-O3</span> <span class="pre">-O2</span></tt>”. The CommandLine library would not be able to catch
+this erroneous input for us.</li>
+<li>We would have to test 4 different variables to see which ones are set.</li>
+<li>This doesn’t map to the numeric levels that we want... so we cannot easily
+see if some level >= “<tt class="docutils literal"><span class="pre">-O1</span></tt>” is enabled.</li>
+</ol>
+<p>To cope with these problems, we can use an enum value, and have the CommandLine
+library fill it in with the appropriate level directly, which is used like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">OptLevel</span> <span class="p">{</span>
+ <span class="n">g</span><span class="p">,</span> <span class="n">O1</span><span class="p">,</span> <span class="n">O2</span><span class="p">,</span> <span class="n">O3</span>
+<span class="p">};</span>
+
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">OptLevel</span><span class="o">></span> <span class="n">OptimizationLevel</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Choose optimization level:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">g</span> <span class="p">,</span> <span class="s">"No optimizations, enable debugging"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O1</span><span class="p">,</span> <span class="s">"Enable trivial optimizations"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O2</span><span class="p">,</span> <span class="s">"Enable default optimizations"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O3</span><span class="p">,</span> <span class="s">"Enable expensive optimizations"</span><span class="p">)));</span>
+
+<span class="p">...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">OptimizationLevel</span> <span class="o">>=</span> <span class="n">O2</span><span class="p">)</span> <span class="n">doPartialRedundancyElimination</span><span class="p">(...);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>This declaration defines a variable “<tt class="docutils literal"><span class="pre">OptimizationLevel</span></tt>” of the
+“<tt class="docutils literal"><span class="pre">OptLevel</span></tt>” enum type. This variable can be assigned any of the values that
+are listed in the declaration. The CommandLine library enforces that
+the user can only specify one of the options, and it ensure that only valid enum
+values can be specified. The “<tt class="docutils literal"><span class="pre">clEnumVal</span></tt>” macros ensure that the command
+line arguments matched the enum values. With this option added, our help output
+now is:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ Choose optimization level:
+ -g - No optimizations, enable debugging
+ -O1 - Enable trivial optimizations
+ -O2 - Enable default optimizations
+ -O3 - Enable expensive optimizations
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename
+ -quiet - Don't print informational messages</pre>
+</div>
+<p>In this case, it is sort of awkward that flag names correspond directly to enum
+names, because we probably don’t want a enum definition named “<tt class="docutils literal"><span class="pre">g</span></tt>” in our
+program. Because of this, we can alternatively write this example like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">OptLevel</span> <span class="p">{</span>
+ <span class="n">Debug</span><span class="p">,</span> <span class="n">O1</span><span class="p">,</span> <span class="n">O2</span><span class="p">,</span> <span class="n">O3</span>
+<span class="p">};</span>
+
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">OptLevel</span><span class="o">></span> <span class="n">OptimizationLevel</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Choose optimization level:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumValN</span><span class="p">(</span><span class="n">Debug</span><span class="p">,</span> <span class="s">"g"</span><span class="p">,</span> <span class="s">"No optimizations, enable debugging"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O1</span> <span class="p">,</span> <span class="s">"Enable trivial optimizations"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O2</span> <span class="p">,</span> <span class="s">"Enable default optimizations"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">O3</span> <span class="p">,</span> <span class="s">"Enable expensive optimizations"</span><span class="p">)));</span>
+
+<span class="p">...</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">OptimizationLevel</span> <span class="o">==</span> <span class="n">Debug</span><span class="p">)</span> <span class="n">outputDebugInfo</span><span class="p">(...);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>By using the “<tt class="docutils literal"><span class="pre">clEnumValN</span></tt>” macro instead of “<tt class="docutils literal"><span class="pre">clEnumVal</span></tt>”, we can directly
+specify the name that the flag should get. In general a direct mapping is nice,
+but sometimes you can’t or don’t want to preserve the mapping, which is when you
+would use it.</p>
+</div>
+<div class="section" id="named-alternatives">
+<h3><a class="toc-backref" href="#id13">Named Alternatives</a><a class="headerlink" href="#named-alternatives" title="Permalink to this headline">¶</a></h3>
+<p>Another useful argument form is a named alternative style. We shall use this
+style in our compiler to specify different debug levels that can be used.
+Instead of each debug level being its own switch, we want to support the
+following options, of which only one can be specified at a time:
+“<tt class="docutils literal"><span class="pre">--debug-level=none</span></tt>”, “<tt class="docutils literal"><span class="pre">--debug-level=quick</span></tt>”,
+“<tt class="docutils literal"><span class="pre">--debug-level=detailed</span></tt>”. To do this, we use the exact same format as our
+optimization level flags, but we also specify an option name. For this case,
+the code looks like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">DebugLev</span> <span class="p">{</span>
+ <span class="n">nodebuginfo</span><span class="p">,</span> <span class="n">quick</span><span class="p">,</span> <span class="n">detailed</span>
+<span class="p">};</span>
+
+<span class="c1">// Enable Debug Options to be specified on the command line</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">DebugLev</span><span class="o">></span> <span class="n">DebugLevel</span><span class="p">(</span><span class="s">"debug_level"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Set the debugging level:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumValN</span><span class="p">(</span><span class="n">nodebuginfo</span><span class="p">,</span> <span class="s">"none"</span><span class="p">,</span> <span class="s">"disable debug information"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">quick</span><span class="p">,</span> <span class="s">"enable quick debug information"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">detailed</span><span class="p">,</span> <span class="s">"enable detailed debug information"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>This definition defines an enumerated command line variable of type “<tt class="docutils literal"><span class="pre">enum</span>
+<span class="pre">DebugLev</span></tt>”, which works exactly the same way as before. The difference here is
+just the interface exposed to the user of your program and the help output by
+the “<tt class="docutils literal"><span class="pre">-help</span></tt>” option:</p>
+<div class="highlight-python"><pre>USAGE: compiler [options] <input file>
+
+OPTIONS:
+ Choose optimization level:
+ -g - No optimizations, enable debugging
+ -O1 - Enable trivial optimizations
+ -O2 - Enable default optimizations
+ -O3 - Enable expensive optimizations
+ -debug_level - Set the debugging level:
+ =none - disable debug information
+ =quick - enable quick debug information
+ =detailed - enable detailed debug information
+ -f - Enable binary output on terminals
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename
+ -quiet - Don't print informational messages</pre>
+</div>
+<p>Again, the only structural difference between the debug level declaration and
+the optimization level declaration is that the debug level declaration includes
+an option name (<tt class="docutils literal"><span class="pre">"debug_level"</span></tt>), which automatically changes how the library
+processes the argument. The CommandLine library supports both forms so that you
+can choose the form most appropriate for your application.</p>
+</div>
+<div class="section" id="parsing-a-list-of-options">
+<span id="lists"></span><h3><a class="toc-backref" href="#id14">Parsing a list of options</a><a class="headerlink" href="#parsing-a-list-of-options" title="Permalink to this headline">¶</a></h3>
+<p>Now that we have the standard run-of-the-mill argument types out of the way,
+lets get a little wild and crazy. Lets say that we want our optimizer to accept
+a <strong>list</strong> of optimizations to perform, allowing duplicates. For example, we
+might want to run: “<tt class="docutils literal"><span class="pre">compiler</span> <span class="pre">-dce</span> <span class="pre">-constprop</span> <span class="pre">-inline</span> <span class="pre">-dce</span> <span class="pre">-strip</span></tt>”. In this
+case, the order of the arguments and the number of appearances is very
+important. This is what the “<tt class="docutils literal"><span class="pre">cl::list</span></tt>” template is for. First, start by
+defining an enum of the optimizations that you would like to perform:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">enum</span> <span class="n">Opts</span> <span class="p">{</span>
+ <span class="c1">// 'inline' is a C++ keyword, so name it 'inlining'</span>
+ <span class="n">dce</span><span class="p">,</span> <span class="n">constprop</span><span class="p">,</span> <span class="n">inlining</span><span class="p">,</span> <span class="n">strip</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Then define your “<tt class="docutils literal"><span class="pre">cl::list</span></tt>” variable:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">Opts</span><span class="o">></span> <span class="n">OptimizationList</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Available Optimizations:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">dce</span> <span class="p">,</span> <span class="s">"Dead Code Elimination"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">constprop</span> <span class="p">,</span> <span class="s">"Constant Propagation"</span><span class="p">),</span>
+ <span class="n">clEnumValN</span><span class="p">(</span><span class="n">inlining</span><span class="p">,</span> <span class="s">"inline"</span><span class="p">,</span> <span class="s">"Procedure Integration"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">strip</span> <span class="p">,</span> <span class="s">"Strip Symbols"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>This defines a variable that is conceptually of the type
+“<tt class="docutils literal"><span class="pre">std::vector<enum</span> <span class="pre">Opts></span></tt>”. Thus, you can access it with standard vector
+methods:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">OptimizationList</span><span class="p">.</span><span class="n">size</span><span class="p">();</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="n">OptimizationList</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+<p>... to iterate through the list of options specified.</p>
+<p>Note that the “<tt class="docutils literal"><span class="pre">cl::list</span></tt>” template is completely general and may be used with
+any data types or other arguments that you can use with the “<tt class="docutils literal"><span class="pre">cl::opt</span></tt>”
+template. One especially useful way to use a list is to capture all of the
+positional arguments together if there may be more than one specified. In the
+case of a linker, for example, the linker takes several ‘<tt class="docutils literal"><span class="pre">.o</span></tt>‘ files, and
+needs to capture them into a list. This is naturally specified as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="p">...</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span> <span class="n">InputFilenames</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<Input files>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">OneOrMore</span><span class="p">);</span>
+<span class="p">...</span>
+</pre></div>
+</div>
+<p>This variable works just like a “<tt class="docutils literal"><span class="pre">vector<string></span></tt>” object. As such, accessing
+the list is simple, just like above. In this example, we used the
+<a class="reference internal" href="#cl-oneormore">cl::OneOrMore</a> modifier to inform the CommandLine library that it is an error
+if the user does not specify any <tt class="docutils literal"><span class="pre">.o</span></tt> files on our command line. Again, this
+just reduces the amount of checking we have to do.</p>
+</div>
+<div class="section" id="collecting-options-as-a-set-of-flags">
+<h3><a class="toc-backref" href="#id15">Collecting options as a set of flags</a><a class="headerlink" href="#collecting-options-as-a-set-of-flags" title="Permalink to this headline">¶</a></h3>
+<p>Instead of collecting sets of options in a list, it is also possible to gather
+information for enum values in a <strong>bit vector</strong>. The representation used by the
+<a class="reference internal" href="#cl-bits">cl::bits</a> class is an <tt class="docutils literal"><span class="pre">unsigned</span></tt> integer. An enum value is represented by a
+0/1 in the enum’s ordinal value bit position. 1 indicating that the enum was
+specified, 0 otherwise. As each specified value is parsed, the resulting enum’s
+bit is set in the option’s bit vector:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">bits</span> <span class="o">|=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="p">(</span><span class="kt">unsigned</span><span class="p">)</span><span class="k">enum</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Options that are specified multiple times are redundant. Any instances after
+the first are discarded.</p>
+<p>Reworking the above list example, we could replace <a class="reference internal" href="#cl-list">cl::list</a> with <a class="reference internal" href="#cl-bits">cl::bits</a>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">bits</span><span class="o"><</span><span class="n">Opts</span><span class="o">></span> <span class="n">OptimizationBits</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Available Optimizations:"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">values</span><span class="p">(</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">dce</span> <span class="p">,</span> <span class="s">"Dead Code Elimination"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">constprop</span> <span class="p">,</span> <span class="s">"Constant Propagation"</span><span class="p">),</span>
+ <span class="n">clEnumValN</span><span class="p">(</span><span class="n">inlining</span><span class="p">,</span> <span class="s">"inline"</span><span class="p">,</span> <span class="s">"Procedure Integration"</span><span class="p">),</span>
+ <span class="n">clEnumVal</span><span class="p">(</span><span class="n">strip</span> <span class="p">,</span> <span class="s">"Strip Symbols"</span><span class="p">)));</span>
+</pre></div>
+</div>
+<p>To test to see if <tt class="docutils literal"><span class="pre">constprop</span></tt> was specified, we can use the <tt class="docutils literal"><span class="pre">cl:bits::isSet</span></tt>
+function:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">if</span> <span class="p">(</span><span class="n">OptimizationBits</span><span class="p">.</span><span class="n">isSet</span><span class="p">(</span><span class="n">constprop</span><span class="p">))</span> <span class="p">{</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It’s also possible to get the raw bit vector using the <tt class="docutils literal"><span class="pre">cl::bits::getBits</span></tt>
+function:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">unsigned</span> <span class="n">bits</span> <span class="o">=</span> <span class="n">OptimizationBits</span><span class="p">.</span><span class="n">getBits</span><span class="p">();</span>
+</pre></div>
+</div>
+<p>Finally, if external storage is used, then the location specified must be of
+<strong>type</strong> <tt class="docutils literal"><span class="pre">unsigned</span></tt>. In all other ways a <a class="reference internal" href="#cl-bits">cl::bits</a> option is equivalent to a
+<a class="reference internal" href="#cl-list">cl::list</a> option.</p>
+</div>
+<div class="section" id="adding-freeform-text-to-help-output">
+<span id="additional-extra-text"></span><h3><a class="toc-backref" href="#id16">Adding freeform text to help output</a><a class="headerlink" href="#adding-freeform-text-to-help-output" title="Permalink to this headline">¶</a></h3>
+<p>As our program grows and becomes more mature, we may decide to put summary
+information about what it does into the help output. The help output is styled
+to look similar to a Unix <tt class="docutils literal"><span class="pre">man</span></tt> page, providing concise information about a
+program. Unix <tt class="docutils literal"><span class="pre">man</span></tt> pages, however often have a description about what the
+program does. To add this to your CommandLine program, simply pass a third
+argument to the <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a> call in main. This additional
+argument is then printed as the overview information for your program, allowing
+you to include any additional information that you want. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">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">cl</span><span class="o">::</span><span class="n">ParseCommandLineOptions</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="s">" CommandLine compiler example</span><span class="se">\n\n</span><span class="s">"</span>
+ <span class="s">" This program blah blah blah...</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>would yield the help output:</p>
+<div class="highlight-python"><pre>**OVERVIEW: CommandLine compiler example
+
+ This program blah blah blah...**
+
+USAGE: compiler [options] <input file>
+
+OPTIONS:
+ ...
+ -help - display available options (-help-hidden for more)
+ -o <filename> - Specify output filename</pre>
+</div>
+</div>
+<div class="section" id="grouping-options-into-categories">
+<span id="id1"></span><h3><a class="toc-backref" href="#id17">Grouping options into categories</a><a class="headerlink" href="#grouping-options-into-categories" title="Permalink to this headline">¶</a></h3>
+<p>If our program has a large number of options it may become difficult for users
+of our tool to navigate the output of <tt class="docutils literal"><span class="pre">-help</span></tt>. To alleviate this problem we
+can put our options into categories. This can be done by declaring option
+categories (<a class="reference internal" href="#cl-optioncategory">cl::OptionCategory</a> objects) and then placing our options into
+these categories using the <a class="reference internal" href="#cl-cat">cl::cat</a> option attribute. For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">OptionCategory</span> <span class="n">StageSelectionCat</span><span class="p">(</span><span class="s">"Stage Selection Options"</span><span class="p">,</span>
+ <span class="s">"These control which stages are run."</span><span class="p">);</span>
+
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Preprocessor</span><span class="p">(</span><span class="s">"E"</span><span class="p">,</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Run preprocessor stage."</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">cat</span><span class="p">(</span><span class="n">StageSelectionCat</span><span class="p">));</span>
+
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">NoLink</span><span class="p">(</span><span class="s">"c"</span><span class="p">,</span><span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Run all stages except linking."</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">cat</span><span class="p">(</span><span class="n">StageSelectionCat</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>The output of <tt class="docutils literal"><span class="pre">-help</span></tt> will become categorized if an option category is
+declared. The output looks something like</p>
+<div class="highlight-python"><pre>OVERVIEW: This is a small program to demo the LLVM CommandLine API
+USAGE: Sample [options]
+
+OPTIONS:
+
+ General options:
+
+ -help - Display available options (-help-hidden for more)
+ -help-list - Display list of available options (-help-list-hidden for more)
+
+
+ Stage Selection Options:
+ These control which stages are run.
+
+ -E - Run preprocessor stage.
+ -c - Run all stages except linking.</pre>
+</div>
+<p>In addition to the behaviour of <tt class="docutils literal"><span class="pre">-help</span></tt> changing when an option category is
+declared, the command line option <tt class="docutils literal"><span class="pre">-help-list</span></tt> becomes visible which will
+print the command line options as uncategorized list.</p>
+<p>Note that Options that are not explicitly categorized will be placed in the
+<tt class="docutils literal"><span class="pre">cl::GeneralCategory</span></tt> category.</p>
+</div>
+</div>
+<div class="section" id="reference-guide">
+<span id="id2"></span><h2><a class="toc-backref" href="#id18">Reference Guide</a><a class="headerlink" href="#reference-guide" title="Permalink to this headline">¶</a></h2>
+<p>Now that you know the basics of how to use the CommandLine library, this section
+will give you the detailed information you need to tune how command line options
+work, as well as information on more “advanced” command line option processing
+capabilities.</p>
+<div class="section" id="positional-options">
+<span id="positional-arguments-section"></span><span id="positional-arguments"></span><span id="positional-argument"></span><span id="positional"></span><span id="id3"></span><h3><a class="toc-backref" href="#id19">Positional Arguments</a><a class="headerlink" href="#positional-options" title="Permalink to this headline">¶</a></h3>
+<p>Positional arguments are those arguments that are not named, and are not
+specified with a hyphen. Positional arguments should be used when an option is
+specified by its position alone. For example, the standard Unix <tt class="docutils literal"><span class="pre">grep</span></tt> tool
+takes a regular expression argument, and an optional filename to search through
+(which defaults to standard input if a filename is not specified). Using the
+CommandLine library, this would be specified as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">Regex</span> <span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<regular expression>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">Required</span><span class="p">);</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">Filename</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input file>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">init</span><span class="p">(</span><span class="s">"-"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>Given these two option declarations, the <tt class="docutils literal"><span class="pre">-help</span></tt> output for our grep
+replacement would look like this:</p>
+<div class="highlight-python"><pre>USAGE: spiffygrep [options] <regular expression> <input file>
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)</pre>
+</div>
+<p>... and the resultant program could be used just like the standard <tt class="docutils literal"><span class="pre">grep</span></tt>
+tool.</p>
+<p>Positional arguments are sorted by their order of construction. This means that
+command line options will be ordered according to how they are listed in a .cpp
+file, but will not have an ordering defined if the positional arguments are
+defined in multiple .cpp files. The fix for this problem is simply to define
+all of your positional arguments in one .cpp file.</p>
+<div class="section" id="specifying-positional-options-with-hyphens">
+<h4><a class="toc-backref" href="#id20">Specifying positional options with hyphens</a><a class="headerlink" href="#specifying-positional-options-with-hyphens" title="Permalink to this headline">¶</a></h4>
+<p>Sometimes you may want to specify a value to your positional argument that
+starts with a hyphen (for example, searching for ‘<tt class="docutils literal"><span class="pre">-foo</span></tt>‘ in a file). At
+first, you will have trouble doing this, because it will try to find an argument
+named ‘<tt class="docutils literal"><span class="pre">-foo</span></tt>‘, and will fail (and single quotes will not save you). Note
+that the system <tt class="docutils literal"><span class="pre">grep</span></tt> has the same problem:</p>
+<div class="highlight-python"><pre>$ spiffygrep '-foo' test.txt
+Unknown command line argument '-foo'. Try: spiffygrep -help'
+
+$ grep '-foo' test.txt
+grep: illegal option -- f
+grep: illegal option -- o
+grep: illegal option -- o
+Usage: grep -hblcnsviw pattern file . . .</pre>
+</div>
+<p>The solution for this problem is the same for both your tool and the system
+version: use the ‘<tt class="docutils literal"><span class="pre">--</span></tt>‘ marker. When the user specifies ‘<tt class="docutils literal"><span class="pre">--</span></tt>‘ on the
+command line, it is telling the program that all options after the ‘<tt class="docutils literal"><span class="pre">--</span></tt>‘
+should be treated as positional arguments, not options. Thus, we can use it
+like this:</p>
+<div class="highlight-python"><pre>$ spiffygrep -- -foo test.txt
+ ...output...</pre>
+</div>
+</div>
+<div class="section" id="determining-absolute-position-with-getposition">
+<h4><a class="toc-backref" href="#id21">Determining absolute position with getPosition()</a><a class="headerlink" href="#determining-absolute-position-with-getposition" title="Permalink to this headline">¶</a></h4>
+<p>Sometimes an option can affect or modify the meaning of another option. For
+example, consider <tt class="docutils literal"><span class="pre">gcc</span></tt>‘s <tt class="docutils literal"><span class="pre">-x</span> <span class="pre">LANG</span></tt> option. This tells <tt class="docutils literal"><span class="pre">gcc</span></tt> to ignore the
+suffix of subsequent positional arguments and force the file to be interpreted
+as if it contained source code in language <tt class="docutils literal"><span class="pre">LANG</span></tt>. In order to handle this
+properly, you need to know the absolute position of each argument, especially
+those in lists, so their interaction(s) can be applied correctly. This is also
+useful for options like <tt class="docutils literal"><span class="pre">-llibname</span></tt> which is actually a positional argument
+that starts with a dash.</p>
+<p>So, generally, the problem is that you have two <tt class="docutils literal"><span class="pre">cl::list</span></tt> variables that
+interact in some way. To ensure the correct interaction, you can use the
+<tt class="docutils literal"><span class="pre">cl::list::getPosition(optnum)</span></tt> method. This method returns the absolute
+position (as found on the command line) of the <tt class="docutils literal"><span class="pre">optnum</span></tt> item in the
+<tt class="docutils literal"><span class="pre">cl::list</span></tt>.</p>
+<p>The idiom for usage is like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span> <span class="n">Files</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">OneOrMore</span><span class="p">);</span>
+<span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span> <span class="n">Libraries</span><span class="p">(</span><span class="s">"l"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">ZeroOrMore</span><span class="p">);</span>
+
+<span class="kt">int</span> <span class="n">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="c1">// ...</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">>::</span><span class="n">iterator</span> <span class="n">fileIt</span> <span class="o">=</span> <span class="n">Files</span><span class="p">.</span><span class="n">begin</span><span class="p">();</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">>::</span><span class="n">iterator</span> <span class="n">libIt</span> <span class="o">=</span> <span class="n">Libraries</span><span class="p">.</span><span class="n">begin</span><span class="p">();</span>
+ <span class="kt">unsigned</span> <span class="n">libPos</span> <span class="o">=</span> <span class="mi">0</span><span class="p">,</span> <span class="n">filePos</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="k">while</span> <span class="p">(</span> <span class="mi">1</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span> <span class="n">libIt</span> <span class="o">!=</span> <span class="n">Libraries</span><span class="p">.</span><span class="n">end</span><span class="p">()</span> <span class="p">)</span>
+ <span class="n">libPos</span> <span class="o">=</span> <span class="n">Libraries</span><span class="p">.</span><span class="n">getPosition</span><span class="p">(</span> <span class="n">libIt</span> <span class="o">-</span> <span class="n">Libraries</span><span class="p">.</span><span class="n">begin</span><span class="p">()</span> <span class="p">);</span>
+ <span class="k">else</span>
+ <span class="n">libPos</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">fileIt</span> <span class="o">!=</span> <span class="n">Files</span><span class="p">.</span><span class="n">end</span><span class="p">()</span> <span class="p">)</span>
+ <span class="n">filePos</span> <span class="o">=</span> <span class="n">Files</span><span class="p">.</span><span class="n">getPosition</span><span class="p">(</span> <span class="n">fileIt</span> <span class="o">-</span> <span class="n">Files</span><span class="p">.</span><span class="n">begin</span><span class="p">()</span> <span class="p">);</span>
+ <span class="k">else</span>
+ <span class="n">filePos</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">filePos</span> <span class="o">!=</span> <span class="mi">0</span> <span class="o">&&</span> <span class="p">(</span><span class="n">libPos</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">||</span> <span class="n">filePos</span> <span class="o"><</span> <span class="n">libPos</span><span class="p">)</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Source File Is next</span>
+ <span class="o">++</span><span class="n">fileIt</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">else</span> <span class="k">if</span> <span class="p">(</span> <span class="n">libPos</span> <span class="o">!=</span> <span class="mi">0</span> <span class="o">&&</span> <span class="p">(</span><span class="n">filePos</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">||</span> <span class="n">libPos</span> <span class="o"><</span> <span class="n">filePos</span><span class="p">)</span> <span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Library is next</span>
+ <span class="o">++</span><span class="n">libIt</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">else</span>
+ <span class="k">break</span><span class="p">;</span> <span class="c1">// we're done with the list</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that, for compatibility reasons, the <tt class="docutils literal"><span class="pre">cl::opt</span></tt> also supports an
+<tt class="docutils literal"><span class="pre">unsigned</span> <span class="pre">getPosition()</span></tt> option that will provide the absolute position of
+that option. You can apply the same approach as above with a <tt class="docutils literal"><span class="pre">cl::opt</span></tt> and a
+<tt class="docutils literal"><span class="pre">cl::list</span></tt> option as you can with two lists.</p>
+</div>
+<div class="section" id="the-cl-consumeafter-modifier">
+<span id="this-section-for-more-information"></span><span id="cl-consumeafter"></span><span id="interpreter-style-options"></span><h4><a class="toc-backref" href="#id22">The <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> modifier</a><a class="headerlink" href="#the-cl-consumeafter-modifier" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> <a class="reference internal" href="#formatting-option">formatting option</a> is used to construct programs that
+use “interpreter style” option processing. With this style of option
+processing, all arguments specified after the last positional argument are
+treated as special interpreter arguments that are not interpreted by the command
+line argument.</p>
+<p>As a concrete example, lets say we are developing a replacement for the standard
+Unix Bourne shell (<tt class="docutils literal"><span class="pre">/bin/sh</span></tt>). To run <tt class="docutils literal"><span class="pre">/bin/sh</span></tt>, first you specify options
+to the shell itself (like <tt class="docutils literal"><span class="pre">-x</span></tt> which turns on trace output), then you specify
+the name of the script to run, then you specify arguments to the script. These
+arguments to the script are parsed by the Bourne shell command line option
+processor, but are not interpreted as options to the shell itself. Using the
+CommandLine library, we would specify this as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">Script</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Positional</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<input script>"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">init</span><span class="p">(</span><span class="s">"-"</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">list</span><span class="o"><</span><span class="n">string</span><span class="o">></span> <span class="n">Argv</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">ConsumeAfter</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"<program arguments>..."</span><span class="p">));</span>
+<span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Trace</span><span class="p">(</span><span class="s">"x"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Enable trace output"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>which automatically provides the help output:</p>
+<div class="highlight-python"><pre>USAGE: spiffysh [options] <input script> <program arguments>...
+
+OPTIONS:
+ -help - display available options (-help-hidden for more)
+ -x - Enable trace output</pre>
+</div>
+<p>At runtime, if we run our new shell replacement as <tt class="docutils literal"><span class="pre">`spiffysh</span> <span class="pre">-x</span> <span class="pre">test.sh</span> <span class="pre">-a</span> <span class="pre">-x</span>
+<span class="pre">-y</span> <span class="pre">bar</span></tt>‘, the <tt class="docutils literal"><span class="pre">Trace</span></tt> variable will be set to true, the <tt class="docutils literal"><span class="pre">Script</span></tt> variable
+will be set to “<tt class="docutils literal"><span class="pre">test.sh</span></tt>”, and the <tt class="docutils literal"><span class="pre">Argv</span></tt> list will contain <tt class="docutils literal"><span class="pre">["-a",</span> <span class="pre">"-x",</span>
+<span class="pre">"-y",</span> <span class="pre">"bar"]</span></tt>, because they were specified after the last positional argument
+(which is the script name).</p>
+<p>There are several limitations to when <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> options can be
+specified. For example, only one <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> can be specified per
+program, there must be at least one <a class="reference internal" href="#positional-argument">positional argument</a> specified, there must
+not be any <a class="reference internal" href="#cl-list">cl::list</a> positional arguments, and the <tt class="docutils literal"><span class="pre">cl::ConsumeAfter</span></tt> option
+should be a <a class="reference internal" href="#cl-list">cl::list</a> option.</p>
+</div>
+</div>
+<div class="section" id="internal-vs-external-storage">
+<span id="can-be-changed"></span><span id="id4"></span><h3><a class="toc-backref" href="#id23">Internal vs External Storage</a><a class="headerlink" href="#internal-vs-external-storage" title="Permalink to this headline">¶</a></h3>
+<p>By default, all command line options automatically hold the value that they
+parse from the command line. This is very convenient in the common case,
+especially when combined with the ability to define command line options in the
+files that use them. This is called the internal storage model.</p>
+<p>Sometimes, however, it is nice to separate the command line option processing
+code from the storage of the value parsed. For example, lets say that we have a
+‘<tt class="docutils literal"><span class="pre">-debug</span></tt>‘ option that we would like to use to enable debug information across
+the entire body of our program. In this case, the boolean value controlling the
+debug code should be globally accessible (in a header file, for example) yet the
+command line option processing code should not be exposed to all of these
+clients (requiring lots of .cpp files to <tt class="docutils literal"><span class="pre">#include</span> <span class="pre">CommandLine.h</span></tt>).</p>
+<p>To do this, set up your .h file with your option, like this for example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// DebugFlag.h - Get access to the '-debug' command line option</span>
+<span class="c1">//</span>
+
+<span class="c1">// DebugFlag - This boolean is set to true if the '-debug' command line option</span>
+<span class="c1">// is specified. This should probably not be referenced directly, instead, use</span>
+<span class="c1">// the DEBUG macro below.</span>
+<span class="c1">//</span>
+<span class="k">extern</span> <span class="kt">bool</span> <span class="n">DebugFlag</span><span class="p">;</span>
+
+<span class="cp">// DEBUG macro - This macro should be used by code to emit debug information.</span>
+<span class="cp">// In the '-debug' option is specified on the command line, and if this is a</span>
+<span class="cp">// debug build, then the code specified as the option to the macro will be</span>
+<span class="cp">// executed. Otherwise it will not be.</span>
+<span class="cp">#ifdef NDEBUG</span>
+<span class="cp">#define LLVM_DEBUG(X)</span>
+<span class="cp">#else</span>
+<span class="cp">#define LLVM_DEBUG(X) do { if (DebugFlag) { X; } } while (0)</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>This allows clients to blissfully use the <tt class="docutils literal"><span class="pre">LLVM_DEBUG()</span></tt> macro, or the
+<tt class="docutils literal"><span class="pre">DebugFlag</span></tt> explicitly if they want to. Now we just need to be able to set
+the <tt class="docutils literal"><span class="pre">DebugFlag</span></tt> boolean when the option is set. To do this, we pass an
+additional argument to our command line argument processor, and we specify where
+to fill in with the <a class="reference internal" href="#cl-location">cl::location</a> attribute:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">DebugFlag</span><span class="p">;</span> <span class="c1">// the actual value</span>
+<span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="p">,</span> <span class="kc">true</span><span class="o">></span> <span class="c1">// The parser</span>
+<span class="n">Debug</span><span class="p">(</span><span class="s">"debug"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Enable debug output"</span><span class="p">),</span> <span class="n">cl</span><span class="o">::</span><span class="n">Hidden</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">location</span><span class="p">(</span><span class="n">DebugFlag</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>In the above example, we specify “<tt class="docutils literal"><span class="pre">true</span></tt>” as the second argument to the
+<a class="reference internal" href="#cl-opt">cl::opt</a> template, indicating that the template should not maintain a copy of
+the value itself. In addition to this, we specify the <a class="reference internal" href="#cl-location">cl::location</a>
+attribute, so that <tt class="docutils literal"><span class="pre">DebugFlag</span></tt> is automatically set.</p>
+</div>
+<div class="section" id="option-attributes">
+<h3><a class="toc-backref" href="#id24">Option Attributes</a><a class="headerlink" href="#option-attributes" title="Permalink to this headline">¶</a></h3>
+<p>This section describes the basic attributes that you can specify on options.</p>
+<ul>
+<li><p class="first">The option name attribute (which is required for all options, except
+<a class="reference internal" href="#positional-options">positional options</a>) specifies what the option name is. This option is
+specified in simple double quotes:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">bool</span><span class="o">></span> <span class="n">Quiet</span><span class="p">(</span><span class="s">"quiet"</span><span class="p">);</span>
+</pre></div>
+</div>
+</li>
+</ul>
+<ul class="simple" id="cl-desc">
+<li>The <strong>cl::desc</strong> attribute specifies a description for the option to be
+shown in the <tt class="docutils literal"><span class="pre">-help</span></tt> output for the program. This attribute supports
+multi-line descriptions with lines separated by ‘n’.</li>
+</ul>
+<ul class="simple" id="cl-value-desc">
+<li>The <strong>cl::value_desc</strong> attribute specifies a string that can be used to
+fine tune the <tt class="docutils literal"><span class="pre">-help</span></tt> output for a command line option. Look <a class="reference internal" href="#here">here</a> for an
+example.</li>
+</ul>
+<ul id="cl-init">
+<li><p class="first">The <strong>cl::init</strong> attribute specifies an initial value for a <a class="reference internal" href="#scalar">scalar</a>
+option. If this attribute is not specified then the command line option value
+defaults to the value created by the default constructor for the
+type.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">If you specify both <strong>cl::init</strong> and <strong>cl::location</strong> for an option, you
+must specify <strong>cl::location</strong> first, so that when the command-line parser
+sees <strong>cl::init</strong>, it knows where to put the initial value. (You will get an
+error at runtime if you don’t put them in the right order.)</p>
+</div>
+</li>
+</ul>
+<ul class="simple" id="cl-location">
+<li>The <strong>cl::location</strong> attribute where to store the value for a parsed command
+line option if using external storage. See the section on <a class="reference internal" href="#internal-vs-external-storage">Internal vs
+External Storage</a> for more information.</li>
+</ul>
+<ul class="simple" id="cl-aliasopt">
+<li>The <strong>cl::aliasopt</strong> attribute specifies which option a <a class="reference internal" href="#cl-alias">cl::alias</a> option is
+an alias for.</li>
+</ul>
+<ul id="cl-values">
+<li><p class="first">The <strong>cl::values</strong> attribute specifies the string-to-value mapping to be used
+by the generic parser. It takes a list of (option, value, description)
+triplets that specify the option name, the value mapped to, and the
+description shown in the <tt class="docutils literal"><span class="pre">-help</span></tt> for the tool. Because the generic parser
+is used most frequently with enum values, two macros are often useful:</p>
+<ol class="arabic simple">
+<li>The <strong>clEnumVal</strong> macro is used as a nice simple way to specify a triplet
+for an enum. This macro automatically makes the option name be the same as
+the enum name. The first option to the macro is the enum, the second is
+the description for the command line option.</li>
+<li>The <strong>clEnumValN</strong> macro is used to specify macro options where the option
+name doesn’t equal the enum name. For this macro, the first argument is
+the enum value, the second is the flag name, and the second is the
+description.</li>
+</ol>
+<p>You will get a compile time error if you try to use cl::values with a parser
+that does not support it.</p>
+</li>
+</ul>
+<ul class="simple" id="cl-multi-val">
+<li>The <strong>cl::multi_val</strong> attribute specifies that this option takes has multiple
+values (example: <tt class="docutils literal"><span class="pre">-sectalign</span> <span class="pre">segname</span> <span class="pre">sectname</span> <span class="pre">sectvalue</span></tt>). This attribute
+takes one unsigned argument - the number of values for the option. This
+attribute is valid only on <tt class="docutils literal"><span class="pre">cl::list</span></tt> options (and will fail with compile
+error if you try to use it with other option types). It is allowed to use all
+of the usual modifiers on multi-valued options (besides
+<tt class="docutils literal"><span class="pre">cl::ValueDisallowed</span></tt>, obviously).</li>
+</ul>
+<ul class="simple" id="cl-cat">
+<li>The <strong>cl::cat</strong> attribute specifies the option category that the option
+belongs to. The category should be a <a class="reference internal" href="#cl-optioncategory">cl::OptionCategory</a> object.</li>
+</ul>
+</div>
+<div class="section" id="option-modifiers">
+<h3><a class="toc-backref" href="#id25">Option Modifiers</a><a class="headerlink" href="#option-modifiers" title="Permalink to this headline">¶</a></h3>
+<p>Option modifiers are the flags and expressions that you pass into the
+constructors for <a class="reference internal" href="#cl-opt">cl::opt</a> and <a class="reference internal" href="#cl-list">cl::list</a>. These modifiers give you the
+ability to tweak how options are parsed and how <tt class="docutils literal"><span class="pre">-help</span></tt> output is generated to
+fit your application well.</p>
+<p>These options fall into five main categories:</p>
+<ol class="arabic simple">
+<li>Hiding an option from <tt class="docutils literal"><span class="pre">-help</span></tt> output</li>
+<li>Controlling the number of occurrences required and allowed</li>
+<li>Controlling whether or not a value must be specified</li>
+<li>Controlling other formatting options</li>
+<li>Miscellaneous option modifiers</li>
+</ol>
+<p>It is not possible to specify two options from the same category (you’ll get a
+runtime error) to a single option, except for options in the miscellaneous
+category. The CommandLine library specifies defaults for all of these settings
+that are the most useful in practice and the most common, which mean that you
+usually shouldn’t have to worry about these.</p>
+<div class="section" id="hiding-an-option-from-help-output">
+<h4><a class="toc-backref" href="#id26">Hiding an option from <tt class="docutils literal"><span class="pre">-help</span></tt> output</a><a class="headerlink" href="#hiding-an-option-from-help-output" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::NotHidden</span></tt>, <tt class="docutils literal"><span class="pre">cl::Hidden</span></tt>, and <tt class="docutils literal"><span class="pre">cl::ReallyHidden</span></tt> modifiers are
+used to control whether or not an option appears in the <tt class="docutils literal"><span class="pre">-help</span></tt> and
+<tt class="docutils literal"><span class="pre">-help-hidden</span></tt> output for the compiled program:</p>
+<ul class="simple" id="cl-nothidden">
+<li>The <strong>cl::NotHidden</strong> modifier (which is the default for <a class="reference internal" href="#cl-opt">cl::opt</a> and
+<a class="reference internal" href="#cl-list">cl::list</a> options) indicates the option is to appear in both help
+listings.</li>
+</ul>
+<ul class="simple" id="cl-hidden">
+<li>The <strong>cl::Hidden</strong> modifier (which is the default for <a class="reference internal" href="#cl-alias">cl::alias</a> options)
+indicates that the option should not appear in the <tt class="docutils literal"><span class="pre">-help</span></tt> output, but
+should appear in the <tt class="docutils literal"><span class="pre">-help-hidden</span></tt> output.</li>
+</ul>
+<ul class="simple" id="cl-reallyhidden">
+<li>The <strong>cl::ReallyHidden</strong> modifier indicates that the option should not appear
+in any help output.</li>
+</ul>
+</div>
+<div class="section" id="controlling-the-number-of-occurrences-required-and-allowed">
+<h4><a class="toc-backref" href="#id27">Controlling the number of occurrences required and allowed</a><a class="headerlink" href="#controlling-the-number-of-occurrences-required-and-allowed" title="Permalink to this headline">¶</a></h4>
+<p>This group of options is used to control how many time an option is allowed (or
+required) to be specified on the command line of your program. Specifying a
+value for this setting allows the CommandLine library to do error checking for
+you.</p>
+<p>The allowed values for this option group are:</p>
+<ul class="simple" id="cl-optional">
+<li>The <strong>cl::Optional</strong> modifier (which is the default for the <a class="reference internal" href="#cl-opt">cl::opt</a> and
+<a class="reference internal" href="#cl-alias">cl::alias</a> classes) indicates that your program will allow either zero or
+one occurrence of the option to be specified.</li>
+</ul>
+<ul class="simple" id="cl-zeroormore">
+<li>The <strong>cl::ZeroOrMore</strong> modifier (which is the default for the <a class="reference internal" href="#cl-list">cl::list</a>
+class) indicates that your program will allow the option to be specified zero
+or more times.</li>
+</ul>
+<ul class="simple" id="cl-required">
+<li>The <strong>cl::Required</strong> modifier indicates that the specified option must be
+specified exactly one time.</li>
+</ul>
+<ul class="simple" id="cl-oneormore">
+<li>The <strong>cl::OneOrMore</strong> modifier indicates that the option must be specified at
+least one time.</li>
+<li>The <strong>cl::ConsumeAfter</strong> modifier is described in the <a class="reference internal" href="#positional-arguments-section">Positional arguments
+section</a>.</li>
+</ul>
+<p>If an option is not specified, then the value of the option is equal to the
+value specified by the <a class="reference internal" href="#cl-init">cl::init</a> attribute. If the <tt class="docutils literal"><span class="pre">cl::init</span></tt> attribute is
+not specified, the option value is initialized with the default constructor for
+the data type.</p>
+<p>If an option is specified multiple times for an option of the <a class="reference internal" href="#cl-opt">cl::opt</a> class,
+only the last value will be retained.</p>
+</div>
+<div class="section" id="controlling-whether-or-not-a-value-must-be-specified">
+<h4><a class="toc-backref" href="#id28">Controlling whether or not a value must be specified</a><a class="headerlink" href="#controlling-whether-or-not-a-value-must-be-specified" title="Permalink to this headline">¶</a></h4>
+<p>This group of options is used to control whether or not the option allows a
+value to be present. In the case of the CommandLine library, a value is either
+specified with an equal sign (e.g. ‘<tt class="docutils literal"><span class="pre">-index-depth=17</span></tt>‘) or as a trailing
+string (e.g. ‘<tt class="docutils literal"><span class="pre">-o</span> <span class="pre">a.out</span></tt>‘).</p>
+<p>The allowed values for this option group are:</p>
+<ul class="simple" id="cl-valueoptional">
+<li>The <strong>cl::ValueOptional</strong> modifier (which is the default for <tt class="docutils literal"><span class="pre">bool</span></tt> typed
+options) specifies that it is acceptable to have a value, or not. A boolean
+argument can be enabled just by appearing on the command line, or it can have
+an explicit ‘<tt class="docutils literal"><span class="pre">-foo=true</span></tt>‘. If an option is specified with this mode, it is
+illegal for the value to be provided without the equal sign. Therefore
+‘<tt class="docutils literal"><span class="pre">-foo</span> <span class="pre">true</span></tt>‘ is illegal. To get this behavior, you must use
+the <a class="reference internal" href="#cl-valuerequired">cl::ValueRequired</a> modifier.</li>
+</ul>
+<ul class="simple" id="cl-valuerequired">
+<li>The <strong>cl::ValueRequired</strong> modifier (which is the default for all other types
+except for <a class="reference internal" href="#unnamed-alternatives-using-the-generic-parser">unnamed alternatives using the generic parser</a>) specifies that a
+value must be provided. This mode informs the command line library that if an
+option is not provides with an equal sign, that the next argument provided
+must be the value. This allows things like ‘<tt class="docutils literal"><span class="pre">-o</span> <span class="pre">a.out</span></tt>‘ to work.</li>
+</ul>
+<ul class="simple" id="cl-valuedisallowed">
+<li>The <strong>cl::ValueDisallowed</strong> modifier (which is the default for <a class="reference internal" href="#unnamed-alternatives-using-the-generic-parser">unnamed
+alternatives using the generic parser</a>) indicates that it is a runtime error
+for the user to specify a value. This can be provided to disallow users from
+providing options to boolean options (like ‘<tt class="docutils literal"><span class="pre">-foo=true</span></tt>‘).</li>
+</ul>
+<p>In general, the default values for this option group work just like you would
+want them to. As mentioned above, you can specify the <a class="reference internal" href="#cl-valuedisallowed">cl::ValueDisallowed</a>
+modifier to a boolean argument to restrict your command line parser. These
+options are mostly useful when <a class="reference internal" href="#extending-the-library">extending the library</a>.</p>
+</div>
+<div class="section" id="controlling-other-formatting-options">
+<span id="formatting-option"></span><h4><a class="toc-backref" href="#id29">Controlling other formatting options</a><a class="headerlink" href="#controlling-other-formatting-options" title="Permalink to this headline">¶</a></h4>
+<p>The formatting option group is used to specify that the command line option has
+special abilities and is otherwise different from other command line arguments.
+As usual, you can only specify one of these arguments at most.</p>
+<ul class="simple" id="cl-normalformatting">
+<li>The <strong>cl::NormalFormatting</strong> modifier (which is the default all options)
+specifies that this option is “normal”.</li>
+</ul>
+<ul class="simple" id="cl-positional">
+<li>The <strong>cl::Positional</strong> modifier specifies that this is a positional argument
+that does not have a command line option associated with it. See the
+<a class="reference internal" href="#positional-arguments">Positional Arguments</a> section for more information.</li>
+<li>The <strong>cl::ConsumeAfter</strong> modifier specifies that this option is used to
+capture “interpreter style” arguments. See <a class="reference internal" href="#this-section-for-more-information">this section for more
+information</a>.</li>
+</ul>
+<ul class="simple" id="cl-prefix">
+<span id="prefix"></span><li>The <strong>cl::Prefix</strong> modifier specifies that this option prefixes its value.
+With ‘Prefix’ options, the equal sign does not separate the value from the
+option name specified. Instead, the value is everything after the prefix,
+including any equal sign if present. This is useful for processing odd
+arguments like <tt class="docutils literal"><span class="pre">-lmalloc</span></tt> and <tt class="docutils literal"><span class="pre">-L/usr/lib</span></tt> in a linker tool or
+<tt class="docutils literal"><span class="pre">-DNAME=value</span></tt> in a compiler tool. Here, the ‘<tt class="docutils literal"><span class="pre">l</span></tt>‘, ‘<tt class="docutils literal"><span class="pre">D</span></tt>‘ and ‘<tt class="docutils literal"><span class="pre">L</span></tt>‘
+options are normal string (or list) options, that have the <strong>cl::Prefix</strong>
+modifier added to allow the CommandLine library to recognize them. Note that
+<strong>cl::Prefix</strong> options must not have the <strong>cl::ValueDisallowed</strong> modifier
+specified.</li>
+</ul>
+<ul class="simple" id="cl-grouping">
+<span id="grouping"></span><li>The <strong>cl::Grouping</strong> modifier is used to implement Unix-style tools (like
+<tt class="docutils literal"><span class="pre">ls</span></tt>) that have lots of single letter arguments, but only require a single
+dash. For example, the ‘<tt class="docutils literal"><span class="pre">ls</span> <span class="pre">-labF</span></tt>‘ command actually enables four different
+options, all of which are single letters. Note that <strong>cl::Grouping</strong> options
+cannot have values.</li>
+</ul>
+<p>The CommandLine library does not restrict how you use the <strong>cl::Prefix</strong> or
+<strong>cl::Grouping</strong> modifiers, but it is possible to specify ambiguous argument
+settings. Thus, it is possible to have multiple letter options that are prefix
+or grouping options, and they will still work as designed.</p>
+<p>To do this, the CommandLine library uses a greedy algorithm to parse the input
+option into (potentially multiple) prefix and grouping options. The strategy
+basically looks like this:</p>
+<div class="highlight-python"><pre>parse(string OrigInput) {
+
+1. string input = OrigInput;
+2. if (isOption(input)) return getOption(input).parse(); // Normal option
+3. while (!isOption(input) && !input.empty()) input.pop_back(); // Remove the last letter
+4. if (input.empty()) return error(); // No matching option
+5. if (getOption(input).isPrefix())
+ return getOption(input).parse(input);
+6. while (!input.empty()) { // Must be grouping options
+ getOption(input).parse();
+ OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());
+ input = OrigInput;
+ while (!isOption(input) && !input.empty()) input.pop_back();
+ }
+7. if (!OrigInput.empty()) error();
+
+}</pre>
+</div>
+</div>
+<div class="section" id="miscellaneous-option-modifiers">
+<h4><a class="toc-backref" href="#id30">Miscellaneous option modifiers</a><a class="headerlink" href="#miscellaneous-option-modifiers" title="Permalink to this headline">¶</a></h4>
+<p>The miscellaneous option modifiers are the only flags where you can specify more
+than one flag from the set: they are not mutually exclusive. These flags
+specify boolean properties that modify the option.</p>
+<ul class="simple" id="cl-commaseparated">
+<li>The <strong>cl::CommaSeparated</strong> modifier indicates that any commas specified for an
+option’s value should be used to split the value up into multiple values for
+the option. For example, these two options are equivalent when
+<tt class="docutils literal"><span class="pre">cl::CommaSeparated</span></tt> is specified: “<tt class="docutils literal"><span class="pre">-foo=a</span> <span class="pre">-foo=b</span> <span class="pre">-foo=c</span></tt>” and
+“<tt class="docutils literal"><span class="pre">-foo=a,b,c</span></tt>”. This option only makes sense to be used in a case where the
+option is allowed to accept one or more values (i.e. it is a <a class="reference internal" href="#cl-list">cl::list</a>
+option).</li>
+</ul>
+<ul class="simple" id="cl-positionaleatsargs">
+<li>The <strong>cl::PositionalEatsArgs</strong> modifier (which only applies to positional
+arguments, and only makes sense for lists) indicates that positional argument
+should consume any strings after it (including strings that start with a “-”)
+up until another recognized positional argument. For example, if you have two
+“eating” positional arguments, “<tt class="docutils literal"><span class="pre">pos1</span></tt>” and “<tt class="docutils literal"><span class="pre">pos2</span></tt>”, the string “<tt class="docutils literal"><span class="pre">-pos1</span>
+<span class="pre">-foo</span> <span class="pre">-bar</span> <span class="pre">baz</span> <span class="pre">-pos2</span> <span class="pre">-bork</span></tt>” would cause the “<tt class="docutils literal"><span class="pre">-foo</span> <span class="pre">-bar</span> <span class="pre">-baz</span></tt>” strings to
+be applied to the “<tt class="docutils literal"><span class="pre">-pos1</span></tt>” option and the “<tt class="docutils literal"><span class="pre">-bork</span></tt>” string to be applied
+to the “<tt class="docutils literal"><span class="pre">-pos2</span></tt>” option.</li>
+</ul>
+<ul class="simple" id="cl-sink">
+<li>The <strong>cl::Sink</strong> modifier is used to handle unknown options. If there is at
+least one option with <tt class="docutils literal"><span class="pre">cl::Sink</span></tt> modifier specified, the parser passes
+unrecognized option strings to it as values instead of signaling an error. As
+with <tt class="docutils literal"><span class="pre">cl::CommaSeparated</span></tt>, this modifier only makes sense with a <a class="reference internal" href="#cl-list">cl::list</a>
+option.</li>
+</ul>
+<p>So far, these are the only three miscellaneous option modifiers.</p>
+</div>
+<div class="section" id="response-files">
+<span id="id5"></span><h4><a class="toc-backref" href="#id31">Response files</a><a class="headerlink" href="#response-files" title="Permalink to this headline">¶</a></h4>
+<p>Some systems, such as certain variants of Microsoft Windows and some older
+Unices have a relatively low limit on command-line length. It is therefore
+customary to use the so-called ‘response files’ to circumvent this
+restriction. These files are mentioned on the command-line (using the “@file”)
+syntax. The program reads these files and inserts the contents into argv,
+thereby working around the command-line length limits.</p>
+</div>
+</div>
+<div class="section" id="top-level-classes-and-functions">
+<h3><a class="toc-backref" href="#id32">Top-Level Classes and Functions</a><a class="headerlink" href="#top-level-classes-and-functions" title="Permalink to this headline">¶</a></h3>
+<p>Despite all of the built-in flexibility, the CommandLine option library really
+only consists of one function <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>) and three main
+classes: <a class="reference internal" href="#cl-opt">cl::opt</a>, <a class="reference internal" href="#cl-list">cl::list</a>, and <a class="reference internal" href="#cl-alias">cl::alias</a>. This section describes
+these three classes in detail.</p>
+<div class="section" id="the-cl-getregisteredoptions-function">
+<span id="cl-getregisteredoptions"></span><h4><a class="toc-backref" href="#id33">The <tt class="docutils literal"><span class="pre">cl::getRegisteredOptions</span></tt> function</a><a class="headerlink" href="#the-cl-getregisteredoptions-function" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::getRegisteredOptions</span></tt> function is designed to give a programmer
+access to declared non-positional command line options so that how they appear
+in <tt class="docutils literal"><span class="pre">-help</span></tt> can be modified prior to calling <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>.
+Note this method should not be called during any static initialisation because
+it cannot be guaranteed that all options will have been initialised. Hence it
+should be called from <tt class="docutils literal"><span class="pre">main</span></tt>.</p>
+<p>This function can be used to gain access to options declared in libraries that
+the tool writter may not have direct access to.</p>
+<p>The function retrieves a <a class="reference internal" href="ProgrammersManual.html#dss-stringmap"><em>StringMap</em></a> that maps the option
+string (e.g. <tt class="docutils literal"><span class="pre">-help</span></tt>) to an <tt class="docutils literal"><span class="pre">Option*</span></tt>.</p>
+<p>Here is an example of how the function could be used:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+<span class="kt">int</span> <span class="n">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">cl</span><span class="o">::</span><span class="n">OptionCategory</span> <span class="n">AnotherCategory</span><span class="p">(</span><span class="s">"Some options"</span><span class="p">);</span>
+
+ <span class="n">StringMap</span><span class="o"><</span><span class="n">cl</span><span class="o">::</span><span class="n">Option</span><span class="o">*></span> <span class="o">&</span><span class="n">Map</span> <span class="o">=</span> <span class="n">cl</span><span class="o">::</span><span class="n">getRegisteredOptions</span><span class="p">();</span>
+
+ <span class="c1">//Unhide useful option and put it in a different category</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Map</span><span class="p">.</span><span class="n">count</span><span class="p">(</span><span class="s">"print-all-options"</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"print-all-options"</span><span class="p">]</span><span class="o">-></span><span class="n">setHiddenFlag</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">NotHidden</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"print-all-options"</span><span class="p">]</span><span class="o">-></span><span class="n">setCategory</span><span class="p">(</span><span class="n">AnotherCategory</span><span class="p">);</span>
+
+ <span class="c1">//Hide an option we don't want to see</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Map</span><span class="p">.</span><span class="n">count</span><span class="p">(</span><span class="s">"enable-no-infs-fp-math"</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"enable-no-infs-fp-math"</span><span class="p">]</span><span class="o">-></span><span class="n">setHiddenFlag</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Hidden</span><span class="p">);</span>
+
+ <span class="c1">//Change --version to --show-version</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Map</span><span class="p">.</span><span class="n">count</span><span class="p">(</span><span class="s">"version"</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"version"</span><span class="p">]</span><span class="o">-></span><span class="n">setArgStr</span><span class="p">(</span><span class="s">"show-version"</span><span class="p">);</span>
+
+ <span class="c1">//Change --help description</span>
+ <span class="n">assert</span><span class="p">(</span><span class="n">Map</span><span class="p">.</span><span class="n">count</span><span class="p">(</span><span class="s">"help"</span><span class="p">)</span> <span class="o">></span> <span class="mi">0</span><span class="p">);</span>
+ <span class="n">Map</span><span class="p">[</span><span class="s">"help"</span><span class="p">]</span><span class="o">-></span><span class="n">setDescription</span><span class="p">(</span><span class="s">"Shows help"</span><span class="p">);</span>
+
+ <span class="n">cl</span><span class="o">::</span><span class="n">ParseCommandLineOptions</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="s">"This is a small program to demo the LLVM CommandLine API"</span><span class="p">);</span>
+ <span class="p">...</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-cl-parsecommandlineoptions-function">
+<span id="cl-parsecommandlineoptions"></span><h4><a class="toc-backref" href="#id34">The <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt> function</a><a class="headerlink" href="#the-cl-parsecommandlineoptions-function" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt> function is designed to be called directly
+from <tt class="docutils literal"><span class="pre">main</span></tt>, and is used to fill in the values of all of the command line
+option variables once <tt class="docutils literal"><span class="pre">argc</span></tt> and <tt class="docutils literal"><span class="pre">argv</span></tt> are available.</p>
+<p>The <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt> function requires two parameters (<tt class="docutils literal"><span class="pre">argc</span></tt>
+and <tt class="docutils literal"><span class="pre">argv</span></tt>), but may also take an optional third parameter which holds
+<a class="reference internal" href="#additional-extra-text">additional extra text</a> to emit when the <tt class="docutils literal"><span class="pre">-help</span></tt> option is invoked.</p>
+</div>
+<div class="section" id="the-cl-parseenvironmentoptions-function">
+<span id="cl-parseenvironmentoptions"></span><h4><a class="toc-backref" href="#id35">The <tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> function</a><a class="headerlink" href="#the-cl-parseenvironmentoptions-function" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> function has mostly the same effects as
+<a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>, except that it is designed to take values for
+options from an environment variable, for those cases in which reading the
+command line is not convenient or desired. It fills in the values of all the
+command line option variables just like <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a> does.</p>
+<p>It takes four parameters: the name of the program (since <tt class="docutils literal"><span class="pre">argv</span></tt> may not be
+available, it can’t just look in <tt class="docutils literal"><span class="pre">argv[0]</span></tt>), the name of the environment
+variable to examine, and the optional <a class="reference internal" href="#additional-extra-text">additional extra text</a> to emit when the
+<tt class="docutils literal"><span class="pre">-help</span></tt> option is invoked.</p>
+<p><tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> will break the environment variable’s value up
+into words and then process them using <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>.
+<strong>Note:</strong> Currently <tt class="docutils literal"><span class="pre">cl::ParseEnvironmentOptions</span></tt> does not support quoting, so
+an environment variable containing <tt class="docutils literal"><span class="pre">-option</span> <span class="pre">"foo</span> <span class="pre">bar"</span></tt> will be parsed as three
+words, <tt class="docutils literal"><span class="pre">-option</span></tt>, <tt class="docutils literal"><span class="pre">"foo</span></tt>, and <tt class="docutils literal"><span class="pre">bar"</span></tt>, which is different from what you
+would get from the shell with the same input.</p>
+</div>
+<div class="section" id="the-cl-setversionprinter-function">
+<h4><a class="toc-backref" href="#id36">The <tt class="docutils literal"><span class="pre">cl::SetVersionPrinter</span></tt> function</a><a class="headerlink" href="#the-cl-setversionprinter-function" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::SetVersionPrinter</span></tt> function is designed to be called directly from
+<tt class="docutils literal"><span class="pre">main</span></tt> and <em>before</em> <tt class="docutils literal"><span class="pre">cl::ParseCommandLineOptions</span></tt>. Its use is optional. It
+simply arranges for a function to be called in response to the <tt class="docutils literal"><span class="pre">--version</span></tt>
+option instead of having the <tt class="docutils literal"><span class="pre">CommandLine</span></tt> library print out the usual version
+string for LLVM. This is useful for programs that are not part of LLVM but wish
+to use the <tt class="docutils literal"><span class="pre">CommandLine</span></tt> facilities. Such programs should just define a small
+function that takes no arguments and returns <tt class="docutils literal"><span class="pre">void</span></tt> and that prints out
+whatever version information is appropriate for the program. Pass the address of
+that function to <tt class="docutils literal"><span class="pre">cl::SetVersionPrinter</span></tt> to arrange for it to be called when
+the <tt class="docutils literal"><span class="pre">--version</span></tt> option is given by the user.</p>
+</div>
+<div class="section" id="the-cl-opt-class">
+<span id="scalar"></span><span id="cl-opt"></span><h4><a class="toc-backref" href="#id37">The <tt class="docutils literal"><span class="pre">cl::opt</span></tt> class</a><a class="headerlink" href="#the-cl-opt-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::opt</span></tt> class is the class used to represent scalar command line
+options, and is the one used most of the time. It is a templated class which
+can take up to three arguments (all except for the first have default values
+though):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">DataType</span><span class="p">,</span> <span class="kt">bool</span> <span class="n">ExternalStorage</span> <span class="o">=</span> <span class="kc">false</span><span class="p">,</span>
+ <span class="k">class</span> <span class="nc">ParserClass</span> <span class="o">=</span> <span class="n">parser</span><span class="o"><</span><span class="n">DataType</span><span class="o">></span> <span class="o">></span>
+ <span class="k">class</span> <span class="nc">opt</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The first template argument specifies what underlying data type the command line
+argument is, and is used to select a default parser implementation. The second
+template argument is used to specify whether the option should contain the
+storage for the option (the default) or whether external storage should be used
+to contain the value parsed for the option (see <a class="reference internal" href="#internal-vs-external-storage">Internal vs External Storage</a>
+for more information).</p>
+<p>The third template argument specifies which parser to use. The default value
+selects an instantiation of the <tt class="docutils literal"><span class="pre">parser</span></tt> class based on the underlying data
+type of the option. In general, this default works well for most applications,
+so this option is only used when using a <a class="reference internal" href="#custom-parser">custom parser</a>.</p>
+</div>
+<div class="section" id="the-cl-list-class">
+<span id="cl-list"></span><span id="lists-of-arguments"></span><h4><a class="toc-backref" href="#id38">The <tt class="docutils literal"><span class="pre">cl::list</span></tt> class</a><a class="headerlink" href="#the-cl-list-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::list</span></tt> class is the class used to represent a list of command line
+options. It too is a templated class which can take up to three arguments:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">DataType</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Storage</span> <span class="o">=</span> <span class="kt">bool</span><span class="p">,</span>
+ <span class="k">class</span> <span class="nc">ParserClass</span> <span class="o">=</span> <span class="n">parser</span><span class="o"><</span><span class="n">DataType</span><span class="o">></span> <span class="o">></span>
+ <span class="k">class</span> <span class="nc">list</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This class works the exact same as the <a class="reference internal" href="#cl-opt">cl::opt</a> class, except that the second
+argument is the <strong>type</strong> of the external storage, not a boolean value. For this
+class, the marker type ‘<tt class="docutils literal"><span class="pre">bool</span></tt>‘ is used to indicate that internal storage
+should be used.</p>
+</div>
+<div class="section" id="the-cl-bits-class">
+<span id="cl-bits"></span><h4><a class="toc-backref" href="#id39">The <tt class="docutils literal"><span class="pre">cl::bits</span></tt> class</a><a class="headerlink" href="#the-cl-bits-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::bits</span></tt> class is the class used to represent a list of command line
+options in the form of a bit vector. It is also a templated class which can
+take up to three arguments:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">template</span> <span class="o"><</span><span class="k">class</span> <span class="nc">DataType</span><span class="p">,</span> <span class="k">class</span> <span class="nc">Storage</span> <span class="o">=</span> <span class="kt">bool</span><span class="p">,</span>
+ <span class="k">class</span> <span class="nc">ParserClass</span> <span class="o">=</span> <span class="n">parser</span><span class="o"><</span><span class="n">DataType</span><span class="o">></span> <span class="o">></span>
+ <span class="k">class</span> <span class="nc">bits</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This class works the exact same as the <a class="reference internal" href="#cl-list">cl::list</a> class, except that the second
+argument must be of <strong>type</strong> <tt class="docutils literal"><span class="pre">unsigned</span></tt> if external storage is used.</p>
+</div>
+<div class="section" id="the-cl-alias-class">
+<span id="cl-alias"></span><h4><a class="toc-backref" href="#id40">The <tt class="docutils literal"><span class="pre">cl::alias</span></tt> class</a><a class="headerlink" href="#the-cl-alias-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::alias</span></tt> class is a nontemplated class that is used to form aliases for
+other arguments.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">alias</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The <a class="reference internal" href="#cl-aliasopt">cl::aliasopt</a> attribute should be used to specify which option this is an
+alias for. Alias arguments default to being <a class="reference internal" href="#cl-hidden">cl::Hidden</a>, and use the aliased
+options parser to do the conversion from string to data.</p>
+</div>
+<div class="section" id="the-cl-extrahelp-class">
+<span id="cl-extrahelp"></span><h4><a class="toc-backref" href="#id41">The <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt> class</a><a class="headerlink" href="#the-cl-extrahelp-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt> class is a nontemplated class that allows extra help text
+to be printed out for the <tt class="docutils literal"><span class="pre">-help</span></tt> option.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">struct</span> <span class="n">extrahelp</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>To use the extrahelp, simply construct one with a <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char*</span></tt> parameter to
+the constructor. The text passed to the constructor will be printed at the
+bottom of the help message, verbatim. Note that multiple <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt>
+<strong>can</strong> be used, but this practice is discouraged. If your tool needs to print
+additional help information, put all that help into a single <tt class="docutils literal"><span class="pre">cl::extrahelp</span></tt>
+instance.</p>
+<p>For example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">cl</span><span class="o">::</span><span class="n">extrahelp</span><span class="p">(</span><span class="s">"</span><span class="se">\n</span><span class="s">ADDITIONAL HELP:</span><span class="se">\n\n</span><span class="s"> This is the extra help</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-cl-optioncategory-class">
+<span id="cl-optioncategory"></span><h4><a class="toc-backref" href="#id42">The <tt class="docutils literal"><span class="pre">cl::OptionCategory</span></tt> class</a><a class="headerlink" href="#the-cl-optioncategory-class" title="Permalink to this headline">¶</a></h4>
+<p>The <tt class="docutils literal"><span class="pre">cl::OptionCategory</span></tt> class is a simple class for declaring
+option categories.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">cl</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">OptionCategory</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>An option category must have a name and optionally a description which are
+passed to the constructor as <tt class="docutils literal"><span class="pre">const</span> <span class="pre">char*</span></tt>.</p>
+<p>Note that declaring an option category and associating it with an option before
+parsing options (e.g. statically) will change the output of <tt class="docutils literal"><span class="pre">-help</span></tt> from
+uncategorized to categorized. If an option category is declared but not
+associated with an option then it will be hidden from the output of <tt class="docutils literal"><span class="pre">-help</span></tt>
+but will be shown in the output of <tt class="docutils literal"><span class="pre">-help-hidden</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="builtin-parsers">
+<span id="discussed-previously"></span><span id="different-parser"></span><h3><a class="toc-backref" href="#id43">Builtin parsers</a><a class="headerlink" href="#builtin-parsers" title="Permalink to this headline">¶</a></h3>
+<p>Parsers control how the string value taken from the command line is translated
+into a typed value, suitable for use in a C++ program. By default, the
+CommandLine library uses an instance of <tt class="docutils literal"><span class="pre">parser<type></span></tt> if the command line
+option specifies that it uses values of type ‘<tt class="docutils literal"><span class="pre">type</span></tt>‘. Because of this,
+custom option processing is specified with specializations of the ‘<tt class="docutils literal"><span class="pre">parser</span></tt>‘
+class.</p>
+<p>The CommandLine library provides the following builtin parser specializations,
+which are sufficient for most applications. It can, however, also be extended to
+work with new data types and new ways of interpreting the same data. See the
+<a class="reference internal" href="#writing-a-custom-parser">Writing a Custom Parser</a> for more details on this type of library extension.</p>
+<ul class="simple" id="cl-parser">
+<span id="enums"></span><li>The generic <tt class="docutils literal"><span class="pre">parser<t></span></tt> parser can be used to map strings values to any data
+type, through the use of the <a class="reference internal" href="#cl-values">cl::values</a> property, which specifies the
+mapping information. The most common use of this parser is for parsing enum
+values, which allows you to use the CommandLine library for all of the error
+checking to make sure that only valid enum values are specified (as opposed to
+accepting arbitrary strings). Despite this, however, the generic parser class
+can be used for any data type.</li>
+</ul>
+<ul class="simple" id="bool-parser">
+<span id="boolean-flags"></span><li>The <strong>parser<bool> specialization</strong> is used to convert boolean strings to a
+boolean value. Currently accepted strings are “<tt class="docutils literal"><span class="pre">true</span></tt>”, “<tt class="docutils literal"><span class="pre">TRUE</span></tt>”,
+“<tt class="docutils literal"><span class="pre">True</span></tt>”, “<tt class="docutils literal"><span class="pre">1</span></tt>”, “<tt class="docutils literal"><span class="pre">false</span></tt>”, “<tt class="docutils literal"><span class="pre">FALSE</span></tt>”, “<tt class="docutils literal"><span class="pre">False</span></tt>”, and “<tt class="docutils literal"><span class="pre">0</span></tt>”.</li>
+<li>The <strong>parser<boolOrDefault> specialization</strong> is used for cases where the value
+is boolean, but we also need to know whether the option was specified at all.
+boolOrDefault is an enum with 3 values, BOU_UNSET, BOU_TRUE and BOU_FALSE.
+This parser accepts the same strings as <strong>``parser<bool>``</strong>.</li>
+</ul>
+<ul class="simple" id="strings">
+<li>The <strong>parser<string> specialization</strong> simply stores the parsed string into the
+string value specified. No conversion or modification of the data is
+performed.</li>
+</ul>
+<ul class="simple" id="int">
+<span id="integers"></span><li>The <strong>parser<int> specialization</strong> uses the C <tt class="docutils literal"><span class="pre">strtol</span></tt> function to parse the
+string input. As such, it will accept a decimal number (with an optional ‘+’
+or ‘-‘ prefix) which must start with a non-zero digit. It accepts octal
+numbers, which are identified with a ‘<tt class="docutils literal"><span class="pre">0</span></tt>‘ prefix digit, and hexadecimal
+numbers with a prefix of ‘<tt class="docutils literal"><span class="pre">0x</span></tt>‘ or ‘<tt class="docutils literal"><span class="pre">0X</span></tt>‘.</li>
+</ul>
+<ul class="simple" id="double">
+<span id="float"></span><span id="doubles"></span><li>The <strong>parser<double></strong> and <strong>parser<float> specializations</strong> use the standard
+C <tt class="docutils literal"><span class="pre">strtod</span></tt> function to convert floating point strings into floating point
+values. As such, a broad range of string formats is supported, including
+exponential notation (ex: <tt class="docutils literal"><span class="pre">1.7e15</span></tt>) and properly supports locales.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="extending-the-library">
+<span id="extension-guide"></span><span id="id6"></span><h2><a class="toc-backref" href="#id44">Extension Guide</a><a class="headerlink" href="#extending-the-library" title="Permalink to this headline">¶</a></h2>
+<p>Although the CommandLine library has a lot of functionality built into it
+already (as discussed previously), one of its true strengths lie in its
+extensibility. This section discusses how the CommandLine library works under
+the covers and illustrates how to do some simple, common, extensions.</p>
+<div class="section" id="writing-a-custom-parser">
+<span id="custom-parser"></span><span id="custom-parsers"></span><span id="id7"></span><h3><a class="toc-backref" href="#id45">Writing a custom parser</a><a class="headerlink" href="#writing-a-custom-parser" title="Permalink to this headline">¶</a></h3>
+<p>One of the simplest and most common extensions is the use of a custom parser.
+As <a class="reference internal" href="#discussed-previously">discussed previously</a>, parsers are the portion of the CommandLine library
+that turns string input from the user into a particular parsed data type,
+validating the input in the process.</p>
+<p>There are two ways to use a new parser:</p>
+<ol class="arabic">
+<li><p class="first">Specialize the <a class="reference internal" href="#cl-parser">cl::parser</a> template for your custom data type.</p>
+<p>This approach has the advantage that users of your custom data type will
+automatically use your custom parser whenever they define an option with a
+value type of your data type. The disadvantage of this approach is that it
+doesn’t work if your fundamental data type is something that is already
+supported.</p>
+</li>
+<li><p class="first">Write an independent class, using it explicitly from options that need it.</p>
+<p>This approach works well in situations where you would line to parse an
+option using special syntax for a not-very-special data-type. The drawback
+of this approach is that users of your parser have to be aware that they are
+using your parser instead of the builtin ones.</p>
+</li>
+</ol>
+<p>To guide the discussion, we will discuss a custom parser that accepts file
+sizes, specified with an optional unit after the numeric size. For example, we
+would like to parse “102kb”, “41M”, “1G” into the appropriate integer value. In
+this case, the underlying data type we want to parse into is ‘<tt class="docutils literal"><span class="pre">unsigned</span></tt>‘. We
+choose approach #2 above because we don’t want to make this the default for all
+<tt class="docutils literal"><span class="pre">unsigned</span></tt> options.</p>
+<p>To start out, we declare our new <tt class="docutils literal"><span class="pre">FileSizeParser</span></tt> class:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">FileSizeParser</span> <span class="o">:</span> <span class="k">public</span> <span class="n">cl</span><span class="o">::</span><span class="n">parser</span><span class="o"><</span><span class="kt">unsigned</span><span class="o">></span> <span class="p">{</span>
+ <span class="c1">// parse - Return true on error.</span>
+ <span class="kt">bool</span> <span class="n">parse</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Option</span> <span class="o">&</span><span class="n">O</span><span class="p">,</span> <span class="n">StringRef</span> <span class="n">ArgName</span><span class="p">,</span> <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">ArgValue</span><span class="p">,</span>
+ <span class="kt">unsigned</span> <span class="o">&</span><span class="n">Val</span><span class="p">);</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>Our new class inherits from the <tt class="docutils literal"><span class="pre">cl::parser</span></tt> template class to fill in
+the default, boiler plate code for us. We give it the data type that we parse
+into, the last argument to the <tt class="docutils literal"><span class="pre">parse</span></tt> method, so that clients of our custom
+parser know what object type to pass in to the parse method. (Here we declare
+that we parse into ‘<tt class="docutils literal"><span class="pre">unsigned</span></tt>‘ variables.)</p>
+<p>For most purposes, the only method that must be implemented in a custom parser
+is the <tt class="docutils literal"><span class="pre">parse</span></tt> method. The <tt class="docutils literal"><span class="pre">parse</span></tt> method is called whenever the option is
+invoked, passing in the option itself, the option name, the string to parse, and
+a reference to a return value. If the string to parse is not well-formed, the
+parser should output an error message and return true. Otherwise it should
+return false and set ‘<tt class="docutils literal"><span class="pre">Val</span></tt>‘ to the parsed value. In our example, we
+implement <tt class="docutils literal"><span class="pre">parse</span></tt> as:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">bool</span> <span class="n">FileSizeParser</span><span class="o">::</span><span class="n">parse</span><span class="p">(</span><span class="n">cl</span><span class="o">::</span><span class="n">Option</span> <span class="o">&</span><span class="n">O</span><span class="p">,</span> <span class="n">StringRef</span> <span class="n">ArgName</span><span class="p">,</span>
+ <span class="k">const</span> <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="o">&</span><span class="n">Arg</span><span class="p">,</span> <span class="kt">unsigned</span> <span class="o">&</span><span class="n">Val</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">const</span> <span class="kt">char</span> <span class="o">*</span><span class="n">ArgStart</span> <span class="o">=</span> <span class="n">Arg</span><span class="p">.</span><span class="n">c_str</span><span class="p">();</span>
+ <span class="kt">char</span> <span class="o">*</span><span class="n">End</span><span class="p">;</span>
+
+ <span class="c1">// Parse integer part, leaving 'End' pointing to the first non-integer char</span>
+ <span class="n">Val</span> <span class="o">=</span> <span class="p">(</span><span class="kt">unsigned</span><span class="p">)</span><span class="n">strtol</span><span class="p">(</span><span class="n">ArgStart</span><span class="p">,</span> <span class="o">&</span><span class="n">End</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+
+ <span class="k">while</span> <span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">switch</span> <span class="p">(</span><span class="o">*</span><span class="n">End</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="mi">0</span><span class="o">:</span> <span class="k">return</span> <span class="kc">false</span><span class="p">;</span> <span class="c1">// No error</span>
+ <span class="k">case</span> <span class="sc">'i'</span><span class="o">:</span> <span class="c1">// Ignore the 'i' in KiB if people use that</span>
+ <span class="k">case</span> <span class="sc">'b'</span><span class="o">:</span> <span class="k">case</span> <span class="sc">'B'</span><span class="o">:</span> <span class="c1">// Ignore B suffix</span>
+ <span class="k">break</span><span class="p">;</span>
+
+ <span class="k">case</span> <span class="sc">'g'</span><span class="o">:</span> <span class="k">case</span> <span class="sc">'G'</span><span class="o">:</span> <span class="n">Val</span> <span class="o">*=</span> <span class="mi">1024</span><span class="o">*</span><span class="mi">1024</span><span class="o">*</span><span class="mi">1024</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="sc">'m'</span><span class="o">:</span> <span class="k">case</span> <span class="sc">'M'</span><span class="o">:</span> <span class="n">Val</span> <span class="o">*=</span> <span class="mi">1024</span><span class="o">*</span><span class="mi">1024</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+ <span class="k">case</span> <span class="sc">'k'</span><span class="o">:</span> <span class="k">case</span> <span class="sc">'K'</span><span class="o">:</span> <span class="n">Val</span> <span class="o">*=</span> <span class="mi">1024</span><span class="p">;</span> <span class="k">break</span><span class="p">;</span>
+
+ <span class="k">default</span><span class="o">:</span>
+ <span class="c1">// Print an error message if unrecognized character!</span>
+ <span class="k">return</span> <span class="n">O</span><span class="p">.</span><span class="n">error</span><span class="p">(</span><span class="s">"'"</span> <span class="o">+</span> <span class="n">Arg</span> <span class="o">+</span> <span class="s">"' value invalid for file size argument!"</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This function implements a very simple parser for the kinds of strings we are
+interested in. Although it has some holes (it allows “<tt class="docutils literal"><span class="pre">123KKK</span></tt>” for example),
+it is good enough for this example. Note that we use the option itself to print
+out the error message (the <tt class="docutils literal"><span class="pre">error</span></tt> method always returns true) in order to get
+a nice error message (shown below). Now that we have our parser class, we can
+use it like this:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">static</span> <span class="n">cl</span><span class="o">::</span><span class="n">opt</span><span class="o"><</span><span class="kt">unsigned</span><span class="p">,</span> <span class="kc">false</span><span class="p">,</span> <span class="n">FileSizeParser</span><span class="o">></span>
+<span class="n">MFS</span><span class="p">(</span><span class="s">"max-file-size"</span><span class="p">,</span> <span class="n">cl</span><span class="o">::</span><span class="n">desc</span><span class="p">(</span><span class="s">"Maximum file size to accept"</span><span class="p">),</span>
+ <span class="n">cl</span><span class="o">::</span><span class="n">value_desc</span><span class="p">(</span><span class="s">"size"</span><span class="p">));</span>
+</pre></div>
+</div>
+<p>Which adds this to the output of our program:</p>
+<div class="highlight-python"><pre>OPTIONS:
+ -help - display available options (-help-hidden for more)
+ ...
+ -max-file-size=<size> - Maximum file size to accept</pre>
+</div>
+<p>And we can test that our parse works correctly now (the test program just prints
+out the max-file-size argument value):</p>
+<div class="highlight-python"><pre>$ ./test
+MFS: 0
+$ ./test -max-file-size=123MB
+MFS: 128974848
+$ ./test -max-file-size=3G
+MFS: 3221225472
+$ ./test -max-file-size=dog
+-max-file-size option: 'dog' value invalid for file size argument!</pre>
+</div>
+<p>It looks like it works. The error message that we get is nice and helpful, and
+we seem to accept reasonable file sizes. This wraps up the “custom parser”
+tutorial.</p>
+</div>
+<div class="section" id="exploiting-external-storage">
+<h3><a class="toc-backref" href="#id46">Exploiting external storage</a><a class="headerlink" href="#exploiting-external-storage" title="Permalink to this headline">¶</a></h3>
+<p>Several of the LLVM libraries define static <tt class="docutils literal"><span class="pre">cl::opt</span></tt> instances that will
+automatically be included in any program that links with that library. This is
+a feature. However, sometimes it is necessary to know the value of the command
+line option outside of the library. In these cases the library does or should
+provide an external storage location that is accessible to users of the
+library. Examples of this include the <tt class="docutils literal"><span class="pre">llvm::DebugFlag</span></tt> exported by the
+<tt class="docutils literal"><span class="pre">lib/Support/Debug.cpp</span></tt> file and the <tt class="docutils literal"><span class="pre">llvm::TimePassesIsEnabled</span></tt> flag
+exported by the <tt class="docutils literal"><span class="pre">lib/IR/PassManager.cpp</span></tt> file.</p>
+</div>
+<div class="section" id="dynamically-adding-command-line-options">
+<span id="dynamically-loaded-options"></span><h3><a class="toc-backref" href="#id47">Dynamically adding command line options</a><a class="headerlink" href="#dynamically-adding-command-line-options" title="Permalink to this headline">¶</a></h3>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CodingStandards.html" title="LLVM Coding Standards"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CompileCudaWithLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CompileCudaWithLLVM.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CompileCudaWithLLVM.html (added)
+++ www-releases/trunk/7.0.1/docs/CompileCudaWithLLVM.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,611 @@
+
+
+<!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>Compiling CUDA with clang — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Reporting Guide" href="ReportingGuide.html" />
+ <link rel="prev" title="LLVM Community Code of Conduct" href="CodeOfConduct.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="ReportingGuide.html" title="Reporting Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CodeOfConduct.html" title="LLVM Community Code of Conduct"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="compiling-cuda-with-clang">
+<h1>Compiling CUDA with clang<a class="headerlink" href="#compiling-cuda-with-clang" 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="#compiling-cuda-code" id="id2">Compiling CUDA Code</a><ul>
+<li><a class="reference internal" href="#prerequisites" id="id3">Prerequisites</a></li>
+<li><a class="reference internal" href="#invoking-clang" id="id4">Invoking clang</a></li>
+<li><a class="reference internal" href="#flags-that-control-numerical-code" id="id5">Flags that control numerical code</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#standard-library-support" id="id6">Standard library support</a><ul>
+<li><a class="reference internal" href="#math-h-and-cmath" id="id7"><tt class="docutils literal"><span class="pre"><math.h></span></tt> and <tt class="docutils literal"><span class="pre"><cmath></span></tt></a></li>
+<li><a class="reference internal" href="#std-complex" id="id8"><tt class="docutils literal"><span class="pre"><std::complex></span></tt></a></li>
+<li><a class="reference internal" href="#algorithm" id="id9"><tt class="docutils literal"><span class="pre"><algorithm></span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#detecting-clang-vs-nvcc-from-code" id="id10">Detecting clang vs NVCC from code</a></li>
+<li><a class="reference internal" href="#dialect-differences-between-clang-and-nvcc" id="id11">Dialect Differences Between clang and nvcc</a><ul>
+<li><a class="reference internal" href="#compilation-models" id="id12">Compilation Models</a></li>
+<li><a class="reference internal" href="#overloading-based-on-host-and-device-attributes" id="id13">Overloading Based on <tt class="docutils literal"><span class="pre">__host__</span></tt> and <tt class="docutils literal"><span class="pre">__device__</span></tt> Attributes</a></li>
+<li><a class="reference internal" href="#using-a-different-class-on-host-device" id="id14">Using a Different Class on Host/Device</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#optimizations" id="id15">Optimizations</a></li>
+<li><a class="reference internal" href="#publication" id="id16">Publication</a></li>
+<li><a class="reference internal" href="#obtaining-help" id="id17">Obtaining Help</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes how to compile CUDA code with clang, and gives some
+details about LLVM and clang’s CUDA implementations.</p>
+<p>This document assumes a basic familiarity with CUDA. Information about CUDA
+programming can be found in the
+<a class="reference external" href="http://docs.nvidia.com/cuda/cuda-c-programming-guide/index.html">CUDA programming guide</a>.</p>
+</div>
+<div class="section" id="compiling-cuda-code">
+<h2><a class="toc-backref" href="#id2">Compiling CUDA Code</a><a class="headerlink" href="#compiling-cuda-code" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="prerequisites">
+<h3><a class="toc-backref" href="#id3">Prerequisites</a><a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h3>
+<p>CUDA is supported in llvm 3.9, but it’s still in active development, so we
+recommend you <a class="reference external" href="http://llvm.org/docs/GettingStarted.html">compile clang/LLVM from HEAD</a>.</p>
+<p>Before you build CUDA code, you’ll need to have installed the appropriate
+driver for your nvidia GPU and the CUDA SDK. See <a class="reference external" href="https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html">NVIDIA’s CUDA installation
+guide</a>
+for details. Note that clang <a class="reference external" href="https://llvm.org/bugs/show_bug.cgi?id=26966">does not support</a> the CUDA toolkit as installed
+by many Linux package managers; you probably need to install nvidia’s package.</p>
+<p>You will need CUDA 7.0, 7.5, or 8.0 to compile with clang.</p>
+<p>CUDA compilation is supported on Linux, on MacOS as of 2016-11-18, and on
+Windows as of 2017-01-05.</p>
+</div>
+<div class="section" id="invoking-clang">
+<h3><a class="toc-backref" href="#id4">Invoking clang</a><a class="headerlink" href="#invoking-clang" title="Permalink to this headline">¶</a></h3>
+<p>Invoking clang for CUDA compilation works similarly to compiling regular C++.
+You just need to be aware of a few additional flags.</p>
+<p>You can use <a class="reference external" href="https://gist.github.com/855e277884eb6b388cd2f00d956c2fd4">this</a>
+program as a toy example. Save it as <tt class="docutils literal"><span class="pre">axpy.cu</span></tt>. (Clang detects that you’re
+compiling CUDA code by noticing that your filename ends with <tt class="docutils literal"><span class="pre">.cu</span></tt>.
+Alternatively, you can pass <tt class="docutils literal"><span class="pre">-x</span> <span class="pre">cuda</span></tt>.)</p>
+<p>To build and run, run the following commands, filling in the parts in angle
+brackets as described below:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="gp">$</span> clang++ axpy.cu -o axpy --cuda-gpu-arch<span class="o">=</span><GPU arch> <span class="se">\</span>
+<span class="go"> -L<CUDA install path>/<lib64 or lib> \</span>
+<span class="go"> -lcudart_static -ldl -lrt -pthread</span>
+<span class="gp">$</span> ./axpy
+<span class="go">y[0] = 2</span>
+<span class="go">y[1] = 4</span>
+<span class="go">y[2] = 6</span>
+<span class="go">y[3] = 8</span>
+</pre></div>
+</div>
+<p>On MacOS, replace <cite>-lcudart_static</cite> with <cite>-lcudart</cite>; otherwise, you may get
+“CUDA driver version is insufficient for CUDA runtime version” errors when you
+run your program.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre"><CUDA</span> <span class="pre">install</span> <span class="pre">path></span></tt> – the directory where you installed CUDA SDK.
+Typically, <tt class="docutils literal"><span class="pre">/usr/local/cuda</span></tt>.</p>
+<p>Pass e.g. <tt class="docutils literal"><span class="pre">-L/usr/local/cuda/lib64</span></tt> if compiling in 64-bit mode; otherwise,
+pass e.g. <tt class="docutils literal"><span class="pre">-L/usr/local/cuda/lib</span></tt>. (In CUDA, the device code and host code
+always have the same pointer widths, so if you’re compiling 64-bit code for
+the host, you’re also compiling 64-bit code for the device.)</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre"><GPU</span> <span class="pre">arch></span></tt> – the <a class="reference external" href="https://developer.nvidia.com/cuda-gpus">compute capability</a> of your GPU. For example, if you
+want to run your program on a GPU with compute capability of 3.5, specify
+<tt class="docutils literal"><span class="pre">--cuda-gpu-arch=sm_35</span></tt>.</p>
+<p>Note: You cannot pass <tt class="docutils literal"><span class="pre">compute_XX</span></tt> as an argument to <tt class="docutils literal"><span class="pre">--cuda-gpu-arch</span></tt>;
+only <tt class="docutils literal"><span class="pre">sm_XX</span></tt> is currently supported. However, clang always includes PTX in
+its binaries, so e.g. a binary compiled with <tt class="docutils literal"><span class="pre">--cuda-gpu-arch=sm_30</span></tt> would be
+forwards-compatible with e.g. <tt class="docutils literal"><span class="pre">sm_35</span></tt> GPUs.</p>
+<p>You can pass <tt class="docutils literal"><span class="pre">--cuda-gpu-arch</span></tt> multiple times to compile for multiple archs.</p>
+</li>
+</ul>
+<p>The <cite>-L</cite> and <cite>-l</cite> flags only need to be passed when linking. When compiling,
+you may also need to pass <tt class="docutils literal"><span class="pre">--cuda-path=/path/to/cuda</span></tt> if you didn’t install
+the CUDA SDK into <tt class="docutils literal"><span class="pre">/usr/local/cuda</span></tt>, <tt class="docutils literal"><span class="pre">/usr/local/cuda-7.0</span></tt>, or
+<tt class="docutils literal"><span class="pre">/usr/local/cuda-7.5</span></tt>.</p>
+</div>
+<div class="section" id="flags-that-control-numerical-code">
+<h3><a class="toc-backref" href="#id5">Flags that control numerical code</a><a class="headerlink" href="#flags-that-control-numerical-code" title="Permalink to this headline">¶</a></h3>
+<p>If you’re using GPUs, you probably care about making numerical code run fast.
+GPU hardware allows for more control over numerical operations than most CPUs,
+but this results in more compiler options for you to juggle.</p>
+<p>Flags you may wish to tweak include:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-ffp-contract={on,off,fast}</span></tt> (defaults to <tt class="docutils literal"><span class="pre">fast</span></tt> on host and device when
+compiling CUDA) Controls whether the compiler emits fused multiply-add
+operations.</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">off</span></tt>: never emit fma operations, and prevent ptxas from fusing multiply
+and add instructions.</li>
+<li><tt class="docutils literal"><span class="pre">on</span></tt>: fuse multiplies and adds within a single statement, but never
+across statements (C11 semantics). Prevent ptxas from fusing other
+multiplies and adds.</li>
+<li><tt class="docutils literal"><span class="pre">fast</span></tt>: fuse multiplies and adds wherever profitable, even across
+statements. Doesn’t prevent ptxas from fusing additional multiplies and
+adds.</li>
+</ul>
+<p>Fused multiply-add instructions can be much faster than the unfused
+equivalents, but because the intermediate result in an fma is not rounded,
+this flag can affect numerical code.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-fcuda-flush-denormals-to-zero</span></tt> (default: off) When this is enabled,
+floating point operations may flush <a class="reference external" href="https://en.wikipedia.org/wiki/Denormal_number">denormal</a> inputs and/or outputs to 0.
+Operations on denormal numbers are often much slower than the same operations
+on normal numbers.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">-fcuda-approx-transcendentals</span></tt> (default: off) When this is enabled, the
+compiler may emit calls to faster, approximate versions of transcendental
+functions, instead of using the slower, fully IEEE-compliant versions. For
+example, this flag allows clang to emit the ptx <tt class="docutils literal"><span class="pre">sin.approx.f32</span></tt>
+instruction.</p>
+<p>This is implied by <tt class="docutils literal"><span class="pre">-ffast-math</span></tt>.</p>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="standard-library-support">
+<h2><a class="toc-backref" href="#id6">Standard library support</a><a class="headerlink" href="#standard-library-support" title="Permalink to this headline">¶</a></h2>
+<p>In clang and nvcc, most of the C++ standard library is not supported on the
+device side.</p>
+<div class="section" id="math-h-and-cmath">
+<h3><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre"><math.h></span></tt> and <tt class="docutils literal"><span class="pre"><cmath></span></tt></a><a class="headerlink" href="#math-h-and-cmath" title="Permalink to this headline">¶</a></h3>
+<p>In clang, <tt class="docutils literal"><span class="pre">math.h</span></tt> and <tt class="docutils literal"><span class="pre">cmath</span></tt> are available and <a class="reference external" href="https://github.com/llvm-mirror/test-suite/blob/master/External/CUDA/math_h.cu">pass</a>
+<a class="reference external" href="https://github.com/llvm-mirror/test-suite/blob/master/External/CUDA/cmath.cu">tests</a>
+adapted from libc++’s test suite.</p>
+<p>In nvcc <tt class="docutils literal"><span class="pre">math.h</span></tt> and <tt class="docutils literal"><span class="pre">cmath</span></tt> are mostly available. Versions of <tt class="docutils literal"><span class="pre">::foof</span></tt>
+in namespace std (e.g. <tt class="docutils literal"><span class="pre">std::sinf</span></tt>) are not available, and where the standard
+calls for overloads that take integral arguments, these are usually not
+available.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include <math.h></span>
+<span class="cp">#include <cmath.h></span>
+
+<span class="c1">// clang is OK with everything in this function.</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">sin</span><span class="p">(</span><span class="mf">0.</span><span class="p">);</span> <span class="c1">// nvcc - ok</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">sin</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span> <span class="c1">// nvcc - error, because no std::sin(int) override is available.</span>
+ <span class="n">sin</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span> <span class="c1">// nvcc - same as above.</span>
+
+ <span class="n">sinf</span><span class="p">(</span><span class="mf">0.</span><span class="p">);</span> <span class="c1">// nvcc - ok</span>
+ <span class="n">std</span><span class="o">::</span><span class="n">sinf</span><span class="p">(</span><span class="mf">0.</span><span class="p">);</span> <span class="c1">// nvcc - no such function</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="std-complex">
+<h3><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre"><std::complex></span></tt></a><a class="headerlink" href="#std-complex" title="Permalink to this headline">¶</a></h3>
+<p>nvcc does not officially support <tt class="docutils literal"><span class="pre">std::complex</span></tt>. It’s an error to use
+<tt class="docutils literal"><span class="pre">std::complex</span></tt> in <tt class="docutils literal"><span class="pre">__device__</span></tt> code, but it often works in <tt class="docutils literal"><span class="pre">__host__</span>
+<span class="pre">__device__</span></tt> code due to nvcc’s interpretation of the “wrong-side rule” (see
+below). However, we have heard from implementers that it’s possible to get
+into situations where nvcc will omit a call to an <tt class="docutils literal"><span class="pre">std::complex</span></tt> function,
+especially when compiling without optimizations.</p>
+<p>As of 2016-11-16, clang supports <tt class="docutils literal"><span class="pre">std::complex</span></tt> without these caveats. It is
+tested with libstdc++ 4.8.5 and newer, but is known to work only with libc++
+newer than 2016-11-16.</p>
+</div>
+<div class="section" id="algorithm">
+<h3><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre"><algorithm></span></tt></a><a class="headerlink" href="#algorithm" title="Permalink to this headline">¶</a></h3>
+<p>In C++14, many useful functions from <tt class="docutils literal"><span class="pre"><algorithm></span></tt> (notably, <tt class="docutils literal"><span class="pre">std::min</span></tt> and
+<tt class="docutils literal"><span class="pre">std::max</span></tt>) become constexpr. You can therefore use these in device code,
+when compiling with clang.</p>
+</div>
+</div>
+<div class="section" id="detecting-clang-vs-nvcc-from-code">
+<h2><a class="toc-backref" href="#id10">Detecting clang vs NVCC from code</a><a class="headerlink" href="#detecting-clang-vs-nvcc-from-code" title="Permalink to this headline">¶</a></h2>
+<p>Although clang’s CUDA implementation is largely compatible with NVCC’s, you may
+still want to detect when you’re compiling CUDA code specifically with clang.</p>
+<p>This is tricky, because NVCC may invoke clang as part of its own compilation
+process! For example, NVCC uses the host compiler’s preprocessor when
+compiling for device code, and that host compiler may in fact be clang.</p>
+<p>When clang is actually compiling CUDA code – rather than being used as a
+subtool of NVCC’s – it defines the <tt class="docutils literal"><span class="pre">__CUDA__</span></tt> macro. <tt class="docutils literal"><span class="pre">__CUDA_ARCH__</span></tt> is
+defined only in device mode (but will be defined if NVCC is using clang as a
+preprocessor). So you can use the following incantations to detect clang CUDA
+compilation, in host and device modes:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#if defined(__clang__) && defined(__CUDA__) && !defined(__CUDA_ARCH__)</span>
+<span class="cp">// clang compiling CUDA code, host mode.</span>
+<span class="cp">#endif</span>
+
+<span class="cp">#if defined(__clang__) && defined(__CUDA__) && defined(__CUDA_ARCH__)</span>
+<span class="cp">// clang compiling CUDA code, device mode.</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>Both clang and nvcc define <tt class="docutils literal"><span class="pre">__CUDACC__</span></tt> during CUDA compilation. You can
+detect NVCC specifically by looking for <tt class="docutils literal"><span class="pre">__NVCC__</span></tt>.</p>
+</div>
+<div class="section" id="dialect-differences-between-clang-and-nvcc">
+<h2><a class="toc-backref" href="#id11">Dialect Differences Between clang and nvcc</a><a class="headerlink" href="#dialect-differences-between-clang-and-nvcc" title="Permalink to this headline">¶</a></h2>
+<p>There is no formal CUDA spec, and clang and nvcc speak slightly different
+dialects of the language. Below, we describe some of the differences.</p>
+<p>This section is painful; hopefully you can skip this section and live your life
+blissfully unaware.</p>
+<div class="section" id="compilation-models">
+<h3><a class="toc-backref" href="#id12">Compilation Models</a><a class="headerlink" href="#compilation-models" title="Permalink to this headline">¶</a></h3>
+<p>Most of the differences between clang and nvcc stem from the different
+compilation models used by clang and nvcc. nvcc uses <em>split compilation</em>,
+which works roughly as follows:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Run a preprocessor over the input <tt class="docutils literal"><span class="pre">.cu</span></tt> file to split it into two source
+files: <tt class="docutils literal"><span class="pre">H</span></tt>, containing source code for the host, and <tt class="docutils literal"><span class="pre">D</span></tt>, containing
+source code for the device.</li>
+<li>For each GPU architecture <tt class="docutils literal"><span class="pre">arch</span></tt> that we’re compiling for, do:<ul>
+<li>Compile <tt class="docutils literal"><span class="pre">D</span></tt> using nvcc proper. The result of this is a <tt class="docutils literal"><span class="pre">ptx</span></tt> file for
+<tt class="docutils literal"><span class="pre">P_arch</span></tt>.</li>
+<li>Optionally, invoke <tt class="docutils literal"><span class="pre">ptxas</span></tt>, the PTX assembler, to generate a file,
+<tt class="docutils literal"><span class="pre">S_arch</span></tt>, containing GPU machine code (SASS) for <tt class="docutils literal"><span class="pre">arch</span></tt>.</li>
+</ul>
+</li>
+<li>Invoke <tt class="docutils literal"><span class="pre">fatbin</span></tt> to combine all <tt class="docutils literal"><span class="pre">P_arch</span></tt> and <tt class="docutils literal"><span class="pre">S_arch</span></tt> files into a
+single “fat binary” file, <tt class="docutils literal"><span class="pre">F</span></tt>.</li>
+<li>Compile <tt class="docutils literal"><span class="pre">H</span></tt> using an external host compiler (gcc, clang, or whatever you
+like). <tt class="docutils literal"><span class="pre">F</span></tt> is packaged up into a header file which is force-included into
+<tt class="docutils literal"><span class="pre">H</span></tt>; nvcc generates code that calls into this header to e.g. launch
+kernels.</li>
+</ul>
+</div></blockquote>
+<p>clang uses <em>merged parsing</em>. This is similar to split compilation, except all
+of the host and device code is present and must be semantically-correct in both
+compilation steps.</p>
+<blockquote>
+<div><ul>
+<li><p class="first">For each GPU architecture <tt class="docutils literal"><span class="pre">arch</span></tt> that we’re compiling for, do:</p>
+<ul>
+<li><p class="first">Compile the input <tt class="docutils literal"><span class="pre">.cu</span></tt> file for device, using clang. <tt class="docutils literal"><span class="pre">__host__</span></tt> code
+is parsed and must be semantically correct, even though we’re not
+generating code for the host at this time.</p>
+<p>The output of this step is a <tt class="docutils literal"><span class="pre">ptx</span></tt> file <tt class="docutils literal"><span class="pre">P_arch</span></tt>.</p>
+</li>
+<li><p class="first">Invoke <tt class="docutils literal"><span class="pre">ptxas</span></tt> to generate a SASS file, <tt class="docutils literal"><span class="pre">S_arch</span></tt>. Note that, unlike
+nvcc, clang always generates SASS code.</p>
+</li>
+</ul>
+</li>
+<li><p class="first">Invoke <tt class="docutils literal"><span class="pre">fatbin</span></tt> to combine all <tt class="docutils literal"><span class="pre">P_arch</span></tt> and <tt class="docutils literal"><span class="pre">S_arch</span></tt> files into a
+single fat binary file, <tt class="docutils literal"><span class="pre">F</span></tt>.</p>
+</li>
+<li><p class="first">Compile <tt class="docutils literal"><span class="pre">H</span></tt> using clang. <tt class="docutils literal"><span class="pre">__device__</span></tt> code is parsed and must be
+semantically correct, even though we’re not generating code for the device
+at this time.</p>
+<p><tt class="docutils literal"><span class="pre">F</span></tt> is passed to this compilation, and clang includes it in a special ELF
+section, where it can be found by tools like <tt class="docutils literal"><span class="pre">cuobjdump</span></tt>.</p>
+</li>
+</ul>
+</div></blockquote>
+<p>(You may ask at this point, why does clang need to parse the input file
+multiple times? Why not parse it just once, and then use the AST to generate
+code for the host and each device architecture?</p>
+<p>Unfortunately this can’t work because we have to define different macros during
+host compilation and during device compilation for each GPU architecture.)</p>
+<p>clang’s approach allows it to be highly robust to C++ edge cases, as it doesn’t
+need to decide at an early stage which declarations to keep and which to throw
+away. But it has some consequences you should be aware of.</p>
+</div>
+<div class="section" id="overloading-based-on-host-and-device-attributes">
+<h3><a class="toc-backref" href="#id13">Overloading Based on <tt class="docutils literal"><span class="pre">__host__</span></tt> and <tt class="docutils literal"><span class="pre">__device__</span></tt> Attributes</a><a class="headerlink" href="#overloading-based-on-host-and-device-attributes" title="Permalink to this headline">¶</a></h3>
+<p>Let “H”, “D”, and “HD” stand for “<tt class="docutils literal"><span class="pre">__host__</span></tt> functions”, “<tt class="docutils literal"><span class="pre">__device__</span></tt>
+functions”, and “<tt class="docutils literal"><span class="pre">__host__</span> <span class="pre">__device__</span></tt> functions”, respectively. Functions
+with no attributes behave the same as H.</p>
+<p>nvcc does not allow you to create H and D functions with the same signature:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// nvcc: error - function "foo" has already been defined</span>
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>However, nvcc allows you to “overload” H and D functions with different
+signatures:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// nvcc: no error</span>
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>In clang, the <tt class="docutils literal"><span class="pre">__host__</span></tt> and <tt class="docutils literal"><span class="pre">__device__</span></tt> attributes are part of a
+function’s signature, and so it’s legal to have H and D functions with
+(otherwise) the same signature:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// clang: no error</span>
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>HD functions cannot be overloaded by H or D functions with the same signature:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">// nvcc: error - function "foo" has already been defined</span>
+<span class="c1">// clang: error - redefinition of 'foo'</span>
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{}</span>
+
+<span class="c1">// nvcc: no error</span>
+<span class="c1">// clang: no error</span>
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">(</span><span class="kt">int</span><span class="p">)</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">()</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>When resolving an overloaded function, clang considers the host/device
+attributes of the caller and callee. These are used as a tiebreaker during
+overload resolution. See <a class="reference external" href="http://clang.llvm.org/doxygen/SemaCUDA_8cpp.html">IdentifyCUDAPreference</a> for the full set of rules,
+but at a high level they are:</p>
+<blockquote>
+<div><ul>
+<li><p class="first">D functions prefer to call other Ds. HDs are given lower priority.</p>
+</li>
+<li><p class="first">Similarly, H functions prefer to call other Hs, or <tt class="docutils literal"><span class="pre">__global__</span></tt> functions
+(with equal priority). HDs are given lower priority.</p>
+</li>
+<li><p class="first">HD functions prefer to call other HDs.</p>
+<p>When compiling for device, HDs will call Ds with lower priority than HD, and
+will call Hs with still lower priority. If it’s forced to call an H, the
+program is malformed if we emit code for this HD function. We call this the
+“wrong-side rule”, see example below.</p>
+<p>The rules are symmetrical when compiling for host.</p>
+</li>
+</ul>
+</div></blockquote>
+<p>Some examples:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">();</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">();</span>
+
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">();</span>
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">();</span>
+
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">test_host</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">();</span> <span class="c1">// calls H overload</span>
+ <span class="n">bar</span><span class="p">();</span> <span class="c1">// calls H overload</span>
+<span class="p">}</span>
+
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">test_device</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">();</span> <span class="c1">// calls D overload</span>
+ <span class="n">bar</span><span class="p">();</span> <span class="c1">// calls HD overload</span>
+<span class="p">}</span>
+
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">test_hd</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">foo</span><span class="p">();</span> <span class="c1">// calls H overload when compiling for host, otherwise D overload</span>
+ <span class="n">bar</span><span class="p">();</span> <span class="c1">// always calls HD overload</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Wrong-side rule example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">__host__</span> <span class="kt">void</span> <span class="n">host_only</span><span class="p">();</span>
+
+<span class="c1">// We don't codegen inline functions unless they're referenced by a</span>
+<span class="c1">// non-inline function. inline_hd1() is called only from the host side, so</span>
+<span class="c1">// does not generate an error. inline_hd2() is called from the device side,</span>
+<span class="c1">// so it generates an error.</span>
+<span class="kr">inline</span> <span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">inline_hd1</span><span class="p">()</span> <span class="p">{</span> <span class="n">host_only</span><span class="p">();</span> <span class="p">}</span> <span class="c1">// no error</span>
+<span class="kr">inline</span> <span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">inline_hd2</span><span class="p">()</span> <span class="p">{</span> <span class="n">host_only</span><span class="p">();</span> <span class="p">}</span> <span class="c1">// error</span>
+
+<span class="n">__host__</span> <span class="kt">void</span> <span class="n">host_fn</span><span class="p">()</span> <span class="p">{</span> <span class="n">inline_hd1</span><span class="p">();</span> <span class="p">}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">device_fn</span><span class="p">()</span> <span class="p">{</span> <span class="n">inline_hd2</span><span class="p">();</span> <span class="p">}</span>
+
+<span class="c1">// This function is not inline, so it's always codegen'ed on both the host</span>
+<span class="c1">// and the device. Therefore, it generates an error.</span>
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="n">not_inline_hd</span><span class="p">()</span> <span class="p">{</span> <span class="n">host_only</span><span class="p">();</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>For the purposes of the wrong-side rule, templated functions also behave like
+<tt class="docutils literal"><span class="pre">inline</span></tt> functions: They aren’t codegen’ed unless they’re instantiated
+(usually as part of the process of invoking them).</p>
+<p>clang’s behavior with respect to the wrong-side rule matches nvcc’s, except
+nvcc only emits a warning for <tt class="docutils literal"><span class="pre">not_inline_hd</span></tt>; device code is allowed to call
+<tt class="docutils literal"><span class="pre">not_inline_hd</span></tt>. In its generated code, nvcc may omit <tt class="docutils literal"><span class="pre">not_inline_hd</span></tt>‘s
+call to <tt class="docutils literal"><span class="pre">host_only</span></tt> entirely, or it may try to generate code for
+<tt class="docutils literal"><span class="pre">host_only</span></tt> on the device. What you get seems to depend on whether or not
+the compiler chooses to inline <tt class="docutils literal"><span class="pre">host_only</span></tt>.</p>
+<p>Member functions, including constructors, may be overloaded using H and D
+attributes. However, destructors cannot be overloaded.</p>
+</div>
+<div class="section" id="using-a-different-class-on-host-device">
+<h3><a class="toc-backref" href="#id14">Using a Different Class on Host/Device</a><a class="headerlink" href="#using-a-different-class-on-host-device" title="Permalink to this headline">¶</a></h3>
+<p>Occasionally you may want to have a class with different host/device versions.</p>
+<p>If all of the class’s members are the same on the host and device, you can just
+provide overloads for the class’s member functions.</p>
+<p>However, if you want your class to have different members on host/device, you
+won’t be able to provide working H and D overloads in both classes. In this
+case, clang is likely to be unhappy with you.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#ifdef __CUDA_ARCH__</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{</span>
+ <span class="n">__device__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span> <span class="cm">/* use device_only */</span> <span class="p">}</span>
+ <span class="kt">int</span> <span class="n">device_only</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="cp">#else</span>
+<span class="k">struct</span> <span class="n">S</span> <span class="p">{</span>
+ <span class="n">__host__</span> <span class="kt">void</span> <span class="n">foo</span><span class="p">()</span> <span class="p">{</span> <span class="cm">/* use host_only */</span> <span class="p">}</span>
+ <span class="kt">double</span> <span class="n">host_only</span><span class="p">;</span>
+<span class="p">};</span>
+
+<span class="n">__device__</span> <span class="kt">void</span> <span class="n">test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">S</span> <span class="n">s</span><span class="p">;</span>
+ <span class="c1">// clang generates an error here, because during host compilation, we</span>
+ <span class="c1">// have ifdef'ed away the __device__ overload of S::foo(). The __device__</span>
+ <span class="c1">// overload must be present *even during host compilation*.</span>
+ <span class="n">S</span><span class="p">.</span><span class="n">foo</span><span class="p">();</span>
+<span class="p">}</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>We posit that you don’t really want to have classes with different members on H
+and D. For example, if you were to pass one of these as a parameter to a
+kernel, it would have a different layout on H and D, so would not work
+properly.</p>
+<p>To make code like this compatible with clang, we recommend you separate it out
+into two classes. If you need to write code that works on both host and
+device, consider writing an overloaded wrapper function that returns different
+types on host and device.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">HostS</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">DeviceS</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
+
+<span class="n">__host__</span> <span class="n">HostS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">HostS</span><span class="p">();</span> <span class="p">}</span>
+<span class="n">__device__</span> <span class="n">DeviceS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">DeviceS</span><span class="p">();</span> <span class="p">}</span>
+
+<span class="c1">// Now host and device code can call MakeStruct().</span>
+</pre></div>
+</div>
+<p>Unfortunately, this idiom isn’t compatible with nvcc, because it doesn’t allow
+you to overload based on the H/D attributes. Here’s an idiom that works with
+both clang and nvcc:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">HostS</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
+<span class="k">struct</span> <span class="n">DeviceS</span> <span class="p">{</span> <span class="p">...</span> <span class="p">};</span>
+
+<span class="cp">#ifdef __NVCC__</span>
+<span class="cp"> #ifndef __CUDA_ARCH__</span>
+ <span class="n">__host__</span> <span class="n">HostS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">HostS</span><span class="p">();</span> <span class="p">}</span>
+<span class="cp"> #else</span>
+ <span class="n">__device__</span> <span class="n">DeviceS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">DeviceS</span><span class="p">();</span> <span class="p">}</span>
+<span class="cp"> #endif</span>
+<span class="cp">#else</span>
+ <span class="n">__host__</span> <span class="n">HostS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">HostS</span><span class="p">();</span> <span class="p">}</span>
+ <span class="n">__device__</span> <span class="n">DeviceS</span> <span class="n">MakeStruct</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span> <span class="n">DeviceS</span><span class="p">();</span> <span class="p">}</span>
+<span class="cp">#endif</span>
+
+<span class="c1">// Now host and device code can call MakeStruct().</span>
+</pre></div>
+</div>
+<p>Hopefully you don’t have to do this sort of thing often.</p>
+</div>
+</div>
+<div class="section" id="optimizations">
+<h2><a class="toc-backref" href="#id15">Optimizations</a><a class="headerlink" href="#optimizations" title="Permalink to this headline">¶</a></h2>
+<p>Modern CPUs and GPUs are architecturally quite different, so code that’s fast
+on a CPU isn’t necessarily fast on a GPU. We’ve made a number of changes to
+LLVM to make it generate good GPU code. Among these changes are:</p>
+<ul>
+<li><p class="first"><a class="reference external" href="https://goo.gl/4Rb9As">Straight-line scalar optimizations</a> – These
+reduce redundancy within straight-line code.</p>
+</li>
+<li><p class="first"><a class="reference external" href="http://llvm.org/docs/doxygen/html/SpeculativeExecution_8cpp_source.html">Aggressive speculative execution</a>
+– This is mainly for promoting straight-line scalar optimizations, which are
+most effective on code along dominator paths.</p>
+</li>
+<li><p class="first"><a class="reference external" href="http://llvm.org/doxygen/NVPTXInferAddressSpaces_8cpp_source.html">Memory space inference</a> –
+In PTX, we can operate on pointers that are in a paricular “address space”
+(global, shared, constant, or local), or we can operate on pointers in the
+“generic” address space, which can point to anything. Operations in a
+non-generic address space are faster, but pointers in CUDA are not explicitly
+annotated with their address space, so it’s up to LLVM to infer it where
+possible.</p>
+</li>
+<li><p class="first"><a class="reference external" href="http://llvm.org/docs/doxygen/html/BypassSlowDivision_8cpp_source.html">Bypassing 64-bit divides</a> –
+This was an existing optimization that we enabled for the PTX backend.</p>
+<p>64-bit integer divides are much slower than 32-bit ones on NVIDIA GPUs.
+Many of the 64-bit divides in our benchmarks have a divisor and dividend
+which fit in 32-bits at runtime. This optimization provides a fast path for
+this common case.</p>
+</li>
+<li><p class="first">Aggressive loop unrooling and function inlining – Loop unrolling and
+function inlining need to be more aggressive for GPUs than for CPUs because
+control flow transfer in GPU is more expensive. More aggressive unrolling and
+inlining also promote other optimizations, such as constant propagation and
+SROA, which sometimes speed up code by over 10x.</p>
+<p>(Programmers can force unrolling and inline using clang’s <a class="reference external" href="http://clang.llvm.org/docs/AttributeReference.html#pragma-unroll-pragma-nounroll">loop unrolling pragmas</a>
+and <tt class="docutils literal"><span class="pre">__attribute__((always_inline))</span></tt>.)</p>
+</li>
+</ul>
+</div>
+<div class="section" id="publication">
+<h2><a class="toc-backref" href="#id16">Publication</a><a class="headerlink" href="#publication" title="Permalink to this headline">¶</a></h2>
+<p>The team at Google published a paper in CGO 2016 detailing the optimizations
+they’d made to clang/LLVM. Note that “gpucc” is no longer a meaningful name:
+The relevant tools are now just vanilla clang/LLVM.</p>
+<div class="line-block">
+<div class="line"><a class="reference external" href="http://dl.acm.org/citation.cfm?id=2854041">gpucc: An Open-Source GPGPU Compiler</a></div>
+<div class="line">Jingyue Wu, Artem Belevich, Eli Bendersky, Mark Heffernan, Chris Leary, Jacques Pienaar, Bjarke Roune, Rob Springer, Xuetian Weng, Robert Hundt</div>
+<div class="line"><em>Proceedings of the 2016 International Symposium on Code Generation and Optimization (CGO 2016)</em></div>
+<div class="line"><br /></div>
+<div class="line"><a class="reference external" href="http://wujingyue.com/docs/gpucc-talk.pdf">Slides from the CGO talk</a></div>
+<div class="line"><br /></div>
+<div class="line"><a class="reference external" href="http://wujingyue.com/docs/gpucc-tutorial.pdf">Tutorial given at CGO</a></div>
+</div>
+</div>
+<div class="section" id="obtaining-help">
+<h2><a class="toc-backref" href="#id17">Obtaining Help</a><a class="headerlink" href="#obtaining-help" title="Permalink to this headline">¶</a></h2>
+<p>To obtain help on LLVM in general and its CUDA support, see <a class="reference external" href="http://llvm.org/docs/#mailing-lists">the LLVM
+community</a>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="ReportingGuide.html" title="Reporting Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CodeOfConduct.html" title="LLVM Community Code of Conduct"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CompilerWriterInfo.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CompilerWriterInfo.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CompilerWriterInfo.html (added)
+++ www-releases/trunk/7.0.1/docs/CompilerWriterInfo.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,290 @@
+
+
+<!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>Architecture & Platform Information for Compiler Writers — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Extending LLVM: Adding instructions, intrinsics, types, etc." href="ExtendingLLVM.html" />
+ <link rel="prev" title="CommandLine 2.0 Library Manual" href="CommandLine.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CommandLine.html" title="CommandLine 2.0 Library Manual"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="architecture-platform-information-for-compiler-writers">
+<h1>Architecture & Platform Information for Compiler Writers<a class="headerlink" href="#architecture-platform-information-for-compiler-writers" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#hardware" id="id1">Hardware</a><ul>
+<li><a class="reference internal" href="#aarch64-arm" id="id2">AArch64 & ARM</a></li>
+<li><a class="reference internal" href="#itanium-ia64" id="id3">Itanium (ia64)</a></li>
+<li><a class="reference internal" href="#lanai" id="id4">Lanai</a></li>
+<li><a class="reference internal" href="#mips" id="id5">MIPS</a></li>
+<li><a class="reference internal" href="#powerpc" id="id6">PowerPC</a><ul>
+<li><a class="reference internal" href="#ibm-official-manuals-and-docs" id="id7">IBM - Official manuals and docs</a></li>
+<li><a class="reference internal" href="#other-documents-collections-notes" id="id8">Other documents, collections, notes</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#amdgpu" id="id9">AMDGPU</a></li>
+<li><a class="reference internal" href="#risc-v" id="id10">RISC-V</a></li>
+<li><a class="reference internal" href="#sparc" id="id11">SPARC</a></li>
+<li><a class="reference internal" href="#systemz" id="id12">SystemZ</a></li>
+<li><a class="reference internal" href="#x86" id="id13">X86</a></li>
+<li><a class="reference internal" href="#xcore" id="id14">XCore</a></li>
+<li><a class="reference internal" href="#hexagon" id="id15">Hexagon</a></li>
+<li><a class="reference internal" href="#other-relevant-lists" id="id16">Other relevant lists</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#abi" id="id17">ABI</a><ul>
+<li><a class="reference internal" href="#linux" id="id18">Linux</a></li>
+<li><a class="reference internal" href="#os-x" id="id19">OS X</a></li>
+<li><a class="reference internal" href="#windows" id="id20">Windows</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#nvptx" id="id21">NVPTX</a></li>
+<li><a class="reference internal" href="#miscellaneous-resources" id="id22">Miscellaneous Resources</a></li>
+</ul>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This document is a work-in-progress. Additions and clarifications are
+welcome.</p>
+</div>
+<div class="section" id="hardware">
+<h2><a class="toc-backref" href="#id1">Hardware</a><a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="aarch64-arm">
+<h3><a class="toc-backref" href="#id2">AArch64 & ARM</a><a class="headerlink" href="#aarch64-arm" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.h/index.html">ARMv8-A Architecture Reference Manual</a> (authentication required, free sign-up). This document covers both AArch64 and ARM instructions</li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ddi0403e.b/index.html">ARMv7-M Architecture Reference Manual</a> (authentication required, free sign-up). This covers the Thumb2-only microcontrollers</li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ddi0419c/index.html">ARMv6-M Architecture Reference Manual</a> (authentication required, free sign-up). This covers the Thumb1-only microcontrollers</li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf">ARM C Language Extensions</a></li>
+<li>AArch32 <a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0045d/IHI0045D_ABI_addenda.pdf">ABI Addenda and Errata</a></li>
+</ul>
+</div>
+<div class="section" id="itanium-ia64">
+<h3><a class="toc-backref" href="#id3">Itanium (ia64)</a><a class="headerlink" href="#itanium-ia64" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://developer.intel.com/design/itanium2/documentation.htm">Itanium documentation</a></li>
+</ul>
+</div>
+<div class="section" id="lanai">
+<h3><a class="toc-backref" href="#id4">Lanai</a><a class="headerlink" href="#lanai" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://g.co/lanai/isa">Lanai Instruction Set Architecture</a></li>
+</ul>
+</div>
+<div class="section" id="mips">
+<h3><a class="toc-backref" href="#id5">MIPS</a><a class="headerlink" href="#mips" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://www.mips.com/products/">MIPS Processor Architecture</a></li>
+<li><a class="reference external" href="http://techpubs.sgi.com/library/manuals/4000/007-4658-001/pdf/007-4658-001.pdf">MIPS 64-bit ELF Object File Specification</a></li>
+</ul>
+</div>
+<div class="section" id="powerpc">
+<h3><a class="toc-backref" href="#id6">PowerPC</a><a class="headerlink" href="#powerpc" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="ibm-official-manuals-and-docs">
+<h4><a class="toc-backref" href="#id7">IBM - Official manuals and docs</a><a class="headerlink" href="#ibm-official-manuals-and-docs" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><a class="reference external" href="https://www.power.org/technology-introduction/standards-specifications">Power Instruction Set Architecture, Versions 2.03 through 2.06 (authentication required, free sign-up)</a></li>
+<li><a class="reference external" href="http://www.ibm.com/chips/techlib/techlib.nsf/techdocs/852569B20050FF7785256996007558C6">PowerPC Compiler Writer’s Guide</a></li>
+<li><a class="reference external" href="http://www.ibm.com/developerworks/linux/library/l-powarch/">Intro to PowerPC Architecture</a></li>
+<li><a class="reference external" href="http://www.ibm.com/chips/techlib/techlib.nsf/products/PowerPC">PowerPC Processor Manuals (embedded)</a></li>
+<li><a class="reference external" href="https://www.power.org/documentation/?document_company=105&document_category=all&publish_year=all&grid_order=DESC&grid_sort=title">Various IBM specifications and white papers</a></li>
+<li><a class="reference external" href="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixassem/alangref/alangreftfrm.htm">IBM AIX/5L for POWER Assembly Reference</a></li>
+</ul>
+</div>
+<div class="section" id="other-documents-collections-notes">
+<h4><a class="toc-backref" href="#id8">Other documents, collections, notes</a><a class="headerlink" href="#other-documents-collections-notes" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><a class="reference external" href="http://penguinppc.org/dev/#library">PowerPC ABI documents</a></li>
+<li><a class="reference external" href="http://gcc.gnu.org/ml/gcc-patches/2003-09/msg00997.html">PowerPC64 alignment of long doubles (from GCC)</a></li>
+<li><a class="reference external" href="http://sources.redhat.com/ml/binutils/2002-04/msg00573.html">Long branch stubs for powerpc64-linux (from binutils)</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="amdgpu">
+<h3><a class="toc-backref" href="#id9">AMDGPU</a><a class="headerlink" href="#amdgpu" title="Permalink to this headline">¶</a></h3>
+<p>Refer to <a class="reference internal" href="AMDGPUUsage.html"><em>User Guide for AMDGPU Backend</em></a> for additional documentation.</p>
+</div>
+<div class="section" id="risc-v">
+<h3><a class="toc-backref" href="#id10">RISC-V</a><a class="headerlink" href="#risc-v" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://riscv.org/specifications/">RISC-V User-Level ISA Specification</a></li>
+</ul>
+</div>
+<div class="section" id="sparc">
+<h3><a class="toc-backref" href="#id11">SPARC</a><a class="headerlink" href="#sparc" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://sparc.org/standards">SPARC standards</a></li>
+<li><a class="reference external" href="http://sparc.org/standards/64.psabi.1.35.ps.Z">SPARC V9 ABI</a></li>
+<li><a class="reference external" href="http://sparc.org/standards/psABI3rd.pdf">SPARC V8 ABI</a></li>
+</ul>
+</div>
+<div class="section" id="systemz">
+<h3><a class="toc-backref" href="#id12">SystemZ</a><a class="headerlink" href="#systemz" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://www-01.ibm.com/support/docview.wss?uid=isg2b9de5f05a9d57819852571c500428f9a">z/Architecture Principles of Operation (registration required, free sign-up)</a></li>
+</ul>
+</div>
+<div class="section" id="x86">
+<h3><a class="toc-backref" href="#id13">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://developer.amd.com/resources/developer-guides-manuals/">AMD processor manuals</a></li>
+<li><a class="reference external" href="http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html">Intel 64 and IA-32 manuals</a></li>
+<li><a class="reference external" href="http://www.intel.com/design/itanium/documentation.htm?iid=ipp_srvr_proc_itanium2+techdocs">Intel Itanium documentation</a></li>
+<li><a class="reference external" href="https://github.com/hjl-tools/x86-psABI/wiki/X86-psABI">X86 and X86-64 SysV psABI</a></li>
+<li><a class="reference external" href="http://www.agner.org/optimize/calling_conventions.pdf">Calling conventions for different C++ compilers and operating systems</a></li>
+</ul>
+</div>
+<div class="section" id="xcore">
+<h3><a class="toc-backref" href="#id14">XCore</a><a class="headerlink" href="#xcore" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://www.xmos.com/en/download/public/The-XMOS-XS1-Architecture%28X7879A%29.pdf">The XMOS XS1 Architecture (ISA)</a></li>
+<li><a class="reference external" href="https://www.xmos.com/download/public/Tools-Development-Guide%28X9114A%29.pdf">Tools Development Guide (includes ABI)</a></li>
+</ul>
+</div>
+<div class="section" id="hexagon">
+<h3><a class="toc-backref" href="#id15">Hexagon</a><a class="headerlink" href="#hexagon" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://developer.qualcomm.com/software/hexagon-dsp-sdk/tools">Hexagon Programmer’s Reference Manuals and Hexagon ABI Specification (registration required, free sign-up)</a></li>
+</ul>
+</div>
+<div class="section" id="other-relevant-lists">
+<h3><a class="toc-backref" href="#id16">Other relevant lists</a><a class="headerlink" href="#other-relevant-lists" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://gcc.gnu.org/readings.html">GCC reading list</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="abi">
+<h2><a class="toc-backref" href="#id17">ABI</a><a class="headerlink" href="#abi" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="http://www.sco.com/developers/gabi/latest/contents.html">System V Application Binary Interface</a></li>
+<li><a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/">Itanium C++ ABI</a></li>
+</ul>
+<div class="section" id="linux">
+<h3><a class="toc-backref" href="#id18">Linux</a><a class="headerlink" href="#linux" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://github.com/hjl-tools/linux-abi/wiki/Linux-Extensions-to-gABI">Linux extensions to gabi</a></li>
+<li><a class="reference external" href="http://www.linuxbase.org/spec/ELF/ppc64/">PowerPC 64-bit ELF ABI Supplement</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055a/IHI0055A_aapcs64.pdf">Procedure Call Standard for the AArch64 Architecture</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0044e/IHI0044E_aaelf.pdf">ELF for the ARM Architecture</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0056a/IHI0056A_aaelf64.pdf">ELF for the ARM 64-bit Architecture (AArch64)</a></li>
+<li><a class="reference external" href="http://legacy.redhat.com/pub/redhat/linux/7.1/es/os/s390x/doc/lzsabi0.pdf">System z ELF ABI Supplement</a></li>
+</ul>
+</div>
+<div class="section" id="os-x">
+<h3><a class="toc-backref" href="#id19">OS X</a><a class="headerlink" href="#os-x" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html">Mach-O Runtime Architecture</a></li>
+<li><a class="reference external" href="http://www.unsanity.org/archives/000044.php">Notes on Mach-O ABI</a></li>
+</ul>
+</div>
+<div class="section" id="windows">
+<h3><a class="toc-backref" href="#id20">Windows</a><a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://www.microsoft.com/whdc/system/platform/firmware/pecoff.mspx">Microsoft PE/COFF Specification</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="nvptx">
+<h2><a class="toc-backref" href="#id21">NVPTX</a><a class="headerlink" href="#nvptx" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="http://docs.nvidia.com/cuda/index.html">CUDA Documentation</a> includes the PTX
+ISA and Driver API documentation</li>
+</ul>
+</div>
+<div class="section" id="miscellaneous-resources">
+<h2><a class="toc-backref" href="#id22">Miscellaneous Resources</a><a class="headerlink" href="#miscellaneous-resources" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="http://www.nondot.org/sabre/os/articles/ExecutableFileFormats/">Executable File Format library</a></li>
+<li><a class="reference external" href="http://gcc.gnu.org/projects/prefetch.html">GCC prefetch project</a> page has a
+good survey of the prefetching capabilities of a variety of modern
+processors.</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CommandLine.html" title="CommandLine 2.0 Library Manual"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/Contributing.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/Contributing.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/Contributing.html (added)
+++ www-releases/trunk/7.0.1/docs/Contributing.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,204 @@
+
+
+<!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>Contributing to LLVM — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="LLVM Developer Policy" href="DeveloperPolicy.html" />
+ <link rel="prev" title="Control Flow Verification Tool Design Document" href="CFIVerify.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="DeveloperPolicy.html" title="LLVM Developer Policy"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CFIVerify.html" title="Control Flow Verification Tool Design Document"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="contributing-to-llvm">
+<h1>Contributing to LLVM<a class="headerlink" href="#contributing-to-llvm" title="Permalink to this headline">¶</a></h1>
+<p>Thank you for your interest in contributing to LLVM! There are multiple ways to
+contribute, and we appreciate all contributions. In case you
+have questions, you can either use the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">Developer’s List (llvm-dev)</a>
+or the #llvm channel on <a class="reference external" href="irc://irc.oftc.net/llvm">irc.oftc.net</a>.</p>
+<p>If you want to contribute code, please familiarize yourself with the <a class="reference internal" href="DeveloperPolicy.html"><em>LLVM Developer Policy</em></a>.</p>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#ways-to-contribute" id="id3">Ways to Contribute</a><ul>
+<li><a class="reference internal" href="#bug-reports" id="id4">Bug Reports</a></li>
+<li><a class="reference internal" href="#bug-fixes" id="id5">Bug Fixes</a></li>
+<li><a class="reference internal" href="#bigger-pieces-of-work" id="id6">Bigger Pieces of Work</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#how-to-submit-a-patch" id="id7">How to Submit a Patch</a></li>
+<li><a class="reference internal" href="#helpful-information-about-llvm" id="id8">Helpful Information About LLVM</a></li>
+</ul>
+</div>
+<div class="section" id="ways-to-contribute">
+<h2><a class="toc-backref" href="#id3">Ways to Contribute</a><a class="headerlink" href="#ways-to-contribute" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="bug-reports">
+<h3><a class="toc-backref" href="#id4">Bug Reports</a><a class="headerlink" href="#bug-reports" title="Permalink to this headline">¶</a></h3>
+<p>If you are working with LLVM and run into a bug, we definitely want to know
+about it. Please let us know and follow the instructions in
+<a class="reference internal" href="HowToSubmitABug.html"><em>How to submit an LLVM bug report</em></a> to create a bug report.</p>
+</div>
+<div class="section" id="bug-fixes">
+<h3><a class="toc-backref" href="#id5">Bug Fixes</a><a class="headerlink" href="#bug-fixes" title="Permalink to this headline">¶</a></h3>
+<p>If you are interested in contributing code to LLVM, bugs labeled with the
+<a class="reference external" href="https://bugs.llvm.org/buglist.cgi?bug_status=NEW&bug_status=REOPENED&keywords=beginner%2C%20&keywords_type=allwords&list_id=130748&query_format=advanced&resolution=---">beginner keyword</a> in the <a class="reference external" href="https://bugs.llvm.org">bug tracker</a> are a good way to get familiar with
+the code base. If you are interested in fixing a bug, please create an account
+for the bug tracker and assign it to yourself, to let people know you are working on
+it.</p>
+<p>Then try to reproduce and fix the bug with upstream LLVM. Start by building
+LLVM from source as described in <a class="reference internal" href="GettingStarted.html"><em>Getting Started with the LLVM System</em></a> and
+and use the built binaries to reproduce the failure described in the bug. Use
+a debug build (<cite>-DCMAKE_BUILD_TYPE=Debug</cite>) or a build with assertions
+(<cite>-DLLVM_ENABLE_ASSERTIONS=On</cite>, enabled for Debug builds).</p>
+</div>
+<div class="section" id="bigger-pieces-of-work">
+<h3><a class="toc-backref" href="#id6">Bigger Pieces of Work</a><a class="headerlink" href="#bigger-pieces-of-work" title="Permalink to this headline">¶</a></h3>
+<p>In case you are interested in taking on a bigger piece of work, a list of
+interesting projects is maintained at the <a class="reference external" href="https://llvm.org/OpenProjects.html#what">LLVM’s Open Projects page</a>. In case
+you are interested in working on any of these projects, please send a mail to
+the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">LLVM Developer’s mailing list</a>, so that we know the project is being
+worked on.</p>
+</div>
+</div>
+<div class="section" id="how-to-submit-a-patch">
+<h2><a class="toc-backref" href="#id7">How to Submit a Patch</a><a class="headerlink" href="#how-to-submit-a-patch" title="Permalink to this headline">¶</a></h2>
+<p>Once you have a patch ready, it is time to submit it. The patch should:</p>
+<ul class="simple">
+<li>include a small unit test</li>
+<li>conform to the <a class="reference internal" href="CodingStandards.html"><em>LLVM Coding Standards</em></a>. You can use the <a class="reference external" href="https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/clang-format-diff.py">clang-format-diff.py</a> or <a class="reference external" href="https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/git-clang-format">git-clang-format</a> tools to automatically format your patch properly.</li>
+<li>not contain any unrelated changes</li>
+<li>be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier.</li>
+</ul>
+<p>To get a patch accepted, it has to be reviewed by the LLVM community. This can
+be done using <a class="reference external" href="https://reviews.llvm.org/">LLVM’s Phabricator</a> or the llvm-commits mailing list.
+Please follow <a class="reference internal" href="Phabricator.html#phabricator-request-review-web"><em>Phabricator#requesting-a-review-via-the-web-interface</em></a>
+to request a review using Phabricator.</p>
+<p>To make sure the right people see your patch, please select suitable reviewers
+and add them to your patch when requesting a review. Suitable reviewers are the
+code owner (see CODE_OWNERS.txt) and other people doing work in the area your
+patch touches. If you are using Phabricator, add them to the <cite>Reviewers</cite> field
+when creating a review and if you are using <cite>llvm-commits</cite>, add them to the CC of
+your email.</p>
+<p>A reviewer may request changes or ask questions during the review. If you are
+uncertain on how to provide test cases, documentation, etc., feel free to ask
+for guidance during the review. Please address the feedback and re-post an
+updated version of your patch. This cycle continues until all requests and comments
+have been addressed and a reviewer accepts the patch with a <cite>Looks good to me</cite> or <cite>LGTM</cite>.
+Once that is done the change can be committed. If you do not have commit
+access, please let people know during the review and someone should commit it
+on your behalf.</p>
+<p>If you have received no comments on your patch for a week, you can request a
+review by ‘ping’ing a patch by responding to the email thread containing the
+patch, or the Phabricator review with “Ping.” The common courtesy ‘ping’ rate
+is once a week. Please remember that you are asking for valuable time from other
+professional developers.</p>
+</div>
+<div class="section" id="helpful-information-about-llvm">
+<h2><a class="toc-backref" href="#id8">Helpful Information About LLVM</a><a class="headerlink" href="#helpful-information-about-llvm" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="index.html"><em>LLVM’s documentation</em></a> provides a wealth of information about LLVM’s internals as
+well as various user guides. The pages listed below should provide a good overview
+of LLVM’s high-level design, as well as its internals:</p>
+<dl class="docutils">
+<dt><a class="reference internal" href="GettingStarted.html"><em>Getting Started with the LLVM System</em></a></dt>
+<dd>Discusses how to get up and running quickly with the LLVM infrastructure.
+Everything from unpacking and compilation of the distribution to execution
+of some tools.</dd>
+<dt><a class="reference internal" href="LangRef.html"><em>LLVM Language Reference Manual</em></a></dt>
+<dd>Defines the LLVM intermediate representation.</dd>
+<dt><a class="reference internal" href="ProgrammersManual.html"><em>LLVM Programmer’s Manual</em></a></dt>
+<dd>Introduction to the general layout of the LLVM sourcebase, important classes
+and APIs, and some tips & tricks.</dd>
+<dt><a class="reference internal" href="index.html#index-subsystem-docs"><em>Subsystem Documentation</em></a></dt>
+<dd>A collection of pages documenting various subsystems of LLVM.</dd>
+<dt><a class="reference external" href="http://www.cs.cornell.edu/~asampson/blog/llvm.html">LLVM for Grad Students</a></dt>
+<dd>This is an introduction to the LLVM infrastructure by Adrian Sampson. While it
+has been written for grad students, it provides a good, compact overview of
+LLVM’s architecture, LLVM’s IR and how to write a new pass.</dd>
+<dt><a class="reference external" href="http://www.aosabook.org/en/llvm.html">Intro to LLVM</a></dt>
+<dd>Book chapter providing a compiler hacker’s introduction to LLVM.</dd>
+</dl>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="DeveloperPolicy.html" title="LLVM Developer Policy"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CFIVerify.html" title="Control Flow Verification Tool Design Document"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/Coroutines.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/Coroutines.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/Coroutines.html (added)
+++ www-releases/trunk/7.0.1/docs/Coroutines.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,1251 @@
+
+
+<!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>Coroutines in LLVM — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Global Instruction Selection" href="GlobalISel.html" />
+ <link rel="prev" title="Machine IR (MIR) Format Reference Manual" href="MIRLangRef.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="GlobalISel.html" title="Global Instruction Selection"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="coroutines-in-llvm">
+<h1>Coroutines in LLVM<a class="headerlink" href="#coroutines-in-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id48">Introduction</a></li>
+<li><a class="reference internal" href="#coroutines-by-example" id="id49">Coroutines by Example</a><ul>
+<li><a class="reference internal" href="#coroutine-representation" id="id50">Coroutine Representation</a></li>
+<li><a class="reference internal" href="#coroutine-transformation" id="id51">Coroutine Transformation</a></li>
+<li><a class="reference internal" href="#avoiding-heap-allocations" id="id52">Avoiding Heap Allocations</a></li>
+<li><a class="reference internal" href="#multiple-suspend-points" id="id53">Multiple Suspend Points</a></li>
+<li><a class="reference internal" href="#distinct-save-and-suspend" id="id54">Distinct Save and Suspend</a></li>
+<li><a class="reference internal" href="#coroutine-promise" id="id55">Coroutine Promise</a></li>
+<li><a class="reference internal" href="#final-suspend" id="id56">Final Suspend</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#intrinsics" id="id57">Intrinsics</a><ul>
+<li><a class="reference internal" href="#coroutine-manipulation-intrinsics" id="id58">Coroutine Manipulation Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-coro-destroy-intrinsic" id="id59">‘llvm.coro.destroy’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-resume-intrinsic" id="id60">‘llvm.coro.resume’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-done-intrinsic" id="id61">‘llvm.coro.done’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-promise-intrinsic" id="id62">‘llvm.coro.promise’ Intrinsic</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#coroutine-structure-intrinsics" id="id63">Coroutine Structure Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-coro-size-intrinsic" id="id64">‘llvm.coro.size’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-begin-intrinsic" id="id65">‘llvm.coro.begin’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-free-intrinsic" id="id66">‘llvm.coro.free’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-alloc-intrinsic" id="id67">‘llvm.coro.alloc’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-noop-intrinsic" id="id68">‘llvm.coro.noop’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-frame-intrinsic" id="id69">‘llvm.coro.frame’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-id-intrinsic" id="id70">‘llvm.coro.id’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-end-intrinsic" id="id71">‘llvm.coro.end’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-suspend-intrinsic" id="id72">‘llvm.coro.suspend’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-save-intrinsic" id="id73">‘llvm.coro.save’ Intrinsic</a></li>
+<li><a class="reference internal" href="#llvm-coro-param-intrinsic" id="id74">‘llvm.coro.param’ Intrinsic</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#coroutine-transformation-passes" id="id75">Coroutine Transformation Passes</a><ul>
+<li><a class="reference internal" href="#coroearly" id="id76">CoroEarly</a></li>
+<li><a class="reference internal" href="#corosplit" id="id77">CoroSplit</a></li>
+<li><a class="reference internal" href="#coroelide" id="id78">CoroElide</a></li>
+<li><a class="reference internal" href="#corocleanup" id="id79">CoroCleanup</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#areas-requiring-attention" id="id80">Areas Requiring Attention</a></li>
+</ul>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">This is a work in progress. Compatibility across LLVM releases is not
+guaranteed.</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id48">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p id="coroutine-handle">LLVM coroutines are functions that have one or more <a class="reference internal" href="#suspend-points">suspend points</a>.
+When a suspend point is reached, the execution of a coroutine is suspended and
+control is returned back to its caller. A suspended coroutine can be resumed
+to continue execution from the last suspend point or it can be destroyed.</p>
+<p>In the following example, we call function <cite>f</cite> (which may or may not be a
+coroutine itself) that returns a handle to a suspended coroutine
+(<strong>coroutine handle</strong>) that is used by <cite>main</cite> to resume the coroutine twice and
+then destroy it:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@f</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.destroy</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p id="coroutine-frame">In addition to the function stack frame which exists when a coroutine is
+executing, there is an additional region of storage that contains objects that
+keep the coroutine state when a coroutine is suspended. This region of storage
+is called <strong>coroutine frame</strong>. It is created when a coroutine is called and
+destroyed when a coroutine runs to completion or destroyed by a call to
+the <a class="reference internal" href="#coro-destroy">coro.destroy</a> intrinsic.</p>
+<p>An LLVM coroutine is represented as an LLVM function that has calls to
+<a class="reference internal" href="#coroutine-intrinsics">coroutine intrinsics</a> defining the structure of the coroutine.
+After lowering, a coroutine is split into several
+functions that represent three different ways of how control can enter the
+coroutine:</p>
+<ol class="arabic simple">
+<li>a ramp function, which represents an initial invocation of the coroutine that
+creates the coroutine frame and executes the coroutine code until it
+encounters a suspend point or reaches the end of the function;</li>
+<li>a coroutine resume function that is invoked when the coroutine is resumed;</li>
+<li>a coroutine destroy function that is invoked when the coroutine is destroyed.</li>
+</ol>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Splitting out resume and destroy functions are just one of the
+possible ways of lowering the coroutine. We chose it for initial
+implementation as it matches closely the mental model and results in
+reasonably nice code.</p>
+</div>
+</div>
+<div class="section" id="coroutines-by-example">
+<h2><a class="toc-backref" href="#id49">Coroutines by Example</a><a class="headerlink" href="#coroutines-by-example" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="coroutine-representation">
+<h3><a class="toc-backref" href="#id50">Coroutine Representation</a><a class="headerlink" href="#coroutine-representation" title="Permalink to this headline">¶</a></h3>
+<p>Let’s look at an example of an LLVM coroutine with the behavior sketched
+by the following pseudo-code.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="o">*</span><span class="n">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span><span class="p">(;;)</span> <span class="p">{</span>
+ <span class="n">print</span><span class="p">(</span><span class="n">n</span><span class="o">++</span><span class="p">);</span>
+ <span class="o"><</span><span class="n">suspend</span><span class="o">></span> <span class="c1">// returns a coroutine handle on first suspend</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This coroutine calls some function <cite>print</cite> with value <cite>n</cite> as an argument and
+suspends execution. Every time this coroutine resumes, it calls <cite>print</cite> again with an argument one bigger than the last time. This coroutine never completes by itself and must be destroyed explicitly. If we use this coroutine with
+a <cite>main</cite> shown in the previous section. It will call <cite>print</cite> with values 4, 5
+and 6 after which the coroutine will be destroyed.</p>
+<p>The LLVM IR for this coroutine looks like this:</p>
+<div class="highlight-llvm"><pre>define i8* @f(i32 %n) {
+entry:
+ %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+ %size = call i32 @llvm.coro.size.i32()
+ %alloc = call i8* @malloc(i32 %size)
+ %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %alloc)
+ br label %loop
+loop:
+ %n.val = phi i32 [ %n, %entry ], [ %inc, %loop ]
+ %inc = add nsw i32 %n.val, 1
+ call void @print(i32 %n.val)
+ %0 = call i8 @llvm.coro.suspend(token none, i1 false)
+ switch i8 %0, label %suspend [i8 0, label %loop
+ i8 1, label %cleanup]
+cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %hdl)
+ call void @free(i8* %mem)
+ br label %suspend
+suspend:
+ %unused = call i1 @llvm.coro.end(i8* %hdl, i1 false)
+ ret i8* %hdl
+}</pre>
+</div>
+<p>The <cite>entry</cite> block establishes the coroutine frame. The <a class="reference internal" href="#coro-size">coro.size</a> intrinsic is
+lowered to a constant representing the size required for the coroutine frame.
+The <a class="reference internal" href="#coro-begin">coro.begin</a> intrinsic initializes the coroutine frame and returns the
+coroutine handle. The second parameter of <cite>coro.begin</cite> is given a block of memory
+to be used if the coroutine frame needs to be allocated dynamically.
+The <a class="reference internal" href="#coro-id">coro.id</a> intrinsic serves as coroutine identity useful in cases when the
+<a class="reference internal" href="#coro-begin">coro.begin</a> intrinsic get duplicated by optimization passes such as
+jump-threading.</p>
+<p>The <cite>cleanup</cite> block destroys the coroutine frame. The <a class="reference internal" href="#coro-free">coro.free</a> intrinsic,
+given the coroutine handle, returns a pointer of the memory block to be freed or
+<cite>null</cite> if the coroutine frame was not allocated dynamically. The <cite>cleanup</cite>
+block is entered when coroutine runs to completion by itself or destroyed via
+call to the <a class="reference internal" href="#coro-destroy">coro.destroy</a> intrinsic.</p>
+<p>The <cite>suspend</cite> block contains code to be executed when coroutine runs to
+completion or suspended. The <a class="reference internal" href="#coro-end">coro.end</a> intrinsic marks the point where
+a coroutine needs to return control back to the caller if it is not an initial
+invocation of the coroutine.</p>
+<p>The <cite>loop</cite> blocks represents the body of the coroutine. The <a class="reference internal" href="#coro-suspend">coro.suspend</a>
+intrinsic in combination with the following switch indicates what happens to
+control flow when a coroutine is suspended (default case), resumed (case 0) or
+destroyed (case 1).</p>
+</div>
+<div class="section" id="coroutine-transformation">
+<h3><a class="toc-backref" href="#id51">Coroutine Transformation</a><a class="headerlink" href="#coroutine-transformation" title="Permalink to this headline">¶</a></h3>
+<p>One of the steps of coroutine lowering is building the coroutine frame. The
+def-use chains are analyzed to determine which objects need be kept alive across
+suspend points. In the coroutine shown in the previous section, use of virtual register
+<cite>%n.val</cite> is separated from the definition by a suspend point, therefore, it
+cannot reside on the stack frame since the latter goes away once the coroutine
+is suspended and control is returned back to the caller. An i32 slot is
+allocated in the coroutine frame and <cite>%n.val</cite> is spilled and reloaded from that
+slot as needed.</p>
+<p>We also store addresses of the resume and destroy functions so that the
+<cite>coro.resume</cite> and <cite>coro.destroy</cite> intrinsics can resume and destroy the coroutine
+when its identity cannot be determined statically at compile time. For our
+example, the coroutine frame will be:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%f.frame</span> <span class="p">=</span> <span class="k">type</span> <span class="p">{</span> <span class="kt">void</span> <span class="p">(</span><span class="nv">%f.frame</span><span class="p">*)*,</span> <span class="kt">void</span> <span class="p">(</span><span class="nv">%f.frame</span><span class="p">*)*,</span> <span class="k">i32</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>After resume and destroy parts are outlined, function <cite>f</cite> will contain only the
+code responsible for creation and initialization of the coroutine frame and
+execution of the coroutine until a suspend point is reached:</p>
+<div class="highlight-llvm"><pre>define i8* @f(i32 %n) {
+entry:
+ %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+ %alloc = call noalias i8* @malloc(i32 24)
+ %0 = call noalias i8* @llvm.coro.begin(token %id, i8* %alloc)
+ %frame = bitcast i8* %0 to %f.frame*
+ %1 = getelementptr %f.frame, %f.frame* %frame, i32 0, i32 0
+ store void (%f.frame*)* @f.resume, void (%f.frame*)** %1
+ %2 = getelementptr %f.frame, %f.frame* %frame, i32 0, i32 1
+ store void (%f.frame*)* @f.destroy, void (%f.frame*)** %2
+
+ %inc = add nsw i32 %n, 1
+ %inc.spill.addr = getelementptr inbounds %f.Frame, %f.Frame* %FramePtr, i32 0, i32 2
+ store i32 %inc, i32* %inc.spill.addr
+ call void @print(i32 %n)
+
+ ret i8* %frame
+}</pre>
+</div>
+<p>Outlined resume part of the coroutine will reside in function <cite>f.resume</cite>:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">internal</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@f.resume</span><span class="p">(</span><span class="nv">%f.frame</span><span class="p">*</span> <span class="nv">%frame.ptr.resume</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%inc.spill.addr</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%f.frame</span><span class="p">,</span> <span class="nv">%f.frame</span><span class="p">*</span> <span class="nv">%frame.ptr.resume</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span>
+ <span class="nv">%inc.spill</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">%inc.spill.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="nv">%inc</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%n.val</span><span class="p">,</span> <span class="m">1</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%inc</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%inc.spill.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%inc</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Whereas function <cite>f.destroy</cite> will contain the cleanup code for the coroutine:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">internal</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@f.destroy</span><span class="p">(</span><span class="nv">%f.frame</span><span class="p">*</span> <span class="nv">%frame.ptr.destroy</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%f.frame</span><span class="p">*</span> <span class="nv">%frame.ptr.destroy</span> <span class="k">to</span> <span class="k">i8</span><span class="p">*</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@free</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv-Anonymous">%0</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="avoiding-heap-allocations">
+<h3><a class="toc-backref" href="#id52">Avoiding Heap Allocations</a><a class="headerlink" href="#avoiding-heap-allocations" title="Permalink to this headline">¶</a></h3>
+<p>A particular coroutine usage pattern, which is illustrated by the <cite>main</cite>
+function in the overview section, where a coroutine is created, manipulated and
+destroyed by the same calling function, is common for coroutines implementing
+RAII idiom and is suitable for allocation elision optimization which avoid
+dynamic allocation by storing the coroutine frame as a static <cite>alloca</cite> in its
+caller.</p>
+<p>In the entry block, we will call <a class="reference internal" href="#coro-alloc">coro.alloc</a> intrinsic that will return <cite>true</cite>
+when dynamic allocation is required, and <cite>false</cite> if dynamic allocation is
+elided.</p>
+<div class="highlight-llvm"><pre>entry:
+ %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+ %need.dyn.alloc = call i1 @llvm.coro.alloc(token %id)
+ br i1 %need.dyn.alloc, label %dyn.alloc, label %coro.begin
+dyn.alloc:
+ %size = call i32 @llvm.coro.size.i32()
+ %alloc = call i8* @CustomAlloc(i32 %size)
+ br label %coro.begin
+coro.begin:
+ %phi = phi i8* [ null, %entry ], [ %alloc, %dyn.alloc ]
+ %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %phi)</pre>
+</div>
+<p>In the cleanup block, we will make freeing the coroutine frame conditional on
+<a class="reference internal" href="#coro-free">coro.free</a> intrinsic. If allocation is elided, <a class="reference internal" href="#coro-free">coro.free</a> returns <cite>null</cite>
+thus skipping the deallocation code:</p>
+<div class="highlight-llvm"><pre>cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %hdl)
+ %need.dyn.free = icmp ne i8* %mem, null
+ br i1 %need.dyn.free, label %dyn.free, label %if.end
+dyn.free:
+ call void @CustomFree(i8* %mem)
+ br label %if.end
+if.end:
+ ...</pre>
+</div>
+<p>With allocations and deallocations represented as described as above, after
+coroutine heap allocation elision optimization, the resulting main will be:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">5</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">6</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="multiple-suspend-points">
+<h3><a class="toc-backref" href="#id53">Multiple Suspend Points</a><a class="headerlink" href="#multiple-suspend-points" title="Permalink to this headline">¶</a></h3>
+<p>Let’s consider the coroutine that has more than one suspend point:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">void</span> <span class="o">*</span><span class="n">f</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">for</span><span class="p">(;;)</span> <span class="p">{</span>
+ <span class="n">print</span><span class="p">(</span><span class="n">n</span><span class="o">++</span><span class="p">);</span>
+ <span class="o"><</span><span class="n">suspend</span><span class="o">></span>
+ <span class="n">print</span><span class="p">(</span><span class="o">-</span><span class="n">n</span><span class="p">);</span>
+ <span class="o"><</span><span class="n">suspend</span><span class="o">></span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Matching LLVM code would look like (with the rest of the code remaining the same
+as the code in the previous section):</p>
+<div class="highlight-llvm"><pre>loop:
+ %n.addr = phi i32 [ %n, %entry ], [ %inc, %loop.resume ]
+ call void @print(i32 %n.addr) #4
+ %2 = call i8 @llvm.coro.suspend(token none, i1 false)
+ switch i8 %2, label %suspend [i8 0, label %loop.resume
+ i8 1, label %cleanup]
+loop.resume:
+ %inc = add nsw i32 %n.addr, 1
+ %sub = xor i32 %n.addr, -1
+ call void @print(i32 %sub)
+ %3 = call i8 @llvm.coro.suspend(token none, i1 false)
+ switch i8 %3, label %suspend [i8 0, label %loop
+ i8 1, label %cleanup]</pre>
+</div>
+<p>In this case, the coroutine frame would include a suspend index that will
+indicate at which suspend point the coroutine needs to resume. The resume
+function will use an index to jump to an appropriate basic block and will look
+as follows:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">internal</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@f.Resume</span><span class="p">(</span><span class="nv">%f.Frame</span><span class="p">*</span> <span class="nv">%FramePtr</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry.Resume:</span>
+ <span class="nv">%index.addr</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="k">inbounds</span> <span class="nv">%f.Frame</span><span class="p">,</span> <span class="nv">%f.Frame</span><span class="p">*</span> <span class="nv">%FramePtr</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</span>
+ <span class="nv">%index</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">%index.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">1</span>
+ <span class="nv">%switch</span> <span class="p">=</span> <span class="k">icmp</span> <span class="k">eq</span> <span class="k">i8</span> <span class="nv">%index</span><span class="p">,</span> <span class="m">0</span>
+ <span class="nv">%n.addr</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="k">inbounds</span> <span class="nv">%f.Frame</span><span class="p">,</span> <span class="nv">%f.Frame</span><span class="p">*</span> <span class="nv">%FramePtr</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">3</span>
+ <span class="nv">%n</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">%n.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%switch</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%loop.resume</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%loop</span>
+
+<span class="nl">loop.resume:</span>
+ <span class="nv">%sub</span> <span class="p">=</span> <span class="k">xor</span> <span class="k">i32</span> <span class="nv">%n</span><span class="p">,</span> <span class="m">-1</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%sub</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%suspend</span>
+<span class="nl">loop:</span>
+ <span class="nv">%inc</span> <span class="p">=</span> <span class="k">add</span> <span class="k">nsw</span> <span class="k">i32</span> <span class="nv">%n</span><span class="p">,</span> <span class="m">1</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%inc</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%n.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%inc</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%suspend</span>
+
+<span class="nl">suspend:</span>
+ <span class="nv">%storemerge</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">%loop</span> <span class="p">],</span> <span class="p">[</span> <span class="m">1</span><span class="p">,</span> <span class="nv">%loop.resume</span> <span class="p">]</span>
+ <span class="k">store</span> <span class="k">i8</span> <span class="nv">%storemerge</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%index.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">1</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If different cleanup code needs to get executed for different suspend points,
+a similar switch will be in the <cite>f.destroy</cite> function.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Using suspend index in a coroutine state and having a switch in <cite>f.resume</cite> and
+<cite>f.destroy</cite> is one of the possible implementation strategies. We explored
+another option where a distinct <cite>f.resume1</cite>, <cite>f.resume2</cite>, etc. are created for
+every suspend point, and instead of storing an index, the resume and destroy
+function pointers are updated at every suspend. Early testing showed that the
+current approach is easier on the optimizer than the latter so it is a
+lowering strategy implemented at the moment.</p>
+</div>
+</div>
+<div class="section" id="distinct-save-and-suspend">
+<h3><a class="toc-backref" href="#id54">Distinct Save and Suspend</a><a class="headerlink" href="#distinct-save-and-suspend" title="Permalink to this headline">¶</a></h3>
+<p>In the previous example, setting a resume index (or some other state change that
+needs to happen to prepare a coroutine for resumption) happens at the same time as
+a suspension of a coroutine. However, in certain cases, it is necessary to control
+when coroutine is prepared for resumption and when it is suspended.</p>
+<p>In the following example, a coroutine represents some activity that is driven
+by completions of asynchronous operations <cite>async_op1</cite> and <cite>async_op2</cite> which get
+a coroutine handle as a parameter and resume the coroutine once async
+operation is finished.</p>
+<div class="highlight-text"><div class="highlight"><pre>void g() {
+ for (;;)
+ if (cond()) {
+ async_op1(<coroutine-handle>); // will resume once async_op1 completes
+ <suspend>
+ do_one();
+ }
+ else {
+ async_op2(<coroutine-handle>); // will resume once async_op2 completes
+ <suspend>
+ do_two();
+ }
+ }
+}
+</pre></div>
+</div>
+<p>In this case, coroutine should be ready for resumption prior to a call to
+<cite>async_op1</cite> and <cite>async_op2</cite>. The <a class="reference internal" href="#coro-save">coro.save</a> intrinsic is used to indicate a
+point when coroutine should be ready for resumption (namely, when a resume index
+should be stored in the coroutine frame, so that it can be resumed at the
+correct resume point):</p>
+<div class="highlight-llvm"><pre>if.true:
+ %save1 = call token @llvm.coro.save(i8* %hdl)
+ call void @async_op1(i8* %hdl)
+ %suspend1 = call i1 @llvm.coro.suspend(token %save1, i1 false)
+ switch i8 %suspend1, label %suspend [i8 0, label %resume1
+ i8 1, label %cleanup]
+if.false:
+ %save2 = call token @llvm.coro.save(i8* %hdl)
+ call void @async_op2(i8* %hdl)
+ %suspend2 = call i1 @llvm.coro.suspend(token %save2, i1 false)
+ switch i8 %suspend1, label %suspend [i8 0, label %resume2
+ i8 1, label %cleanup]</pre>
+</div>
+</div>
+<div class="section" id="coroutine-promise">
+<span id="id1"></span><h3><a class="toc-backref" href="#id55">Coroutine Promise</a><a class="headerlink" href="#coroutine-promise" title="Permalink to this headline">¶</a></h3>
+<p>A coroutine author or a frontend may designate a distinguished <cite>alloca</cite> that can
+be used to communicate with the coroutine. This distinguished alloca is called
+<strong>coroutine promise</strong> and is provided as the second parameter to the
+<a class="reference internal" href="#coro-id">coro.id</a> intrinsic.</p>
+<p>The following coroutine designates a 32 bit integer <cite>promise</cite> and uses it to
+store the current value produced by a coroutine.</p>
+<div class="highlight-llvm"><pre>define i8* @f(i32 %n) {
+entry:
+ %promise = alloca i32
+ %pv = bitcast i32* %promise to i8*
+ %id = call token @llvm.coro.id(i32 0, i8* %pv, i8* null, i8* null)
+ %need.dyn.alloc = call i1 @llvm.coro.alloc(token %id)
+ br i1 %need.dyn.alloc, label %dyn.alloc, label %coro.begin
+dyn.alloc:
+ %size = call i32 @llvm.coro.size.i32()
+ %alloc = call i8* @malloc(i32 %size)
+ br label %coro.begin
+coro.begin:
+ %phi = phi i8* [ null, %entry ], [ %alloc, %dyn.alloc ]
+ %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %phi)
+ br label %loop
+loop:
+ %n.val = phi i32 [ %n, %coro.begin ], [ %inc, %loop ]
+ %inc = add nsw i32 %n.val, 1
+ store i32 %n.val, i32* %promise
+ %0 = call i8 @llvm.coro.suspend(token none, i1 false)
+ switch i8 %0, label %suspend [i8 0, label %loop
+ i8 1, label %cleanup]
+cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %hdl)
+ call void @free(i8* %mem)
+ br label %suspend
+suspend:
+ %unused = call i1 @llvm.coro.end(i8* %hdl, i1 false)
+ ret i8* %hdl
+}</pre>
+</div>
+<p>A coroutine consumer can rely on the <a class="reference internal" href="#coro-promise">coro.promise</a> intrinsic to access the
+coroutine promise.</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@f</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="nv">%promise.addr.raw</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.promise</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">,</span> <span class="k">i32</span> <span class="m">4</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="nv">%promise.addr</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%promise.addr.raw</span> <span class="k">to</span> <span class="k">i32</span><span class="p">*</span>
+ <span class="nv">%val0</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">%promise.addr</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%val0</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="nv">%val1</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">%promise.addr</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%val1</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="nv">%val2</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">%promise.addr</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%val2</span><span class="p">)</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.destroy</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>After example in this section is compiled, result of the compilation will be:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">5</span><span class="p">)</span>
+ <span class="k">tail</span> <span class="k">call</span> <span class="kt">void</span> <span class="vg">@print</span><span class="p">(</span><span class="k">i32</span> <span class="m">6</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="final-suspend">
+<span id="final"></span><span id="id2"></span><h3><a class="toc-backref" href="#id56">Final Suspend</a><a class="headerlink" href="#final-suspend" title="Permalink to this headline">¶</a></h3>
+<p>A coroutine author or a frontend may designate a particular suspend to be final,
+by setting the second argument of the <a class="reference internal" href="#coro-suspend">coro.suspend</a> intrinsic to <cite>true</cite>.
+Such a suspend point has two properties:</p>
+<ul class="simple">
+<li>it is possible to check whether a suspended coroutine is at the final suspend
+point via <a class="reference internal" href="#coro-done">coro.done</a> intrinsic;</li>
+<li>a resumption of a coroutine stopped at the final suspend point leads to
+undefined behavior. The only possible action for a coroutine at a final
+suspend point is destroying it via <a class="reference internal" href="#coro-destroy">coro.destroy</a> intrinsic.</li>
+</ul>
+<p>From the user perspective, the final suspend point represents an idea of a
+coroutine reaching the end. From the compiler perspective, it is an optimization
+opportunity for reducing number of resume points (and therefore switch cases) in
+the resume function.</p>
+<p>The following is an example of a function that keeps resuming the coroutine
+until the final suspend point is reached after which point the coroutine is
+destroyed:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">i32</span> <span class="vg">@main</span><span class="p">()</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@f</span><span class="p">(</span><span class="k">i32</span> <span class="m">4</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%while</span>
+<span class="nl">while:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.resume</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="nv">%done</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.done</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%done</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%end</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%while</span>
+<span class="nl">end:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.coro.destroy</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i32</span> <span class="m">0</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Usually, final suspend point is a frontend injected suspend point that does not
+correspond to any explicitly authored suspend point of the high level language.
+For example, for a Python generator that has only one suspend point:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="k">def</span> <span class="nf">coroutine</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
+ <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
+ <span class="k">yield</span> <span class="n">i</span>
+</pre></div>
+</div>
+<p>Python frontend would inject two more suspend points, so that the actual code
+looks like this:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span><span class="o">*</span> <span class="nf">coroutine</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">current_value</span><span class="p">;</span>
+ <span class="o"><</span><span class="n">designate</span> <span class="n">current_value</span> <span class="n">to</span> <span class="n">be</span> <span class="n">coroutine</span> <span class="n">promise</span><span class="o">></span>
+ <span class="o"><</span><span class="n">SUSPEND</span><span class="o">></span> <span class="c1">// injected suspend point, so that the coroutine starts suspended</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">int</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o"><</span> <span class="n">n</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">current_value</span> <span class="o">=</span> <span class="n">i</span><span class="p">;</span> <span class="o"><</span><span class="n">SUSPEND</span><span class="o">></span><span class="p">;</span> <span class="c1">// corresponds to "yield i"</span>
+ <span class="p">}</span>
+ <span class="o"><</span><span class="n">SUSPEND</span> <span class="n">final</span><span class="o">=</span><span class="nb">true</span><span class="o">></span> <span class="c1">// injected final suspend point</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>and python iterator <cite>__next__</cite> would look like:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="kt">int</span> <span class="n">__next__</span><span class="p">(</span><span class="kt">void</span><span class="o">*</span> <span class="n">hdl</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">coro</span><span class="p">.</span><span class="n">resume</span><span class="p">(</span><span class="n">hdl</span><span class="p">);</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">coro</span><span class="p">.</span><span class="n">done</span><span class="p">(</span><span class="n">hdl</span><span class="p">))</span> <span class="k">throw</span> <span class="n">StopIteration</span><span class="p">();</span>
+ <span class="k">return</span> <span class="o">*</span><span class="p">(</span><span class="kt">int</span><span class="o">*</span><span class="p">)</span><span class="n">coro</span><span class="p">.</span><span class="n">promise</span><span class="p">(</span><span class="n">hdl</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="kc">false</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="intrinsics">
+<h2><a class="toc-backref" href="#id57">Intrinsics</a><a class="headerlink" href="#intrinsics" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="coroutine-manipulation-intrinsics">
+<h3><a class="toc-backref" href="#id58">Coroutine Manipulation Intrinsics</a><a class="headerlink" href="#coroutine-manipulation-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>Intrinsics described in this section are used to manipulate an existing
+coroutine. They can be used in any function which happen to have a pointer
+to a <a class="reference internal" href="#coroutine-frame">coroutine frame</a> or a pointer to a <a class="reference internal" href="#coroutine-promise">coroutine promise</a>.</p>
+<div class="section" id="llvm-coro-destroy-intrinsic">
+<span id="coro-destroy"></span><h4><a class="toc-backref" href="#id59">‘llvm.coro.destroy’ Intrinsic</a><a class="headerlink" href="#llvm-coro-destroy-intrinsic" 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>
+<div class="highlight-python"><pre>declare void @llvm.coro.destroy(i8* <handle>)</pre>
+</div>
+</div>
+<div class="section" id="overview">
+<h5>Overview:<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.destroy</span></tt>‘ intrinsic destroys a suspended
+coroutine.</p>
+</div>
+<div class="section" id="arguments">
+<h5>Arguments:<a class="headerlink" href="#arguments" title="Permalink to this headline">¶</a></h5>
+<p>The argument is a coroutine handle to a suspended coroutine.</p>
+</div>
+<div class="section" id="semantics">
+<h5>Semantics:<a class="headerlink" href="#semantics" title="Permalink to this headline">¶</a></h5>
+<p>When possible, the <cite>coro.destroy</cite> intrinsic is replaced with a direct call to
+the coroutine destroy function. Otherwise it is replaced with an indirect call
+based on the function pointer for the destroy function stored in the coroutine
+frame. Destroying a coroutine that is not suspended leads to undefined behavior.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-resume-intrinsic">
+<span id="coro-resume"></span><h4><a class="toc-backref" href="#id60">‘llvm.coro.resume’ Intrinsic</a><a class="headerlink" href="#llvm-coro-resume-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare void @llvm.coro.resume(i8* <handle>)</pre>
+</div>
+<div class="section" id="id3">
+<h5>Overview:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.resume</span></tt>‘ intrinsic resumes a suspended coroutine.</p>
+</div>
+<div class="section" id="id4">
+<h5>Arguments:<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h5>
+<p>The argument is a handle to a suspended coroutine.</p>
+</div>
+<div class="section" id="id5">
+<h5>Semantics:<a class="headerlink" href="#id5" title="Permalink to this headline">¶</a></h5>
+<p>When possible, the <cite>coro.resume</cite> intrinsic is replaced with a direct call to the
+coroutine resume function. Otherwise it is replaced with an indirect call based
+on the function pointer for the resume function stored in the coroutine frame.
+Resuming a coroutine that is not suspended leads to undefined behavior.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-done-intrinsic">
+<span id="coro-done"></span><h4><a class="toc-backref" href="#id61">‘llvm.coro.done’ Intrinsic</a><a class="headerlink" href="#llvm-coro-done-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i1 @llvm.coro.done(i8* <handle>)</pre>
+</div>
+<div class="section" id="id6">
+<h5>Overview:<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.done</span></tt>‘ intrinsic checks whether a suspended coroutine is at
+the final suspend point or not.</p>
+</div>
+<div class="section" id="id7">
+<h5>Arguments:<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h5>
+<p>The argument is a handle to a suspended coroutine.</p>
+</div>
+<div class="section" id="id8">
+<h5>Semantics:<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h5>
+<p>Using this intrinsic on a coroutine that does not have a <a class="reference internal" href="#final-suspend">final suspend</a> point
+or on a coroutine that is not suspended leads to undefined behavior.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-promise-intrinsic">
+<span id="coro-promise"></span><h4><a class="toc-backref" href="#id62">‘llvm.coro.promise’ Intrinsic</a><a class="headerlink" href="#llvm-coro-promise-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8* @llvm.coro.promise(i8* <ptr>, i32 <alignment>, i1 <from>)</pre>
+</div>
+<div class="section" id="id9">
+<h5>Overview:<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.promise</span></tt>‘ intrinsic obtains a pointer to a
+<a class="reference internal" href="#coroutine-promise">coroutine promise</a> given a coroutine handle and vice versa.</p>
+</div>
+<div class="section" id="id10">
+<h5>Arguments:<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h5>
+<p>The first argument is a handle to a coroutine if <cite>from</cite> is false. Otherwise,
+it is a pointer to a coroutine promise.</p>
+<p>The second argument is an alignment requirements of the promise.
+If a frontend designated <cite>%promise = alloca i32</cite> as a promise, the alignment
+argument to <cite>coro.promise</cite> should be the alignment of <cite>i32</cite> on the target
+platform. If a frontend designated <cite>%promise = alloca i32, align 16</cite> as a
+promise, the alignment argument should be 16.
+This argument only accepts constants.</p>
+<p>The third argument is a boolean indicating a direction of the transformation.
+If <cite>from</cite> is true, the intrinsic returns a coroutine handle given a pointer
+to a promise. If <cite>from</cite> is false, the intrinsics return a pointer to a promise
+from a coroutine handle. This argument only accepts constants.</p>
+</div>
+<div class="section" id="id11">
+<h5>Semantics:<a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h5>
+<p>Using this intrinsic on a coroutine that does not have a coroutine promise
+leads to undefined behavior. It is possible to read and modify coroutine
+promise of the coroutine which is currently executing. The coroutine author and
+a coroutine user are responsible to makes sure there is no data races.</p>
+</div>
+<div class="section" id="example">
+<h5>Example:<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>define i8* @f(i32 %n) {
+entry:
+ %promise = alloca i32
+ %pv = bitcast i32* %promise to i8*
+ ; the second argument to coro.id points to the coroutine promise.
+ %id = call token @llvm.coro.id(i32 0, i8* %pv, i8* null, i8* null)
+ ...
+ %hdl = call noalias i8* @llvm.coro.begin(token %id, i8* %alloc)
+ ...
+ store i32 42, i32* %promise ; store something into the promise
+ ...
+ ret i8* %hdl
+}
+
+define i32 @main() {
+entry:
+ %hdl = call i8* @f(i32 4) ; starts the coroutine and returns its handle
+ %promise.addr.raw = call i8* @llvm.coro.promise(i8* %hdl, i32 4, i1 false)
+ %promise.addr = bitcast i8* %promise.addr.raw to i32*
+ %val = load i32, i32* %promise.addr ; load a value from the promise
+ call void @print(i32 %val)
+ call void @llvm.coro.destroy(i8* %hdl)
+ ret i32 0
+}</pre>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="coroutine-structure-intrinsics">
+<span id="coroutine-intrinsics"></span><h3><a class="toc-backref" href="#id63">Coroutine Structure Intrinsics</a><a class="headerlink" href="#coroutine-structure-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>Intrinsics described in this section are used within a coroutine to describe
+the coroutine structure. They should not be used outside of a coroutine.</p>
+<div class="section" id="llvm-coro-size-intrinsic">
+<span id="coro-size"></span><h4><a class="toc-backref" href="#id64">‘llvm.coro.size’ Intrinsic</a><a class="headerlink" href="#llvm-coro-size-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i32 @llvm.coro.size.i32()
+declare i64 @llvm.coro.size.i64()</pre>
+</div>
+<div class="section" id="id12">
+<h5>Overview:<a class="headerlink" href="#id12" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.size</span></tt>‘ intrinsic returns the number of bytes
+required to store a <a class="reference internal" href="#coroutine-frame">coroutine frame</a>.</p>
+</div>
+<div class="section" id="id13">
+<h5>Arguments:<a class="headerlink" href="#id13" title="Permalink to this headline">¶</a></h5>
+<p>None</p>
+</div>
+<div class="section" id="id14">
+<h5>Semantics:<a class="headerlink" href="#id14" title="Permalink to this headline">¶</a></h5>
+<p>The <cite>coro.size</cite> intrinsic is lowered to a constant representing the size of
+the coroutine frame.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-begin-intrinsic">
+<span id="coro-begin"></span><h4><a class="toc-backref" href="#id65">‘llvm.coro.begin’ Intrinsic</a><a class="headerlink" href="#llvm-coro-begin-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8* @llvm.coro.begin(token <id>, i8* <mem>)</pre>
+</div>
+<div class="section" id="id15">
+<h5>Overview:<a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.begin</span></tt>‘ intrinsic returns an address of the coroutine frame.</p>
+</div>
+<div class="section" id="id16">
+<h5>Arguments:<a class="headerlink" href="#id16" title="Permalink to this headline">¶</a></h5>
+<p>The first argument is a token returned by a call to ‘<tt class="docutils literal"><span class="pre">llvm.coro.id</span></tt>‘
+identifying the coroutine.</p>
+<p>The second argument is a pointer to a block of memory where coroutine frame
+will be stored if it is allocated dynamically.</p>
+</div>
+<div class="section" id="id17">
+<h5>Semantics:<a class="headerlink" href="#id17" title="Permalink to this headline">¶</a></h5>
+<p>Depending on the alignment requirements of the objects in the coroutine frame
+and/or on the codegen compactness reasons the pointer returned from <cite>coro.begin</cite>
+may be at offset to the <cite>%mem</cite> argument. (This could be beneficial if
+instructions that express relative access to data can be more compactly encoded
+with small positive and negative offsets).</p>
+<p>A frontend should emit exactly one <cite>coro.begin</cite> intrinsic per coroutine.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-free-intrinsic">
+<span id="coro-free"></span><h4><a class="toc-backref" href="#id66">‘llvm.coro.free’ Intrinsic</a><a class="headerlink" href="#llvm-coro-free-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8* @llvm.coro.free(token %id, i8* <frame>)</pre>
+</div>
+<div class="section" id="id18">
+<h5>Overview:<a class="headerlink" href="#id18" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.free</span></tt>‘ intrinsic returns a pointer to a block of memory where
+coroutine frame is stored or <cite>null</cite> if this instance of a coroutine did not use
+dynamically allocated memory for its coroutine frame.</p>
+</div>
+<div class="section" id="id19">
+<h5>Arguments:<a class="headerlink" href="#id19" title="Permalink to this headline">¶</a></h5>
+<p>The first argument is a token returned by a call to ‘<tt class="docutils literal"><span class="pre">llvm.coro.id</span></tt>‘
+identifying the coroutine.</p>
+<p>The second argument is a pointer to the coroutine frame. This should be the same
+pointer that was returned by prior <cite>coro.begin</cite> call.</p>
+</div>
+<div class="section" id="example-custom-deallocation-function">
+<h5>Example (custom deallocation function):<a class="headerlink" href="#example-custom-deallocation-function" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %frame)
+ %mem_not_null = icmp ne i8* %mem, null
+ br i1 %mem_not_null, label %if.then, label %if.end
+if.then:
+ call void @CustomFree(i8* %mem)
+ br label %if.end
+if.end:
+ ret void</pre>
+</div>
+</div>
+<div class="section" id="example-standard-deallocation-functions">
+<h5>Example (standard deallocation functions):<a class="headerlink" href="#example-standard-deallocation-functions" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>cleanup:
+ %mem = call i8* @llvm.coro.free(token %id, i8* %frame)
+ call void @free(i8* %mem)
+ ret void</pre>
+</div>
+</div>
+</div>
+<div class="section" id="llvm-coro-alloc-intrinsic">
+<span id="coro-alloc"></span><h4><a class="toc-backref" href="#id67">‘llvm.coro.alloc’ Intrinsic</a><a class="headerlink" href="#llvm-coro-alloc-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i1 @llvm.coro.alloc(token <id>)</pre>
+</div>
+<div class="section" id="id20">
+<h5>Overview:<a class="headerlink" href="#id20" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.alloc</span></tt>‘ intrinsic returns <cite>true</cite> if dynamic allocation is
+required to obtain a memory for the coroutine frame and <cite>false</cite> otherwise.</p>
+</div>
+<div class="section" id="id21">
+<h5>Arguments:<a class="headerlink" href="#id21" title="Permalink to this headline">¶</a></h5>
+<p>The first argument is a token returned by a call to ‘<tt class="docutils literal"><span class="pre">llvm.coro.id</span></tt>‘
+identifying the coroutine.</p>
+</div>
+<div class="section" id="id22">
+<h5>Semantics:<a class="headerlink" href="#id22" title="Permalink to this headline">¶</a></h5>
+<p>A frontend should emit at most one <cite>coro.alloc</cite> intrinsic per coroutine.
+The intrinsic is used to suppress dynamic allocation of the coroutine frame
+when possible.</p>
+</div>
+<div class="section" id="id23">
+<h5>Example:<a class="headerlink" href="#id23" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>entry:
+ %id = call token @llvm.coro.id(i32 0, i8* null, i8* null, i8* null)
+ %dyn.alloc.required = call i1 @llvm.coro.alloc(token %id)
+ br i1 %dyn.alloc.required, label %coro.alloc, label %coro.begin
+
+coro.alloc:
+ %frame.size = call i32 @llvm.coro.size()
+ %alloc = call i8* @MyAlloc(i32 %frame.size)
+ br label %coro.begin
+
+coro.begin:
+ %phi = phi i8* [ null, %entry ], [ %alloc, %coro.alloc ]
+ %frame = call i8* @llvm.coro.begin(token %id, i8* %phi)</pre>
+</div>
+</div>
+</div>
+<div class="section" id="llvm-coro-noop-intrinsic">
+<span id="coro-noop"></span><h4><a class="toc-backref" href="#id68">‘llvm.coro.noop’ Intrinsic</a><a class="headerlink" href="#llvm-coro-noop-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8* @llvm.coro.noop()</pre>
+</div>
+<div class="section" id="id24">
+<h5>Overview:<a class="headerlink" href="#id24" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.noop</span></tt>‘ intrinsic returns an address of the coroutine frame of
+a coroutine that does nothing when resumed or destroyed.</p>
+</div>
+<div class="section" id="id25">
+<h5>Arguments:<a class="headerlink" href="#id25" title="Permalink to this headline">¶</a></h5>
+<p>None</p>
+</div>
+<div class="section" id="id26">
+<h5>Semantics:<a class="headerlink" href="#id26" title="Permalink to this headline">¶</a></h5>
+<p>This intrinsic is lowered to refer to a private constant coroutine frame. The
+resume and destroy handlers for this frame are empty functions that do nothing.
+Note that in different translation units llvm.coro.noop may return different pointers.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-frame-intrinsic">
+<span id="coro-frame"></span><h4><a class="toc-backref" href="#id69">‘llvm.coro.frame’ Intrinsic</a><a class="headerlink" href="#llvm-coro-frame-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8* @llvm.coro.frame()</pre>
+</div>
+<div class="section" id="id27">
+<h5>Overview:<a class="headerlink" href="#id27" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.frame</span></tt>‘ intrinsic returns an address of the coroutine frame of
+the enclosing coroutine.</p>
+</div>
+<div class="section" id="id28">
+<h5>Arguments:<a class="headerlink" href="#id28" title="Permalink to this headline">¶</a></h5>
+<p>None</p>
+</div>
+<div class="section" id="id29">
+<h5>Semantics:<a class="headerlink" href="#id29" title="Permalink to this headline">¶</a></h5>
+<p>This intrinsic is lowered to refer to the <a class="reference internal" href="#coro-begin">coro.begin</a> instruction. This is
+a frontend convenience intrinsic that makes it easier to refer to the
+coroutine frame.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-id-intrinsic">
+<span id="coro-id"></span><h4><a class="toc-backref" href="#id70">‘llvm.coro.id’ Intrinsic</a><a class="headerlink" href="#llvm-coro-id-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare token @llvm.coro.id(i32 <align>, i8* <promise>, i8* <coroaddr>,
+ i8* <fnaddrs>)</pre>
+</div>
+<div class="section" id="id30">
+<h5>Overview:<a class="headerlink" href="#id30" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.id</span></tt>‘ intrinsic returns a token identifying a coroutine.</p>
+</div>
+<div class="section" id="id31">
+<h5>Arguments:<a class="headerlink" href="#id31" title="Permalink to this headline">¶</a></h5>
+<p>The first argument provides information on the alignment of the memory returned
+by the allocation function and given to <cite>coro.begin</cite> by the first argument. If
+this argument is 0, the memory is assumed to be aligned to 2 * sizeof(i8*).
+This argument only accepts constants.</p>
+<p>The second argument, if not <cite>null</cite>, designates a particular alloca instruction
+to be a <a class="reference internal" href="#coroutine-promise">coroutine promise</a>.</p>
+<p>The third argument is <cite>null</cite> coming out of the frontend. The CoroEarly pass sets
+this argument to point to the function this coro.id belongs to.</p>
+<p>The fourth argument is <cite>null</cite> before coroutine is split, and later is replaced
+to point to a private global constant array containing function pointers to
+outlined resume and destroy parts of the coroutine.</p>
+</div>
+<div class="section" id="id32">
+<h5>Semantics:<a class="headerlink" href="#id32" title="Permalink to this headline">¶</a></h5>
+<p>The purpose of this intrinsic is to tie together <cite>coro.id</cite>, <cite>coro.alloc</cite> and
+<cite>coro.begin</cite> belonging to the same coroutine to prevent optimization passes from
+duplicating any of these instructions unless entire body of the coroutine is
+duplicated.</p>
+<p>A frontend should emit exactly one <cite>coro.id</cite> intrinsic per coroutine.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-end-intrinsic">
+<span id="coro-end"></span><h4><a class="toc-backref" href="#id71">‘llvm.coro.end’ Intrinsic</a><a class="headerlink" href="#llvm-coro-end-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i1 @llvm.coro.end(i8* <handle>, i1 <unwind>)</pre>
+</div>
+<div class="section" id="id33">
+<h5>Overview:<a class="headerlink" href="#id33" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.end</span></tt>‘ marks the point where execution of the resume part of
+the coroutine should end and control should return to the caller.</p>
+</div>
+<div class="section" id="id34">
+<h5>Arguments:<a class="headerlink" href="#id34" title="Permalink to this headline">¶</a></h5>
+<p>The first argument should refer to the coroutine handle of the enclosing
+coroutine. A frontend is allowed to supply null as the first parameter, in this
+case <cite>coro-early</cite> pass will replace the null with an appropriate coroutine
+handle value.</p>
+<p>The second argument should be <cite>true</cite> if this coro.end is in the block that is
+part of the unwind sequence leaving the coroutine body due to an exception and
+<cite>false</cite> otherwise.</p>
+</div>
+<div class="section" id="id35">
+<h5>Semantics:<a class="headerlink" href="#id35" title="Permalink to this headline">¶</a></h5>
+<p>The purpose of this intrinsic is to allow frontends to mark the cleanup and
+other code that is only relevant during the initial invocation of the coroutine
+and should not be present in resume and destroy parts.</p>
+<p>This intrinsic is lowered when a coroutine is split into
+the start, resume and destroy parts. In the start part, it is a no-op,
+in resume and destroy parts, it is replaced with <cite>ret void</cite> instruction and
+the rest of the block containing <cite>coro.end</cite> instruction is discarded.
+In landing pads it is replaced with an appropriate instruction to unwind to
+caller. The handling of coro.end differs depending on whether the target is
+using landingpad or WinEH exception model.</p>
+<p>For landingpad based exception model, it is expected that frontend uses the
+<a class="reference internal" href="#coro-end">coro.end</a> intrinsic as follows:</p>
+<div class="highlight-llvm"><pre>ehcleanup:
+ %InResumePart = call i1 @llvm.coro.end(i8* null, i1 true)
+ br i1 %InResumePart, label %eh.resume, label %cleanup.cont
+
+cleanup.cont:
+ ; rest of the cleanup
+
+eh.resume:
+ %exn = load i8*, i8** %exn.slot, align 8
+ %sel = load i32, i32* %ehselector.slot, align 4
+ %lpad.val = insertvalue { i8*, i32 } undef, i8* %exn, 0
+ %lpad.val29 = insertvalue { i8*, i32 } %lpad.val, i32 %sel, 1
+ resume { i8*, i32 } %lpad.val29</pre>
+</div>
+<p>The <cite>CoroSpit</cite> pass replaces <cite>coro.end</cite> with <tt class="docutils literal"><span class="pre">True</span></tt> in the resume functions,
+thus leading to immediate unwind to the caller, whereas in start function it
+is replaced with <tt class="docutils literal"><span class="pre">False</span></tt>, thus allowing to proceed to the rest of the cleanup
+code that is only needed during initial invocation of the coroutine.</p>
+<p>For Windows Exception handling model, a frontend should attach a funclet bundle
+referring to an enclosing cleanuppad as follows:</p>
+<div class="highlight-llvm"><pre>ehcleanup:
+ %tok = cleanuppad within none []
+ %unused = call i1 @llvm.coro.end(i8* null, i1 true) [ "funclet"(token %tok) ]
+ cleanupret from %tok unwind label %RestOfTheCleanup</pre>
+</div>
+<p>The <cite>CoroSplit</cite> pass, if the funclet bundle is present, will insert
+<tt class="docutils literal"><span class="pre">cleanupret</span> <span class="pre">from</span> <span class="pre">%tok</span> <span class="pre">unwind</span> <span class="pre">to</span> <span class="pre">caller</span></tt> before
+the <a class="reference internal" href="#coro-end">coro.end</a> intrinsic and will remove the rest of the block.</p>
+<p>The following table summarizes the handling of <a class="reference internal" href="#coro-end">coro.end</a> intrinsic.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="16%" />
+<col width="17%" />
+<col width="25%" />
+<col width="41%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td colspan="2"> </td>
+<td>In Start Function</td>
+<td>In Resume/Destroy Functions</td>
+</tr>
+<tr class="row-even"><td colspan="2">unwind=false</td>
+<td>nothing</td>
+<td><tt class="docutils literal"><span class="pre">ret</span> <span class="pre">void</span></tt></td>
+</tr>
+<tr class="row-odd"><td rowspan="2">unwind=true</td>
+<td>WinEH</td>
+<td>nothing</td>
+<td><tt class="docutils literal"><span class="pre">cleanupret</span> <span class="pre">unwind</span> <span class="pre">to</span> <span class="pre">caller</span></tt></td>
+</tr>
+<tr class="row-even"><td>Landingpad</td>
+<td>nothing</td>
+<td>nothing</td>
+</tr>
+</tbody>
+</table>
+</div>
+</div>
+<div class="section" id="llvm-coro-suspend-intrinsic">
+<span id="suspend-points"></span><span id="coro-suspend"></span><h4><a class="toc-backref" href="#id72">‘llvm.coro.suspend’ Intrinsic</a><a class="headerlink" href="#llvm-coro-suspend-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i8 @llvm.coro.suspend(token <save>, i1 <final>)</pre>
+</div>
+<div class="section" id="id36">
+<h5>Overview:<a class="headerlink" href="#id36" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.suspend</span></tt>‘ marks the point where execution of the coroutine
+need to get suspended and control returned back to the caller.
+Conditional branches consuming the result of this intrinsic lead to basic blocks
+where coroutine should proceed when suspended (-1), resumed (0) or destroyed
+(1).</p>
+</div>
+<div class="section" id="id37">
+<h5>Arguments:<a class="headerlink" href="#id37" title="Permalink to this headline">¶</a></h5>
+<p>The first argument refers to a token of <cite>coro.save</cite> intrinsic that marks the
+point when coroutine state is prepared for suspension. If <cite>none</cite> token is passed,
+the intrinsic behaves as if there were a <cite>coro.save</cite> immediately preceding
+the <cite>coro.suspend</cite> intrinsic.</p>
+<p>The second argument indicates whether this suspension point is <a class="reference internal" href="#final">final</a>.
+The second argument only accepts constants. If more than one suspend point is
+designated as final, the resume and destroy branches should lead to the same
+basic blocks.</p>
+</div>
+<div class="section" id="example-normal-suspend-point">
+<h5>Example (normal suspend point):<a class="headerlink" href="#example-normal-suspend-point" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>%0 = call i8 @llvm.coro.suspend(token none, i1 false)
+switch i8 %0, label %suspend [i8 0, label %resume
+ i8 1, label %cleanup]</pre>
+</div>
+</div>
+<div class="section" id="example-final-suspend-point">
+<h5>Example (final suspend point):<a class="headerlink" href="#example-final-suspend-point" title="Permalink to this headline">¶</a></h5>
+<div class="highlight-llvm"><pre>while.end:
+ %s.final = call i8 @llvm.coro.suspend(token none, i1 true)
+ switch i8 %s.final, label %suspend [i8 0, label %trap
+ i8 1, label %cleanup]
+trap:
+ call void @llvm.trap()
+ unreachable</pre>
+</div>
+</div>
+<div class="section" id="id38">
+<h5>Semantics:<a class="headerlink" href="#id38" title="Permalink to this headline">¶</a></h5>
+<p>If a coroutine that was suspended at the suspend point marked by this intrinsic
+is resumed via <a class="reference internal" href="#coro-resume">coro.resume</a> the control will transfer to the basic block
+of the 0-case. If it is resumed via <a class="reference internal" href="#coro-destroy">coro.destroy</a>, it will proceed to the
+basic block indicated by the 1-case. To suspend, coroutine proceed to the
+default label.</p>
+<p>If suspend intrinsic is marked as final, it can consider the <cite>true</cite> branch
+unreachable and can perform optimizations that can take advantage of that fact.</p>
+</div>
+</div>
+<div class="section" id="llvm-coro-save-intrinsic">
+<span id="coro-save"></span><h4><a class="toc-backref" href="#id73">‘llvm.coro.save’ Intrinsic</a><a class="headerlink" href="#llvm-coro-save-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare token @llvm.coro.save(i8* <handle>)</pre>
+</div>
+<div class="section" id="id39">
+<h5>Overview:<a class="headerlink" href="#id39" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.save</span></tt>‘ marks the point where a coroutine need to update its
+state to prepare for resumption to be considered suspended (and thus eligible
+for resumption).</p>
+</div>
+<div class="section" id="id40">
+<h5>Arguments:<a class="headerlink" href="#id40" title="Permalink to this headline">¶</a></h5>
+<p>The first argument points to a coroutine handle of the enclosing coroutine.</p>
+</div>
+<div class="section" id="id41">
+<h5>Semantics:<a class="headerlink" href="#id41" title="Permalink to this headline">¶</a></h5>
+<p>Whatever coroutine state changes are required to enable resumption of
+the coroutine from the corresponding suspend point should be done at the point
+of <cite>coro.save</cite> intrinsic.</p>
+</div>
+<div class="section" id="id42">
+<h5>Example:<a class="headerlink" href="#id42" title="Permalink to this headline">¶</a></h5>
+<p>Separate save and suspend points are necessary when a coroutine is used to
+represent an asynchronous control flow driven by callbacks representing
+completions of asynchronous operations.</p>
+<p>In such a case, a coroutine should be ready for resumption prior to a call to
+<cite>async_op</cite> function that may trigger resumption of a coroutine from the same or
+a different thread possibly prior to <cite>async_op</cite> call returning control back
+to the coroutine:</p>
+<div class="highlight-llvm"><pre>%save1 = call token @llvm.coro.save(i8* %hdl)
+call void @async_op1(i8* %hdl)
+%suspend1 = call i1 @llvm.coro.suspend(token %save1, i1 false)
+switch i8 %suspend1, label %suspend [i8 0, label %resume1
+ i8 1, label %cleanup]</pre>
+</div>
+</div>
+</div>
+<div class="section" id="llvm-coro-param-intrinsic">
+<span id="coro-param"></span><h4><a class="toc-backref" href="#id74">‘llvm.coro.param’ Intrinsic</a><a class="headerlink" href="#llvm-coro-param-intrinsic" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-python"><pre>declare i1 @llvm.coro.param(i8* <original>, i8* <copy>)</pre>
+</div>
+<div class="section" id="id43">
+<h5>Overview:<a class="headerlink" href="#id43" title="Permalink to this headline">¶</a></h5>
+<p>The ‘<tt class="docutils literal"><span class="pre">llvm.coro.param</span></tt>‘ is used by a frontend to mark up the code used to
+construct and destruct copies of the parameters. If the optimizer discovers that
+a particular parameter copy is not used after any suspends, it can remove the
+construction and destruction of the copy by replacing corresponding coro.param
+with <cite>i1 false</cite> and replacing any use of the <cite>copy</cite> with the <cite>original</cite>.</p>
+</div>
+<div class="section" id="id44">
+<h5>Arguments:<a class="headerlink" href="#id44" title="Permalink to this headline">¶</a></h5>
+<p>The first argument points to an <cite>alloca</cite> storing the value of a parameter to a
+coroutine.</p>
+<p>The second argument points to an <cite>alloca</cite> storing the value of the copy of that
+parameter.</p>
+</div>
+<div class="section" id="id45">
+<h5>Semantics:<a class="headerlink" href="#id45" title="Permalink to this headline">¶</a></h5>
+<p>The optimizer is free to always replace this intrinsic with <cite>i1 true</cite>.</p>
+<p>The optimizer is also allowed to replace it with <cite>i1 false</cite> provided that the
+parameter copy is only used prior to control flow reaching any of the suspend
+points. The code that would be DCE’d if the <cite>coro.param</cite> is replaced with
+<cite>i1 false</cite> is not considered to be a use of the parameter copy.</p>
+<p>The frontend can emit this intrinsic if its language rules allow for this
+optimization.</p>
+</div>
+<div class="section" id="id46">
+<h5>Example:<a class="headerlink" href="#id46" title="Permalink to this headline">¶</a></h5>
+<p>Consider the following example. A coroutine takes two parameters <cite>a</cite> and <cite>b</cite>
+that has a destructor and a move constructor.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">A</span> <span class="p">{</span> <span class="o">~</span><span class="n">A</span><span class="p">();</span> <span class="n">A</span><span class="p">(</span><span class="n">A</span><span class="o">&&</span><span class="p">);</span> <span class="kt">bool</span> <span class="n">foo</span><span class="p">();</span> <span class="kt">void</span> <span class="n">bar</span><span class="p">();</span> <span class="p">};</span>
+
+<span class="n">task</span><span class="o"><</span><span class="kt">int</span><span class="o">></span> <span class="n">f</span><span class="p">(</span><span class="n">A</span> <span class="n">a</span><span class="p">,</span> <span class="n">A</span> <span class="n">b</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span> <span class="p">(</span><span class="n">a</span><span class="p">.</span><span class="n">foo</span><span class="p">())</span>
+ <span class="k">return</span> <span class="mi">42</span><span class="p">;</span>
+
+ <span class="n">a</span><span class="p">.</span><span class="n">bar</span><span class="p">();</span>
+ <span class="n">co_await</span> <span class="n">read_async</span><span class="p">();</span> <span class="c1">// introduces suspend point</span>
+ <span class="n">b</span><span class="p">.</span><span class="n">bar</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Note that, uses of <cite>b</cite> is used after a suspend point and thus must be copied
+into a coroutine frame, whereas <cite>a</cite> does not have to, since it never used
+after suspend.</p>
+<p>A frontend can create parameter copies for <cite>a</cite> and <cite>b</cite> as follows:</p>
+<div class="highlight-text"><div class="highlight"><pre>task<int> f(A a', A b') {
+ a = alloca A;
+ b = alloca A;
+ // move parameters to its copies
+ if (coro.param(a', a)) A::A(a, A&& a');
+ if (coro.param(b', b)) A::A(b, A&& b');
+ ...
+ // destroy parameters copies
+ if (coro.param(a', a)) A::~A(a);
+ if (coro.param(b', b)) A::~A(b);
+}
+</pre></div>
+</div>
+<p>The optimizer can replace coro.param(a’,a) with <cite>i1 false</cite> and replace all uses
+of <cite>a</cite> with <cite>a’</cite>, since it is not used after suspend.</p>
+<p>The optimizer must replace coro.param(b’, b) with <cite>i1 true</cite>, since <cite>b</cite> is used
+after suspend and therefore, it has to reside in the coroutine frame.</p>
+</div>
+</div>
+</div>
+</div>
+<div class="section" id="coroutine-transformation-passes">
+<h2><a class="toc-backref" href="#id75">Coroutine Transformation Passes</a><a class="headerlink" href="#coroutine-transformation-passes" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="coroearly">
+<h3><a class="toc-backref" href="#id76">CoroEarly</a><a class="headerlink" href="#coroearly" title="Permalink to this headline">¶</a></h3>
+<p>The pass CoroEarly lowers coroutine intrinsics that hide the details of the
+structure of the coroutine frame, but, otherwise not needed to be preserved to
+help later coroutine passes. This pass lowers <a class="reference internal" href="#coro-frame">coro.frame</a>, <a class="reference internal" href="#coro-done">coro.done</a>,
+and <a class="reference internal" href="#coro-promise">coro.promise</a> intrinsics.</p>
+</div>
+<div class="section" id="corosplit">
+<span id="id47"></span><h3><a class="toc-backref" href="#id77">CoroSplit</a><a class="headerlink" href="#corosplit" title="Permalink to this headline">¶</a></h3>
+<p>The pass CoroSplit buides coroutine frame and outlines resume and destroy parts
+into separate functions.</p>
+</div>
+<div class="section" id="coroelide">
+<h3><a class="toc-backref" href="#id78">CoroElide</a><a class="headerlink" href="#coroelide" title="Permalink to this headline">¶</a></h3>
+<p>The pass CoroElide examines if the inlined coroutine is eligible for heap
+allocation elision optimization. If so, it replaces
+<cite>coro.begin</cite> intrinsic with an address of a coroutine frame placed on its caller
+and replaces <cite>coro.alloc</cite> and <cite>coro.free</cite> intrinsics with <cite>false</cite> and <cite>null</cite>
+respectively to remove the deallocation code.
+This pass also replaces <cite>coro.resume</cite> and <cite>coro.destroy</cite> intrinsics with direct
+calls to resume and destroy functions for a particular coroutine where possible.</p>
+</div>
+<div class="section" id="corocleanup">
+<h3><a class="toc-backref" href="#id79">CoroCleanup</a><a class="headerlink" href="#corocleanup" title="Permalink to this headline">¶</a></h3>
+<p>This pass runs late to lower all coroutine related intrinsics not replaced by
+earlier passes.</p>
+</div>
+</div>
+<div class="section" id="areas-requiring-attention">
+<h2><a class="toc-backref" href="#id80">Areas Requiring Attention</a><a class="headerlink" href="#areas-requiring-attention" title="Permalink to this headline">¶</a></h2>
+<ol class="arabic simple">
+<li>A coroutine frame is bigger than it could be. Adding stack packing and stack
+coloring like optimization on the coroutine frame will result in tighter
+coroutine frames.</li>
+<li>Take advantage of the lifetime intrinsics for the data that goes into the
+coroutine frame. Leave lifetime intrinsics as is for the data that stays in
+allocas.</li>
+<li>The CoroElide optimization pass relies on coroutine ramp function to be
+inlined. It would be beneficial to split the ramp function further to
+increase the chance that it will get inlined into its caller.</li>
+<li>Design a convention that would make it possible to apply coroutine heap
+elision optimization across ABI boundaries.</li>
+<li>Cannot handle coroutines with <cite>inalloca</cite> parameters (used in x86 on Windows).</li>
+<li>Alignment is ignored by coro.begin and coro.free intrinsics.</li>
+<li>Make required changes to make sure that coroutine optimizations work with
+LTO.</li>
+<li>More tests, more tests, more tests</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="GlobalISel.html" title="Global Instruction Selection"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/CoverageMappingFormat.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/CoverageMappingFormat.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/CoverageMappingFormat.html (added)
+++ www-releases/trunk/7.0.1/docs/CoverageMappingFormat.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,664 @@
+
+
+<!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 Code Coverage Mapping Format — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Garbage Collection Safepoints in LLVM" href="Statepoints.html" />
+ <link rel="prev" title="Using ARM NEON instructions in big endian mode" href="BigEndianNEON.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Statepoints.html" title="Garbage Collection Safepoints in LLVM"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="BigEndianNEON.html" title="Using ARM NEON instructions in big endian mode"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-code-coverage-mapping-format">
+<h1>LLVM Code Coverage Mapping Format<a class="headerlink" href="#llvm-code-coverage-mapping-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="id11">Introduction</a></li>
+<li><a class="reference internal" href="#quick-start" id="id12">Quick Start</a></li>
+<li><a class="reference internal" href="#high-level-overview" id="id13">High Level Overview</a></li>
+<li><a class="reference internal" href="#advanced-concepts" id="id14">Advanced Concepts</a><ul>
+<li><a class="reference internal" href="#mapping-region" id="id15">Mapping Region</a><ul>
+<li><a class="reference internal" href="#source-range" id="id16">Source Range:</a></li>
+<li><a class="reference internal" href="#file-id" id="id17">File ID:</a></li>
+<li><a class="reference internal" href="#counter" id="id18">Counter:</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#llvm-ir-representation" id="id19">LLVM IR Representation</a><ul>
+<li><a class="reference internal" href="#coverage-mapping-header" id="id20">Coverage Mapping Header:</a></li>
+<li><a class="reference internal" href="#function-record" id="id21">Function record:</a></li>
+<li><a class="reference internal" href="#encoded-data" id="id22">Encoded data:</a><ul>
+<li><a class="reference internal" href="#dissecting-the-sample" id="id23">Dissecting the sample:</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#encoding" id="id24">Encoding</a><ul>
+<li><a class="reference internal" href="#types" id="id25">Types</a><ul>
+<li><a class="reference internal" href="#leb128" id="id26">LEB128</a></li>
+<li><a class="reference internal" href="#strings" id="id27">Strings</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#file-id-mapping" id="id28">File ID Mapping</a></li>
+<li><a class="reference internal" href="#id3" id="id29">Counter</a><ul>
+<li><a class="reference internal" href="#tag" id="id30">Tag:</a></li>
+<li><a class="reference internal" href="#data" id="id31">Data:</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#counter-expressions" id="id32">Counter Expressions</a></li>
+<li><a class="reference internal" href="#mapping-regions" id="id33">Mapping Regions</a><ul>
+<li><a class="reference internal" href="#sub-array-of-regions" id="id34">Sub-Array of Regions</a></li>
+<li><a class="reference internal" href="#id6" id="id35">Mapping Region</a></li>
+<li><a class="reference internal" href="#header" id="id36">Header</a><ul>
+<li><a class="reference internal" href="#id8" id="id37">Counter:</a></li>
+<li><a class="reference internal" href="#pseudo-counter" id="id38">Pseudo-Counter:</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#id9" id="id39">Source Range</a></li>
+</ul>
+</li>
+</ul>
+</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>LLVM’s code coverage mapping format is used to provide code coverage
+analysis using LLVM’s and Clang’s instrumenation based profiling
+(Clang’s <tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> option).</p>
+<p>This document is aimed at those who use LLVM’s code coverage mapping to provide
+code coverage analysis for their own programs, and for those who would like
+to know how it works under the hood. A prior knowledge of how Clang’s profile
+guided optimization works is useful, but not required.</p>
+<p>We start by showing how to use LLVM and Clang for code coverage analysis,
+then we briefly describe LLVM’s code coverage mapping format and the
+way that Clang and LLVM’s code coverage tool work with this format. After
+the basics are down, more advanced features of the coverage mapping format
+are discussed - such as the data structures, LLVM IR representation and
+the binary encoding.</p>
+</div>
+<div class="section" id="quick-start">
+<h2><a class="toc-backref" href="#id12">Quick Start</a><a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
+<p>Here’s a short story that describes how to generate code coverage overview
+for a sample source file called <em>test.c</em>.</p>
+<ul>
+<li><p class="first">First, compile an instrumented version of your program using Clang’s
+<tt class="docutils literal"><span class="pre">-fprofile-instr-generate</span></tt> option with the additional <tt class="docutils literal"><span class="pre">-fcoverage-mapping</span></tt>
+option:</p>
+<p><tt class="docutils literal"><span class="pre">clang</span> <span class="pre">-o</span> <span class="pre">test</span> <span class="pre">-fprofile-instr-generate</span> <span class="pre">-fcoverage-mapping</span> <span class="pre">test.c</span></tt></p>
+</li>
+<li><p class="first">Then, run the instrumented binary. The runtime will produce a file called
+<em>default.profraw</em> containing the raw profile instrumentation data:</p>
+<p><tt class="docutils literal"><span class="pre">./test</span></tt></p>
+</li>
+<li><p class="first">After that, merge the profile data using the <em>llvm-profdata</em> tool:</p>
+<p><tt class="docutils literal"><span class="pre">llvm-profdata</span> <span class="pre">merge</span> <span class="pre">-o</span> <span class="pre">test.profdata</span> <span class="pre">default.profraw</span></tt></p>
+</li>
+<li><p class="first">Finally, run LLVM’s code coverage tool (<em>llvm-cov</em>) to produce the code
+coverage overview for the sample source file:</p>
+<p><tt class="docutils literal"><span class="pre">llvm-cov</span> <span class="pre">show</span> <span class="pre">./test</span> <span class="pre">-instr-profile=test.profdata</span> <span class="pre">test.c</span></tt></p>
+</li>
+</ul>
+</div>
+<div class="section" id="high-level-overview">
+<h2><a class="toc-backref" href="#id13">High Level Overview</a><a class="headerlink" href="#high-level-overview" title="Permalink to this headline">¶</a></h2>
+<p>LLVM’s code coverage mapping format is designed to be a self contained
+data format, that can be embedded into the LLVM IR and object files.
+It’s described in this document as a <strong>mapping</strong> format because its goal is
+to store the data that is required for a code coverage tool to map between
+the specific source ranges in a file and the execution counts obtained
+after running the instrumented version of the program.</p>
+<p>The mapping data is used in two places in the code coverage process:</p>
+<ol class="arabic simple">
+<li>When clang compiles a source file with <tt class="docutils literal"><span class="pre">-fcoverage-mapping</span></tt>, it
+generates the mapping information that describes the mapping between the
+source ranges and the profiling instrumentation counters.
+This information gets embedded into the LLVM IR and conveniently
+ends up in the final executable file when the program is linked.</li>
+<li>It is also used by <em>llvm-cov</em> - the mapping information is extracted from an
+object file and is used to associate the execution counts (the values of the
+profile instrumentation counters), and the source ranges in a file.
+After that, the tool is able to generate various code coverage reports
+for the program.</li>
+</ol>
+<p>The coverage mapping format aims to be a “universal format” that would be
+suitable for usage by any frontend, and not just by Clang. It also aims to
+provide the frontend the possibility of generating the minimal coverage mapping
+data in order to reduce the size of the IR and object files - for example,
+instead of emitting mapping information for each statement in a function, the
+frontend is allowed to group the statements with the same execution count into
+regions of code, and emit the mapping information only for those regions.</p>
+</div>
+<div class="section" id="advanced-concepts">
+<h2><a class="toc-backref" href="#id14">Advanced Concepts</a><a class="headerlink" href="#advanced-concepts" title="Permalink to this headline">¶</a></h2>
+<p>The remainder of this guide is meant to give you insight into the way the
+coverage mapping format works.</p>
+<p>The coverage mapping format operates on a per-function level as the
+profile instrumentation counters are associated with a specific function.
+For each function that requires code coverage, the frontend has to create
+coverage mapping data that can map between the source code ranges and
+the profile instrumentation counters for that function.</p>
+<div class="section" id="mapping-region">
+<h3><a class="toc-backref" href="#id15">Mapping Region</a><a class="headerlink" href="#mapping-region" title="Permalink to this headline">¶</a></h3>
+<p>The function’s coverage mapping data contains an array of mapping regions.
+A mapping region stores the <a class="reference internal" href="#source-code-range">source code range</a> that is covered by this region,
+the <a class="reference internal" href="#coverage-file-id">file id</a>, the <a class="reference internal" href="#coverage-mapping-counter">coverage mapping counter</a> and
+the region’s kind.
+There are several kinds of mapping regions:</p>
+<ul>
+<li><p class="first">Code regions associate portions of source code and <a class="reference internal" href="#coverage-mapping-counters">coverage mapping
+counters</a>. They make up the majority of the mapping regions. They are used
+by the code coverage tool to compute the execution counts for lines,
+highlight the regions of code that were never executed, and to obtain
+the various code coverage statistics for a function.
+For example:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char *argv[]) </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Code Region from 1:40 to 9:2</span>
+<span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> if (argc > 1) </span><span style='background-color:#85C1F5'>{ </span> <span class='c1'>// Code Region from 3:17 to 5:4</span>
+<span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span>
+<span style='background-color:#85C1F5'> }</span><span style='background-color:#4A789C'> else </span><span style='background-color:#F6D55D'>{ </span> <span class='c1'>// Code Region from 5:10 to 7:4</span>
+<span style='background-color:#F6D55D'> printf("\n"); </span>
+<span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> return 0; </span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+</li>
+<li><p class="first">Skipped regions are used to represent source ranges that were skipped
+by Clang’s preprocessor. They don’t associate with
+<a class="reference internal" href="#coverage-mapping-counters">coverage mapping counters</a>, as the frontend knows that they are never
+executed. They are used by the code coverage tool to mark the skipped lines
+inside a function as non-code lines that don’t have execution counts.
+For example:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int main() </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Code Region from 1:12 to 6:2</span>
+<span style='background-color:#85C1F5'>#ifdef DEBUG </span> <span class='c1'>// Skipped Region from 2:1 to 4:2</span>
+<span style='background-color:#85C1F5'> printf("Hello world"); </span>
+<span style='background-color:#85C1F5'>#</span><span style='background-color:#4A789C'>endif </span>
+<span style='background-color:#4A789C'> return 0; </span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+</li>
+<li><p class="first">Expansion regions are used to represent Clang’s macro expansions. They
+have an additional property - <em>expanded file id</em>. This property can be
+used by the code coverage tool to find the mapping regions that are created
+as a result of this macro expansion, by checking if their file id matches the
+expanded file id. They don’t associate with <a class="reference internal" href="#coverage-mapping-counters">coverage mapping counters</a>,
+as the code coverage tool can determine the execution count for this region
+by looking up the execution count of the first region with a corresponding
+file id.
+For example:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int func(int x) </span><span style='background-color:#4A789C'>{ </span>
+<span style='background-color:#4A789C'> #define MAX(x,y) </span><span style='background-color:#85C1F5'>((x) > (y)? </span><span style='background-color:#F6D55D'>(x)</span><span style='background-color:#85C1F5'> : </span><span style='background-color:#F4BA70'>(y)</span><span style='background-color:#85C1F5'>)</span><span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> return </span><span style='background-color:#7FCA9F'>MAX</span><span style='background-color:#4A789C'>(x, 42); </span> <span class='c1'>// Expansion Region from 3:10 to 3:13</span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+</li>
+</ul>
+<div class="section" id="source-range">
+<span id="source-code-range"></span><h4><a class="toc-backref" href="#id16">Source Range:</a><a class="headerlink" href="#source-range" title="Permalink to this headline">¶</a></h4>
+<p>The source range record contains the starting and ending location of a certain
+mapping region. Both locations include the line and the column numbers.</p>
+</div>
+<div class="section" id="file-id">
+<span id="coverage-file-id"></span><h4><a class="toc-backref" href="#id17">File ID:</a><a class="headerlink" href="#file-id" title="Permalink to this headline">¶</a></h4>
+<p>The file id an integer value that tells us
+in which source file or macro expansion is this region located.
+It enables Clang to produce mapping information for the code
+defined inside macros, like this example demonstrates:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>void func(const char *str) </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Code Region from 1:28 to 6:2 with file id 0</span>
+<span style='background-color:#4A789C'> #define PUT </span><span style='background-color:#85C1F5'>printf("%s\n", str)</span><span style='background-color:#4A789C'> </span> <span class='c1'>// 2 Code Regions from 2:15 to 2:34 with file ids 1 and 2</span>
+<span style='background-color:#4A789C'> if(*str) </span>
+<span style='background-color:#4A789C'> </span><span style='background-color:#F6D55D'>PUT</span><span style='background-color:#4A789C'>; </span> <span class='c1'>// Expansion Region from 4:5 to 4:8 with file id 0 that expands a macro with file id 1</span>
+<span style='background-color:#4A789C'> </span><span style='background-color:#F6D55D'>PUT</span><span style='background-color:#4A789C'>; </span> <span class='c1'>// Expansion Region from 5:3 to 5:6 with file id 0 that expands a macro with file id 2</span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+</div>
+<div class="section" id="counter">
+<span id="coverage-mapping-counters"></span><span id="coverage-mapping-counter"></span><h4><a class="toc-backref" href="#id18">Counter:</a><a class="headerlink" href="#counter" title="Permalink to this headline">¶</a></h4>
+<p>A coverage mapping counter can represents a reference to the profile
+instrumentation counter. The execution count for a region with such counter
+is determined by looking up the value of the corresponding profile
+instrumentation counter.</p>
+<p>It can also represent a binary arithmetical expression that operates on
+coverage mapping counters or other expressions.
+The execution count for a region with an expression counter is determined by
+evaluating the expression’s arguments and then adding them together or
+subtracting them from one another.
+In the example below, a subtraction expression is used to compute the execution
+count for the compound statement that follows the <em>else</em> keyword:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int main(int argc, const char *argv[]) </span><span style='background-color:#4A789C'>{ </span> <span class='c1'>// Region's counter is a reference to the profile counter #0</span>
+<span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> if (argc > 1) </span><span style='background-color:#85C1F5'>{ </span> <span class='c1'>// Region's counter is a reference to the profile counter #1</span>
+<span style='background-color:#85C1F5'> printf("%s\n", argv[1]); </span><span> </span>
+<span style='background-color:#85C1F5'> }</span><span style='background-color:#4A789C'> else </span><span style='background-color:#F6D55D'>{ </span> <span class='c1'>// Region's counter is an expression (reference to the profile counter #0 - reference to the profile counter #1)</span>
+<span style='background-color:#F6D55D'> printf("\n"); </span>
+<span style='background-color:#F6D55D'> }</span><span style='background-color:#4A789C'> </span>
+<span style='background-color:#4A789C'> return 0; </span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+<p>Finally, a coverage mapping counter can also represent an execution count of
+of zero. The zero counter is used to provide coverage mapping for
+unreachable statements and expressions, like in the example below:</p>
+<p><span class="raw-html"><pre class='highlight' style='line-height:initial;'><span>int main() </span><span style='background-color:#4A789C'>{ </span>
+<span style='background-color:#4A789C'> return 0; </span>
+<span style='background-color:#4A789C'> </span><span style='background-color:#85C1F5'>printf("Hello world!\n")</span><span style='background-color:#4A789C'>; </span> <span class='c1'>// Unreachable region's counter is zero</span>
+<span style='background-color:#4A789C'>}</span>
+</pre></span></p>
+<p>The zero counters allow the code coverage tool to display proper line execution
+counts for the unreachable lines and highlight the unreachable code.
+Without them, the tool would think that those lines and regions were still
+executed, as it doesn’t possess the frontend’s knowledge.</p>
+</div>
+</div>
+</div>
+<div class="section" id="llvm-ir-representation">
+<h2><a class="toc-backref" href="#id19">LLVM IR Representation</a><a class="headerlink" href="#llvm-ir-representation" title="Permalink to this headline">¶</a></h2>
+<p>The coverage mapping data is stored in the LLVM IR using a single global
+constant structure variable called <em>__llvm_coverage_mapping</em>
+with the <em>__llvm_covmap</em> section specifier.</p>
+<p>For example, letâs consider a C file and how it gets compiled to LLVM:</p>
+<div class="highlight-c" id="coverage-mapping-sample"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">42</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="kt">int</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">13</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The coverage mapping variable generated by Clang has 3 fields:</p>
+<ul class="simple">
+<li>Coverage mapping header.</li>
+<li>An array of function records.</li>
+<li>Coverage mapping data which is an array of bytes. Zero paddings are added at the end to force 8 byte alignment.</li>
+</ul>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="vg">@__llvm_coverage_mapping</span> <span class="p">=</span> <span class="k">internal</span> <span class="k">constant</span> <span class="p">{</span> <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span> <span class="p">},</span> <span class="p">[</span><span class="m">2</span> <span class="k">x</span> <span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}],</span> <span class="p">[</span><span class="m">40</span> <span class="k">x</span> <span class="k">i8</span><span class="p">]</span> <span class="p">}</span>
+<span class="p">{</span>
+ <span class="p">{</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span> <span class="p">}</span> <span class="c">; Coverage map header</span>
+ <span class="p">{</span>
+ <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="c">; The number of function records</span>
+ <span class="k">i32</span> <span class="m">20</span><span class="p">,</span> <span class="c">; The length of the string that contains the encoded translation unit filenames</span>
+ <span class="k">i32</span> <span class="m">20</span><span class="p">,</span> <span class="c">; The length of the string that contains the encoded coverage mapping data</span>
+ <span class="k">i32</span> <span class="m">2</span><span class="p">,</span> <span class="c">; Coverage mapping format version</span>
+ <span class="p">},</span>
+ <span class="p">[</span><span class="m">2</span> <span class="k">x</span> <span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}]</span> <span class="p">[</span> <span class="c">; Function records</span>
+ <span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}</span> <span class="p">{</span>
+ <span class="k">i64</span> <span class="m">0x5cf8c24cdb18bdac</span><span class="p">,</span> <span class="c">; Function's name MD5</span>
+ <span class="k">i32</span> <span class="m">9</span><span class="p">,</span> <span class="c">; Function's encoded coverage mapping data string length</span>
+ <span class="k">i64</span> <span class="m">0</span> <span class="c">; Function's structural hash</span>
+ <span class="p">},</span>
+ <span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}</span> <span class="p">{</span>
+ <span class="k">i64</span> <span class="m">0xe413754a191db537</span><span class="p">,</span> <span class="c">; Function's name MD5</span>
+ <span class="k">i32</span> <span class="m">9</span><span class="p">,</span> <span class="c">; Function's encoded coverage mapping data string length</span>
+ <span class="k">i64</span> <span class="m">0</span> <span class="c">; Function's structural hash</span>
+ <span class="p">}],</span>
+ <span class="p">[</span><span class="m">40</span> <span class="k">x</span> <span class="k">i8</span><span class="p">]</span> <span class="k">c</span><span class="s">"..."</span> <span class="c">; Encoded data (dissected later)</span>
+<span class="p">},</span> <span class="k">section</span> <span class="s">"__llvm_covmap"</span><span class="p">,</span> <span class="k">align</span> <span class="m">8</span>
+</pre></div>
+</div>
+<p>The current version of the format is version 3. The only difference from version 2 is that a special encoding for column end locations was introduced to indicate gap regions.</p>
+<p>The function record layout has evolved since version 1. In version 1, the function record for <em>foo</em> is defined as follows:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*</span> <span class="k">getelementptr</span> <span class="k">inbounds</span> <span class="p">([</span><span class="m">3</span> <span class="k">x</span> <span class="k">i8</span><span class="p">]*</span> <span class="vg">@__profn_foo</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">),</span> <span class="c">; Function's name</span>
+ <span class="k">i32</span> <span class="m">3</span><span class="p">,</span> <span class="c">; Function's name length</span>
+ <span class="k">i32</span> <span class="m">9</span><span class="p">,</span> <span class="c">; Function's encoded coverage mapping data string length</span>
+ <span class="k">i64</span> <span class="m">0</span> <span class="c">; Function's structural hash</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="section" id="coverage-mapping-header">
+<h3><a class="toc-backref" href="#id20">Coverage Mapping Header:</a><a class="headerlink" href="#coverage-mapping-header" title="Permalink to this headline">¶</a></h3>
+<p>The coverage mapping header has the following fields:</p>
+<ul class="simple">
+<li>The number of function records.</li>
+<li>The length of the string in the third field of <em>__llvm_coverage_mapping</em> that contains the encoded translation unit filenames.</li>
+<li>The length of the string in the third field of <em>__llvm_coverage_mapping</em> that contains the encoded coverage mapping data.</li>
+<li>The format version. The current version is 3 (encoded as a 2).</li>
+</ul>
+</div>
+<div class="section" id="function-record">
+<span id="function-records"></span><h3><a class="toc-backref" href="#id21">Function record:</a><a class="headerlink" href="#function-record" title="Permalink to this headline">¶</a></h3>
+<p>A function record is a structure of the following type:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="p">{</span> <span class="k">i64</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="k">i64</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>It contains function name’s MD5, the length of the encoded mapping data for that function, and function’s
+structural hash value.</p>
+</div>
+<div class="section" id="encoded-data">
+<h3><a class="toc-backref" href="#id22">Encoded data:</a><a class="headerlink" href="#encoded-data" title="Permalink to this headline">¶</a></h3>
+<p>The encoded data is stored in a single string that contains
+the encoded filenames used by this translation unit and the encoded coverage
+mapping data for each function in this translation unit.</p>
+<p>The encoded data has the following structure:</p>
+<p><tt class="docutils literal"><span class="pre">[filenames,</span> <span class="pre">coverageMappingDataForFunctionRecord0,</span> <span class="pre">coverageMappingDataForFunctionRecord1,</span> <span class="pre">...,</span> <span class="pre">padding]</span></tt></p>
+<p>If necessary, the encoded data is padded with zeroes so that the size
+of the data string is rounded up to the nearest multiple of 8 bytes.</p>
+<div class="section" id="dissecting-the-sample">
+<h4><a class="toc-backref" href="#id23">Dissecting the sample:</a><a class="headerlink" href="#dissecting-the-sample" title="Permalink to this headline">¶</a></h4>
+<p>Here’s an overview of the encoded data that was stored in the
+IR for the <a class="reference internal" href="#coverage-mapping-sample">coverage mapping sample</a> that was shown earlier:</p>
+<ul>
+<li><p class="first">The IR contains the following string constant that represents the encoded
+coverage mapping data for the sample translation unit:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">c</span><span class="s">"\01\12/Users/alex/test.c\01\00\00\01\01\01\0C\02\02\01\00\00\01\01\04\0C\02\02\00\00"</span>
+</pre></div>
+</div>
+</li>
+<li><p class="first">The string contains values that are encoded in the LEB128 format, which is
+used throughout for storing integers. It also contains a string value.</p>
+</li>
+<li><p class="first">The length of the substring that contains the encoded translation unit
+filenames is the value of the second field in the <em>__llvm_coverage_mapping</em>
+structure, which is 20, thus the filenames are encoded in this string:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">c</span><span class="s">"\01\12/Users/alex/test.c"</span>
+</pre></div>
+</div>
+<p>This string contains the following data:</p>
+<ul class="simple">
+<li>Its first byte has a value of <tt class="docutils literal"><span class="pre">0x01</span></tt>. It stores the number of filenames
+contained in this string.</li>
+<li>Its second byte stores the length of the first filename in this string.</li>
+<li>The remaining 18 bytes are used to store the first filename.</li>
+</ul>
+</li>
+<li><p class="first">The length of the substring that contains the encoded coverage mapping data
+for the first function is the value of the third field in the first
+structure in an array of <a class="reference internal" href="#function-records">function records</a> stored in the
+third field of the <em>__llvm_coverage_mapping</em> structure, which is the 9.
+Therefore, the coverage mapping for the first function record is encoded
+in this string:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">c</span><span class="s">"\01\00\00\01\01\01\0C\02\02"</span>
+</pre></div>
+</div>
+<p>This string consists of the following bytes:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="8%" />
+<col width="92%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x01</span></tt></td>
+<td>The number of file ids used by this function. There is only one file id used by the mapping data in this function.</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x00</span></tt></td>
+<td>An index into the filenames array which corresponds to the file “/Users/alex/test.c”.</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x00</span></tt></td>
+<td>The number of counter expressions used by this function. This function doesn’t use any expressions.</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x01</span></tt></td>
+<td>The number of mapping regions that are stored in an array for the function’s file id #0.</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x01</span></tt></td>
+<td>The coverage mapping counter for the first region in this function. The value of 1 tells us that it’s a coverage
+mapping counter that is a reference to the profile instrumentation counter with an index of 0.</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x01</span></tt></td>
+<td>The starting line of the first mapping region in this function.</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x0C</span></tt></td>
+<td>The starting column of the first mapping region in this function.</td>
+</tr>
+<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x02</span></tt></td>
+<td>The ending line of the first mapping region in this function.</td>
+</tr>
+<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x02</span></tt></td>
+<td>The ending column of the first mapping region in this function.</td>
+</tr>
+</tbody>
+</table>
+</li>
+<li><p class="first">The length of the substring that contains the encoded coverage mapping data
+for the second function record is also 9. It’s structured like the mapping data
+for the first function record.</p>
+</li>
+<li><p class="first">The two trailing bytes are zeroes and are used to pad the coverage mapping
+data to give it the 8 byte alignment.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+<div class="section" id="encoding">
+<h2><a class="toc-backref" href="#id24">Encoding</a><a class="headerlink" href="#encoding" title="Permalink to this headline">¶</a></h2>
+<p>The per-function coverage mapping data is encoded as a stream of bytes,
+with a simple structure. The structure consists of the encoding
+<a class="reference internal" href="#cvmtypes">types</a> like variable-length unsigned integers, that
+are used to encode <a class="reference internal" href="#file-id-mapping">File ID Mapping</a>, <a class="reference internal" href="#counter-expressions">Counter Expressions</a> and
+the <a class="reference internal" href="#mapping-regions">Mapping Regions</a>.</p>
+<p>The format of the structure follows:</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">[file</span> <span class="pre">id</span> <span class="pre">mapping,</span> <span class="pre">counter</span> <span class="pre">expressions,</span> <span class="pre">mapping</span> <span class="pre">regions]</span></tt></div></blockquote>
+<p>The translation unit filenames are encoded using the same encoding
+<a class="reference internal" href="#cvmtypes">types</a> as the per-function coverage mapping data, with the
+following structure:</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">[numFilenames</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">filename0</span> <span class="pre">:</span> <span class="pre">string,</span> <span class="pre">filename1</span> <span class="pre">:</span> <span class="pre">string,</span> <span class="pre">...]</span></tt></div></blockquote>
+<div class="section" id="types">
+<span id="cvmtypes"></span><h3><a class="toc-backref" href="#id25">Types</a><a class="headerlink" href="#types" title="Permalink to this headline">¶</a></h3>
+<p>This section describes the basic types that are used by the encoding format
+and can appear after <tt class="docutils literal"><span class="pre">:</span></tt> in the <tt class="docutils literal"><span class="pre">[foo</span> <span class="pre">:</span> <span class="pre">type]</span></tt> description.</p>
+<div class="section" id="leb128">
+<span id="id1"></span><h4><a class="toc-backref" href="#id26">LEB128</a><a class="headerlink" href="#leb128" title="Permalink to this headline">¶</a></h4>
+<p>LEB128 is an unsigned integer value that is encoded using DWARF’s LEB128
+encoding, optimizing for the case where values are small
+(1 byte for values less than 128).</p>
+</div>
+<div class="section" id="strings">
+<span id="coveragestrings"></span><h4><a class="toc-backref" href="#id27">Strings</a><a class="headerlink" href="#strings" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[length</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">characters...]</span></tt></p>
+<p>String values are encoded with a <a class="reference internal" href="#leb128">LEB value</a> for the length
+of the string and a sequence of bytes for its characters.</p>
+</div>
+</div>
+<div class="section" id="file-id-mapping">
+<span id="id2"></span><h3><a class="toc-backref" href="#id28">File ID Mapping</a><a class="headerlink" href="#file-id-mapping" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">[numIndices</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">filenameIndex0</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">filenameIndex1</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">...]</span></tt></p>
+<p>File id mapping in a function’s coverage mapping stream
+contains the indices into the translation unit’s filenames array.</p>
+</div>
+<div class="section" id="id3">
+<h3><a class="toc-backref" href="#id29">Counter</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">[value</span> <span class="pre">:</span> <span class="pre">LEB128]</span></tt></p>
+<p>A <a class="reference internal" href="#coverage-mapping-counter">coverage mapping counter</a> is stored in a single <a class="reference internal" href="#leb128">LEB value</a>.
+It is composed of two things — the <a class="reference internal" href="#counter-tag">tag</a>
+which is stored in the lowest 2 bits, and the <a class="reference internal" href="#counter-data">counter data</a> which is stored
+in the remaining bits.</p>
+<div class="section" id="tag">
+<span id="counter-tag"></span><h4><a class="toc-backref" href="#id30">Tag:</a><a class="headerlink" href="#tag" title="Permalink to this headline">¶</a></h4>
+<p>The counter’s tag encodes the counter’s kind
+and, if the counter is an expression, the expression’s kind.
+The possible tag values are:</p>
+<ul class="simple">
+<li>0 - The counter is zero.</li>
+<li>1 - The counter is a reference to the profile instrumentation counter.</li>
+<li>2 - The counter is a subtraction expression.</li>
+<li>3 - The counter is an addition expression.</li>
+</ul>
+</div>
+<div class="section" id="data">
+<span id="counter-data"></span><h4><a class="toc-backref" href="#id31">Data:</a><a class="headerlink" href="#data" title="Permalink to this headline">¶</a></h4>
+<p>The counter’s data is interpreted in the following manner:</p>
+<ul class="simple">
+<li>When the counter is a reference to the profile instrumentation counter,
+then the counter’s data is the id of the profile counter.</li>
+<li>When the counter is an expression, then the counter’s data
+is the index into the array of counter expressions.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="counter-expressions">
+<span id="id4"></span><h3><a class="toc-backref" href="#id32">Counter Expressions</a><a class="headerlink" href="#counter-expressions" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">[numExpressions</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">expr0LHS</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">expr0RHS</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">expr1LHS</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">expr1RHS</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">...]</span></tt></p>
+<p>Counter expressions consist of two counters as they
+represent binary arithmetic operations.
+The expression’s kind is determined from the <a class="reference internal" href="#counter-tag">tag</a> of the
+counter that references this expression.</p>
+</div>
+<div class="section" id="mapping-regions">
+<span id="id5"></span><h3><a class="toc-backref" href="#id33">Mapping Regions</a><a class="headerlink" href="#mapping-regions" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">[numRegionArrays</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">regionsForFile0,</span> <span class="pre">regionsForFile1,</span> <span class="pre">...]</span></tt></p>
+<p>The mapping regions are stored in an array of sub-arrays where every
+region in a particular sub-array has the same file id.</p>
+<p>The file id for a sub-array of regions is the index of that
+sub-array in the main array e.g. The first sub-array will have the file id
+of 0.</p>
+<div class="section" id="sub-array-of-regions">
+<h4><a class="toc-backref" href="#id34">Sub-Array of Regions</a><a class="headerlink" href="#sub-array-of-regions" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[numRegions</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">region0,</span> <span class="pre">region1,</span> <span class="pre">...]</span></tt></p>
+<p>The mapping regions for a specific file id are stored in an array that is
+sorted in an ascending order by the region’s starting location.</p>
+</div>
+<div class="section" id="id6">
+<h4><a class="toc-backref" href="#id35">Mapping Region</a><a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[header,</span> <span class="pre">source</span> <span class="pre">range]</span></tt></p>
+<p>The mapping region record contains two sub-records —
+the <a class="reference internal" href="#header">header</a>, which stores the counter and/or the region’s kind,
+and the <a class="reference internal" href="#id9">source range</a> that contains the starting and ending
+location of this region.</p>
+</div>
+<div class="section" id="header">
+<span id="id7"></span><h4><a class="toc-backref" href="#id36">Header</a><a class="headerlink" href="#header" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[counter]</span></tt></p>
+<p>or</p>
+<p><tt class="docutils literal"><span class="pre">[pseudo-counter]</span></tt></p>
+<p>The header encodes the region’s counter and the region’s kind.</p>
+<p>The value of the counter’s tag distinguishes between the counters and
+pseudo-counters — if the tag is zero, than this header contains a
+pseudo-counter, otherwise this header contains an ordinary counter.</p>
+<div class="section" id="id8">
+<h5><a class="toc-backref" href="#id37">Counter:</a><a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h5>
+<p>A mapping region whose header has a counter with a non-zero tag is
+a code region.</p>
+</div>
+<div class="section" id="pseudo-counter">
+<h5><a class="toc-backref" href="#id38">Pseudo-Counter:</a><a class="headerlink" href="#pseudo-counter" title="Permalink to this headline">¶</a></h5>
+<p><tt class="docutils literal"><span class="pre">[value</span> <span class="pre">:</span> <span class="pre">LEB128]</span></tt></p>
+<p>A pseudo-counter is stored in a single <a class="reference internal" href="#leb128">LEB value</a>, just like
+the ordinary counter. It has the following interpretation:</p>
+<ul>
+<li><p class="first">bits 0-1: tag, which is always 0.</p>
+</li>
+<li><p class="first">bit 2: expansionRegionTag. If this bit is set, then this mapping region
+is an expansion region.</p>
+</li>
+<li><p class="first">remaining bits: data. If this region is an expansion region, then the data
+contains the expanded file id of that region.</p>
+<p>Otherwise, the data contains the region’s kind. The possible region
+kind values are:</p>
+<ul class="simple">
+<li>0 - This mapping region is a code region with a counter of zero.</li>
+<li>2 - This mapping region is a skipped region.</li>
+</ul>
+</li>
+</ul>
+</div>
+</div>
+<div class="section" id="id9">
+<span id="id10"></span><h4><a class="toc-backref" href="#id39">Source Range</a><a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">[deltaLineStart</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">columnStart</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">numLines</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">columnEnd</span> <span class="pre">:</span> <span class="pre">LEB128]</span></tt></p>
+<p>The source range record contains the following fields:</p>
+<ul>
+<li><p class="first"><em>deltaLineStart</em>: The difference between the starting line of the
+current mapping region and the starting line of the previous mapping region.</p>
+<p>If the current mapping region is the first region in the current
+sub-array, then it stores the starting line of that region.</p>
+</li>
+<li><p class="first"><em>columnStart</em>: The starting column of the mapping region.</p>
+</li>
+<li><p class="first"><em>numLines</em>: The difference between the ending line and the starting line
+of the current mapping region.</p>
+</li>
+<li><p class="first"><em>columnEnd</em>: The ending column of the mapping region. If the high bit is set,
+the current mapping region is a gap area. A count for a gap area is only used
+as the line execution count if there are no other regions on a line.</p>
+</li>
+</ul>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Statepoints.html" title="Garbage Collection Safepoints in LLVM"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="BigEndianNEON.html" title="Using ARM NEON instructions in big endian mode"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/DebuggingJITedCode.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/DebuggingJITedCode.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/DebuggingJITedCode.html (added)
+++ www-releases/trunk/7.0.1/docs/DebuggingJITedCode.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,222 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Debugging JIT-ed Code With GDB — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="The LLVM gold plugin" href="GoldPlugin.html" />
+ <link rel="prev" title="TableGen Deficiencies" href="TableGen/Deficiencies.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="GoldPlugin.html" title="The LLVM gold plugin"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TableGen/Deficiencies.html" title="TableGen Deficiencies"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="debugging-jit-ed-code-with-gdb">
+<h1>Debugging JIT-ed Code With GDB<a class="headerlink" href="#debugging-jit-ed-code-with-gdb" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="background">
+<h2>Background<a class="headerlink" href="#background" title="Permalink to this headline">¶</a></h2>
+<p>Without special runtime support, debugging dynamically generated code with
+GDB (as well as most debuggers) can be quite painful. Debuggers generally
+read debug information from the object file of the code, but for JITed
+code, there is no such file to look for.</p>
+<p>In order to communicate the necessary debug info to GDB, an interface for
+registering JITed code with debuggers has been designed and implemented for
+GDB and LLVM MCJIT. At a high level, whenever MCJIT generates new machine code,
+it does so in an in-memory object file that contains the debug information in
+DWARF format. MCJIT then adds this in-memory object file to a global list of
+dynamically generated object files and calls a special function
+(<tt class="docutils literal"><span class="pre">__jit_debug_register_code</span></tt>) marked noinline that GDB knows about. When
+GDB attaches to a process, it puts a breakpoint in this function and loads all
+of the object files in the global list. When MCJIT calls the registration
+function, GDB catches the breakpoint signal, loads the new object file from
+the inferior’s memory, and resumes the execution. In this way, GDB can get the
+necessary debug information.</p>
+</div>
+<div class="section" id="gdb-version">
+<h2>GDB Version<a class="headerlink" href="#gdb-version" title="Permalink to this headline">¶</a></h2>
+<p>In order to debug code JIT-ed by LLVM, you need GDB 7.0 or newer, which is
+available on most modern distributions of Linux. The version of GDB that
+Apple ships with Xcode has been frozen at 6.3 for a while. LLDB may be a
+better option for debugging JIT-ed code on Mac OS X.</p>
+</div>
+<div class="section" id="debugging-mcjit-ed-code">
+<h2>Debugging MCJIT-ed code<a class="headerlink" href="#debugging-mcjit-ed-code" title="Permalink to this headline">¶</a></h2>
+<p>The emerging MCJIT component of LLVM allows full debugging of JIT-ed code with
+GDB. This is due to MCJIT’s ability to use the MC emitter to provide full
+DWARF debugging information to GDB.</p>
+<p>Note that lli has to be passed the <tt class="docutils literal"><span class="pre">-use-mcjit</span></tt> flag to JIT the code with
+MCJIT instead of the old JIT.</p>
+<div class="section" id="example">
+<h3>Example<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h3>
+<p>Consider the following C code (with line numbers added to make the example
+easier to follow):</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="mi">1</span> <span class="kt">int</span> <span class="n">compute_factorial</span><span class="p">(</span><span class="kt">int</span> <span class="n">n</span><span class="p">)</span>
+<span class="mi">2</span> <span class="p">{</span>
+<span class="mi">3</span> <span class="k">if</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="mi">4</span> <span class="k">return</span> <span class="mi">1</span><span class="p">;</span>
+<span class="mi">5</span>
+<span class="mi">6</span> <span class="kt">int</span> <span class="n">f</span> <span class="o">=</span> <span class="n">n</span><span class="p">;</span>
+<span class="mi">7</span> <span class="k">while</span> <span class="p">(</span><span class="o">--</span><span class="n">n</span> <span class="o">></span> <span class="mi">1</span><span class="p">)</span>
+<span class="mi">8</span> <span class="n">f</span> <span class="o">*=</span> <span class="n">n</span><span class="p">;</span>
+<span class="mi">9</span> <span class="k">return</span> <span class="n">f</span><span class="p">;</span>
+<span class="mi">10</span> <span class="p">}</span>
+<span class="mi">11</span>
+<span class="mi">12</span>
+<span class="mi">13</span> <span class="kt">int</span> <span class="n">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="mi">14</span> <span class="p">{</span>
+<span class="mi">15</span> <span class="k">if</span> <span class="p">(</span><span class="n">argc</span> <span class="o"><</span> <span class="mi">2</span><span class="p">)</span>
+<span class="mi">16</span> <span class="k">return</span> <span class="o">-</span><span class="mi">1</span><span class="p">;</span>
+<span class="mi">17</span> <span class="kt">char</span> <span class="n">firstletter</span> <span class="o">=</span> <span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">][</span><span class="mi">0</span><span class="p">];</span>
+<span class="mi">18</span> <span class="kt">int</span> <span class="n">result</span> <span class="o">=</span> <span class="n">compute_factorial</span><span class="p">(</span><span class="n">firstletter</span> <span class="o">-</span> <span class="sc">'0'</span><span class="p">);</span>
+<span class="mi">19</span>
+<span class="mi">20</span> <span class="c1">// Returned result is clipped at 255...</span>
+<span class="mi">21</span> <span class="k">return</span> <span class="n">result</span><span class="p">;</span>
+<span class="mi">22</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Here is a sample command line session that shows how to build and run this
+code via <tt class="docutils literal"><span class="pre">lli</span></tt> inside GDB:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ $BINPATH</span>/clang -cc1 -O0 -g -emit-llvm showdebug.c
+<span class="nv">$ </span>gdb --quiet --args <span class="nv">$BINPATH</span>/lli -use-mcjit showdebug.ll 5
+Reading symbols from <span class="nv">$BINPATH</span>/lli...done.
+<span class="o">(</span>gdb<span class="o">)</span> b showdebug.c:6
+No <span class="nb">source </span>file named showdebug.c.
+Make breakpoint pending on future shared library load? <span class="o">(</span>y or <span class="o">[</span>n<span class="o">])</span> y
+Breakpoint 1 <span class="o">(</span>showdebug.c:6<span class="o">)</span> pending.
+<span class="o">(</span>gdb<span class="o">)</span> r
+Starting program: <span class="nv">$BINPATH</span>/lli -use-mcjit showdebug.ll 5
+<span class="o">[</span>Thread debugging using libthread_db enabled<span class="o">]</span>
+
+Breakpoint 1, compute_factorial <span class="o">(</span><span class="nv">n</span><span class="o">=</span>5<span class="o">)</span> at showdebug.c:6
+6 int <span class="nv">f</span> <span class="o">=</span> n;
+<span class="o">(</span>gdb<span class="o">)</span> p n
+<span class="nv">$1</span> <span class="o">=</span> 5
+<span class="o">(</span>gdb<span class="o">)</span> p f
+<span class="nv">$2</span> <span class="o">=</span> 0
+<span class="o">(</span>gdb<span class="o">)</span> n
+7 <span class="k">while</span> <span class="o">(</span>--n > 1<span class="o">)</span>
+<span class="o">(</span>gdb<span class="o">)</span> p f
+<span class="nv">$3</span> <span class="o">=</span> 5
+<span class="o">(</span>gdb<span class="o">)</span> b showdebug.c:9
+Breakpoint 2 at 0x7ffff7ed404c: file showdebug.c, line 9.
+<span class="o">(</span>gdb<span class="o">)</span> c
+Continuing.
+
+Breakpoint 2, compute_factorial <span class="o">(</span><span class="nv">n</span><span class="o">=</span>1<span class="o">)</span> at showdebug.c:9
+9 <span class="k">return </span>f;
+<span class="o">(</span>gdb<span class="o">)</span> p f
+<span class="nv">$4</span> <span class="o">=</span> 120
+<span class="o">(</span>gdb<span class="o">)</span> bt
+<span class="c">#0 compute_factorial (n=1) at showdebug.c:9</span>
+<span class="c">#1 0x00007ffff7ed40a9 in main (argc=2, argv=0x16677e0) at showdebug.c:18</span>
+<span class="c">#2 0x3500000001652748 in ?? ()</span>
+<span class="c">#3 0x00000000016677e0 in ?? ()</span>
+<span class="c">#4 0x0000000000000002 in ?? ()</span>
+<span class="c">#5 0x0000000000d953b3 in llvm::MCJIT::runFunction (this=0x16151f0, F=0x1603020, ArgValues=...) at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/MCJIT/MCJIT.cpp:161</span>
+<span class="c">#6 0x0000000000dc8872 in llvm::ExecutionEngine::runFunctionAsMain (this=0x16151f0, Fn=0x1603020, argv=..., envp=0x7fffffffe040)</span>
+ at /home/ebenders_test/llvm_svn_rw/lib/ExecutionEngine/ExecutionEngine.cpp:397
+<span class="c">#7 0x000000000059c583 in main (argc=4, argv=0x7fffffffe018, envp=0x7fffffffe040) at /home/ebenders_test/llvm_svn_rw/tools/lli/lli.cpp:324</span>
+<span class="o">(</span>gdb<span class="o">)</span> finish
+Run till <span class="nb">exit </span>from <span class="c">#0 compute_factorial (n=1) at showdebug.c:9</span>
+0x00007ffff7ed40a9 in main <span class="o">(</span><span class="nv">argc</span><span class="o">=</span>2, <span class="nv">argv</span><span class="o">=</span>0x16677e0<span class="o">)</span> at showdebug.c:18
+18 int <span class="nv">result</span> <span class="o">=</span> compute_factorial<span class="o">(</span>firstletter - <span class="s1">'0'</span><span class="o">)</span>;
+Value returned is <span class="nv">$5</span> <span class="o">=</span> 120
+<span class="o">(</span>gdb<span class="o">)</span> p result
+<span class="nv">$6</span> <span class="o">=</span> 23406408
+<span class="o">(</span>gdb<span class="o">)</span> n
+21 <span class="k">return </span>result;
+<span class="o">(</span>gdb<span class="o">)</span> p result
+<span class="nv">$7</span> <span class="o">=</span> 120
+<span class="o">(</span>gdb<span class="o">)</span> c
+Continuing.
+
+Program exited with code 0170.
+<span class="o">(</span>gdb<span class="o">)</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="GoldPlugin.html" title="The LLVM gold plugin"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TableGen/Deficiencies.html" title="TableGen Deficiencies"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/DeveloperPolicy.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/DeveloperPolicy.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/DeveloperPolicy.html (added)
+++ www-releases/trunk/7.0.1/docs/DeveloperPolicy.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,730 @@
+
+
+<!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 Developer Policy — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Creating an LLVM Project" href="Projects.html" />
+ <link rel="prev" title="Contributing to LLVM" href="Contributing.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Projects.html" title="Creating an LLVM Project"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Contributing.html" title="Contributing to LLVM"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-developer-policy">
+<h1>LLVM Developer Policy<a class="headerlink" href="#llvm-developer-policy" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id9">Introduction</a></li>
+<li><a class="reference internal" href="#developer-policies" id="id10">Developer Policies</a><ul>
+<li><a class="reference internal" href="#stay-informed" id="id11">Stay Informed</a></li>
+<li><a class="reference internal" href="#making-and-submitting-a-patch" id="id12">Making and Submitting a Patch</a></li>
+<li><a class="reference internal" href="#code-reviews" id="id13">Code Reviews</a></li>
+<li><a class="reference internal" href="#code-owners" id="id14">Code Owners</a></li>
+<li><a class="reference internal" href="#test-cases" id="id15">Test Cases</a></li>
+<li><a class="reference internal" href="#quality" id="id16">Quality</a></li>
+<li><a class="reference internal" href="#commit-messages" id="id17">Commit messages</a></li>
+<li><a class="reference internal" href="#obtaining-commit-access" id="id18">Obtaining Commit Access</a></li>
+<li><a class="reference internal" href="#making-a-major-change" id="id19">Making a Major Change</a></li>
+<li><a class="reference internal" href="#incremental-development" id="id20">Incremental Development</a></li>
+<li><a class="reference internal" href="#attribution-of-changes" id="id21">Attribution of Changes</a></li>
+<li><a class="reference internal" href="#ir-backwards-compatibility" id="id22">IR Backwards Compatibility</a></li>
+<li><a class="reference internal" href="#c-api-changes" id="id23">C API Changes</a></li>
+<li><a class="reference internal" href="#new-targets" id="id24">New Targets</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#copyright-license-and-patents" id="id25">Copyright, License, and Patents</a><ul>
+<li><a class="reference internal" href="#copyright" id="id26">Copyright</a></li>
+<li><a class="reference internal" href="#license" id="id27">License</a></li>
+<li><a class="reference internal" href="#patents" id="id28">Patents</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id9">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains the LLVM Developer Policy which defines the project’s
+policy towards developers and their contributions. The intent of this policy is
+to eliminate miscommunication, rework, and confusion that might arise from the
+distributed nature of LLVM’s development. By stating the policy in clear terms,
+we hope each developer can know ahead of time what to expect when making LLVM
+contributions. This policy covers all llvm.org subprojects, including Clang,
+LLDB, libc++, etc.</p>
+<p>This policy is also designed to accomplish the following objectives:</p>
+<ol class="arabic simple">
+<li>Attract both users and developers to the LLVM project.</li>
+<li>Make life as simple and easy for contributors as possible.</li>
+<li>Keep the top of Subversion trees as stable as possible.</li>
+<li>Establish awareness of the project’s <a class="reference internal" href="#copyright-license-patents"><em>copyright, license, and patent
+policies</em></a> with contributors to the project.</li>
+</ol>
+<p>This policy is aimed at frequent contributors to LLVM. People interested in
+contributing one-off patches can do so in an informal way by sending them to the
+<a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-commits">llvm-commits mailing list</a> and engaging another
+developer to see it through the process.</p>
+</div>
+<div class="section" id="developer-policies">
+<h2><a class="toc-backref" href="#id10">Developer Policies</a><a class="headerlink" href="#developer-policies" title="Permalink to this headline">¶</a></h2>
+<p>This section contains policies that pertain to frequent LLVM developers. We
+always welcome <a class="reference internal" href="#one-off-patches">one-off patches</a> from people who do not routinely contribute to
+LLVM, but we expect more from frequent contributors to keep the system as
+efficient as possible for everyone. Frequent LLVM contributors are expected to
+meet the following requirements in order for LLVM to maintain a high standard of
+quality.</p>
+<div class="section" id="stay-informed">
+<h3><a class="toc-backref" href="#id11">Stay Informed</a><a class="headerlink" href="#stay-informed" title="Permalink to this headline">¶</a></h3>
+<p>Developers should stay informed by reading at least the “dev” mailing list for
+the projects you are interested in, such as <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a> for LLVM, <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a> for Clang, or <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/lldb-dev">lldb-dev</a> for LLDB. If you are
+doing anything more than just casual work on LLVM, it is suggested that you also
+subscribe to the “commits” mailing list for the subproject you’re interested in,
+such as <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-commits">llvm-commits</a>, <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/cfe-commits">cfe-commits</a>, or <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/lldb-commits">lldb-commits</a>. Reading the
+“commits” list and paying attention to changes being made by others is a good
+way to see what other people are interested in and watching the flow of the
+project as a whole.</p>
+<p>We recommend that active developers register an email account with <a class="reference external" href="https://bugs.llvm.org/">LLVM
+Bugzilla</a> and preferably subscribe to the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-bugs">llvm-bugs</a> email list to keep track
+of bugs and enhancements occurring in LLVM. We really appreciate people who are
+proactive at catching incoming bugs in their components and dealing with them
+promptly.</p>
+<p>Please be aware that all public LLVM mailing lists are public and archived, and
+that notices of confidentiality or non-disclosure cannot be respected.</p>
+</div>
+<div class="section" id="making-and-submitting-a-patch">
+<span id="one-off-patches"></span><span id="patch"></span><h3><a class="toc-backref" href="#id12">Making and Submitting a Patch</a><a class="headerlink" href="#making-and-submitting-a-patch" title="Permalink to this headline">¶</a></h3>
+<p>When making a patch for review, the goal is to make it as easy for the reviewer
+to read it as possible. As such, we recommend that you:</p>
+<ol class="arabic simple">
+<li>Make your patch against the Subversion trunk, not a branch, and not an old
+version of LLVM. This makes it easy to apply the patch. For information on
+how to check out SVN trunk, please see the <a class="reference external" href="GettingStarted.html#checkout">Getting Started
+Guide</a>.</li>
+<li>Similarly, patches should be submitted soon after they are generated. Old
+patches may not apply correctly if the underlying code changes between the
+time the patch was created and the time it is applied.</li>
+<li>Patches should be made with <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">diff</span></tt>, or similar. If you use a
+different tool, make sure it uses the <tt class="docutils literal"><span class="pre">diff</span> <span class="pre">-u</span></tt> format and that it
+doesn’t contain clutter which makes it hard to read.</li>
+<li>If you are modifying generated files, such as the top-level <tt class="docutils literal"><span class="pre">configure</span></tt>
+script, please separate out those changes into a separate patch from the rest
+of your changes.</li>
+</ol>
+<p>Once your patch is ready, submit it by emailing it to the appropriate project’s
+commit mailing list (or commit it directly if applicable). Alternatively, some
+patches get sent to the project’s development list or component of the LLVM bug
+tracker, but the commit list is the primary place for reviews and should
+generally be preferred.</p>
+<p>When sending a patch to a mailing list, it is a good idea to send it as an
+<em>attachment</em> to the message, not embedded into the text of the message. This
+ensures that your mailer will not mangle the patch when it sends it (e.g. by
+making whitespace changes or by wrapping lines).</p>
+<p><em>For Thunderbird users:</em> Before submitting a patch, please open <em>Preferences >
+Advanced > General > Config Editor</em>, find the key
+<tt class="docutils literal"><span class="pre">mail.content_disposition_type</span></tt>, and set its value to <tt class="docutils literal"><span class="pre">1</span></tt>. Without this
+setting, Thunderbird sends your attachment using <tt class="docutils literal"><span class="pre">Content-Disposition:</span> <span class="pre">inline</span></tt>
+rather than <tt class="docutils literal"><span class="pre">Content-Disposition:</span> <span class="pre">attachment</span></tt>. Apple Mail gamely displays such
+a file inline, making it difficult to work with for reviewers using that
+program.</p>
+<p>When submitting patches, please do not add confidentiality or non-disclosure
+notices to the patches themselves. These notices conflict with the <a class="reference internal" href="#llvm-license">LLVM
+License</a> and may result in your contribution being excluded.</p>
+</div>
+<div class="section" id="code-reviews">
+<span id="code-review"></span><h3><a class="toc-backref" href="#id13">Code Reviews</a><a class="headerlink" href="#code-reviews" title="Permalink to this headline">¶</a></h3>
+<p>LLVM has a code review policy. Code review is one way to increase the quality of
+software. We generally follow these policies:</p>
+<ol class="arabic simple">
+<li>All developers are required to have significant changes reviewed before they
+are committed to the repository.</li>
+<li>Code reviews are conducted by email on the relevant project’s commit mailing
+list, or alternatively on the project’s development list or bug tracker.</li>
+<li>Code can be reviewed either before it is committed or after. We expect major
+changes to be reviewed before being committed, but smaller changes (or
+changes where the developer owns the component) can be reviewed after commit.</li>
+<li>The developer responsible for a code change is also responsible for making
+all necessary review-related changes.</li>
+<li>Code review can be an iterative process, which continues until the patch is
+ready to be committed. Specifically, once a patch is sent out for review, it
+needs an explicit “looks good” before it is submitted. Do not assume silent
+approval, or request active objections to the patch with a deadline.</li>
+</ol>
+<p>Sometimes code reviews will take longer than you would hope for, especially for
+larger features. Accepted ways to speed up review times for your patches are:</p>
+<ul class="simple">
+<li>Review other people’s patches. If you help out, everybody will be more
+willing to do the same for you; goodwill is our currency.</li>
+<li>Ping the patch. If it is urgent, provide reasons why it is important to you to
+get this patch landed and ping it every couple of days. If it is
+not urgent, the common courtesy ping rate is one week. Remember that you’re
+asking for valuable time from other professional developers.</li>
+<li>Ask for help on IRC. Developers on IRC will be able to either help you
+directly, or tell you who might be a good reviewer.</li>
+<li>Split your patch into multiple smaller patches that build on each other. The
+smaller your patch, the higher the probability that somebody will take a quick
+look at it.</li>
+</ul>
+<p>Developers should participate in code reviews as both reviewers and
+reviewees. If someone is kind enough to review your code, you should return the
+favor for someone else. Note that anyone is welcome to review and give feedback
+on a patch, but only people with Subversion write access can approve it.</p>
+<p>There is a web based code review tool that can optionally be used
+for code reviews. See <a class="reference internal" href="Phabricator.html"><em>Code Reviews with Phabricator</em></a>.</p>
+</div>
+<div class="section" id="code-owners">
+<span id="id1"></span><h3><a class="toc-backref" href="#id14">Code Owners</a><a class="headerlink" href="#code-owners" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM Project relies on two features of its process to maintain rapid
+development in addition to the high quality of its source base: the combination
+of code review plus post-commit review for trusted maintainers. Having both is
+a great way for the project to take advantage of the fact that most people do
+the right thing most of the time, and only commit patches without pre-commit
+review when they are confident they are right.</p>
+<p>The trick to this is that the project has to guarantee that all patches that are
+committed are reviewed after they go in: you don’t want everyone to assume
+someone else will review it, allowing the patch to go unreviewed. To solve this
+problem, we have a notion of an ‘owner’ for a piece of the code. The sole
+responsibility of a code owner is to ensure that a commit to their area of the
+code is appropriately reviewed, either by themself or by someone else. The list
+of current code owners can be found in the file
+<a class="reference external" href="http://git.llvm.org/klaus/llvm/blob/master/CODE_OWNERS.TXT">CODE_OWNERS.TXT</a>
+in the root of the LLVM source tree.</p>
+<p>Note that code ownership is completely different than reviewers: anyone can
+review a piece of code, and we welcome code review from anyone who is
+interested. Code owners are the “last line of defense” to guarantee that all
+patches that are committed are actually reviewed.</p>
+<p>Being a code owner is a somewhat unglamorous position, but it is incredibly
+important for the ongoing success of the project. Because people get busy,
+interests change, and unexpected things happen, code ownership is purely opt-in,
+and anyone can choose to resign their “title” at any time. For now, we do not
+have an official policy on how one gets elected to be a code owner.</p>
+</div>
+<div class="section" id="test-cases">
+<span id="include-a-testcase"></span><h3><a class="toc-backref" href="#id15">Test Cases</a><a class="headerlink" href="#test-cases" title="Permalink to this headline">¶</a></h3>
+<p>Developers are required to create test cases for any bugs fixed and any new
+features added. Some tips for getting your testcase approved:</p>
+<ul class="simple">
+<li>All feature and regression test cases are added to the <tt class="docutils literal"><span class="pre">llvm/test</span></tt>
+directory. The appropriate sub-directory should be selected (see the
+<a class="reference internal" href="TestingGuide.html"><em>Testing Guide</em></a> for details).</li>
+<li>Test cases should be written in <a class="reference internal" href="LangRef.html"><em>LLVM assembly language</em></a>.</li>
+<li>Test cases, especially for regressions, should be reduced as much as possible,
+by <a class="reference internal" href="Bugpoint.html"><em>bugpoint</em></a> or manually. It is unacceptable to place an
+entire failing program into <tt class="docutils literal"><span class="pre">llvm/test</span></tt> as this creates a <em>time-to-test</em>
+burden on all developers. Please keep them short.</li>
+</ul>
+<p>Note that llvm/test and clang/test are designed for regression and small feature
+tests only. More extensive test cases (e.g., entire applications, benchmarks,
+etc) should be added to the <tt class="docutils literal"><span class="pre">llvm-test</span></tt> test suite. The llvm-test suite is
+for coverage (correctness, performance, etc) testing, not feature or regression
+testing.</p>
+</div>
+<div class="section" id="quality">
+<h3><a class="toc-backref" href="#id16">Quality</a><a class="headerlink" href="#quality" title="Permalink to this headline">¶</a></h3>
+<p>The minimum quality standards that any change must satisfy before being
+committed to the main development branch are:</p>
+<ol class="arabic simple">
+<li>Code must adhere to the <a class="reference external" href="CodingStandards.html">LLVM Coding Standards</a>.</li>
+<li>Code must compile cleanly (no errors, no warnings) on at least one platform.</li>
+<li>Bug fixes and new features should <a class="reference internal" href="#include-a-testcase">include a testcase</a> so we know if the
+fix/feature ever regresses in the future.</li>
+<li>Code must pass the <tt class="docutils literal"><span class="pre">llvm/test</span></tt> test suite.</li>
+<li>The code must not cause regressions on a reasonable subset of llvm-test,
+where “reasonable” depends on the contributor’s judgement and the scope of
+the change (more invasive changes require more testing). A reasonable subset
+might be something like “<tt class="docutils literal"><span class="pre">llvm-test/MultiSource/Benchmarks</span></tt>”.</li>
+</ol>
+<p>Additionally, the committer is responsible for addressing any problems found in
+the future that the change is responsible for. For example:</p>
+<ul class="simple">
+<li>The code should compile cleanly on all supported platforms.</li>
+<li>The changes should not cause any correctness regressions in the <tt class="docutils literal"><span class="pre">llvm-test</span></tt>
+suite and must not cause any major performance regressions.</li>
+<li>The change set should not cause performance or correctness regressions for the
+LLVM tools.</li>
+<li>The changes should not cause performance or correctness regressions in code
+compiled by LLVM on all applicable targets.</li>
+<li>You are expected to address any <a class="reference external" href="https://bugs.llvm.org/">Bugzilla bugs</a> that
+result from your change.</li>
+</ul>
+<p>We prefer for this to be handled before submission but understand that it isn’t
+possible to test all of this for every submission. Our build bots and nightly
+testing infrastructure normally finds these problems. A good rule of thumb is
+to check the nightly testers for regressions the day after your change. Build
+bots will directly email you if a group of commits that included yours caused a
+failure. You are expected to check the build bot messages to see if they are
+your fault and, if so, fix the breakage.</p>
+<p>Commits that violate these quality standards (e.g. are very broken) may be
+reverted. This is necessary when the change blocks other developers from making
+progress. The developer is welcome to re-commit the change after the problem has
+been fixed.</p>
+</div>
+<div class="section" id="commit-messages">
+<span id="id2"></span><h3><a class="toc-backref" href="#id17">Commit messages</a><a class="headerlink" href="#commit-messages" title="Permalink to this headline">¶</a></h3>
+<p>Although we don’t enforce the format of commit messages, we prefer that
+you follow these guidelines to help review, search in logs, email formatting
+and so on. These guidelines are very similar to rules used by other open source
+projects.</p>
+<p>Most importantly, the contents of the message should be carefully written to
+convey the rationale of the change (without delving too much in detail). It
+also should avoid being vague or overly specific. For example, “bits were not
+set right” will leave the reviewer wondering about which bits, and why they
+weren’t right, while “Correctly set overflow bits in TargetInfo” conveys almost
+all there is to the change.</p>
+<p>Below are some guidelines about the format of the message itself:</p>
+<ul class="simple">
+<li>Separate the commit message into title, body and, if you’re not the original
+author, a “Patch by” attribution line (see below).</li>
+<li>The title should be concise. Because all commits are emailed to the list with
+the first line as the subject, long titles are frowned upon. Short titles
+also look better in <cite>git log</cite>.</li>
+<li>When the changes are restricted to a specific part of the code (e.g. a
+back-end or optimization pass), it is customary to add a tag to the
+beginning of the line in square brackets. For example, “[SCEV] ...”
+or “[OpenMP] ...”. This helps email filters and searches for post-commit
+reviews.</li>
+<li>The body, if it exists, should be separated from the title by an empty line.</li>
+<li>The body should be concise, but explanatory, including a complete
+reasoning. Unless it is required to understand the change, examples,
+code snippets and gory details should be left to bug comments, web
+review or the mailing list.</li>
+<li>If the patch fixes a bug in bugzilla, please include the PR# in the message.</li>
+<li><a class="reference internal" href="#attribution-of-changes">Attribution of Changes</a> should be in a separate line, after the end of
+the body, as simple as “Patch by John Doe.”. This is how we officially
+handle attribution, and there are automated processes that rely on this
+format.</li>
+<li>Text formatting and spelling should follow the same rules as documentation
+and in-code comments, ex. capitalization, full stop, etc.</li>
+<li>If the commit is a bug fix on top of another recently committed patch, or a
+revert or reapply of a patch, include the svn revision number of the prior
+related commit. This could be as simple as “Revert rNNNN because it caused
+PR#”.</li>
+</ul>
+<p>For minor violations of these recommendations, the community normally favors
+reminding the contributor of this policy over reverting. Minor corrections and
+omissions can be handled by sending a reply to the commits mailing list.</p>
+</div>
+<div class="section" id="obtaining-commit-access">
+<h3><a class="toc-backref" href="#id18">Obtaining Commit Access</a><a class="headerlink" href="#obtaining-commit-access" title="Permalink to this headline">¶</a></h3>
+<p>We grant commit access to contributors with a track record of submitting high
+quality patches. If you would like commit access, please send an email to
+<a class="reference external" href="mailto:clattner%40llvm.org">Chris</a> with the following information:</p>
+<ol class="arabic simple">
+<li>The user name you want to commit with, e.g. “hacker”.</li>
+<li>The full name and email address you want message to llvm-commits to come
+from, e.g. “J. Random Hacker <<a class="reference external" href="mailto:hacker%40yoyodyne.com">hacker<span>@</span>yoyodyne<span>.</span>com</a>>”.</li>
+<li>A “password hash” of the password you want to use, e.g. “<tt class="docutils literal"><span class="pre">2ACR96qjUqsyM</span></tt>”.
+Note that you don’t ever tell us what your password is; you just give it to
+us in an encrypted form. To get this, run “<tt class="docutils literal"><span class="pre">htpasswd</span></tt>” (a utility that
+comes with apache) in <em>crypt</em> mode (often enabled with “<tt class="docutils literal"><span class="pre">-d</span></tt>”), or find a web
+page that will do it for you. Note that our system does not work with MD5
+hashes. These are significantly longer than a crypt hash - e.g.
+“<tt class="docutils literal"><span class="pre">$apr1$vea6bBV2$Z8IFx.AfeD8LhqlZFqJer0</span></tt>”, we only accept the shorter crypt hash.</li>
+</ol>
+<p>Once you’ve been granted commit access, you should be able to check out an LLVM
+tree with an SVN URL of “<a class="reference external" href="https://username@llvm.org/">https://username@llvm.org/</a>...” instead of the normal
+anonymous URL of “<a class="reference external" href="http://llvm.org/">http://llvm.org/</a>...”. The first time you commit you’ll have
+to type in your password. Note that you may get a warning from SVN about an
+untrusted key; you can ignore this. To verify that your commit access works,
+please do a test commit (e.g. change a comment or add a blank line). Your first
+commit to a repository may require the autogenerated email to be approved by a
+mailing list. This is normal and will be done when the mailing list owner has
+time.</p>
+<p>If you have recently been granted commit access, these policies apply:</p>
+<ol class="arabic simple">
+<li>You are granted <em>commit-after-approval</em> to all parts of LLVM. To get
+approval, submit a <a class="reference internal" href="#patch">patch</a> to <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-commits">llvm-commits</a>. When approved,
+you may commit it yourself.</li>
+<li>You are allowed to commit patches without approval which you think are
+obvious. This is clearly a subjective decision — we simply expect you to
+use good judgement. Examples include: fixing build breakage, reverting
+obviously broken patches, documentation/comment changes, any other minor
+changes.</li>
+<li>You are allowed to commit patches without approval to those portions of LLVM
+that you have contributed or maintain (i.e., have been assigned
+responsibility for), with the proviso that such commits must not break the
+build. This is a “trust but verify” policy, and commits of this nature are
+reviewed after they are committed.</li>
+<li>Multiple violations of these policies or a single egregious violation may
+cause commit access to be revoked.</li>
+</ol>
+<p>In any case, your changes are still subject to <a class="reference internal" href="#code-review">code review</a> (either before or
+after they are committed, depending on the nature of the change). You are
+encouraged to review other peoples’ patches as well, but you aren’t required
+to do so.</p>
+</div>
+<div class="section" id="making-a-major-change">
+<span id="discuss-the-change-gather-consensus"></span><h3><a class="toc-backref" href="#id19">Making a Major Change</a><a class="headerlink" href="#making-a-major-change" title="Permalink to this headline">¶</a></h3>
+<p>When a developer begins a major new project with the aim of contributing it back
+to LLVM, they should inform the community with an email to the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a> email list, to the extent
+possible. The reason for this is to:</p>
+<ol class="arabic simple">
+<li>keep the community informed about future changes to LLVM,</li>
+<li>avoid duplication of effort by preventing multiple parties working on the
+same thing and not knowing about it, and</li>
+<li>ensure that any technical issues around the proposed work are discussed and
+resolved before any significant work is done.</li>
+</ol>
+<p>The design of LLVM is carefully controlled to ensure that all the pieces fit
+together well and are as consistent as possible. If you plan to make a major
+change to the way LLVM works or want to add a major new extension, it is a good
+idea to get consensus with the development community before you start working on
+it.</p>
+<p>Once the design of the new feature is finalized, the work itself should be done
+as a series of <a class="reference internal" href="#incremental-changes">incremental changes</a>, not as a long-term development branch.</p>
+</div>
+<div class="section" id="incremental-development">
+<span id="incremental-changes"></span><h3><a class="toc-backref" href="#id20">Incremental Development</a><a class="headerlink" href="#incremental-development" title="Permalink to this headline">¶</a></h3>
+<p>In the LLVM project, we do all significant changes as a series of incremental
+patches. We have a strong dislike for huge changes or long-term development
+branches. Long-term development branches have a number of drawbacks:</p>
+<ol class="arabic simple">
+<li>Branches must have mainline merged into them periodically. If the branch
+development and mainline development occur in the same pieces of code,
+resolving merge conflicts can take a lot of time.</li>
+<li>Other people in the community tend to ignore work on branches.</li>
+<li>Huge changes (produced when a branch is merged back onto mainline) are
+extremely difficult to <a class="reference internal" href="#code-review">code review</a>.</li>
+<li>Branches are not routinely tested by our nightly tester infrastructure.</li>
+<li>Changes developed as monolithic large changes often don’t work until the
+entire set of changes is done. Breaking it down into a set of smaller
+changes increases the odds that any of the work will be committed to the main
+repository.</li>
+</ol>
+<p>To address these problems, LLVM uses an incremental development style and we
+require contributors to follow this practice when making a large/invasive
+change. Some tips:</p>
+<ul class="simple">
+<li>Large/invasive changes usually have a number of secondary changes that are
+required before the big change can be made (e.g. API cleanup, etc). These
+sorts of changes can often be done before the major change is done,
+independently of that work.</li>
+<li>The remaining inter-related work should be decomposed into unrelated sets of
+changes if possible. Once this is done, define the first increment and get
+consensus on what the end goal of the change is.</li>
+<li>Each change in the set can be stand alone (e.g. to fix a bug), or part of a
+planned series of changes that works towards the development goal.</li>
+<li>Each change should be kept as small as possible. This simplifies your work
+(into a logical progression), simplifies code review and reduces the chance
+that you will get negative feedback on the change. Small increments also
+facilitate the maintenance of a high quality code base.</li>
+<li>Often, an independent precursor to a big change is to add a new API and slowly
+migrate clients to use the new API. Each change to use the new API is often
+“obvious” and can be committed without review. Once the new API is in place
+and used, it is much easier to replace the underlying implementation of the
+API. This implementation change is logically separate from the API
+change.</li>
+</ul>
+<p>If you are interested in making a large change, and this scares you, please make
+sure to first <a class="reference internal" href="#discuss-the-change-gather-consensus">discuss the change/gather consensus</a> then ask about the best way
+to go about making the change.</p>
+</div>
+<div class="section" id="attribution-of-changes">
+<h3><a class="toc-backref" href="#id21">Attribution of Changes</a><a class="headerlink" href="#attribution-of-changes" title="Permalink to this headline">¶</a></h3>
+<p>When contributors submit a patch to an LLVM project, other developers with
+commit access may commit it for the author once appropriate (based on the
+progression of code review, etc.). When doing so, it is important to retain
+correct attribution of contributions to their contributors. However, we do not
+want the source code to be littered with random attributions “this code written
+by J. Random Hacker” (this is noisy and distracting). In practice, the revision
+control system keeps a perfect history of who changed what, and the CREDITS.txt
+file describes higher-level contributions. If you commit a patch for someone
+else, please follow the attribution of changes in the simple manner as outlined
+by the <a class="reference internal" href="#commit-messages">commit messages</a> section. Overall, please do not add contributor names
+to the source code.</p>
+<p>Also, don’t commit patches authored by others unless they have submitted the
+patch to the project or you have been authorized to submit them on their behalf
+(you work together and your company authorized you to contribute the patches,
+etc.). The author should first submit them to the relevant project’s commit
+list, development list, or LLVM bug tracker component. If someone sends you
+a patch privately, encourage them to submit it to the appropriate list first.</p>
+</div>
+<div class="section" id="ir-backwards-compatibility">
+<span id="id5"></span><h3><a class="toc-backref" href="#id22">IR Backwards Compatibility</a><a class="headerlink" href="#ir-backwards-compatibility" title="Permalink to this headline">¶</a></h3>
+<p>When the IR format has to be changed, keep in mind that we try to maintain some
+backwards compatibility. The rules are intended as a balance between convenience
+for llvm users and not imposing a big burden on llvm developers:</p>
+<ul class="simple">
+<li>The textual format is not backwards compatible. We don’t change it too often,
+but there are no specific promises.</li>
+<li>Additions and changes to the IR should be reflected in
+<tt class="docutils literal"><span class="pre">test/Bitcode/compatibility.ll</span></tt>.</li>
+<li>The current LLVM version supports loading any bitcode since version 3.0.</li>
+<li>After each X.Y release, <tt class="docutils literal"><span class="pre">compatibility.ll</span></tt> must be copied to
+<tt class="docutils literal"><span class="pre">compatibility-X.Y.ll</span></tt>. The corresponding bitcode file should be assembled
+using the X.Y build and committed as <tt class="docutils literal"><span class="pre">compatibility-X.Y.ll.bc</span></tt>.</li>
+<li>Newer releases can ignore features from older releases, but they cannot
+miscompile them. For example, if nsw is ever replaced with something else,
+dropping it would be a valid way to upgrade the IR.</li>
+<li>Debug metadata is special in that it is currently dropped during upgrades.</li>
+<li>Non-debug metadata is defined to be safe to drop, so a valid way to upgrade
+it is to drop it. That is not very user friendly and a bit more effort is
+expected, but no promises are made.</li>
+</ul>
+</div>
+<div class="section" id="c-api-changes">
+<h3><a class="toc-backref" href="#id23">C API Changes</a><a class="headerlink" href="#c-api-changes" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Stability Guarantees: The C API is, in general, a “best effort” for stability.
+This means that we make every attempt to keep the C API stable, but that
+stability will be limited by the abstractness of the interface and the
+stability of the C++ API that it wraps. In practice, this means that things
+like “create debug info” or “create this type of instruction” are likely to be
+less stable than “take this IR file and JIT it for my current machine”.</li>
+<li>Release stability: We won’t break the C API on the release branch with patches
+that go on that branch, with the exception that we will fix an unintentional
+C API break that will keep the release consistent with both the previous and
+next release.</li>
+<li>Testing: Patches to the C API are expected to come with tests just like any
+other patch.</li>
+<li>Including new things into the API: If an LLVM subcomponent has a C API already
+included, then expanding that C API is acceptable. Adding C API for
+subcomponents that don’t currently have one needs to be discussed on the
+mailing list for design and maintainability feedback prior to implementation.</li>
+<li>Documentation: Any changes to the C API are required to be documented in the
+release notes so that it’s clear to external users who do not follow the
+project how the C API is changing and evolving.</li>
+</ul>
+</div>
+<div class="section" id="new-targets">
+<h3><a class="toc-backref" href="#id24">New Targets</a><a class="headerlink" href="#new-targets" title="Permalink to this headline">¶</a></h3>
+<p>LLVM is very receptive to new targets, even experimental ones, but a number of
+problems can appear when adding new large portions of code, and back-ends are
+normally added in bulk. We have found that landing large pieces of new code
+and then trying to fix emergent problems in-tree is problematic for a variety
+of reasons.</p>
+<p>For these reasons, new targets are <em>always</em> added as <em>experimental</em> until
+they can be proven stable, and later moved to non-experimental. The difference
+between both classes is that experimental targets are not built by default
+(need to be added to -DLLVM_TARGETS_TO_BUILD at CMake time).</p>
+<p>The basic rules for a back-end to be upstreamed in <strong>experimental</strong> mode are:</p>
+<ul class="simple">
+<li>Every target must have a <a class="reference internal" href="#code-owners"><em>code owner</em></a>. The <cite>CODE_OWNERS.TXT</cite>
+file has to be updated as part of the first merge. The code owner makes sure
+that changes to the target get reviewed and steers the overall effort.</li>
+<li>There must be an active community behind the target. This community
+will help maintain the target by providing buildbots, fixing
+bugs, answering the LLVM community’s questions and making sure the new
+target doesn’t break any of the other targets, or generic code. This
+behavior is expected to continue throughout the lifetime of the
+target’s code.</li>
+<li>The code must be free of contentious issues, for example, large
+changes in how the IR behaves or should be formed by the front-ends,
+unless agreed by the majority of the community via refactoring of the
+(<a class="reference internal" href="LangRef.html"><em>IR standard</em></a>) <strong>before</strong> the merge of the new target changes,
+following the <a class="reference internal" href="#ir-backwards-compatibility"><em>IR Backwards Compatibility</em></a>.</li>
+<li>The code conforms to all of the policies laid out in this developer policy
+document, including license, patent, and coding standards.</li>
+<li>The target should have either reasonable documentation on how it
+works (ISA, ABI, etc.) or a publicly available simulator/hardware
+(either free or cheap enough) - preferably both. This allows
+developers to validate assumptions, understand constraints and review code
+that can affect the target.</li>
+</ul>
+<p>In addition, the rules for a back-end to be promoted to <strong>official</strong> are:</p>
+<ul class="simple">
+<li>The target must have addressed every other minimum requirement and
+have been stable in tree for at least 3 months. This cool down
+period is to make sure that the back-end and the target community can
+endure continuous upstream development for the foreseeable future.</li>
+<li>The target’s code must have been completely adapted to this policy
+as well as the <a class="reference internal" href="CodingStandards.html"><em>coding standards</em></a>. Any exceptions that
+were made to move into experimental mode must have been fixed <strong>before</strong>
+becoming official.</li>
+<li>The test coverage needs to be broad and well written (small tests,
+well documented). The build target <tt class="docutils literal"><span class="pre">check-all</span></tt> must pass with the
+new target built, and where applicable, the <tt class="docutils literal"><span class="pre">test-suite</span></tt> must also
+pass without errors, in at least one configuration (publicly
+demonstrated, for example, via buildbots).</li>
+<li>Public buildbots need to be created and actively maintained, unless
+the target requires no additional buildbots (ex. <tt class="docutils literal"><span class="pre">check-all</span></tt> covers
+all tests). The more relevant and public the new target’s CI infrastructure
+is, the more the LLVM community will embrace it.</li>
+</ul>
+<p>To <strong>continue</strong> as a supported and official target:</p>
+<ul class="simple">
+<li>The maintainer(s) must continue following these rules throughout the lifetime
+of the target. Continuous violations of aforementioned rules and policies
+could lead to complete removal of the target from the code base.</li>
+<li>Degradation in support, documentation or test coverage will make the target as
+nuisance to other targets and be considered a candidate for deprecation and
+ultimately removed.</li>
+</ul>
+<p>In essences, these rules are necessary for targets to gain and retain their
+status, but also markers to define bit-rot, and will be used to clean up the
+tree from unmaintained targets.</p>
+</div>
+</div>
+<div class="section" id="copyright-license-and-patents">
+<span id="copyright-license-patents"></span><h2><a class="toc-backref" href="#id25">Copyright, License, and Patents</a><a class="headerlink" href="#copyright-license-and-patents" title="Permalink to this headline">¶</a></h2>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This section deals with legal matters but does not provide legal advice. We
+are not lawyers — please seek legal counsel from an attorney.</p>
+</div>
+<p>This section addresses the issues of copyright, license and patents for the LLVM
+project. The copyright for the code is held by the individual contributors of
+the code and the terms of its license to LLVM users and developers is the
+<a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">University of Illinois/NCSA Open Source License</a> (with portions dual licensed
+under the <a class="reference external" href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>,
+see below). As contributor to the LLVM project, you agree to allow any
+contributions to the project to licensed under these terms.</p>
+<div class="section" id="copyright">
+<h3><a class="toc-backref" href="#id26">Copyright</a><a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM project does not require copyright assignments, which means that the
+copyright for the code in the project is held by its respective contributors who
+have each agreed to release their contributed code under the terms of the <a class="reference internal" href="#llvm-license">LLVM
+License</a>.</p>
+<p>An implication of this is that the LLVM license is unlikely to ever change:
+changing it would require tracking down all the contributors to LLVM and getting
+them to agree that a license change is acceptable for their contribution. Since
+there are no plans to change the license, this is not a cause for concern.</p>
+<p>As a contributor to the project, this means that you (or your company) retain
+ownership of the code you contribute, that it cannot be used in a way that
+contradicts the license (which is a liberal BSD-style license), and that the
+license for your contributions won’t change without your approval in the
+future.</p>
+</div>
+<div class="section" id="license">
+<span id="llvm-license"></span><h3><a class="toc-backref" href="#id27">License</a><a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h3>
+<p>We intend to keep LLVM perpetually open source and to use a liberal open source
+license. <strong>As a contributor to the project, you agree that any contributions be
+licensed under the terms of the corresponding subproject.</strong> All of the code in
+LLVM is available under the <a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">University of Illinois/NCSA Open Source License</a>, which boils down to
+this:</p>
+<ul class="simple">
+<li>You can freely distribute LLVM.</li>
+<li>You must retain the copyright notice if you redistribute LLVM.</li>
+<li>Binaries derived from LLVM must reproduce the copyright notice (e.g. in an
+included readme file).</li>
+<li>You can’t use our names to promote your LLVM derived products.</li>
+<li>There’s no warranty on LLVM at all.</li>
+</ul>
+<p>We believe this fosters the widest adoption of LLVM because it <strong>allows
+commercial products to be derived from LLVM</strong> with few restrictions and without
+a requirement for making any derived works also open source (i.e. LLVM’s
+license is not a “copyleft” license like the GPL). We suggest that you read the
+<a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">License</a> if further
+clarification is needed.</p>
+<p>In addition to the UIUC license, the runtime library components of LLVM
+(<strong>compiler_rt, libc++, and libclc</strong>) are also licensed under the <a class="reference external" href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>, which does not contain
+the binary redistribution clause. As a user of these runtime libraries, it
+means that you can choose to use the code under either license (and thus don’t
+need the binary redistribution clause), and as a contributor to the code that
+you agree that any contributions to these libraries be licensed under both
+licenses. We feel that this is important for runtime libraries, because they
+are implicitly linked into applications and therefore should not subject those
+applications to the binary redistribution clause. This also means that it is ok
+to move code from (e.g.) libc++ to the LLVM core without concern, but that code
+cannot be moved from the LLVM core to libc++ without the copyright owner’s
+permission.</p>
+<p>Note that the LLVM Project does distribute dragonegg, <strong>which is
+GPL.</strong> This means that anything “linked” into dragonegg must itself be compatible
+with the GPL, and must be releasable under the terms of the GPL. This implies
+that <strong>any code linked into dragonegg and distributed to others may be subject to
+the viral aspects of the GPL</strong> (for example, a proprietary code generator linked
+into dragonegg must be made available under the GPL). This is not a problem for
+code already distributed under a more liberal license (like the UIUC license),
+and GPL-containing subprojects are kept in separate SVN repositories whose
+LICENSE.txt files specifically indicate that they contain GPL code.</p>
+<p>We have no plans to change the license of LLVM. If you have questions or
+comments about the license, please contact the <a class="reference external" href="mailto:llvm-dev%40lists.llvm.org">LLVM Developer's Mailing
+List</a>.</p>
+</div>
+<div class="section" id="patents">
+<h3><a class="toc-backref" href="#id28">Patents</a><a class="headerlink" href="#patents" title="Permalink to this headline">¶</a></h3>
+<p>To the best of our knowledge, LLVM does not infringe on any patents (we have
+actually removed code from LLVM in the past that was found to infringe). Having
+code in LLVM that infringes on patents would violate an important goal of the
+project by making it hard or impossible to reuse the code for arbitrary purposes
+(including commercial use).</p>
+<p>When contributing code, we expect contributors to notify us of any potential for
+patent-related trouble with their changes (including from third parties). If
+you or your employer own the rights to a patent and would like to contribute
+code to LLVM that relies on it, we require that the copyright owner sign an
+agreement that allows any other user of LLVM to freely use your patent. Please
+contact the <a class="reference external" href="mailto:board%40llvm.org">LLVM Foundation Board of Directors</a> for more
+details.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Projects.html" title="Creating an LLVM Project"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Contributing.html" title="Contributing to LLVM"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/Docker.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/Docker.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/Docker.html (added)
+++ www-releases/trunk/7.0.1/docs/Docker.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,259 @@
+
+
+<!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>A guide to Dockerfiles for building LLVM — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="LLVM Atomic Instructions and Concurrency Guide" href="Atomics.html" />
+ <link rel="prev" title="Benchmarking tips" href="Benchmarking.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Atomics.html" title="LLVM Atomic Instructions and Concurrency Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="Benchmarking.html" title="Benchmarking tips"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="a-guide-to-dockerfiles-for-building-llvm">
+<h1>A guide to Dockerfiles for building LLVM<a class="headerlink" href="#a-guide-to-dockerfiles-for-building-llvm" 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>You can find a number of sources to build docker images with LLVM components in
+<tt class="docutils literal"><span class="pre">llvm/utils/docker</span></tt>. They can be used by anyone who wants to build the docker
+images for their own use, or as a starting point for someone who wants to write
+their own Dockerfiles.</p>
+<p>We currently provide Dockerfiles with <tt class="docutils literal"><span class="pre">debian8</span></tt> and <tt class="docutils literal"><span class="pre">nvidia-cuda</span></tt> base images.
+We also provide an <tt class="docutils literal"><span class="pre">example</span></tt> image, which contains placeholders that one would need
+to fill out in order to produce Dockerfiles for a new docker image.</p>
+<div class="section" id="why">
+<h3>Why?<a class="headerlink" href="#why" title="Permalink to this headline">¶</a></h3>
+<p>Docker images provide a way to produce binary distributions of
+software inside a controlled environment. Having Dockerfiles to builds docker images
+inside LLVM repo makes them much more discoverable than putting them into any other
+place.</p>
+</div>
+<div class="section" id="docker-basics">
+<h3>Docker basics<a class="headerlink" href="#docker-basics" title="Permalink to this headline">¶</a></h3>
+<p>If you’ve never heard about Docker before, you might find this section helpful
+to get a very basic explanation of it.
+<a class="reference external" href="https://www.docker.com/">Docker</a> is a popular solution for running programs in
+an isolated and reproducible environment, especially to maintain releases for
+software deployed to large distributed fleets.
+It uses linux kernel namespaces and cgroups to provide a lightweight isolation
+inside currently running linux kernel.
+A single active instance of dockerized environment is called a <em>docker
+container</em>.
+A snapshot of a docker container filesystem is called a <em>docker image</em>.
+One can start a container from a prebuilt docker image.</p>
+<p>Docker images are built from a so-called <em>Dockerfile</em>, a source file written in
+a specialized language that defines instructions to be used when build
+the docker image (see <a class="reference external" href="https://docs.docker.com/engine/reference/builder/">official
+documentation</a> for more
+details). A minimal Dockerfile typically contains a base image and a number
+of RUN commands that have to be executed to build the image. When building a new
+image, docker will first download your base image, mount its filesystem as
+read-only and then add a writable overlay on top of it to keep track of all
+filesystem modifications, performed while building your image. When the build
+process is finished, a diff between your image’s final filesystem state and the
+base image’s filesystem is stored in the resulting image.</p>
+</div>
+</div>
+<div class="section" id="overview">
+<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">llvm/utils/docker</span></tt> folder contains Dockerfiles and simple bash scripts to
+serve as a basis for anyone who wants to create their own Docker image with
+LLVM components, compiled from sources. The sources are checked out from the
+upstream svn repository when building the image.</p>
+<p>The resulting image contains only the requested LLVM components and a few extra
+packages to make the image minimally useful for C++ development, e.g. libstdc++
+and binutils.</p>
+<p>The interface to run the build is <tt class="docutils literal"><span class="pre">build_docker_image.sh</span></tt> script. It accepts a
+list of LLVM repositories to checkout and arguments for CMake invocation.</p>
+<p>If you want to write your own docker image, start with an <tt class="docutils literal"><span class="pre">example/</span></tt> subfolder.
+It provides an incomplete Dockerfile with (very few) FIXMEs explaining the steps
+you need to take in order to make your Dockerfiles functional.</p>
+</div>
+<div class="section" id="usage">
+<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">llvm/utils/build_docker_image.sh</span></tt> script provides a rather high degree of
+control on how to run the build. It allows you to specify the projects to
+checkout from svn and provide a list of CMake arguments to use during when
+building LLVM inside docker container.</p>
+<p>Here’s a very simple example of getting a docker image with clang binary,
+compiled by the system compiler in the debian8 image:</p>
+<div class="highlight-bash"><div class="highlight"><pre>./llvm/utils/docker/build_docker_image.sh <span class="se">\</span>
+ --source debian8 <span class="se">\</span>
+ --docker-repository clang-debian8 --docker-tag <span class="s2">"staging"</span> <span class="se">\</span>
+ -p clang -i install-clang -i install-clang-headers <span class="se">\</span>
+ -- <span class="se">\</span>
+ -DCMAKE_BUILD_TYPE<span class="o">=</span>Release
+</pre></div>
+</div>
+<p>Note that a build like that doesn’t use a 2-stage build process that
+you probably want for clang. Running a 2-stage build is a little more intricate,
+this command will do that:</p>
+<div class="highlight-bash"><div class="highlight"><pre><span class="c"># Run a 2-stage build.</span>
+<span class="c"># LLVM_TARGETS_TO_BUILD=Native is to reduce stage1 compile time.</span>
+<span class="c"># Options, starting with BOOTSTRAP_* are passed to stage2 cmake invocation.</span>
+./build_docker_image.sh <span class="se">\</span>
+ --source debian8 <span class="se">\</span>
+ --docker-repository clang-debian8 --docker-tag <span class="s2">"staging"</span> <span class="se">\</span>
+ -p clang -i stage2-install-clang -i stage2-install-clang-headers <span class="se">\</span>
+ -- <span class="se">\</span>
+ -DLLVM_TARGETS_TO_BUILD<span class="o">=</span>Native -DCMAKE_BUILD_TYPE<span class="o">=</span>Release <span class="se">\</span>
+ -DBOOTSTRAP_CMAKE_BUILD_TYPE<span class="o">=</span>Release <span class="se">\</span>
+ -DCLANG_ENABLE_BOOTSTRAP<span class="o">=</span>ON -DCLANG_BOOTSTRAP_TARGETS<span class="o">=</span><span class="s2">"install-clang;install-clang-headers"</span>
+</pre></div>
+</div>
+<p>This will produce a new image <tt class="docutils literal"><span class="pre">clang-debian8:staging</span></tt> from the latest
+upstream revision.
+After the image is built you can run bash inside a container based on your image
+like this:</p>
+<div class="highlight-bash"><div class="highlight"><pre>docker run -ti clang-debian8:staging bash
+</pre></div>
+</div>
+<p>Now you can run bash commands as you normally would:</p>
+<div class="highlight-bash"><div class="highlight"><pre>root at 80f351b51825:/# clang -v
+clang version 5.0.0 <span class="o">(</span>trunk 305064<span class="o">)</span>
+Target: x86_64-unknown-linux-gnu
+Thread model: posix
+InstalledDir: /bin
+Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.8
+Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.8.4
+Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.9
+Found candidate GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.9.2
+Selected GCC installation: /usr/lib/gcc/x86_64-linux-gnu/4.9
+Candidate multilib: .;@m64
+Selected multilib: .;@m64
+</pre></div>
+</div>
+</div>
+<div class="section" id="which-image-should-i-choose">
+<h2>Which image should I choose?<a class="headerlink" href="#which-image-should-i-choose" title="Permalink to this headline">¶</a></h2>
+<p>We currently provide two images: debian8-based and nvidia-cuda-based. They
+differ in the base image that they use, i.e. they have a different set of
+preinstalled binaries. Debian8 is very minimal, nvidia-cuda is larger, but has
+preinstalled CUDA libraries and allows to access a GPU, installed on your
+machine.</p>
+<p>If you need a minimal linux distribution with only clang and libstdc++ included,
+you should try debian8-based image.</p>
+<p>If you want to use CUDA libraries and have access to a GPU on your machine,
+you should choose nvidia-cuda-based image and use <a class="reference external" href="https://github.com/NVIDIA/nvidia-docker">nvidia-docker</a> to run your docker containers. Note
+that you don’t need nvidia-docker to build the images, but you need it in order
+to have an access to GPU from a docker container that is running the built
+image.</p>
+<p>If you have a different use-case, you could create your own image based on
+<tt class="docutils literal"><span class="pre">example/</span></tt> folder.</p>
+<p>Any docker image can be built and run using only the docker binary, i.e. you can
+run debian8 build on Fedora or any other Linux distribution. You don’t need to
+install CMake, compilers or any other clang dependencies. It is all handled
+during the build process inside Docker’s isolated environment.</p>
+</div>
+<div class="section" id="stable-build">
+<h2>Stable build<a class="headerlink" href="#stable-build" title="Permalink to this headline">¶</a></h2>
+<p>If you want a somewhat recent and somewhat stable build, use the
+<tt class="docutils literal"><span class="pre">branches/google/stable</span></tt> branch, i.e. the following command will produce a
+debian8-based image using the latest <tt class="docutils literal"><span class="pre">google/stable</span></tt> sources for you:</p>
+<div class="highlight-bash"><div class="highlight"><pre>./llvm/utils/docker/build_docker_image.sh <span class="se">\</span>
+ -s debian8 --d clang-debian8 -t <span class="s2">"staging"</span> <span class="se">\</span>
+ --branch branches/google/stable <span class="se">\</span>
+ -p clang -i install-clang -i install-clang-headers <span class="se">\</span>
+ -- <span class="se">\</span>
+ -DCMAKE_BUILD_TYPE<span class="o">=</span>Release
+</pre></div>
+</div>
+</div>
+<div class="section" id="minimizing-docker-image-size">
+<h2>Minimizing docker image size<a class="headerlink" href="#minimizing-docker-image-size" title="Permalink to this headline">¶</a></h2>
+<p>Due to how Docker’s filesystem works, all intermediate writes are persisted in
+the resulting image, even if they are removed in the following commands.
+To minimize the resulting image size we use <a class="reference external" href="https://docs.docker.com/develop/develop-images/multistage-build/">multi-stage Docker builds</a>.
+Internally Docker builds two images. The first image does all the work: installs
+build dependencies, checks out LLVM source code, compiles LLVM, etc.
+The first image is only used during build and does not have a descriptive name,
+i.e. it is only accessible via the hash value after the build is finished.
+The second image is our resulting image. It contains only the built binaries
+and not any build dependencies. It is also accessible via a descriptive name
+(specified by -d and -t flags).</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Atomics.html" title="LLVM Atomic Instructions and Concurrency Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Benchmarking.html" title="Benchmarking tips"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/ExceptionHandling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/ExceptionHandling.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/ExceptionHandling.html (added)
+++ www-releases/trunk/7.0.1/docs/ExceptionHandling.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,926 @@
+
+
+<!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>Exception Handling in LLVM — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="LLVM Link Time Optimization: Design and Implementation" href="LinkTimeOptimization.html" />
+ <link rel="prev" title="The LLVM Target-Independent Code Generator" href="CodeGenerator.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CodeGenerator.html" title="The LLVM Target-Independent Code Generator"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="exception-handling-in-llvm">
+<h1>Exception Handling in LLVM<a class="headerlink" href="#exception-handling-in-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id8">Introduction</a><ul>
+<li><a class="reference internal" href="#itanium-abi-zero-cost-exception-handling" id="id9">Itanium ABI Zero-cost Exception Handling</a></li>
+<li><a class="reference internal" href="#setjmp-longjmp-exception-handling" id="id10">Setjmp/Longjmp Exception Handling</a></li>
+<li><a class="reference internal" href="#windows-runtime-exception-handling" id="id11">Windows Runtime Exception Handling</a></li>
+<li><a class="reference internal" href="#overview" id="id12">Overview</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#llvm-code-generation" id="id13">LLVM Code Generation</a><ul>
+<li><a class="reference internal" href="#throw" id="id14">Throw</a></li>
+<li><a class="reference internal" href="#try-catch" id="id15">Try/Catch</a></li>
+<li><a class="reference internal" href="#cleanups" id="id16">Cleanups</a></li>
+<li><a class="reference internal" href="#throw-filters" id="id17">Throw Filters</a></li>
+<li><a class="reference internal" href="#restrictions" id="id18">Restrictions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#exception-handling-intrinsics" id="id19">Exception Handling Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-eh-typeid-for" id="id20"><tt class="docutils literal"><span class="pre">llvm.eh.typeid.for</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-begincatch" id="id21"><tt class="docutils literal"><span class="pre">llvm.eh.begincatch</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-endcatch" id="id22"><tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-exceptionpointer" id="id23"><tt class="docutils literal"><span class="pre">llvm.eh.exceptionpointer</span></tt></a></li>
+<li><a class="reference internal" href="#sjlj-intrinsics" id="id24">SJLJ Intrinsics</a><ul>
+<li><a class="reference internal" href="#llvm-eh-sjlj-setjmp" id="id25"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.setjmp</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-longjmp" id="id26"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.longjmp</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-lsda" id="id27"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.lsda</span></tt></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-callsite" id="id28"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.callsite</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#asm-table-formats" id="id29">Asm Table Formats</a><ul>
+<li><a class="reference internal" href="#exception-handling-frame" id="id30">Exception Handling Frame</a></li>
+<li><a class="reference internal" href="#exception-tables" id="id31">Exception Tables</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#exception-handling-using-the-windows-runtime" id="id32">Exception Handling using the Windows Runtime</a><ul>
+<li><a class="reference internal" href="#background-on-windows-exceptions" id="id33">Background on Windows exceptions</a></li>
+<li><a class="reference internal" href="#seh-filter-expressions" id="id34">SEH filter expressions</a></li>
+<li><a class="reference internal" href="#new-exception-handling-instructions" id="id35">New exception handling instructions</a></li>
+<li><a class="reference internal" href="#funclet-parent-tokens" id="id36">Funclet parent tokens</a></li>
+<li><a class="reference internal" href="#funclet-transitions" id="id37">Funclet transitions</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#exception-handling-support-on-the-target" id="id38">Exception Handling support on the target</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id8">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document is the central repository for all information pertaining to
+exception handling in LLVM. It describes the format that LLVM exception
+handling information takes, which is useful for those interested in creating
+front-ends or dealing directly with the information. Further, this document
+provides specific examples of what exception handling information is used for in
+C and C++.</p>
+<div class="section" id="itanium-abi-zero-cost-exception-handling">
+<h3><a class="toc-backref" href="#id9">Itanium ABI Zero-cost Exception Handling</a><a class="headerlink" href="#itanium-abi-zero-cost-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>Exception handling for most programming languages is designed to recover from
+conditions that rarely occur during general use of an application. To that end,
+exception handling should not interfere with the main flow of an application’s
+algorithm by performing checkpointing tasks, such as saving the current pc or
+register state.</p>
+<p>The Itanium ABI Exception Handling Specification defines a methodology for
+providing outlying data in the form of exception tables without inlining
+speculative exception handling code in the flow of an application’s main
+algorithm. Thus, the specification is said to add “zero-cost” to the normal
+execution of an application.</p>
+<p>A more complete description of the Itanium ABI exception handling runtime
+support of can be found at <a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/abi-eh.html">Itanium C++ ABI: Exception Handling</a>. A description of the
+exception frame format can be found at <a class="reference external" href="http://refspecs.linuxfoundation.org/LSB_3.0.0/LSB-Core-generic/LSB-Core-generic/ehframechpt.html">Exception Frames</a>,
+with details of the DWARF 4 specification at <a class="reference external" href="http://dwarfstd.org/Dwarf4Std.php">DWARF 4 Standard</a>. A description for the C++ exception
+table formats can be found at <a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/exceptions.pdf">Exception Handling Tables</a>.</p>
+</div>
+<div class="section" id="setjmp-longjmp-exception-handling">
+<h3><a class="toc-backref" href="#id10">Setjmp/Longjmp Exception Handling</a><a class="headerlink" href="#setjmp-longjmp-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>Setjmp/Longjmp (SJLJ) based exception handling uses LLVM intrinsics
+<a class="reference internal" href="#llvm-eh-sjlj-setjmp">llvm.eh.sjlj.setjmp</a> and <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a> to handle control flow for
+exception handling.</p>
+<p>For each function which does exception processing — be it <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt>
+blocks or cleanups — that function registers itself on a global frame
+list. When exceptions are unwinding, the runtime uses this list to identify
+which functions need processing.</p>
+<p>Landing pad selection is encoded in the call site entry of the function
+context. The runtime returns to the function via <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a>, where
+a switch table transfers control to the appropriate landing pad based on the
+index stored in the function context.</p>
+<p>In contrast to DWARF exception handling, which encodes exception regions and
+frame information in out-of-line tables, SJLJ exception handling builds and
+removes the unwind frame context at runtime. This results in faster exception
+handling at the expense of slower execution when no exceptions are thrown. As
+exceptions are, by their nature, intended for uncommon code paths, DWARF
+exception handling is generally preferred to SJLJ.</p>
+</div>
+<div class="section" id="windows-runtime-exception-handling">
+<h3><a class="toc-backref" href="#id11">Windows Runtime Exception Handling</a><a class="headerlink" href="#windows-runtime-exception-handling" title="Permalink to this headline">¶</a></h3>
+<p>LLVM supports handling exceptions produced by the Windows runtime, but it
+requires a very different intermediate representation. It is not based on the
+“<a class="reference internal" href="LangRef.html#i-landingpad"><em>landingpad</em></a>” instruction like the other two models, and is
+described later in this document under <a class="reference internal" href="#wineh"><em>Exception Handling using the Windows Runtime</em></a>.</p>
+</div>
+<div class="section" id="overview">
+<h3><a class="toc-backref" href="#id12">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h3>
+<p>When an exception is thrown in LLVM code, the runtime does its best to find a
+handler suited to processing the circumstance.</p>
+<p>The runtime first attempts to find an <em>exception frame</em> corresponding to the
+function where the exception was thrown. If the programming language supports
+exception handling (e.g. C++), the exception frame contains a reference to an
+exception table describing how to process the exception. If the language does
+not support exception handling (e.g. C), or if the exception needs to be
+forwarded to a prior activation, the exception frame contains information about
+how to unwind the current activation and restore the state of the prior
+activation. This process is repeated until the exception is handled. If the
+exception is not handled and no activations remain, then the application is
+terminated with an appropriate error message.</p>
+<p>Because different programming languages have different behaviors when handling
+exceptions, the exception handling ABI provides a mechanism for
+supplying <em>personalities</em>. An exception handling personality is defined by
+way of a <em>personality function</em> (e.g. <tt class="docutils literal"><span class="pre">__gxx_personality_v0</span></tt> in C++),
+which receives the context of the exception, an <em>exception structure</em>
+containing the exception object type and value, and a reference to the exception
+table for the current function. The personality function for the current
+compile unit is specified in a <em>common exception frame</em>.</p>
+<p>The organization of an exception table is language dependent. For C++, an
+exception table is organized as a series of code ranges defining what to do if
+an exception occurs in that range. Typically, the information associated with a
+range defines which types of exception objects (using C++ <em>type info</em>) that are
+handled in that range, and an associated action that should take place. Actions
+typically pass control to a <em>landing pad</em>.</p>
+<p>A landing pad corresponds roughly to the code found in the <tt class="docutils literal"><span class="pre">catch</span></tt> portion of
+a <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> sequence. When execution resumes at a landing pad, it
+receives an <em>exception structure</em> and a <em>selector value</em> corresponding to the
+<em>type</em> of exception thrown. The selector is then used to determine which <em>catch</em>
+should actually process the exception.</p>
+</div>
+</div>
+<div class="section" id="llvm-code-generation">
+<h2><a class="toc-backref" href="#id13">LLVM Code Generation</a><a class="headerlink" href="#llvm-code-generation" title="Permalink to this headline">¶</a></h2>
+<p>From a C++ developer’s perspective, exceptions are defined in terms of the
+<tt class="docutils literal"><span class="pre">throw</span></tt> and <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> statements. In this section we will describe the
+implementation of LLVM exception handling in terms of C++ examples.</p>
+<div class="section" id="throw">
+<h3><a class="toc-backref" href="#id14">Throw</a><a class="headerlink" href="#throw" title="Permalink to this headline">¶</a></h3>
+<p>Languages that support exception handling typically provide a <tt class="docutils literal"><span class="pre">throw</span></tt>
+operation to initiate the exception process. Internally, a <tt class="docutils literal"><span class="pre">throw</span></tt> operation
+breaks down into two steps.</p>
+<ol class="arabic simple">
+<li>A request is made to allocate exception space for an exception structure.
+This structure needs to survive beyond the current activation. This structure
+will contain the type and value of the object being thrown.</li>
+<li>A call is made to the runtime to raise the exception, passing the exception
+structure as an argument.</li>
+</ol>
+<p>In C++, the allocation of the exception structure is done by the
+<tt class="docutils literal"><span class="pre">__cxa_allocate_exception</span></tt> runtime function. The exception raising is handled
+by <tt class="docutils literal"><span class="pre">__cxa_throw</span></tt>. The type of the exception is represented using a C++ RTTI
+structure.</p>
+</div>
+<div class="section" id="try-catch">
+<h3><a class="toc-backref" href="#id15">Try/Catch</a><a class="headerlink" href="#try-catch" title="Permalink to this headline">¶</a></h3>
+<p>A call within the scope of a <em>try</em> statement can potentially raise an
+exception. In those circumstances, the LLVM C++ front-end replaces the call with
+an <tt class="docutils literal"><span class="pre">invoke</span></tt> instruction. Unlike a call, the <tt class="docutils literal"><span class="pre">invoke</span></tt> has two potential
+continuation points:</p>
+<ol class="arabic simple">
+<li>where to continue when the call succeeds as per normal, and</li>
+<li>where to continue if the call raises an exception, either by a throw or the
+unwinding of a throw</li>
+</ol>
+<p>The term used to define the place where an <tt class="docutils literal"><span class="pre">invoke</span></tt> continues after an
+exception is called a <em>landing pad</em>. LLVM landing pads are conceptually
+alternative function entry points where an exception structure reference and a
+type info index are passed in as arguments. The landing pad saves the exception
+structure reference and then proceeds to select the catch block that corresponds
+to the type info of the exception object.</p>
+<p>The LLVM <a class="reference internal" href="LangRef.html#i-landingpad"><em>‘landingpad’ Instruction</em></a> is used to convey information about the landing
+pad to the back end. For C++, the <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction returns a pointer
+and integer pair corresponding to the pointer to the <em>exception structure</em> and
+the <em>selector value</em> respectively.</p>
+<p>The <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction looks for a reference to the personality
+function to be used for this <tt class="docutils literal"><span class="pre">try</span></tt>/<tt class="docutils literal"><span class="pre">catch</span></tt> sequence in the parent
+function’s attribute list. The instruction contains a list of <em>cleanup</em>,
+<em>catch</em>, and <em>filter</em> clauses. The exception is tested against the clauses
+sequentially from first to last. The clauses have the following meanings:</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">catch</span> <span class="pre"><type></span> <span class="pre">@ExcType</span></tt></p>
+<ul class="simple">
+<li>This clause means that the landingpad block should be entered if the
+exception being thrown is of type <tt class="docutils literal"><span class="pre">@ExcType</span></tt> or a subtype of
+<tt class="docutils literal"><span class="pre">@ExcType</span></tt>. For C++, <tt class="docutils literal"><span class="pre">@ExcType</span></tt> is a pointer to the <tt class="docutils literal"><span class="pre">std::type_info</span></tt>
+object (an RTTI object) representing the C++ exception type.</li>
+<li>If <tt class="docutils literal"><span class="pre">@ExcType</span></tt> is <tt class="docutils literal"><span class="pre">null</span></tt>, any exception matches, so the landingpad
+should always be entered. This is used for C++ catch-all blocks (“<tt class="docutils literal"><span class="pre">catch</span>
+<span class="pre">(...)</span></tt>”).</li>
+<li>When this clause is matched, the selector value will be equal to the value
+returned by “<tt class="docutils literal"><span class="pre">@llvm.eh.typeid.for(i8*</span> <span class="pre">@ExcType)</span></tt>”. This will always be a
+positive value.</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">filter</span> <span class="pre"><type></span> <span class="pre">[<type></span> <span class="pre">@ExcType1,</span> <span class="pre">...,</span> <span class="pre"><type></span> <span class="pre">@ExcTypeN]</span></tt></p>
+<ul class="simple">
+<li>This clause means that the landingpad should be entered if the exception
+being thrown does <em>not</em> match any of the types in the list (which, for C++,
+are again specified as <tt class="docutils literal"><span class="pre">std::type_info</span></tt> pointers).</li>
+<li>C++ front-ends use this to implement C++ exception specifications, such as
+“<tt class="docutils literal"><span class="pre">void</span> <span class="pre">foo()</span> <span class="pre">throw</span> <span class="pre">(ExcType1,</span> <span class="pre">...,</span> <span class="pre">ExcTypeN)</span> <span class="pre">{</span> <span class="pre">...</span> <span class="pre">}</span></tt>”.</li>
+<li>When this clause is matched, the selector value will be negative.</li>
+<li>The array argument to <tt class="docutils literal"><span class="pre">filter</span></tt> may be empty; for example, “<tt class="docutils literal"><span class="pre">[0</span> <span class="pre">x</span> <span class="pre">i8**]</span>
+<span class="pre">undef</span></tt>”. This means that the landingpad should always be entered. (Note
+that such a <tt class="docutils literal"><span class="pre">filter</span></tt> would not be equivalent to “<tt class="docutils literal"><span class="pre">catch</span> <span class="pre">i8*</span> <span class="pre">null</span></tt>”,
+because <tt class="docutils literal"><span class="pre">filter</span></tt> and <tt class="docutils literal"><span class="pre">catch</span></tt> produce negative and positive selector
+values respectively.)</li>
+</ul>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">cleanup</span></tt></p>
+<ul>
+<li><p class="first">This clause means that the landingpad should always be entered.</p>
+</li>
+<li><p class="first">C++ front-ends use this for calling objects’ destructors.</p>
+</li>
+<li><p class="first">When this clause is matched, the selector value will be zero.</p>
+</li>
+<li><p class="first">The runtime may treat “<tt class="docutils literal"><span class="pre">cleanup</span></tt>” differently from “<tt class="docutils literal"><span class="pre">catch</span> <span class="pre"><type></span>
+<span class="pre">null</span></tt>”.</p>
+<p>In C++, if an unhandled exception occurs, the language runtime will call
+<tt class="docutils literal"><span class="pre">std::terminate()</span></tt>, but it is implementation-defined whether the runtime
+unwinds the stack and calls object destructors first. For example, the GNU
+C++ unwinder does not call object destructors when an unhandled exception
+occurs. The reason for this is to improve debuggability: it ensures that
+<tt class="docutils literal"><span class="pre">std::terminate()</span></tt> is called from the context of the <tt class="docutils literal"><span class="pre">throw</span></tt>, so that
+this context is not lost by unwinding the stack. A runtime will typically
+implement this by searching for a matching non-<tt class="docutils literal"><span class="pre">cleanup</span></tt> clause, and
+aborting if it does not find one, before entering any landingpad blocks.</p>
+</li>
+</ul>
+</li>
+</ul>
+<p>Once the landing pad has the type info selector, the code branches to the code
+for the first catch. The catch then checks the value of the type info selector
+against the index of type info for that catch. Since the type info index is not
+known until all the type infos have been gathered in the backend, the catch code
+must call the <a class="reference internal" href="#llvm-eh-typeid-for">llvm.eh.typeid.for</a> intrinsic to determine the index for a given
+type info. If the catch fails to match the selector then control is passed on to
+the next catch.</p>
+<p>Finally, the entry and exit of catch code is bracketed with calls to
+<tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt> and <tt class="docutils literal"><span class="pre">__cxa_end_catch</span></tt>.</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt> takes an exception structure reference as an argument
+and returns the value of the exception object.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">__cxa_end_catch</span></tt> takes no arguments. This function:</p>
+<ol class="arabic simple">
+<li>Locates the most recently caught exception and decrements its handler
+count,</li>
+<li>Removes the exception from the <em>caught</em> stack if the handler count goes to
+zero, and</li>
+<li>Destroys the exception if the handler count goes to zero and the exception
+was not re-thrown by throw.</li>
+</ol>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">a rethrow from within the catch may replace this call with a
+<tt class="docutils literal"><span class="pre">__cxa_rethrow</span></tt>.</p>
+</div>
+</li>
+</ul>
+</div>
+<div class="section" id="cleanups">
+<h3><a class="toc-backref" href="#id16">Cleanups</a><a class="headerlink" href="#cleanups" title="Permalink to this headline">¶</a></h3>
+<p>A cleanup is extra code which needs to be run as part of unwinding a scope. C++
+destructors are a typical example, but other languages and language extensions
+provide a variety of different kinds of cleanups. In general, a landing pad may
+need to run arbitrary amounts of cleanup code before actually entering a catch
+block. To indicate the presence of cleanups, a <a class="reference internal" href="LangRef.html#i-landingpad"><em>‘landingpad’ Instruction</em></a> should have
+a <em>cleanup</em> clause. Otherwise, the unwinder will not stop at the landing pad if
+there are no catches or filters that require it to.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Do not allow a new exception to propagate out of the execution of a
+cleanup. This can corrupt the internal state of the unwinder. Different
+languages describe different high-level semantics for these situations: for
+example, C++ requires that the process be terminated, whereas Ada cancels both
+exceptions and throws a third.</p>
+</div>
+<p>When all cleanups are finished, if the exception is not handled by the current
+function, resume unwinding by calling the <a class="reference internal" href="LangRef.html#i-resume"><em>resume instruction</em></a>,
+passing in the result of the <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction for the original
+landing pad.</p>
+</div>
+<div class="section" id="throw-filters">
+<h3><a class="toc-backref" href="#id17">Throw Filters</a><a class="headerlink" href="#throw-filters" title="Permalink to this headline">¶</a></h3>
+<p>C++ allows the specification of which exception types may be thrown from a
+function. To represent this, a top level landing pad may exist to filter out
+invalid types. To express this in LLVM code the <a class="reference internal" href="LangRef.html#i-landingpad"><em>‘landingpad’ Instruction</em></a> will have a
+filter clause. The clause consists of an array of type infos.
+<tt class="docutils literal"><span class="pre">landingpad</span></tt> will return a negative value
+if the exception does not match any of the type infos. If no match is found then
+a call to <tt class="docutils literal"><span class="pre">__cxa_call_unexpected</span></tt> should be made, otherwise
+<tt class="docutils literal"><span class="pre">_Unwind_Resume</span></tt>. Each of these functions requires a reference to the
+exception structure. Note that the most general form of a <tt class="docutils literal"><span class="pre">landingpad</span></tt>
+instruction can have any number of catch, cleanup, and filter clauses (though
+having more than one cleanup is pointless). The LLVM C++ front-end can generate
+such <tt class="docutils literal"><span class="pre">landingpad</span></tt> instructions due to inlining creating nested exception
+handling scopes.</p>
+</div>
+<div class="section" id="restrictions">
+<span id="undefined"></span><h3><a class="toc-backref" href="#id18">Restrictions</a><a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h3>
+<p>The unwinder delegates the decision of whether to stop in a call frame to that
+call frame’s language-specific personality function. Not all unwinders guarantee
+that they will stop to perform cleanups. For example, the GNU C++ unwinder
+doesn’t do so unless the exception is actually caught somewhere further up the
+stack.</p>
+<p>In order for inlining to behave correctly, landing pads must be prepared to
+handle selector results that they did not originally advertise. Suppose that a
+function catches exceptions of type <tt class="docutils literal"><span class="pre">A</span></tt>, and it’s inlined into a function that
+catches exceptions of type <tt class="docutils literal"><span class="pre">B</span></tt>. The inliner will update the <tt class="docutils literal"><span class="pre">landingpad</span></tt>
+instruction for the inlined landing pad to include the fact that <tt class="docutils literal"><span class="pre">B</span></tt> is also
+caught. If that landing pad assumes that it will only be entered to catch an
+<tt class="docutils literal"><span class="pre">A</span></tt>, it’s in for a rude awakening. Consequently, landing pads must test for
+the selector results they understand and then resume exception propagation with
+the <a class="reference external" href="LangRef.html#i_resume">resume instruction</a> if none of the conditions
+match.</p>
+</div>
+</div>
+<div class="section" id="exception-handling-intrinsics">
+<h2><a class="toc-backref" href="#id19">Exception Handling Intrinsics</a><a class="headerlink" href="#exception-handling-intrinsics" title="Permalink to this headline">¶</a></h2>
+<p>In addition to the <tt class="docutils literal"><span class="pre">landingpad</span></tt> and <tt class="docutils literal"><span class="pre">resume</span></tt> instructions, LLVM uses several
+intrinsic functions (name prefixed with <tt class="docutils literal"><span class="pre">llvm.eh</span></tt>) to provide exception
+handling information at various points in generated code.</p>
+<div class="section" id="llvm-eh-typeid-for">
+<span id="id1"></span><h3><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">llvm.eh.typeid.for</span></tt></a><a class="headerlink" href="#llvm-eh-typeid-for" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i32</span> <span class="vg">@llvm.eh.typeid.for</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%type_info</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This intrinsic returns the type info index in the exception table of the current
+function. This value can be used to compare against the result of
+<tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction. The single argument is a reference to a type info.</p>
+<p>Uses of this intrinsic are generated by the C++ front-end.</p>
+</div>
+<div class="section" id="llvm-eh-begincatch">
+<span id="id2"></span><h3><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">llvm.eh.begincatch</span></tt></a><a class="headerlink" href="#llvm-eh-begincatch" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.begincatch</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%ehptr</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%ehobj</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>This intrinsic marks the beginning of catch handling code within the blocks
+following a <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction. The exact behavior of this function
+depends on the compilation target and the personality function associated
+with the <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction.</p>
+<p>The first argument to this intrinsic is a pointer that was previously extracted
+from the aggregate return value of the <tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction. The second
+argument to the intrinsic is a pointer to stack space where the exception object
+should be stored. The runtime handles the details of copying the exception
+object into the slot. If the second parameter is null, no copy occurs.</p>
+<p>Uses of this intrinsic are generated by the C++ front-end. Many targets will
+use implementation-specific functions (such as <tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt>) instead
+of this intrinsic. The intrinsic is provided for targets that require a more
+abstract interface.</p>
+<p>When used in the native Windows C++ exception handling implementation, this
+intrinsic serves as a placeholder to delimit code before a catch handler is
+outlined. When the handler is outlined, this intrinsic will be replaced
+by instructions that retrieve the exception object pointer from the frame
+allocation block.</p>
+</div>
+<div class="section" id="llvm-eh-endcatch">
+<span id="id3"></span><h3><a class="toc-backref" href="#id22"><tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt></a><a class="headerlink" href="#llvm-eh-endcatch" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.endcatch</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>This intrinsic marks the end of catch handling code within the current block,
+which will be a successor of a block which called <tt class="docutils literal"><span class="pre">llvm.eh.begincatch''.</span>
+<span class="pre">The</span> <span class="pre">exact</span> <span class="pre">behavior</span> <span class="pre">of</span> <span class="pre">this</span> <span class="pre">function</span> <span class="pre">depends</span> <span class="pre">on</span> <span class="pre">the</span> <span class="pre">compilation</span> <span class="pre">target</span> <span class="pre">and</span> <span class="pre">the</span>
+<span class="pre">personality</span> <span class="pre">function</span> <span class="pre">associated</span> <span class="pre">with</span> <span class="pre">the</span> <span class="pre">corresponding</span> <span class="pre">``landingpad</span></tt>
+instruction.</p>
+<p>There may be more than one call to <tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt> for any given call to
+<tt class="docutils literal"><span class="pre">llvm.eh.begincatch</span></tt> with each <tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt> call corresponding to the
+end of a different control path. All control paths following a call to
+<tt class="docutils literal"><span class="pre">llvm.eh.begincatch</span></tt> must reach a call to <tt class="docutils literal"><span class="pre">llvm.eh.endcatch</span></tt>.</p>
+<p>Uses of this intrinsic are generated by the C++ front-end. Many targets will
+use implementation-specific functions (such as <tt class="docutils literal"><span class="pre">__cxa_begin_catch</span></tt>) instead
+of this intrinsic. The intrinsic is provided for targets that require a more
+abstract interface.</p>
+<p>When used in the native Windows C++ exception handling implementation, this
+intrinsic serves as a placeholder to delimit code before a catch handler is
+outlined. After the handler is outlined, this intrinsic is simply removed.</p>
+</div>
+<div class="section" id="llvm-eh-exceptionpointer">
+<span id="id4"></span><h3><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">llvm.eh.exceptionpointer</span></tt></a><a class="headerlink" href="#llvm-eh-exceptionpointer" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-text"><div class="highlight"><pre>i8 addrspace(N)* @llvm.eh.padparam.pNi8(token %catchpad)
+</pre></div>
+</div>
+<p>This intrinsic retrieves a pointer to the exception caught by the given
+<tt class="docutils literal"><span class="pre">catchpad</span></tt>.</p>
+</div>
+<div class="section" id="sjlj-intrinsics">
+<h3><a class="toc-backref" href="#id24">SJLJ Intrinsics</a><a class="headerlink" href="#sjlj-intrinsics" title="Permalink to this headline">¶</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">llvm.eh.sjlj</span></tt> intrinsics are used internally within LLVM’s
+backend. Uses of them are generated by the backend’s
+<tt class="docutils literal"><span class="pre">SjLjEHPrepare</span></tt> pass.</p>
+<div class="section" id="llvm-eh-sjlj-setjmp">
+<span id="id5"></span><h4><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.setjmp</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-setjmp" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-text"><div class="highlight"><pre>i32 @llvm.eh.sjlj.setjmp(i8* %setjmp_buf)
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, this intrinsic forces register saving for the
+current function and stores the address of the following instruction for use as
+a destination address by <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a>. The buffer format and the
+overall functioning of this intrinsic is compatible with the GCC
+<tt class="docutils literal"><span class="pre">__builtin_setjmp</span></tt> implementation allowing code built with the clang and GCC
+to interoperate.</p>
+<p>The single parameter is a pointer to a five word buffer in which the calling
+context is saved. The front end places the frame pointer in the first word, and
+the target implementation of this intrinsic should place the destination address
+for a <a class="reference internal" href="#llvm-eh-sjlj-longjmp">llvm.eh.sjlj.longjmp</a> in the second word. The following three words are
+available for use in a target-specific manner.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-longjmp">
+<span id="id6"></span><h4><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.longjmp</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-longjmp" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.sjlj.longjmp</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%setjmp_buf</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, the <tt class="docutils literal"><span class="pre">llvm.eh.sjlj.longjmp</span></tt> intrinsic is
+used to implement <tt class="docutils literal"><span class="pre">__builtin_longjmp()</span></tt>. The single parameter is a pointer to
+a buffer populated by <a class="reference internal" href="#llvm-eh-sjlj-setjmp">llvm.eh.sjlj.setjmp</a>. The frame pointer and stack
+pointer are restored from the buffer, then control is transferred to the
+destination address.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-lsda">
+<h4><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.lsda</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-lsda" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.eh.sjlj.lsda</span><span class="p">()</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, the <tt class="docutils literal"><span class="pre">llvm.eh.sjlj.lsda</span></tt> intrinsic returns
+the address of the Language Specific Data Area (LSDA) for the current
+function. The SJLJ front-end code stores this address in the exception handling
+function context for use by the runtime.</p>
+</div>
+<div class="section" id="llvm-eh-sjlj-callsite">
+<h4><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">llvm.eh.sjlj.callsite</span></tt></a><a class="headerlink" href="#llvm-eh-sjlj-callsite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.eh.sjlj.callsite</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%call_site_num</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For SJLJ based exception handling, the <tt class="docutils literal"><span class="pre">llvm.eh.sjlj.callsite</span></tt> intrinsic
+identifies the callsite value associated with the following <tt class="docutils literal"><span class="pre">invoke</span></tt>
+instruction. This is used to ensure that landing pad entries in the LSDA are
+generated in matching order.</p>
+</div>
+</div>
+</div>
+<div class="section" id="asm-table-formats">
+<h2><a class="toc-backref" href="#id29">Asm Table Formats</a><a class="headerlink" href="#asm-table-formats" title="Permalink to this headline">¶</a></h2>
+<p>There are two tables that are used by the exception handling runtime to
+determine which actions should be taken when an exception is thrown.</p>
+<div class="section" id="exception-handling-frame">
+<h3><a class="toc-backref" href="#id30">Exception Handling Frame</a><a class="headerlink" href="#exception-handling-frame" title="Permalink to this headline">¶</a></h3>
+<p>An exception handling frame <tt class="docutils literal"><span class="pre">eh_frame</span></tt> is very similar to the unwind frame
+used by DWARF debug info. The frame contains all the information necessary to
+tear down the current frame and restore the state of the prior frame. There is
+an exception handling frame for each function in a compile unit, plus a common
+exception handling frame that defines information common to all functions in the
+unit.</p>
+<p>The format of this call frame information (CFI) is often platform-dependent,
+however. ARM, for example, defines their own format. Apple has their own compact
+unwind info format. On Windows, another format is used for all architectures
+since 32-bit x86. LLVM will emit whatever information is required by the
+target.</p>
+</div>
+<div class="section" id="exception-tables">
+<h3><a class="toc-backref" href="#id31">Exception Tables</a><a class="headerlink" href="#exception-tables" title="Permalink to this headline">¶</a></h3>
+<p>An exception table contains information about what actions to take when an
+exception is thrown in a particular part of a function’s code. This is typically
+referred to as the language-specific data area (LSDA). The format of the LSDA
+table is specific to the personality function, but the majority of personalities
+out there use a variation of the tables consumed by <tt class="docutils literal"><span class="pre">__gxx_personality_v0</span></tt>.
+There is one exception table per function, except leaf functions and functions
+that have calls only to non-throwing functions. They do not need an exception
+table.</p>
+</div>
+</div>
+<div class="section" id="exception-handling-using-the-windows-runtime">
+<span id="wineh"></span><h2><a class="toc-backref" href="#id32">Exception Handling using the Windows Runtime</a><a class="headerlink" href="#exception-handling-using-the-windows-runtime" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="background-on-windows-exceptions">
+<h3><a class="toc-backref" href="#id33">Background on Windows exceptions</a><a class="headerlink" href="#background-on-windows-exceptions" title="Permalink to this headline">¶</a></h3>
+<p>Interacting with exceptions on Windows is significantly more complicated than
+on Itanium C++ ABI platforms. The fundamental difference between the two models
+is that Itanium EH is designed around the idea of “successive unwinding,” while
+Windows EH is not.</p>
+<p>Under Itanium, throwing an exception typically involes allocating thread local
+memory to hold the exception, and calling into the EH runtime. The runtime
+identifies frames with appropriate exception handling actions, and successively
+resets the register context of the current thread to the most recently active
+frame with actions to run. In LLVM, execution resumes at a <tt class="docutils literal"><span class="pre">landingpad</span></tt>
+instruction, which produces register values provided by the runtime. If a
+function is only cleaning up allocated resources, the function is responsible
+for calling <tt class="docutils literal"><span class="pre">_Unwind_Resume</span></tt> to transition to the next most recently active
+frame after it is finished cleaning up. Eventually, the frame responsible for
+handling the exception calls <tt class="docutils literal"><span class="pre">__cxa_end_catch</span></tt> to destroy the exception,
+release its memory, and resume normal control flow.</p>
+<p>The Windows EH model does not use these successive register context resets.
+Instead, the active exception is typically described by a frame on the stack.
+In the case of C++ exceptions, the exception object is allocated in stack memory
+and its address is passed to <tt class="docutils literal"><span class="pre">__CxxThrowException</span></tt>. General purpose structured
+exceptions (SEH) are more analogous to Linux signals, and they are dispatched by
+userspace DLLs provided with Windows. Each frame on the stack has an assigned EH
+personality routine, which decides what actions to take to handle the exception.
+There are a few major personalities for C and C++ code: the C++ personality
+(<tt class="docutils literal"><span class="pre">__CxxFrameHandler3</span></tt>) and the SEH personalities (<tt class="docutils literal"><span class="pre">_except_handler3</span></tt>,
+<tt class="docutils literal"><span class="pre">_except_handler4</span></tt>, and <tt class="docutils literal"><span class="pre">__C_specific_handler</span></tt>). All of them implement
+cleanups by calling back into a “funclet” contained in the parent function.</p>
+<p>Funclets, in this context, are regions of the parent function that can be called
+as though they were a function pointer with a very special calling convention.
+The frame pointer of the parent frame is passed into the funclet either using
+the standard EBP register or as the first parameter register, depending on the
+architecture. The funclet implements the EH action by accessing local variables
+in memory through the frame pointer, and returning some appropriate value,
+continuing the EH process. No variables live in to or out of the funclet can be
+allocated in registers.</p>
+<p>The C++ personality also uses funclets to contain the code for catch blocks
+(i.e. all user code between the braces in <tt class="docutils literal"><span class="pre">catch</span> <span class="pre">(Type</span> <span class="pre">obj)</span> <span class="pre">{</span> <span class="pre">...</span> <span class="pre">}</span></tt>). The
+runtime must use funclets for catch bodies because the C++ exception object is
+allocated in a child stack frame of the function handling the exception. If the
+runtime rewound the stack back to frame of the catch, the memory holding the
+exception would be overwritten quickly by subsequent function calls. The use of
+funclets also allows <tt class="docutils literal"><span class="pre">__CxxFrameHandler3</span></tt> to implement rethrow without
+resorting to TLS. Instead, the runtime throws a special exception, and then uses
+SEH (<tt class="docutils literal"><span class="pre">__try</span> <span class="pre">/</span> <span class="pre">__except</span></tt>) to resume execution with new information in the child
+frame.</p>
+<p>In other words, the successive unwinding approach is incompatible with Visual
+C++ exceptions and general purpose Windows exception handling. Because the C++
+exception object lives in stack memory, LLVM cannot provide a custom personality
+function that uses landingpads. Similarly, SEH does not provide any mechanism
+to rethrow an exception or continue unwinding. Therefore, LLVM must use the IR
+constructs described later in this document to implement compatible exception
+handling.</p>
+</div>
+<div class="section" id="seh-filter-expressions">
+<h3><a class="toc-backref" href="#id34">SEH filter expressions</a><a class="headerlink" href="#seh-filter-expressions" title="Permalink to this headline">¶</a></h3>
+<p>The SEH personality functions also use funclets to implement filter expressions,
+which allow executing arbitrary user code to decide which exceptions to catch.
+Filter expressions should not be confused with the <tt class="docutils literal"><span class="pre">filter</span></tt> clause of the LLVM
+<tt class="docutils literal"><span class="pre">landingpad</span></tt> instruction. Typically filter expressions are used to determine
+if the exception came from a particular DLL or code region, or if code faulted
+while accessing a particular memory address range. LLVM does not currently have
+IR to represent filter expressions because it is difficult to represent their
+control dependencies. Filter expressions run during the first phase of EH,
+before cleanups run, making it very difficult to build a faithful control flow
+graph. For now, the new EH instructions cannot represent SEH filter
+expressions, and frontends must outline them ahead of time. Local variables of
+the parent function can be escaped and accessed using the <tt class="docutils literal"><span class="pre">llvm.localescape</span></tt>
+and <tt class="docutils literal"><span class="pre">llvm.localrecover</span></tt> intrinsics.</p>
+</div>
+<div class="section" id="new-exception-handling-instructions">
+<h3><a class="toc-backref" href="#id35">New exception handling instructions</a><a class="headerlink" href="#new-exception-handling-instructions" title="Permalink to this headline">¶</a></h3>
+<p>The primary design goal of the new EH instructions is to support funclet
+generation while preserving information about the CFG so that SSA formation
+still works. As a secondary goal, they are designed to be generic across MSVC
+and Itanium C++ exceptions. They make very few assumptions about the data
+required by the personality, so long as it uses the familiar core EH actions:
+catch, cleanup, and terminate. However, the new instructions are hard to modify
+without knowing details of the EH personality. While they can be used to
+represent Itanium EH, the landingpad model is strictly better for optimization
+purposes.</p>
+<p>The following new instructions are considered “exception handling pads”, in that
+they must be the first non-phi instruction of a basic block that may be the
+unwind destination of an EH flow edge:
+<tt class="docutils literal"><span class="pre">catchswitch</span></tt>, <tt class="docutils literal"><span class="pre">catchpad</span></tt>, and <tt class="docutils literal"><span class="pre">cleanuppad</span></tt>.
+As with landingpads, when entering a try scope, if the
+frontend encounters a call site that may throw an exception, it should emit an
+invoke that unwinds to a <tt class="docutils literal"><span class="pre">catchswitch</span></tt> block. Similarly, inside the scope of a
+C++ object with a destructor, invokes should unwind to a <tt class="docutils literal"><span class="pre">cleanuppad</span></tt>.</p>
+<p>New instructions are also used to mark the points where control is transferred
+out of a catch/cleanup handler (which will correspond to exits from the
+generated funclet). A catch handler which reaches its end by normal execution
+executes a <tt class="docutils literal"><span class="pre">catchret</span></tt> instruction, which is a terminator indicating where in
+the function control is returned to. A cleanup handler which reaches its end
+by normal execution executes a <tt class="docutils literal"><span class="pre">cleanupret</span></tt> instruction, which is a terminator
+indicating where the active exception will unwind to next.</p>
+<p>Each of these new EH pad instructions has a way to identify which action should
+be considered after this action. The <tt class="docutils literal"><span class="pre">catchswitch</span></tt> instruction is a terminator
+and has an unwind destination operand analogous to the unwind destination of an
+invoke. The <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> instruction is not
+a terminator, so the unwind destination is stored on the <tt class="docutils literal"><span class="pre">cleanupret</span></tt>
+instruction instead. Successfully executing a catch handler should resume
+normal control flow, so neither <tt class="docutils literal"><span class="pre">catchpad</span></tt> nor <tt class="docutils literal"><span class="pre">catchret</span></tt> instructions can
+unwind. All of these “unwind edges” may refer to a basic block that contains an
+EH pad instruction, or they may unwind to the caller. Unwinding to the caller
+has roughly the same semantics as the <tt class="docutils literal"><span class="pre">resume</span></tt> instruction in the landingpad
+model. When inlining through an invoke, instructions that unwind to the caller
+are hooked up to unwind to the unwind destination of the call site.</p>
+<p>Putting things together, here is a hypothetical lowering of some C++ that uses
+all of the new IR instructions:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">struct</span> <span class="n">Cleanup</span> <span class="p">{</span>
+ <span class="n">Cleanup</span><span class="p">();</span>
+ <span class="o">~</span><span class="n">Cleanup</span><span class="p">();</span>
+ <span class="kt">int</span> <span class="n">m</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="kt">void</span> <span class="n">may_throw</span><span class="p">();</span>
+<span class="kt">int</span> <span class="n">f</span><span class="p">()</span> <span class="n">noexcept</span> <span class="p">{</span>
+ <span class="n">try</span> <span class="p">{</span>
+ <span class="n">Cleanup</span> <span class="n">obj</span><span class="p">;</span>
+ <span class="n">may_throw</span><span class="p">();</span>
+ <span class="p">}</span> <span class="n">catch</span> <span class="p">(</span><span class="kt">int</span> <span class="n">e</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">may_throw</span><span class="p">();</span>
+ <span class="k">return</span> <span class="n">e</span><span class="p">;</span>
+ <span class="p">}</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-text"><div class="highlight"><pre>define i32 @f() nounwind personality i32 (...)* @__CxxFrameHandler3 {
+entry:
+ %obj = alloca %struct.Cleanup, align 4
+ %e = alloca i32, align 4
+ %call = invoke %struct.Cleanup* @"\01??0Cleanup@@QEAA at XZ"(%struct.Cleanup* nonnull %obj)
+ to label %invoke.cont unwind label %lpad.catch
+
+invoke.cont: ; preds = %entry
+ invoke void @"\01?may_throw@@YAXXZ"()
+ to label %invoke.cont.2 unwind label %lpad.cleanup
+
+invoke.cont.2: ; preds = %invoke.cont
+ call void @"\01??_DCleanup@@QEAA at XZ"(%struct.Cleanup* nonnull %obj) nounwind
+ br label %return
+
+return: ; preds = %invoke.cont.3, %invoke.cont.2
+ %retval.0 = phi i32 [ 0, %invoke.cont.2 ], [ %3, %invoke.cont.3 ]
+ ret i32 %retval.0
+
+lpad.cleanup: ; preds = %invoke.cont.2
+ %0 = cleanuppad within none []
+ call void @"\01??1Cleanup@@QEAA at XZ"(%struct.Cleanup* nonnull %obj) nounwind
+ cleanupret %0 unwind label %lpad.catch
+
+lpad.catch: ; preds = %lpad.cleanup, %entry
+ %1 = catchswitch within none [label %catch.body] unwind label %lpad.terminate
+
+catch.body: ; preds = %lpad.catch
+ %catch = catchpad within %1 [%rtti.TypeDescriptor2* @"\01??_R0H at 8", i32 0, i32* %e]
+ invoke void @"\01?may_throw@@YAXXZ"()
+ to label %invoke.cont.3 unwind label %lpad.terminate
+
+invoke.cont.3: ; preds = %catch.body
+ %3 = load i32, i32* %e, align 4
+ catchret from %catch to label %return
+
+lpad.terminate: ; preds = %catch.body, %lpad.catch
+ cleanuppad within none []
+ call void @"\01?terminate@@YAXXZ"
+ unreachable
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="funclet-parent-tokens">
+<h3><a class="toc-backref" href="#id36">Funclet parent tokens</a><a class="headerlink" href="#funclet-parent-tokens" title="Permalink to this headline">¶</a></h3>
+<p>In order to produce tables for EH personalities that use funclets, it is
+necessary to recover the nesting that was present in the source. This funclet
+parent relationship is encoded in the IR using tokens produced by the new “pad”
+instructions. The token operand of a “pad” or “ret” instruction indicates which
+funclet it is in, or “none” if it is not nested within another funclet.</p>
+<p>The <tt class="docutils literal"><span class="pre">catchpad</span></tt> and <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> instructions establish new funclets, and
+their tokens are consumed by other “pad” instructions to establish membership.
+The <tt class="docutils literal"><span class="pre">catchswitch</span></tt> instruction does not create a funclet, but it produces a
+token that is always consumed by its immediate successor <tt class="docutils literal"><span class="pre">catchpad</span></tt>
+instructions. This ensures that every catch handler modelled by a <tt class="docutils literal"><span class="pre">catchpad</span></tt>
+belongs to exactly one <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, which models the dispatch point after a
+C++ try.</p>
+<p>Here is an example of what this nesting looks like using some hypothetical
+C++ code:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">void</span> <span class="nf">f</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">try</span> <span class="p">{</span>
+ <span class="n">throw</span><span class="p">;</span>
+ <span class="p">}</span> <span class="n">catch</span> <span class="p">(...)</span> <span class="p">{</span>
+ <span class="n">try</span> <span class="p">{</span>
+ <span class="n">throw</span><span class="p">;</span>
+ <span class="p">}</span> <span class="n">catch</span> <span class="p">(...)</span> <span class="p">{</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-text"><div class="highlight"><pre>define void @f() #0 personality i8* bitcast (i32 (...)* @__CxxFrameHandler3 to i8*) {
+entry:
+ invoke void @_CxxThrowException(i8* null, %eh.ThrowInfo* null) #1
+ to label %unreachable unwind label %catch.dispatch
+
+catch.dispatch: ; preds = %entry
+ %0 = catchswitch within none [label %catch] unwind to caller
+
+catch: ; preds = %catch.dispatch
+ %1 = catchpad within %0 [i8* null, i32 64, i8* null]
+ invoke void @_CxxThrowException(i8* null, %eh.ThrowInfo* null) #1
+ to label %unreachable unwind label %catch.dispatch2
+
+catch.dispatch2: ; preds = %catch
+ %2 = catchswitch within %1 [label %catch3] unwind to caller
+
+catch3: ; preds = %catch.dispatch2
+ %3 = catchpad within %2 [i8* null, i32 64, i8* null]
+ catchret from %3 to label %try.cont
+
+try.cont: ; preds = %catch3
+ catchret from %1 to label %try.cont6
+
+try.cont6: ; preds = %try.cont
+ ret void
+
+unreachable: ; preds = %catch, %entry
+ unreachable
+}
+</pre></div>
+</div>
+<p>The “inner” <tt class="docutils literal"><span class="pre">catchswitch</span></tt> consumes <tt class="docutils literal"><span class="pre">%1</span></tt> which is produced by the outer
+catchswitch.</p>
+</div>
+<div class="section" id="funclet-transitions">
+<span id="wineh-constraints"></span><h3><a class="toc-backref" href="#id37">Funclet transitions</a><a class="headerlink" href="#funclet-transitions" title="Permalink to this headline">¶</a></h3>
+<p>The EH tables for personalities that use funclets make implicit use of the
+funclet nesting relationship to encode unwind destinations, and so are
+constrained in the set of funclet transitions they can represent. The related
+LLVM IR instructions accordingly have constraints that ensure encodability of
+the EH edges in the flow graph.</p>
+<p>A <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, <tt class="docutils literal"><span class="pre">catchpad</span></tt>, or <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> is said to be “entered”
+when it executes. It may subsequently be “exited” by any of the following
+means:</p>
+<ul class="simple">
+<li>A <tt class="docutils literal"><span class="pre">catchswitch</span></tt> is immediately exited when none of its constituent
+<tt class="docutils literal"><span class="pre">catchpad</span></tt>s are appropriate for the in-flight exception and it unwinds
+to its unwind destination or the caller.</li>
+<li>A <tt class="docutils literal"><span class="pre">catchpad</span></tt> and its parent <tt class="docutils literal"><span class="pre">catchswitch</span></tt> are both exited when a
+<tt class="docutils literal"><span class="pre">catchret</span></tt> from the <tt class="docutils literal"><span class="pre">catchpad</span></tt> is executed.</li>
+<li>A <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> is exited when a <tt class="docutils literal"><span class="pre">cleanupret</span></tt> from it is executed.</li>
+<li>Any of these pads is exited when control unwinds to the function’s caller,
+either by a <tt class="docutils literal"><span class="pre">call</span></tt> which unwinds all the way to the function’s caller,
+a nested <tt class="docutils literal"><span class="pre">catchswitch</span></tt> marked “<tt class="docutils literal"><span class="pre">unwinds</span> <span class="pre">to</span> <span class="pre">caller</span></tt>”, or a nested
+<tt class="docutils literal"><span class="pre">cleanuppad</span></tt>‘s <tt class="docutils literal"><span class="pre">cleanupret</span></tt> marked “<tt class="docutils literal"><span class="pre">unwinds</span> <span class="pre">to</span> <span class="pre">caller"</span></tt>.</li>
+<li>Any of these pads is exited when an unwind edge (from an <tt class="docutils literal"><span class="pre">invoke</span></tt>,
+nested <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, or nested <tt class="docutils literal"><span class="pre">cleanuppad</span></tt>‘s <tt class="docutils literal"><span class="pre">cleanupret</span></tt>)
+unwinds to a destination pad that is not a descendant of the given pad.</li>
+</ul>
+<p>Note that the <tt class="docutils literal"><span class="pre">ret</span></tt> instruction is <em>not</em> a valid way to exit a funclet pad;
+it is undefined behavior to execute a <tt class="docutils literal"><span class="pre">ret</span></tt> when a pad has been entered but
+not exited.</p>
+<p>A single unwind edge may exit any number of pads (with the restrictions that
+the edge from a <tt class="docutils literal"><span class="pre">catchswitch</span></tt> must exit at least itself, and the edge from
+a <tt class="docutils literal"><span class="pre">cleanupret</span></tt> must exit at least its <tt class="docutils literal"><span class="pre">cleanuppad</span></tt>), and then must enter
+exactly one pad, which must be distinct from all the exited pads. The parent
+of the pad that an unwind edge enters must be the most-recently-entered
+not-yet-exited pad (after exiting from any pads that the unwind edge exits),
+or “none” if there is no such pad. This ensures that the stack of executing
+funclets at run-time always corresponds to some path in the funclet pad tree
+that the parent tokens encode.</p>
+<p>All unwind edges which exit any given funclet pad (including <tt class="docutils literal"><span class="pre">cleanupret</span></tt>
+edges exiting their <tt class="docutils literal"><span class="pre">cleanuppad</span></tt> and <tt class="docutils literal"><span class="pre">catchswitch</span></tt> edges exiting their
+<tt class="docutils literal"><span class="pre">catchswitch</span></tt>) must share the same unwind destination. Similarly, any
+funclet pad which may be exited by unwind to caller must not be exited by
+any exception edges which unwind anywhere other than the caller. This
+ensures that each funclet as a whole has only one unwind destination, which
+EH tables for funclet personalities may require. Note that any unwind edge
+which exits a <tt class="docutils literal"><span class="pre">catchpad</span></tt> also exits its parent <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, so this
+implies that for any given <tt class="docutils literal"><span class="pre">catchswitch</span></tt>, its unwind destination must also
+be the unwind destination of any unwind edge that exits any of its constituent
+<tt class="docutils literal"><span class="pre">catchpad</span></tt>s. Because <tt class="docutils literal"><span class="pre">catchswitch</span></tt> has no <tt class="docutils literal"><span class="pre">nounwind</span></tt> variant, and
+because IR producers are not <em>required</em> to annotate calls which will not
+unwind as <tt class="docutils literal"><span class="pre">nounwind</span></tt>, it is legal to nest a <tt class="docutils literal"><span class="pre">call</span></tt> or an “<tt class="docutils literal"><span class="pre">unwind</span> <span class="pre">to</span>
+<span class="pre">caller</span></tt>” <tt class="docutils literal"><span class="pre">catchswitch</span></tt> within a funclet pad that has an unwind
+destination other than caller; it is undefined behavior for such a <tt class="docutils literal"><span class="pre">call</span></tt>
+or <tt class="docutils literal"><span class="pre">catchswitch</span></tt> to unwind.</p>
+<p>Finally, the funclet pads’ unwind destinations cannot form a cycle. This
+ensures that EH lowering can construct “try regions” with a tree-like
+structure, which funclet-based personalities may require.</p>
+</div>
+</div>
+<div class="section" id="exception-handling-support-on-the-target">
+<h2><a class="toc-backref" href="#id38">Exception Handling support on the target</a><a class="headerlink" href="#exception-handling-support-on-the-target" title="Permalink to this headline">¶</a></h2>
+<p>In order to support exception handling on particular target, there are a few
+items need to be implemented.</p>
+<ul>
+<li><p class="first">CFI directives</p>
+<p>First, you have to assign each target register with a unique DWARF number.
+Then in <tt class="docutils literal"><span class="pre">TargetFrameLowering</span></tt>‘s <tt class="docutils literal"><span class="pre">emitPrologue</span></tt>, you have to emit <a class="reference external" href="https://sourceware.org/binutils/docs/as/CFI-directives.html">CFI
+directives</a>
+to specify how to calculate the CFA (Canonical Frame Address) and how register
+is restored from the address pointed by the CFA with an offset. The assembler
+is instructed by CFI directives to build <tt class="docutils literal"><span class="pre">.eh_frame</span></tt> section, which is used
+by th unwinder to unwind stack during exception handling.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">getExceptionPointerRegister</span></tt> and <tt class="docutils literal"><span class="pre">getExceptionSelectorRegister</span></tt></p>
+<p><tt class="docutils literal"><span class="pre">TargetLowering</span></tt> must implement both functions. The <em>personality function</em>
+passes the <em>exception structure</em> (a pointer) and <em>selector value</em> (an integer)
+to the landing pad through the registers specified by <tt class="docutils literal"><span class="pre">getExceptionPointerRegister</span></tt>
+and <tt class="docutils literal"><span class="pre">getExceptionSelectorRegister</span></tt> respectively. On most platforms, they
+will be GPRs and will be the same as the ones specified in the calling convention.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">EH_RETURN</span></tt></p>
+<p>The ISD node represents the undocumented GCC extension <tt class="docutils literal"><span class="pre">__builtin_eh_return</span> <span class="pre">(offset,</span> <span class="pre">handler)</span></tt>,
+which adjusts the stack by offset and then jumps to the handler. <tt class="docutils literal"><span class="pre">__builtin_eh_return</span></tt>
+is used in GCC unwinder (<a class="reference external" href="https://gcc.gnu.org/onlinedocs/gccint/Libgcc.html">libgcc</a>),
+but not in LLVM unwinder (<a class="reference external" href="https://clang.llvm.org/docs/Toolchain.html#unwind-library">libunwind</a>).
+If you are on the top of <tt class="docutils literal"><span class="pre">libgcc</span></tt> and have particular requirement on your target,
+you have to handle <tt class="docutils literal"><span class="pre">EH_RETURN</span></tt> in <tt class="docutils literal"><span class="pre">TargetLowering</span></tt>.</p>
+</li>
+</ul>
+<p>If you don’t leverage the existing runtime (<tt class="docutils literal"><span class="pre">libstdc++</span></tt> and <tt class="docutils literal"><span class="pre">libgcc</span></tt>),
+you have to take a look on <a class="reference external" href="https://libcxx.llvm.org/">libc++</a> and
+<a class="reference external" href="https://clang.llvm.org/docs/Toolchain.html#unwind-library">libunwind</a>
+to see what have to be done there. For <tt class="docutils literal"><span class="pre">libunwind</span></tt>, you have to do the following</p>
+<ul>
+<li><p class="first"><tt class="docutils literal"><span class="pre">__libunwind_config.h</span></tt></p>
+<p>Define macros for your target.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">include/libunwind.h</span></tt></p>
+<p>Define enum for the target registers.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">src/Registers.hpp</span></tt></p>
+<p>Define <tt class="docutils literal"><span class="pre">Registers</span></tt> class for your target, implement setter and getter functions.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">src/UnwindCursor.hpp</span></tt></p>
+<p>Define <tt class="docutils literal"><span class="pre">dwarfEncoding</span></tt> and <tt class="docutils literal"><span class="pre">stepWithCompactEncoding</span></tt> for your <tt class="docutils literal"><span class="pre">Registers</span></tt>
+class.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">src/UnwindRegistersRestore.S</span></tt></p>
+<p>Write an assembly function to restore all your target registers from the memory.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">src/UnwindRegistersSave.S</span></tt></p>
+<p>Write an assembly function to save all your target registers on the memory.</p>
+</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CodeGenerator.html" title="The LLVM Target-Independent Code Generator"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/ExtendingLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/ExtendingLLVM.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/ExtendingLLVM.html (added)
+++ www-releases/trunk/7.0.1/docs/ExtendingLLVM.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,381 @@
+
+
+<!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>Extending LLVM: Adding instructions, intrinsics, types, etc. — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="How to set up LLVM-style RTTI for your class hierarchy" href="HowToSetUpLLVMStyleRTTI.html" />
+ <link rel="prev" title="Architecture & Platform Information for Compiler Writers" href="CompilerWriterInfo.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="extending-llvm-adding-instructions-intrinsics-types-etc">
+<h1>Extending LLVM: Adding instructions, intrinsics, types, etc.<a class="headerlink" href="#extending-llvm-adding-instructions-intrinsics-types-etc" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="introduction-and-warning">
+<h2>Introduction and Warning<a class="headerlink" href="#introduction-and-warning" title="Permalink to this headline">¶</a></h2>
+<p>During the course of using LLVM, you may wish to customize it for your research
+project or for experimentation. At this point, you may realize that you need to
+add something to LLVM, whether it be a new fundamental type, a new intrinsic
+function, or a whole new instruction.</p>
+<p>When you come to this realization, stop and think. Do you really need to extend
+LLVM? Is it a new fundamental capability that LLVM does not support at its
+current incarnation or can it be synthesized from already pre-existing LLVM
+elements? If you are not sure, ask on the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">LLVM-dev</a> list. The reason is that
+extending LLVM will get involved as you need to update all the different passes
+that you intend to use with your extension, and there are <tt class="docutils literal"><span class="pre">many</span></tt> LLVM analyses
+and transformations, so it may be quite a bit of work.</p>
+<p>Adding an <a class="reference internal" href="#intrinsic-function">intrinsic function</a> is far easier than adding an
+instruction, and is transparent to optimization passes. If your added
+functionality can be expressed as a function call, an intrinsic function is the
+method of choice for LLVM extension.</p>
+<p>Before you invest a significant amount of effort into a non-trivial extension,
+<strong>ask on the list</strong> if what you are looking to do can be done with
+already-existing infrastructure, or if maybe someone else is already working on
+it. You will save yourself a lot of time and effort by doing so.</p>
+</div>
+<div class="section" id="adding-a-new-intrinsic-function">
+<span id="intrinsic-function"></span><h2>Adding a new intrinsic function<a class="headerlink" href="#adding-a-new-intrinsic-function" title="Permalink to this headline">¶</a></h2>
+<p>Adding a new intrinsic function to LLVM is much easier than adding a new
+instruction. Almost all extensions to LLVM should start as an intrinsic
+function and then be turned into an instruction if warranted.</p>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/docs/LangRef.html</span></tt>:</p>
+<p>Document the intrinsic. Decide whether it is code generator specific and
+what the restrictions are. Talk to other people about it so that you are
+sure it’s a good idea.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Intrinsics*.td</span></tt>:</p>
+<p>Add an entry for your intrinsic. Describe its memory access characteristics
+for optimization (this controls whether it will be DCE’d, CSE’d, etc). Note
+that any intrinsic using one of the <tt class="docutils literal"><span class="pre">llvm_any*_ty</span></tt> types for an argument or
+return type will be deemed by <tt class="docutils literal"><span class="pre">tblgen</span></tt> as overloaded and the corresponding
+suffix will be required on the intrinsic’s name.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Analysis/ConstantFolding.cpp</span></tt>:</p>
+<p>If it is possible to constant fold your intrinsic, add support to it in the
+<tt class="docutils literal"><span class="pre">canConstantFoldCallTo</span></tt> and <tt class="docutils literal"><span class="pre">ConstantFoldCall</span></tt> functions.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/test/*</span></tt>:</p>
+<p>Add test cases for your test cases to the test suite</p>
+</li>
+</ol>
+<p>Once the intrinsic has been added to the system, you must add code generator
+support for it. Generally you must do the following steps:</p>
+<p>Add support to the .td file for the target(s) of your choice in
+<tt class="docutils literal"><span class="pre">lib/Target/*/*.td</span></tt>.</p>
+<blockquote>
+<div>This is usually a matter of adding a pattern to the .td file that matches the
+intrinsic, though it may obviously require adding the instructions you want to
+generate as well. There are lots of examples in the PowerPC and X86 backend
+to follow.</div></blockquote>
+</div>
+<div class="section" id="adding-a-new-selectiondag-node">
+<h2>Adding a new SelectionDAG node<a class="headerlink" href="#adding-a-new-selectiondag-node" title="Permalink to this headline">¶</a></h2>
+<p>As with intrinsics, adding a new SelectionDAG node to LLVM is much easier than
+adding a new instruction. New nodes are often added to help represent
+instructions common to many targets. These nodes often map to an LLVM
+instruction (add, sub) or intrinsic (byteswap, population count). In other
+cases, new nodes have been added to allow many targets to perform a common task
+(converting between floating point and integer representation) or capture more
+complicated behavior in a single node (rotate).</p>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">include/llvm/CodeGen/ISDOpcodes.h</span></tt>:</p>
+<p>Add an enum value for the new SelectionDAG node.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/SelectionDAG.cpp</span></tt>:</p>
+<dl class="docutils">
+<dt>Add code to print the node to <tt class="docutils literal"><span class="pre">getOperationName</span></tt>. If your new node can be</dt>
+<dd><p class="first last">evaluated at compile time when given constant arguments (such as an add of a
+constant with another constant), find the <tt class="docutils literal"><span class="pre">getNode</span></tt> method that takes the
+appropriate number of arguments, and add a case for your node to the switch
+statement that performs constant folding for nodes that take the same number
+of arguments as your new node.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></tt>:</p>
+<p>Add code to <a class="reference external" href="CodeGenerator.html#selectiondag_legalize">legalize, promote, and expand</a> the node as necessary. At a
+minimum, you will need to add a case statement for your node in
+<tt class="docutils literal"><span class="pre">LegalizeOp</span></tt> which calls LegalizeOp on the node’s operands, and returns a
+new node if any of the operands changed as a result of being legalized. It
+is likely that not all targets supported by the SelectionDAG framework will
+natively support the new node. In this case, you must also add code in your
+node’s case statement in <tt class="docutils literal"><span class="pre">LegalizeOp</span></tt> to Expand your node into simpler,
+legal operations. The case for <tt class="docutils literal"><span class="pre">ISD::UREM</span></tt> for expanding a remainder into
+a divide, multiply, and a subtract is a good example.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></tt>:</p>
+<dl class="docutils">
+<dt>If targets may support the new node being added only at certain sizes, you</dt>
+<dd><p class="first last">will also need to add code to your node’s case statement in <tt class="docutils literal"><span class="pre">LegalizeOp</span></tt>
+to Promote your node’s operands to a larger size, and perform the correct
+operation. You will also need to add code to <tt class="docutils literal"><span class="pre">PromoteOp</span></tt> to do this as
+well. For a good example, see <tt class="docutils literal"><span class="pre">ISD::BSWAP</span></tt>, which promotes its operand to
+a wider size, performs the byteswap, and then shifts the correct bytes right
+to emulate the narrower byteswap in the wider type.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></tt>:</p>
+<p>Add a case for your node in <tt class="docutils literal"><span class="pre">ExpandOp</span></tt> to teach the legalizer how to
+perform the action represented by the new node on a value that has been split
+into high and low halves. This case will be used to support your node with a
+64 bit operand on a 32 bit target.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/CodeGen/SelectionDAG/DAGCombiner.cpp</span></tt>:</p>
+<p>If your node can be combined with itself, or other existing nodes in a
+peephole-like fashion, add a visit function for it, and call that function
+from. There are several good examples for simple combines you can do;
+<tt class="docutils literal"><span class="pre">visitFABS</span></tt> and <tt class="docutils literal"><span class="pre">visitSRL</span></tt> are good starting places.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/Target/PowerPC/PPCISelLowering.cpp</span></tt>:</p>
+<p>Each target has an implementation of the <tt class="docutils literal"><span class="pre">TargetLowering</span></tt> class, usually in
+its own file (although some targets include it in the same file as the
+DAGToDAGISel). The default behavior for a target is to assume that your new
+node is legal for all types that are legal for that target. If this target
+does not natively support your node, then tell the target to either Promote
+it (if it is supported at a larger type) or Expand it. This will cause the
+code you wrote in <tt class="docutils literal"><span class="pre">LegalizeOp</span></tt> above to decompose your new node into other
+legal nodes for this target.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/Target/TargetSelectionDAG.td</span></tt>:</p>
+<p>Most current targets supported by LLVM generate code using the DAGToDAG
+method, where SelectionDAG nodes are pattern matched to target-specific
+nodes, which represent individual instructions. In order for the targets to
+match an instruction to your new node, you must add a def for that node to
+the list in this file, with the appropriate type constraints. Look at
+<tt class="docutils literal"><span class="pre">add</span></tt>, <tt class="docutils literal"><span class="pre">bswap</span></tt>, and <tt class="docutils literal"><span class="pre">fadd</span></tt> for examples.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">lib/Target/PowerPC/PPCInstrInfo.td</span></tt>:</p>
+<p>Each target has a tablegen file that describes the target’s instruction set.
+For targets that use the DAGToDAG instruction selection framework, add a
+pattern for your new node that uses one or more target nodes. Documentation
+for this is a bit sparse right now, but there are several decent examples.
+See the patterns for <tt class="docutils literal"><span class="pre">rotl</span></tt> in <tt class="docutils literal"><span class="pre">PPCInstrInfo.td</span></tt>.</p>
+</li>
+<li><p class="first">TODO: document complex patterns.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/test/CodeGen/*</span></tt>:</p>
+<p>Add test cases for your new node to the test suite.
+<tt class="docutils literal"><span class="pre">llvm/test/CodeGen/X86/bswap.ll</span></tt> is a good example.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="adding-a-new-instruction">
+<h2>Adding a new instruction<a class="headerlink" href="#adding-a-new-instruction" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Adding instructions changes the bitcode format, and it will take some effort
+to maintain compatibility with the previous version. Only add an instruction
+if it is absolutely necessary.</p>
+</div>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Instruction.def</span></tt>:</p>
+<p>add a number for your instruction and an enum name</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Instructions.h</span></tt>:</p>
+<p>add a definition for the class that will represent your instruction</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/InstVisitor.h</span></tt>:</p>
+<p>add a prototype for a visitor to your new instruction type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></tt>:</p>
+<p>add a new token to parse your instruction from assembly text file</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLParser.cpp</span></tt>:</p>
+<p>add the grammar on how your instruction can be read and what it will
+construct as a result</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></tt>:</p>
+<p>add a case for your instruction and how it will be parsed from bitcode</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></tt>:</p>
+<p>add a case for your instruction and how it will be parsed from bitcode</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/Instruction.cpp</span></tt>:</p>
+<p>add a case for how your instruction will be printed out to assembly</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/Instructions.cpp</span></tt>:</p>
+<p>implement the class you defined in <tt class="docutils literal"><span class="pre">llvm/include/llvm/Instructions.h</span></tt></p>
+</li>
+<li><p class="first">Test your instruction</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Target/*</span></tt>:</p>
+<p>add support for your instruction to code generators, or add a lowering pass.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/test/*</span></tt>:</p>
+<p>add your test cases to the test suite.</p>
+</li>
+</ol>
+<p>Also, you need to implement (or modify) any analyses or passes that you want to
+understand this new instruction.</p>
+</div>
+<div class="section" id="adding-a-new-type">
+<h2>Adding a new type<a class="headerlink" href="#adding-a-new-type" title="Permalink to this headline">¶</a></h2>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Adding new types changes the bitcode format, and will break compatibility with
+currently-existing LLVM installations. Only add new types if it is absolutely
+necessary.</p>
+</div>
+<div class="section" id="adding-a-fundamental-type">
+<h3>Adding a fundamental type<a class="headerlink" href="#adding-a-fundamental-type" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Type.h</span></tt>:</p>
+<p>add enum for the new type; add static <tt class="docutils literal"><span class="pre">Type*</span></tt> for this type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/Type.cpp</span></tt> and <tt class="docutils literal"><span class="pre">llvm/lib/IR/ValueTypes.cpp</span></tt>:</p>
+<p>add mapping from <tt class="docutils literal"><span class="pre">TypeID</span></tt> => <tt class="docutils literal"><span class="pre">Type*</span></tt>; initialize the static <tt class="docutils literal"><span class="pre">Type*</span></tt></p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/llvm/llvm-c/Core.cpp</span></tt>:</p>
+<p>add enum <tt class="docutils literal"><span class="pre">LLVMTypeKind</span></tt> and modify
+<tt class="docutils literal"><span class="pre">LLVMTypeKind</span> <span class="pre">LLVMGetTypeKind(LLVMTypeRef</span> <span class="pre">Ty)</span></tt> for the new type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/TypeBuilder.h</span></tt>:</p>
+<p>add new class to represent new type in the hierarchy</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></tt>:</p>
+<p>add ability to parse in the type from text assembly</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLParser.cpp</span></tt>:</p>
+<p>add a token for that type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">static</span> <span class="pre">void</span> <span class="pre">WriteTypeTable(const</span> <span class="pre">ValueEnumerator</span> <span class="pre">&VE,</span>
+<span class="pre">BitstreamWriter</span> <span class="pre">&Stream)</span></tt> to serialize your type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">bool</span> <span class="pre">BitcodeReader::ParseTypeType()</span></tt> to read your data type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">include/llvm/Bitcode/LLVMBitCodes.h</span></tt>:</p>
+<p>add enum <tt class="docutils literal"><span class="pre">TypeCodes</span></tt> for the new type</p>
+</li>
+</ol>
+</div>
+<div class="section" id="adding-a-derived-type">
+<h3>Adding a derived type<a class="headerlink" href="#adding-a-derived-type" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic">
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/Type.h</span></tt>:</p>
+<p>add enum for the new type; add a forward declaration of the type also</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/DerivedTypes.h</span></tt>:</p>
+<p>add new class to represent new class in the hierarchy; add forward
+declaration to the TypeMap value type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/Type.cpp</span></tt> and <tt class="docutils literal"><span class="pre">llvm/lib/IR/ValueTypes.cpp</span></tt>:</p>
+<p>add support for derived type, notably <cite>enum TypeID</cite> and <cite>is</cite>, <cite>get</cite> methods.</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/llvm/llvm-c/Core.cpp</span></tt>:</p>
+<p>add enum <tt class="docutils literal"><span class="pre">LLVMTypeKind</span></tt> and modify
+<cite>LLVMTypeKind LLVMGetTypeKind(LLVMTypeRef Ty)</cite> for the new type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/include/llvm/IR/TypeBuilder.h</span></tt>:</p>
+<p>add new class to represent new class in the hierarchy</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">lltok::Kind</span> <span class="pre">LLLexer::LexIdentifier()</span></tt> to add ability to
+parse in the type from text assembly</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">static</span> <span class="pre">void</span> <span class="pre">WriteTypeTable(const</span> <span class="pre">ValueEnumerator</span> <span class="pre">&VE,</span>
+<span class="pre">BitstreamWriter</span> <span class="pre">&Stream)</span></tt> to serialize your type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">bool</span> <span class="pre">BitcodeReader::ParseTypeType()</span></tt> to read your data type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">include/llvm/Bitcode/LLVMBitCodes.h</span></tt>:</p>
+<p>add enum <tt class="docutils literal"><span class="pre">TypeCodes</span></tt> for the new type</p>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">llvm/lib/IR/AsmWriter.cpp</span></tt>:</p>
+<p>modify <tt class="docutils literal"><span class="pre">void</span> <span class="pre">TypePrinting::print(Type</span> <span class="pre">*Ty,</span> <span class="pre">raw_ostream</span> <span class="pre">&OS)</span></tt>
+to output the new derived type</p>
+</li>
+</ol>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="HowToSetUpLLVMStyleRTTI.html" title="How to set up LLVM-style RTTI for your class hierarchy"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CompilerWriterInfo.html" title="Architecture & Platform Information for Compiler Writers"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/Extensions.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/Extensions.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/Extensions.html (added)
+++ www-releases/trunk/7.0.1/docs/Extensions.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,614 @@
+
+
+<!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 Extensions — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="libFuzzer â a library for coverage-guided fuzz testing." href="LibFuzzer.html" />
+ <link rel="prev" title="LLVM Programmerâs Manual" href="ProgrammersManual.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="llvm-extensions">
+<h1>LLVM Extensions<a class="headerlink" href="#llvm-extensions" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#introduction" id="id5">Introduction</a></li>
+<li><a class="reference internal" href="#general-assembly-syntax" id="id6">General Assembly Syntax</a><ul>
+<li><a class="reference internal" href="#c99-style-hexadecimal-floating-point-constants" id="id7">C99-style Hexadecimal Floating-point Constants</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#machine-specific-assembly-syntax" id="id8">Machine-specific Assembly Syntax</a><ul>
+<li><a class="reference internal" href="#x86-coff-dependent" id="id9">X86/COFF-Dependent</a><ul>
+<li><a class="reference internal" href="#relocations" id="id10">Relocations</a></li>
+<li><a class="reference internal" href="#linkonce-directive" id="id11"><tt class="docutils literal"><span class="pre">.linkonce</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#section-directive" id="id12"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#arm64-coff-dependent" id="id13">ARM64/COFF-Dependent</a><ul>
+<li><a class="reference internal" href="#id1" id="id14">Relocations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#elf-dependent" id="id15">ELF-Dependent</a><ul>
+<li><a class="reference internal" href="#id2" id="id16"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#linker-options-section-linker-options" id="id17"><tt class="docutils literal"><span class="pre">.linker-options</span></tt> Section (linker options)</a></li>
+<li><a class="reference internal" href="#sht-llvm-call-graph-profile-section-call-graph-profile" id="id18"><tt class="docutils literal"><span class="pre">SHT_LLVM_CALL_GRAPH_PROFILE</span></tt> Section (Call Graph Profile)</a></li>
+<li><a class="reference internal" href="#sht-llvm-addrsig-section-address-significance-table" id="id19"><tt class="docutils literal"><span class="pre">SHT_LLVM_ADDRSIG</span></tt> Section (address-significance table)</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#codeview-dependent" id="id20">CodeView-Dependent</a><ul>
+<li><a class="reference internal" href="#cv-file-directive" id="id21"><tt class="docutils literal"><span class="pre">.cv_file</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-func-id-directive" id="id22"><tt class="docutils literal"><span class="pre">.cv_func_id</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-inline-site-id-directive" id="id23"><tt class="docutils literal"><span class="pre">.cv_inline_site_id</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-loc-directive" id="id24"><tt class="docutils literal"><span class="pre">.cv_loc</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-linetable-directive" id="id25"><tt class="docutils literal"><span class="pre">.cv_linetable</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-inline-linetable-directive" id="id26"><tt class="docutils literal"><span class="pre">.cv_inline_linetable</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-def-range-directive" id="id27"><tt class="docutils literal"><span class="pre">.cv_def_range</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-stringtable-directive" id="id28"><tt class="docutils literal"><span class="pre">.cv_stringtable</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-filechecksums-directive" id="id29"><tt class="docutils literal"><span class="pre">.cv_filechecksums</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-filechecksumoffset-directive" id="id30"><tt class="docutils literal"><span class="pre">.cv_filechecksumoffset</span></tt> Directive</a></li>
+<li><a class="reference internal" href="#cv-fpo-data-directive" id="id31"><tt class="docutils literal"><span class="pre">.cv_fpo_data</span></tt> Directive</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#target-specific-behaviour" id="id32">Target Specific Behaviour</a><ul>
+<li><a class="reference internal" href="#x86" id="id33">X86</a><ul>
+<li><a class="reference internal" href="#id3" id="id34">Relocations</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#windows-on-arm" id="id35">Windows on ARM</a><ul>
+<li><a class="reference internal" href="#stack-probe-emission" id="id36">Stack Probe Emission</a></li>
+<li><a class="reference internal" href="#variable-length-arrays" id="id37">Variable Length Arrays</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#windows-on-arm64" id="id38">Windows on ARM64</a><ul>
+<li><a class="reference internal" href="#id4" id="id39">Stack Probe Emission</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="toctree-wrapper compound">
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id5">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes extensions to tools and formats LLVM seeks compatibility
+with.</p>
+</div>
+<div class="section" id="general-assembly-syntax">
+<h2><a class="toc-backref" href="#id6">General Assembly Syntax</a><a class="headerlink" href="#general-assembly-syntax" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="c99-style-hexadecimal-floating-point-constants">
+<h3><a class="toc-backref" href="#id7">C99-style Hexadecimal Floating-point Constants</a><a class="headerlink" href="#c99-style-hexadecimal-floating-point-constants" title="Permalink to this headline">¶</a></h3>
+<p>LLVM’s assemblers allow floating-point constants to be written in C99’s
+hexadecimal format instead of decimal if desired.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.data</span>
+<span class="na">.float</span> <span class="mi">0x1c2</span><span class="no">.2ap3</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="machine-specific-assembly-syntax">
+<h2><a class="toc-backref" href="#id8">Machine-specific Assembly Syntax</a><a class="headerlink" href="#machine-specific-assembly-syntax" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="x86-coff-dependent">
+<h3><a class="toc-backref" href="#id9">X86/COFF-Dependent</a><a class="headerlink" href="#x86-coff-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="relocations">
+<h4><a class="toc-backref" href="#id10">Relocations</a><a class="headerlink" href="#relocations" title="Permalink to this headline">¶</a></h4>
+<p>The following additional relocation types are supported:</p>
+<p><strong>@IMGREL</strong> (AT&T syntax only) generates an image-relative relocation that
+corresponds to the COFF relocation types <tt class="docutils literal"><span class="pre">IMAGE_REL_I386_DIR32NB</span></tt> (32-bit) or
+<tt class="docutils literal"><span class="pre">IMAGE_REL_AMD64_ADDR32NB</span></tt> (64-bit).</p>
+<div class="highlight-text"><div class="highlight"><pre>.text
+fun:
+ mov foo at IMGREL(%ebx, %ecx, 4), %eax
+
+.section .pdata
+ .long fun at IMGREL
+ .long (fun at imgrel + 0x3F)
+ .long $unwind$fun at imgrel
+</pre></div>
+</div>
+<p><strong>.secrel32</strong> generates a relocation that corresponds to the COFF relocation
+types <tt class="docutils literal"><span class="pre">IMAGE_REL_I386_SECREL</span></tt> (32-bit) or <tt class="docutils literal"><span class="pre">IMAGE_REL_AMD64_SECREL</span></tt> (64-bit).</p>
+<p><strong>.secidx</strong> relocation generates an index of the section that contains
+the target. It corresponds to the COFF relocation types
+<tt class="docutils literal"><span class="pre">IMAGE_REL_I386_SECTION</span></tt> (32-bit) or <tt class="docutils literal"><span class="pre">IMAGE_REL_AMD64_SECTION</span></tt> (64-bit).</p>
+<div class="highlight-none"><div class="highlight"><pre>.section .debug$S,"rn"
+ .long 4
+ .long 242
+ .long 40
+ .secrel32 _function_name + 0
+ .secidx _function_name
+ ...
+</pre></div>
+</div>
+</div>
+<div class="section" id="linkonce-directive">
+<h4><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">.linkonce</span></tt> Directive</a><a class="headerlink" href="#linkonce-directive" title="Permalink to this headline">¶</a></h4>
+<p>Syntax:</p>
+<blockquote>
+<div><tt class="docutils literal"><span class="pre">.linkonce</span> <span class="pre">[</span> <span class="pre">comdat</span> <span class="pre">type</span> <span class="pre">]</span></tt></div></blockquote>
+<p>Supported COMDAT types:</p>
+<dl class="docutils">
+<dt><tt class="docutils literal"><span class="pre">discard</span></tt></dt>
+<dd>Discards duplicate sections with the same COMDAT symbol. This is the default
+if no type is specified.</dd>
+<dt><tt class="docutils literal"><span class="pre">one_only</span></tt></dt>
+<dd>If the symbol is defined multiple times, the linker issues an error.</dd>
+<dt><tt class="docutils literal"><span class="pre">same_size</span></tt></dt>
+<dd>Duplicates are discarded, but the linker issues an error if any have
+different sizes.</dd>
+<dt><tt class="docutils literal"><span class="pre">same_contents</span></tt></dt>
+<dd>Duplicates are discarded, but the linker issues an error if any duplicates
+do not have exactly the same content.</dd>
+<dt><tt class="docutils literal"><span class="pre">largest</span></tt></dt>
+<dd>Links the largest section from among the duplicates.</dd>
+<dt><tt class="docutils literal"><span class="pre">newest</span></tt></dt>
+<dd>Links the newest section from among the duplicates.</dd>
+</dl>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.text$foo</span>
+<span class="na">.linkonce</span>
+ <span class="na">...</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="section-directive">
+<h4><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a><a class="headerlink" href="#section-directive" title="Permalink to this headline">¶</a></h4>
+<p>MC supports passing the information in <tt class="docutils literal"><span class="pre">.linkonce</span></tt> at the end of
+<tt class="docutils literal"><span class="pre">.section</span></tt>. For example, these two codes are equivalent</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol1"</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span>
+<span class="na">.linkonce</span> <span class="no">discard</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<p>Note that in the combined form the COMDAT symbol is explicit. This
+extension exists to support multiple sections with the same name in
+different COMDATs:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol1"</span>
+<span class="na">.globl</span> <span class="no">Symbol1</span>
+<span class="nl">Symbol1:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+
+<span class="na">.section</span> <span class="no">secName</span><span class="p">,</span> <span class="s">"dr"</span><span class="p">,</span> <span class="no">discard</span><span class="p">,</span> <span class="s">"Symbol2"</span>
+<span class="na">.globl</span> <span class="no">Symbol2</span>
+<span class="nl">Symbol2:</span>
+<span class="na">.long</span> <span class="mi">1</span>
+</pre></div>
+</div>
+<p>In addition to the types allowed with <tt class="docutils literal"><span class="pre">.linkonce</span></tt>, <tt class="docutils literal"><span class="pre">.section</span></tt> also accepts
+<tt class="docutils literal"><span class="pre">associative</span></tt>. The meaning is that the section is linked if a certain other
+COMDAT section is linked. This other section is indicated by the comdat symbol
+in this directive. It can be any symbol defined in the associated section, but
+is usually the associated section’s comdat.</p>
+<blockquote>
+<div><p>The following restrictions apply to the associated section:</p>
+<ol class="arabic simple">
+<li>It must be a COMDAT section.</li>
+<li>It cannot be another associative COMDAT section.</li>
+</ol>
+</div></blockquote>
+<p>In the following example the symobl <tt class="docutils literal"><span class="pre">sym</span></tt> is the comdat symbol of <tt class="docutils literal"><span class="pre">.foo</span></tt>
+and <tt class="docutils literal"><span class="pre">.bar</span></tt> is associated to <tt class="docutils literal"><span class="pre">.foo</span></tt>.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.foo</span><span class="p">,</span><span class="s">"bw"</span><span class="p">,</span><span class="no">discard</span><span class="p">,</span> <span class="s">"sym"</span>
+<span class="na">.section</span> <span class="no">.bar</span><span class="p">,</span><span class="s">"rd"</span><span class="p">,</span><span class="no">associative</span><span class="p">,</span> <span class="s">"sym"</span>
+</pre></div>
+</div>
+<p>MC supports these flags in the COFF <tt class="docutils literal"><span class="pre">.section</span></tt> directive:</p>
+<blockquote>
+<div><ul class="simple">
+<li><tt class="docutils literal"><span class="pre">b</span></tt>: BSS section (<tt class="docutils literal"><span class="pre">IMAGE_SCN_CNT_INITIALIZED_DATA</span></tt>)</li>
+<li><tt class="docutils literal"><span class="pre">d</span></tt>: Data section (<tt class="docutils literal"><span class="pre">IMAGE_SCN_CNT_UNINITIALIZED_DATA</span></tt>)</li>
+<li><tt class="docutils literal"><span class="pre">n</span></tt>: Section is not loaded (<tt class="docutils literal"><span class="pre">IMAGE_SCN_LNK_REMOVE</span></tt>)</li>
+<li><tt class="docutils literal"><span class="pre">r</span></tt>: Read-only</li>
+<li><tt class="docutils literal"><span class="pre">s</span></tt>: Shared section</li>
+<li><tt class="docutils literal"><span class="pre">w</span></tt>: Writable</li>
+<li><tt class="docutils literal"><span class="pre">x</span></tt>: Executable section</li>
+<li><tt class="docutils literal"><span class="pre">y</span></tt>: Not readable</li>
+<li><tt class="docutils literal"><span class="pre">D</span></tt>: Discardable (<tt class="docutils literal"><span class="pre">IMAGE_SCN_MEM_DISCARDABLE</span></tt>)</li>
+</ul>
+</div></blockquote>
+<p>These flags are all compatible with gas, with the exception of the <tt class="docutils literal"><span class="pre">D</span></tt> flag,
+which gnu as does not support. For gas compatibility, sections with a name
+starting with ”.debug” are implicitly discardable.</p>
+</div>
+</div>
+<div class="section" id="arm64-coff-dependent">
+<h3><a class="toc-backref" href="#id13">ARM64/COFF-Dependent</a><a class="headerlink" href="#arm64-coff-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id1">
+<h4><a class="toc-backref" href="#id14">Relocations</a><a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h4>
+<p>The following additional symbol variants are supported:</p>
+<p><strong>:secrel_lo12:</strong> generates a relocation that corresponds to the COFF relocation
+types <tt class="docutils literal"><span class="pre">IMAGE_REL_ARM64_SECREL_LOW12A</span></tt> or <tt class="docutils literal"><span class="pre">IMAGE_REL_ARM64_SECREL_LOW12L</span></tt>.</p>
+<p><strong>:secrel_hi12:</strong> generates a relocation that corresponds to the COFF relocation
+type <tt class="docutils literal"><span class="pre">IMAGE_REL_ARM64_SECREL_HIGH12A</span></tt>.</p>
+<div class="highlight-gas"><pre>add x0, x0, :secrel_hi12:symbol
+ldr x0, [x0, :secrel_lo12:symbol]
+
+add x1, x1, :secrel_hi12:symbol
+add x1, x1, :secrel_lo12:symbol
+...</pre>
+</div>
+</div>
+</div>
+<div class="section" id="elf-dependent">
+<h3><a class="toc-backref" href="#id15">ELF-Dependent</a><a class="headerlink" href="#elf-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id2">
+<h4><a class="toc-backref" href="#id16"><tt class="docutils literal"><span class="pre">.section</span></tt> Directive</a><a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h4>
+<p>In order to support creating multiple sections with the same name and comdat,
+it is possible to add an unique number at the end of the <tt class="docutils literal"><span class="pre">.seciton</span></tt> directive.
+For example, the following code creates two sections named <tt class="docutils literal"><span class="pre">.text</span></tt>.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.text</span><span class="p">,</span><span class="s">"ax"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,</span><span class="no">unique</span><span class="p">,</span><span class="mi">1</span>
+<span class="nf">nop</span>
+
+<span class="na">.section</span> <span class="no">.text</span><span class="p">,</span><span class="s">"ax"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,</span><span class="no">unique</span><span class="p">,</span><span class="mi">2</span>
+<span class="nf">nop</span>
+</pre></div>
+</div>
+<p>The unique number is not present in the resulting object at all. It is just used
+in the assembler to differentiate the sections.</p>
+<p>The ‘o’ flag is mapped to SHF_LINK_ORDER. If it is present, a symbol
+must be given that identifies the section to be placed is the
+.sh_link.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.foo</span><span class="p">,</span><span class="s">"a"</span><span class="p">,</span><span class="na">@progbits</span>
+<span class="nl">.Ltmp:</span>
+<span class="na">.section</span> <span class="no">.bar</span><span class="p">,</span><span class="s">"ao"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,.</span><span class="no">Ltmp</span>
+</pre></div>
+</div>
+<p>which is equivalent to just</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="no">.foo</span><span class="p">,</span><span class="s">"a"</span><span class="p">,</span><span class="na">@progbits</span>
+<span class="na">.section</span> <span class="no">.bar</span><span class="p">,</span><span class="s">"ao"</span><span class="p">,</span><span class="na">@progbits</span><span class="p">,.</span><span class="no">foo</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="linker-options-section-linker-options">
+<h4><a class="toc-backref" href="#id17"><tt class="docutils literal"><span class="pre">.linker-options</span></tt> Section (linker options)</a><a class="headerlink" href="#linker-options-section-linker-options" title="Permalink to this headline">¶</a></h4>
+<p>In order to support passing linker options from the frontend to the linker, a
+special section of type <tt class="docutils literal"><span class="pre">SHT_LLVM_LINKER_OPTIONS</span></tt> (usually named
+<tt class="docutils literal"><span class="pre">.linker-options</span></tt> though the name is not significant as it is identified by
+the type). The contents of this section is a simple pair-wise encoding of
+directives for consideration by the linker. The strings are encoded as standard
+null-terminated UTF-8 strings. They are emitted inline to avoid having the
+linker traverse the object file for retrieving the value. The linker is
+permitted to not honour the option and instead provide a warning/error to the
+user that the requested option was not honoured.</p>
+<p>The section has type <tt class="docutils literal"><span class="pre">SHT_LLVM_LINKER_OPTIONS</span></tt> and has the <tt class="docutils literal"><span class="pre">SHF_EXCLUDE</span></tt>
+flag to ensure that the section is treated as opaque by linkers which do not
+support the feature and will not be emitted into the final linked binary.</p>
+<p>This would be equivalent to the follow raw assembly:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.section</span> <span class="s">".linker-options"</span><span class="p">,</span><span class="s">"e"</span><span class="p">,</span><span class="na">@llvm_linker_options</span>
+<span class="na">.asciz</span> <span class="s">"option 1"</span>
+<span class="na">.asciz</span> <span class="s">"value 1"</span>
+<span class="na">.asciz</span> <span class="s">"option 2"</span>
+<span class="na">.asciz</span> <span class="s">"value 2"</span>
+</pre></div>
+</div>
+<p>The following directives are specified:</p>
+<blockquote>
+<div><ul>
+<li><p class="first">lib</p>
+<p>The parameter identifies a library to be linked against. The library will
+be looked up in the default and any specified library search paths
+(specified to this point).</p>
+</li>
+<li><p class="first">libpath</p>
+<p>The paramter identifies an additional library search path to be considered
+when looking up libraries after the inclusion of this option.</p>
+</li>
+</ul>
+</div></blockquote>
+</div>
+<div class="section" id="sht-llvm-call-graph-profile-section-call-graph-profile">
+<h4><a class="toc-backref" href="#id18"><tt class="docutils literal"><span class="pre">SHT_LLVM_CALL_GRAPH_PROFILE</span></tt> Section (Call Graph Profile)</a><a class="headerlink" href="#sht-llvm-call-graph-profile-section-call-graph-profile" title="Permalink to this headline">¶</a></h4>
+<p>This section is used to pass a call graph profile to the linker which can be
+used to optimize the placement of sections. It contains a sequence of
+(from symbol, to symbol, weight) tuples.</p>
+<p>It shall have a type of <tt class="docutils literal"><span class="pre">SHT_LLVM_CALL_GRAPH_PROFILE</span></tt> (0x6fff4c02), shall
+have the <tt class="docutils literal"><span class="pre">SHF_EXCLUDE</span></tt> flag set, the <tt class="docutils literal"><span class="pre">sh_link</span></tt> member shall hold the section
+header index of the associated symbol table, and shall have a <tt class="docutils literal"><span class="pre">sh_entsize</span></tt> of
+16. It should be named <tt class="docutils literal"><span class="pre">.llvm.call-graph-profile</span></tt>.</p>
+<p>The contents of the section shall be a sequence of <tt class="docutils literal"><span class="pre">Elf_CGProfile</span></tt> entries.</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
+ <span class="n">Elf_Word</span> <span class="n">cgp_from</span><span class="p">;</span>
+ <span class="n">Elf_Word</span> <span class="n">cgp_to</span><span class="p">;</span>
+ <span class="n">Elf_Xword</span> <span class="n">cgp_weight</span><span class="p">;</span>
+<span class="p">}</span> <span class="n">Elf_CGProfile</span><span class="p">;</span>
+</pre></div>
+</div>
+<dl class="docutils">
+<dt>cgp_from</dt>
+<dd>The symbol index of the source of the edge.</dd>
+<dt>cgp_to</dt>
+<dd>The symbol index of the destination of the edge.</dd>
+<dt>cgp_weight</dt>
+<dd>The weight of the edge.</dd>
+</dl>
+<p>This is represented in assembly as:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.cg_profile</span> <span class="no">from</span><span class="p">,</span> <span class="no">to</span><span class="p">,</span> <span class="mi">42</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">.cg_profile</span></tt> directives are processed at the end of the file. It is an error
+if either <tt class="docutils literal"><span class="pre">from</span></tt> or <tt class="docutils literal"><span class="pre">to</span></tt> are undefined temporary symbols. If either symbol
+is a temporary symbol, then the section symbol is used instead. If either
+symbol is undefined, then that symbol is defined as if <tt class="docutils literal"><span class="pre">.weak</span> <span class="pre">symbol</span></tt> has been
+written at the end of the file. This forces the symbol to show up in the symbol
+table.</p>
+</div>
+<div class="section" id="sht-llvm-addrsig-section-address-significance-table">
+<h4><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">SHT_LLVM_ADDRSIG</span></tt> Section (address-significance table)</a><a class="headerlink" href="#sht-llvm-addrsig-section-address-significance-table" title="Permalink to this headline">¶</a></h4>
+<p>This section is used to mark symbols as address-significant, i.e. the address
+of the symbol is used in a comparison or leaks outside the translation unit. It
+has the same meaning as the absence of the LLVM attributes <tt class="docutils literal"><span class="pre">unnamed_addr</span></tt>
+and <tt class="docutils literal"><span class="pre">local_unnamed_addr</span></tt>.</p>
+<p>Any sections referred to by symbols that are not marked as address-significant
+in any object file may be safely merged by a linker without breaking the
+address uniqueness guarantee provided by the C and C++ language standards.</p>
+<p>The contents of the section are a sequence of ULEB128-encoded integers
+referring to the symbol table indexes of the address-significant symbols.</p>
+<p>There are two associated assembly directives:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.addrsig</span>
+</pre></div>
+</div>
+<p>This instructs the assembler to emit an address-significance table. Without
+this directive, all symbols are considered address-significant.</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="na">.addrsig_sym</span> <span class="no">sym</span>
+</pre></div>
+</div>
+<p>This marks <tt class="docutils literal"><span class="pre">sym</span></tt> as address-significant.</p>
+</div>
+</div>
+<div class="section" id="codeview-dependent">
+<h3><a class="toc-backref" href="#id20">CodeView-Dependent</a><a class="headerlink" href="#codeview-dependent" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="cv-file-directive">
+<h4><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">.cv_file</span></tt> Directive</a><a class="headerlink" href="#cv-file-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><tt class="docutils literal"><span class="pre">.cv_file</span></tt> <em>FileNumber FileName</em> [ <em>checksum</em> ] [ <em>checksumkind</em> ]</dd>
+</dl>
+</div>
+<div class="section" id="cv-func-id-directive">
+<h4><a class="toc-backref" href="#id22"><tt class="docutils literal"><span class="pre">.cv_func_id</span></tt> Directive</a><a class="headerlink" href="#cv-func-id-directive" title="Permalink to this headline">¶</a></h4>
+<p>Introduces a function ID that can be used with <tt class="docutils literal"><span class="pre">.cv_loc</span></tt>.</p>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><tt class="docutils literal"><span class="pre">.cv_func_id</span></tt> <em>FunctionId</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-inline-site-id-directive">
+<h4><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">.cv_inline_site_id</span></tt> Directive</a><a class="headerlink" href="#cv-inline-site-id-directive" title="Permalink to this headline">¶</a></h4>
+<p>Introduces a function ID that can be used with <tt class="docutils literal"><span class="pre">.cv_loc</span></tt>. Includes
+<tt class="docutils literal"><span class="pre">inlined</span> <span class="pre">at</span></tt> source location information for use in the line table of the
+caller, whether the caller is a real function or another inlined call site.</p>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><tt class="docutils literal"><span class="pre">.cv_inline_site_id</span></tt> <em>FunctionId</em> <tt class="docutils literal"><span class="pre">within</span></tt> <em>Function</em> <tt class="docutils literal"><span class="pre">inlined_at</span></tt> <em>FileNumber Line</em> [ <em>Colomn</em> ]</dd>
+</dl>
+</div>
+<div class="section" id="cv-loc-directive">
+<h4><a class="toc-backref" href="#id24"><tt class="docutils literal"><span class="pre">.cv_loc</span></tt> Directive</a><a class="headerlink" href="#cv-loc-directive" title="Permalink to this headline">¶</a></h4>
+<p>The first number is a file number, must have been previously assigned with a
+<tt class="docutils literal"><span class="pre">.file</span></tt> directive, the second number is the line number and optionally the
+third number is a column position (zero if not specified). The remaining
+optional items are <tt class="docutils literal"><span class="pre">.loc</span></tt> sub-directives.</p>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><tt class="docutils literal"><span class="pre">.cv_loc</span></tt> <em>FunctionId FileNumber</em> [ <em>Line</em> ] [ <em>Column</em> ] [ <em>prologue_end</em> ] [ <tt class="docutils literal"><span class="pre">is_stmt</span></tt> <em>value</em> ]</dd>
+</dl>
+</div>
+<div class="section" id="cv-linetable-directive">
+<h4><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">.cv_linetable</span></tt> Directive</a><a class="headerlink" href="#cv-linetable-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><tt class="docutils literal"><span class="pre">.cv_linetable</span></tt> <em>FunctionId</em> <tt class="docutils literal"><span class="pre">,</span></tt> <em>FunctionStart</em> <tt class="docutils literal"><span class="pre">,</span></tt> <em>FunctionEnd</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-inline-linetable-directive">
+<h4><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">.cv_inline_linetable</span></tt> Directive</a><a class="headerlink" href="#cv-inline-linetable-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><tt class="docutils literal"><span class="pre">.cv_inline_linetable</span></tt> <em>PrimaryFunctionId</em> <tt class="docutils literal"><span class="pre">,</span></tt> <em>FileNumber Line FunctionStart FunctionEnd</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-def-range-directive">
+<h4><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">.cv_def_range</span></tt> Directive</a><a class="headerlink" href="#cv-def-range-directive" title="Permalink to this headline">¶</a></h4>
+<p>The <em>GapStart</em> and <em>GapEnd</em> options may be repeated as needed.</p>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><tt class="docutils literal"><span class="pre">.cv_def_range</span></tt> <em>RangeStart RangeEnd</em> [ <em>GapStart GapEnd</em> ] <tt class="docutils literal"><span class="pre">,</span></tt> <em>bytes</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-stringtable-directive">
+<h4><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">.cv_stringtable</span></tt> Directive</a><a class="headerlink" href="#cv-stringtable-directive" title="Permalink to this headline">¶</a></h4>
+</div>
+<div class="section" id="cv-filechecksums-directive">
+<h4><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">.cv_filechecksums</span></tt> Directive</a><a class="headerlink" href="#cv-filechecksums-directive" title="Permalink to this headline">¶</a></h4>
+</div>
+<div class="section" id="cv-filechecksumoffset-directive">
+<h4><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">.cv_filechecksumoffset</span></tt> Directive</a><a class="headerlink" href="#cv-filechecksumoffset-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><tt class="docutils literal"><span class="pre">.cv_filechecksumoffset</span></tt> <em>FileNumber</em></dd>
+</dl>
+</div>
+<div class="section" id="cv-fpo-data-directive">
+<h4><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">.cv_fpo_data</span></tt> Directive</a><a class="headerlink" href="#cv-fpo-data-directive" title="Permalink to this headline">¶</a></h4>
+<dl class="docutils">
+<dt>Syntax:</dt>
+<dd><tt class="docutils literal"><span class="pre">.cv_fpo_data</span></tt> <em>procsym</em></dd>
+</dl>
+</div>
+</div>
+</div>
+<div class="section" id="target-specific-behaviour">
+<h2><a class="toc-backref" href="#id32">Target Specific Behaviour</a><a class="headerlink" href="#target-specific-behaviour" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="x86">
+<h3><a class="toc-backref" href="#id33">X86</a><a class="headerlink" href="#x86" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id3">
+<h4><a class="toc-backref" href="#id34">Relocations</a><a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h4>
+<p><tt class="docutils literal"><span class="pre">@ABS8</span></tt> can be applied to symbols which appear as immediate operands to
+instructions that have an 8-bit immediate form for that operand. It causes
+the assembler to use the 8-bit form and an 8-bit relocation (e.g. <tt class="docutils literal"><span class="pre">R_386_8</span></tt>
+or <tt class="docutils literal"><span class="pre">R_X86_64_8</span></tt>) for the symbol.</p>
+<p>For example:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="nf">cmpq</span> <span class="no">$foo at ABS8</span><span class="p">,</span> <span class="nv">%rdi</span>
+</pre></div>
+</div>
+<p>This causes the assembler to select the form of the 64-bit <tt class="docutils literal"><span class="pre">cmpq</span></tt> instruction
+that takes an 8-bit immediate operand that is sign extended to 64 bits, as
+opposed to <tt class="docutils literal"><span class="pre">cmpq</span> <span class="pre">$foo,</span> <span class="pre">%rdi</span></tt> which takes a 32-bit immediate operand. This
+is also not the same as <tt class="docutils literal"><span class="pre">cmpb</span> <span class="pre">$foo,</span> <span class="pre">%dil</span></tt>, which is an 8-bit comparison.</p>
+</div>
+</div>
+<div class="section" id="windows-on-arm">
+<h3><a class="toc-backref" href="#id35">Windows on ARM</a><a class="headerlink" href="#windows-on-arm" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="stack-probe-emission">
+<h4><a class="toc-backref" href="#id36">Stack Probe Emission</a><a class="headerlink" href="#stack-probe-emission" title="Permalink to this headline">¶</a></h4>
+<p>The reference implementation (Microsoft Visual Studio 2012) emits stack probes
+in the following fashion:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="nf">movw</span> <span class="no">r4</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="nf">bl</span> <span class="no">__chkstk</span>
+<span class="nf">sub.w</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">r4</span>
+</pre></div>
+</div>
+<p>However, this has the limitation of 32 MiB (±16MiB). In order to accommodate
+larger binaries, LLVM supports the use of <tt class="docutils literal"><span class="pre">-mcode-model=large</span></tt> to allow a 4GiB
+range via a slight deviation. It will generate an indirect jump as follows:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="nf">movw</span> <span class="no">r4</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="nf">movw</span> <span class="no">r12</span><span class="p">,</span> <span class="p">:</span><span class="no">lower16</span><span class="p">:</span><span class="no">__chkstk</span>
+<span class="nf">movt</span> <span class="no">r12</span><span class="p">,</span> <span class="p">:</span><span class="no">upper16</span><span class="p">:</span><span class="no">__chkstk</span>
+<span class="nf">blx</span> <span class="no">r12</span>
+<span class="nf">sub.w</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">r4</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="variable-length-arrays">
+<h4><a class="toc-backref" href="#id37">Variable Length Arrays</a><a class="headerlink" href="#variable-length-arrays" title="Permalink to this headline">¶</a></h4>
+<p>The reference implementation (Microsoft Visual Studio 2012) does not permit the
+emission of Variable Length Arrays (VLAs).</p>
+<p>The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
+a dynamic stack allocation. When emitting a variable stack allocation, a call
+to <tt class="docutils literal"><span class="pre">__chkstk</span></tt> is emitted unconditionally to ensure that guard pages are setup
+properly. The emission of this stack probe emission is handled similar to the
+standard stack probe emission.</p>
+<p>The MSVC environment does not emit code for VLAs currently.</p>
+</div>
+</div>
+<div class="section" id="windows-on-arm64">
+<h3><a class="toc-backref" href="#id38">Windows on ARM64</a><a class="headerlink" href="#windows-on-arm64" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="id4">
+<h4><a class="toc-backref" href="#id39">Stack Probe Emission</a><a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h4>
+<p>The reference implementation (Microsoft Visual Studio 2017) emits stack probes
+in the following fashion:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="nf">mov</span> <span class="no">x15</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="nf">bl</span> <span class="no">__chkstk</span>
+<span class="nf">sub</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">x15</span><span class="p">,</span> <span class="no">lsl</span> <span class="c">#4</span>
+</pre></div>
+</div>
+<p>However, this has the limitation of 256 MiB (±128MiB). In order to accommodate
+larger binaries, LLVM supports the use of <tt class="docutils literal"><span class="pre">-mcode-model=large</span></tt> to allow a 8GiB
+(±4GiB) range via a slight deviation. It will generate an indirect jump as
+follows:</p>
+<div class="highlight-gas"><div class="highlight"><pre><span class="nf">mov</span> <span class="no">x15</span><span class="p">,</span> <span class="c">#constant</span>
+<span class="nf">adrp</span> <span class="no">x16</span><span class="p">,</span> <span class="no">__chkstk</span>
+<span class="nf">add</span> <span class="no">x16</span><span class="p">,</span> <span class="no">x16</span><span class="p">,</span> <span class="p">:</span><span class="no">lo12</span><span class="p">:</span><span class="no">__chkstk</span>
+<span class="nf">blr</span> <span class="no">x16</span>
+<span class="nf">sub</span> <span class="no">sp</span><span class="p">,</span> <span class="no">sp</span><span class="p">,</span> <span class="no">x15</span><span class="p">,</span> <span class="no">lsl</span> <span class="c">#4</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ >next</a> |</li>
+ <li class="right" >
+ <a href="ProgrammersManual.html" title="LLVM Programmerâs Manual"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/FAQ.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/FAQ.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/FAQ.html (added)
+++ www-releases/trunk/7.0.1/docs/FAQ.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,437 @@
+
+
+<!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>Frequently Asked Questions (FAQ) — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="The LLVM Lexicon" href="Lexicon.html" />
+ <link rel="prev" title="Getting Started with the LLVM System using Microsoft Visual Studio" href="GettingStartedVS.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="frequently-asked-questions-faq">
+<h1>Frequently Asked Questions (FAQ)<a class="headerlink" href="#frequently-asked-questions-faq" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#license" id="id1">License</a><ul>
+<li><a class="reference internal" href="#does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license" id="id2">Does the University of Illinois Open Source License really qualify as an “open source” license?</a></li>
+<li><a class="reference internal" href="#can-i-modify-llvm-source-code-and-redistribute-the-modified-source" id="id3">Can I modify LLVM source code and redistribute the modified source?</a></li>
+<li><a class="reference internal" href="#can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source" id="id4">Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#source-code" id="id5">Source Code</a><ul>
+<li><a class="reference internal" href="#in-what-language-is-llvm-written" id="id6">In what language is LLVM written?</a></li>
+<li><a class="reference internal" href="#how-portable-is-the-llvm-source-code" id="id7">How portable is the LLVM source code?</a></li>
+<li><a class="reference internal" href="#what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation" id="id8">What API do I use to store a value to one of the virtual registers in LLVM IR’s SSA representation?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#source-languages" id="id9">Source Languages</a><ul>
+<li><a class="reference internal" href="#what-source-languages-are-supported" id="id10">What source languages are supported?</a></li>
+<li><a class="reference internal" href="#i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators" id="id11">I’d like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?</a></li>
+<li><a class="reference internal" href="#what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler" id="id12">What support is there for a higher level source language constructs for building a compiler?</a></li>
+<li><a class="reference internal" href="#i-don-t-understand-the-getelementptr-instruction-help" id="id13">I don’t understand the <tt class="docutils literal"><span class="pre">GetElementPtr</span></tt> instruction. Help!</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#using-the-c-and-c-front-ends" id="id14">Using the C and C++ Front Ends</a><ul>
+<li><a class="reference internal" href="#can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode" id="id15">Can I compile C or C++ code to platform-independent LLVM bitcode?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#questions-about-code-generated-by-the-demo-page" id="id16">Questions about code generated by the demo page</a><ul>
+<li><a class="reference internal" href="#what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream" id="id17">What is this <tt class="docutils literal"><span class="pre">llvm.global_ctors</span></tt> and <tt class="docutils literal"><span class="pre">_GLOBAL__I_a...</span></tt> stuff that happens when I <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><iostream></span></tt>?</a></li>
+<li><a class="reference internal" href="#where-did-all-of-my-code-go" id="id18">Where did all of my code go??</a></li>
+<li><a class="reference internal" href="#what-is-this-undef-thing-that-shows-up-in-my-code" id="id19">What is this “<tt class="docutils literal"><span class="pre">undef</span></tt>” thing that shows up in my code?</a></li>
+<li><a class="reference internal" href="#why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it" id="id20">Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into “unreachable”? Why not make the verifier reject it?</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="license">
+<h2><a class="toc-backref" href="#id1">License</a><a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license">
+<h3><a class="toc-backref" href="#id2">Does the University of Illinois Open Source License really qualify as an “open source” license?</a><a class="headerlink" href="#does-the-university-of-illinois-open-source-license-really-qualify-as-an-open-source-license" title="Permalink to this headline">¶</a></h3>
+<p>Yes, the license is <a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by the Open Source
+Initiative (OSI).</p>
+</div>
+<div class="section" id="can-i-modify-llvm-source-code-and-redistribute-the-modified-source">
+<h3><a class="toc-backref" href="#id3">Can I modify LLVM source code and redistribute the modified source?</a><a class="headerlink" href="#can-i-modify-llvm-source-code-and-redistribute-the-modified-source" title="Permalink to this headline">¶</a></h3>
+<p>Yes. The modified source distribution must retain the copyright notice and
+follow the three bulleted conditions listed in the <a class="reference external" href="http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT">LLVM license</a>.</p>
+</div>
+<div class="section" id="can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source">
+<h3><a class="toc-backref" href="#id4">Can I modify the LLVM source code and redistribute binaries or other tools based on it, without redistributing the source?</a><a class="headerlink" href="#can-i-modify-the-llvm-source-code-and-redistribute-binaries-or-other-tools-based-on-it-without-redistributing-the-source" title="Permalink to this headline">¶</a></h3>
+<p>Yes. This is why we distribute LLVM under a less restrictive license than GPL,
+as explained in the first question above.</p>
+</div>
+</div>
+<div class="section" id="source-code">
+<h2><a class="toc-backref" href="#id5">Source Code</a><a class="headerlink" href="#source-code" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="in-what-language-is-llvm-written">
+<h3><a class="toc-backref" href="#id6">In what language is LLVM written?</a><a class="headerlink" href="#in-what-language-is-llvm-written" title="Permalink to this headline">¶</a></h3>
+<p>All of the LLVM tools and libraries are written in C++ with extensive use of
+the STL.</p>
+</div>
+<div class="section" id="how-portable-is-the-llvm-source-code">
+<h3><a class="toc-backref" href="#id7">How portable is the LLVM source code?</a><a class="headerlink" href="#how-portable-is-the-llvm-source-code" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM source code should be portable to most modern Unix-like operating
+systems. Most of the code is written in standard C++ with operating system
+services abstracted to a support library. The tools required to build and
+test LLVM have been ported to a plethora of platforms.</p>
+<p>Some porting problems may exist in the following areas:</p>
+<ul class="simple">
+<li>The autoconf/makefile build system relies heavily on UNIX shell tools,
+like the Bourne Shell and sed. Porting to systems without these tools
+(MacOS 9, Plan 9) will require more effort.</li>
+</ul>
+</div>
+<div class="section" id="what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation">
+<h3><a class="toc-backref" href="#id8">What API do I use to store a value to one of the virtual registers in LLVM IR’s SSA representation?</a><a class="headerlink" href="#what-api-do-i-use-to-store-a-value-to-one-of-the-virtual-registers-in-llvm-ir-s-ssa-representation" title="Permalink to this headline">¶</a></h3>
+<p>In short: you can’t. It’s actually kind of a silly question once you grok
+what’s going on. Basically, in code like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%result</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%foo</span><span class="p">,</span> <span class="nv">%bar</span>
+</pre></div>
+</div>
+<p>, <tt class="docutils literal"><span class="pre">%result</span></tt> is just a name given to the <tt class="docutils literal"><span class="pre">Value</span></tt> of the <tt class="docutils literal"><span class="pre">add</span></tt>
+instruction. In other words, <tt class="docutils literal"><span class="pre">%result</span></tt> <em>is</em> the add instruction. The
+“assignment” doesn’t explicitly “store” anything to any “virtual register”;
+the “<tt class="docutils literal"><span class="pre">=</span></tt>” is more like the mathematical sense of equality.</p>
+<p>Longer explanation: In order to generate a textual representation of the
+IR, some kind of name has to be given to each instruction so that other
+instructions can textually reference it. However, the isomorphic in-memory
+representation that you manipulate from C++ has no such restriction since
+instructions can simply keep pointers to any other <tt class="docutils literal"><span class="pre">Value</span></tt>‘s that they
+reference. In fact, the names of dummy numbered temporaries like <tt class="docutils literal"><span class="pre">%1</span></tt> are
+not explicitly represented in the in-memory representation at all (see
+<tt class="docutils literal"><span class="pre">Value::getName()</span></tt>).</p>
+</div>
+</div>
+<div class="section" id="source-languages">
+<h2><a class="toc-backref" href="#id9">Source Languages</a><a class="headerlink" href="#source-languages" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-source-languages-are-supported">
+<h3><a class="toc-backref" href="#id10">What source languages are supported?</a><a class="headerlink" href="#what-source-languages-are-supported" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently has full support for C and C++ source languages through
+<a class="reference external" href="http://clang.llvm.org/">Clang</a>. Many other language frontends have
+been written using LLVM, and an incomplete list is available at
+<a class="reference external" href="http://llvm.org/ProjectsWithLLVM/">projects with LLVM</a>.</p>
+</div>
+<div class="section" id="i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators">
+<h3><a class="toc-backref" href="#id11">I’d like to write a self-hosting LLVM compiler. How should I interface with the LLVM middle-end optimizers and back-end code generators?</a><a class="headerlink" href="#i-d-like-to-write-a-self-hosting-llvm-compiler-how-should-i-interface-with-the-llvm-middle-end-optimizers-and-back-end-code-generators" title="Permalink to this headline">¶</a></h3>
+<p>Your compiler front-end will communicate with LLVM by creating a module in the
+LLVM intermediate representation (IR) format. Assuming you want to write your
+language’s compiler in the language itself (rather than C++), there are 3
+major ways to tackle generating LLVM IR from a front-end:</p>
+<ol class="arabic simple">
+<li><strong>Call into the LLVM libraries code using your language’s FFI (foreign
+function interface).</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, and .bc format</li>
+<li><em>for:</em> enables running LLVM optimization passes without a emit/parse
+overhead</li>
+<li><em>for:</em> adapts well to a JIT context</li>
+<li><em>against:</em> lots of ugly glue code to write</li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple" start="2">
+<li><strong>Emit LLVM assembly from your compiler’s native language.</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> very straightforward to get started</li>
+<li><em>against:</em> the .ll parser is slower than the bitcode reader when
+interfacing to the middle end</li>
+<li><em>against:</em> it may be harder to track changes to the IR</li>
+</ul>
+</div></blockquote>
+<ol class="arabic simple" start="3">
+<li><strong>Emit LLVM bitcode from your compiler’s native language.</strong></li>
+</ol>
+<blockquote>
+<div><ul class="simple">
+<li><em>for:</em> can use the more-efficient bitcode reader when interfacing to the
+middle end</li>
+<li><em>against:</em> you’ll have to re-engineer the LLVM IR object model and bitcode
+writer in your language</li>
+<li><em>against:</em> it may be harder to track changes to the IR</li>
+</ul>
+</div></blockquote>
+<p>If you go with the first option, the C bindings in include/llvm-c should help
+a lot, since most languages have strong support for interfacing with C. The
+most common hurdle with calling C from managed code is interfacing with the
+garbage collector. The C interface was designed to require very little memory
+management, and so is straightforward in this regard.</p>
+</div>
+<div class="section" id="what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler">
+<h3><a class="toc-backref" href="#id12">What support is there for a higher level source language constructs for building a compiler?</a><a class="headerlink" href="#what-support-is-there-for-a-higher-level-source-language-constructs-for-building-a-compiler" title="Permalink to this headline">¶</a></h3>
+<p>Currently, there isn’t much. LLVM supports an intermediate representation
+which is useful for code representation but will not support the high level
+(abstract syntax tree) representation needed by most compilers. There are no
+facilities for lexical nor semantic analysis.</p>
+</div>
+<div class="section" id="i-don-t-understand-the-getelementptr-instruction-help">
+<h3><a class="toc-backref" href="#id13">I don’t understand the <tt class="docutils literal"><span class="pre">GetElementPtr</span></tt> instruction. Help!</a><a class="headerlink" href="#i-don-t-understand-the-getelementptr-instruction-help" title="Permalink to this headline">¶</a></h3>
+<p>See <a class="reference external" href="GetElementPtr.html">The Often Misunderstood GEP Instruction</a>.</p>
+</div>
+</div>
+<div class="section" id="using-the-c-and-c-front-ends">
+<h2><a class="toc-backref" href="#id14">Using the C and C++ Front Ends</a><a class="headerlink" href="#using-the-c-and-c-front-ends" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode">
+<h3><a class="toc-backref" href="#id15">Can I compile C or C++ code to platform-independent LLVM bitcode?</a><a class="headerlink" href="#can-i-compile-c-or-c-code-to-platform-independent-llvm-bitcode" title="Permalink to this headline">¶</a></h3>
+<p>No. C and C++ are inherently platform-dependent languages. The most obvious
+example of this is the preprocessor. A very common way that C code is made
+portable is by using the preprocessor to include platform-specific code. In
+practice, information about other platforms is lost after preprocessing, so
+the result is inherently dependent on the platform that the preprocessing was
+targeting.</p>
+<p>Another example is <tt class="docutils literal"><span class="pre">sizeof</span></tt>. It’s common for <tt class="docutils literal"><span class="pre">sizeof(long)</span></tt> to vary
+between platforms. In most C front-ends, <tt class="docutils literal"><span class="pre">sizeof</span></tt> is expanded to a
+constant immediately, thus hard-wiring a platform-specific detail.</p>
+<p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
+lower-level than C, front-ends currently must emit platform-specific IR in
+order to have the result conform to the platform ABI.</p>
+</div>
+</div>
+<div class="section" id="questions-about-code-generated-by-the-demo-page">
+<h2><a class="toc-backref" href="#id16">Questions about code generated by the demo page</a><a class="headerlink" href="#questions-about-code-generated-by-the-demo-page" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream">
+<h3><a class="toc-backref" href="#id17">What is this <tt class="docutils literal"><span class="pre">llvm.global_ctors</span></tt> and <tt class="docutils literal"><span class="pre">_GLOBAL__I_a...</span></tt> stuff that happens when I <tt class="docutils literal"><span class="pre">#include</span> <span class="pre"><iostream></span></tt>?</a><a class="headerlink" href="#what-is-this-llvm-global-ctors-and-global-i-a-stuff-that-happens-when-i-include-iostream" title="Permalink to this headline">¶</a></h3>
+<p>If you <tt class="docutils literal"><span class="pre">#include</span></tt> the <tt class="docutils literal"><span class="pre"><iostream></span></tt> header into a C++ translation unit,
+the file will probably use the <tt class="docutils literal"><span class="pre">std::cin</span></tt>/<tt class="docutils literal"><span class="pre">std::cout</span></tt>/... global objects.
+However, C++ does not guarantee an order of initialization between static
+objects in different translation units, so if a static ctor/dtor in your .cpp
+file used <tt class="docutils literal"><span class="pre">std::cout</span></tt>, for example, the object would not necessarily be
+automatically initialized before your use.</p>
+<p>To make <tt class="docutils literal"><span class="pre">std::cout</span></tt> and friends work correctly in these scenarios, the STL
+that we use declares a static object that gets created in every translation
+unit that includes <tt class="docutils literal"><span class="pre"><iostream></span></tt>. This object has a static constructor
+and destructor that initializes and destroys the global iostream objects
+before they could possibly be used in the file. The code that you see in the
+<tt class="docutils literal"><span class="pre">.ll</span></tt> file corresponds to the constructor and destructor registration code.</p>
+<p>If you would like to make it easier to <em>understand</em> the LLVM code generated
+by the compiler in the demo page, consider using <tt class="docutils literal"><span class="pre">printf()</span></tt> instead of
+<tt class="docutils literal"><span class="pre">iostream</span></tt>s to print values.</p>
+</div>
+<div class="section" id="where-did-all-of-my-code-go">
+<h3><a class="toc-backref" href="#id18">Where did all of my code go??</a><a class="headerlink" href="#where-did-all-of-my-code-go" title="Permalink to this headline">¶</a></h3>
+<p>If you are using the LLVM demo page, you may often wonder what happened to
+all of the code that you typed in. Remember that the demo script is running
+the code through the LLVM optimizers, so if your code doesn’t actually do
+anything useful, it might all be deleted.</p>
+<p>To prevent this, make sure that the code is actually needed. For example, if
+you are computing some expression, return the value from the function instead
+of leaving it in a local variable. If you really want to constrain the
+optimizer, you can read from and assign to <tt class="docutils literal"><span class="pre">volatile</span></tt> global variables.</p>
+</div>
+<div class="section" id="what-is-this-undef-thing-that-shows-up-in-my-code">
+<h3><a class="toc-backref" href="#id19">What is this “<tt class="docutils literal"><span class="pre">undef</span></tt>” thing that shows up in my code?</a><a class="headerlink" href="#what-is-this-undef-thing-that-shows-up-in-my-code" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">undef</span></tt> is the LLVM way of representing a value that is not defined. You
+can get these if you do not initialize a variable before you use it. For
+example, the C function:</p>
+<div class="highlight-c"><div class="highlight"><pre><span class="kt">int</span> <span class="nf">X</span><span class="p">()</span> <span class="p">{</span> <span class="kt">int</span> <span class="n">i</span><span class="p">;</span> <span class="k">return</span> <span class="n">i</span><span class="p">;</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>Is compiled to “<tt class="docutils literal"><span class="pre">ret</span> <span class="pre">i32</span> <span class="pre">undef</span></tt>” because “<tt class="docutils literal"><span class="pre">i</span></tt>” never has a value specified
+for it.</p>
+</div>
+<div class="section" id="why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it">
+<h3><a class="toc-backref" href="#id20">Why does instcombine + simplifycfg turn a call to a function with a mismatched calling convention into “unreachable”? Why not make the verifier reject it?</a><a class="headerlink" href="#why-does-instcombine-simplifycfg-turn-a-call-to-a-function-with-a-mismatched-calling-convention-into-unreachable-why-not-make-the-verifier-reject-it" title="Permalink to this headline">¶</a></h3>
+<p>This is a common problem run into by authors of front-ends that are using
+custom calling conventions: you need to make sure to set the right calling
+convention on both the function and on each call to the function. For
+example, this code:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Is optimized to:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">unreachable</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>... with “<tt class="docutils literal"><span class="pre">opt</span> <span class="pre">-instcombine</span> <span class="pre">-simplifycfg</span></tt>”. This often bites people because
+“all their code disappears”. Setting the calling convention on the caller and
+callee is required for indirect calls to work, so people often ask why not
+make the verifier reject this sort of thing.</p>
+<p>The answer is that this code has undefined behavior, but it is not illegal.
+If we made it illegal, then every transformation that could potentially create
+this would have to ensure that it doesn’t, and there is valid code that can
+create this sort of construct (in dead code). The sorts of things that can
+cause this to happen are fairly contrived, but we still need to accept them.
+Here’s an example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="k">internal</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">(</span><span class="kt">void</span><span class="p">()*</span> <span class="nv">%FP</span><span class="p">,</span> <span class="k">i1</span> <span class="nv">%cond</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%cond</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F</span>
+<span class="nl">T:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="nv">%FP</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="nl">F:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="nv">%FP</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">or</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">false</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@bar</span><span class="p">(</span><span class="kt">void</span><span class="p">()*</span> <span class="vg">@foo</span><span class="p">,</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In this example, “test” always passes <tt class="docutils literal"><span class="pre">@foo</span></tt>/<tt class="docutils literal"><span class="pre">false</span></tt> into <tt class="docutils literal"><span class="pre">bar</span></tt>, which
+ensures that it is dynamically called with the right calling conv (thus, the
+code is perfectly well defined). If you run this through the inliner, you
+get this (the explicit “or” is there so that the inliner doesn’t dead code
+eliminate a bunch of stuff):</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">()</span> <span class="p">{</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">or</span> <span class="k">i1</span> <span class="k">false</span><span class="p">,</span> <span class="k">false</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T.i</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F.i</span>
+<span class="nl">T.i:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">bar.exit:</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Here you can see that the inlining pass made an undefined call to <tt class="docutils literal"><span class="pre">@foo</span></tt>
+with the wrong calling convention. We really don’t want to make the inliner
+have to know about this sort of thing, so it needs to be valid code. In this
+case, dead code elimination can trivially remove the undefined code. However,
+if <tt class="docutils literal"><span class="pre">%X</span></tt> was an input argument to <tt class="docutils literal"><span class="pre">@test</span></tt>, the inliner would produce this:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%X</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%T.i</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%F.i</span>
+<span class="nl">T.i:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%bar.exit</span>
+<span class="nl">bar.exit:</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The interesting thing about this is that <tt class="docutils literal"><span class="pre">%X</span></tt> <em>must</em> be false for the
+code to be well-defined, but no amount of dead code elimination will be able
+to delete the broken call as unreachable. However, since
+<tt class="docutils literal"><span class="pre">instcombine</span></tt>/<tt class="docutils literal"><span class="pre">simplifycfg</span></tt> turns the undefined call into unreachable, we
+end up with a branch on a condition that goes to unreachable: a branch to
+unreachable can never happen, so “<tt class="docutils literal"><span class="pre">-inline</span> <span class="pre">-instcombine</span> <span class="pre">-simplifycfg</span></tt>” is
+able to produce:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+<span class="k">define</span> <span class="kt">void</span> <span class="vg">@test</span><span class="p">(</span><span class="k">i1</span> <span class="nv">%X</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">F.i:</span>
+ <span class="k">call</span> <span class="k">fastcc</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Lexicon.html" title="The LLVM Lexicon"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="GettingStartedVS.html" title="Getting Started with the LLVM System using Microsoft Visual Studio"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/FaultMaps.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/FaultMaps.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/FaultMaps.html (added)
+++ www-releases/trunk/7.0.1/docs/FaultMaps.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,225 @@
+
+
+<!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>FaultMaps and implicit checks — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Machine IR (MIR) Format Reference Manual" href="MIRLangRef.html" />
+ <link rel="prev" title="Type Metadata" href="TypeMetadata.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="TypeMetadata.html" title="Type Metadata"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="faultmaps-and-implicit-checks">
+<h1>FaultMaps and implicit checks<a class="headerlink" href="#faultmaps-and-implicit-checks" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#motivation" id="id1">Motivation</a></li>
+<li><a class="reference internal" href="#the-fault-map-section" id="id2">The Fault Map Section</a></li>
+<li><a class="reference internal" href="#the-implicitnullchecks-pass" id="id3">The <tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass</a><ul>
+<li><a class="reference internal" href="#make-implicit-metadata" id="id4"><tt class="docutils literal"><span class="pre">make.implicit</span></tt> metadata</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="motivation">
+<h2><a class="toc-backref" href="#id1">Motivation</a><a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h2>
+<p>Code generated by managed language runtimes tend to have checks that
+are required for safety but never fail in practice. In such cases, it
+is profitable to make the non-failing case cheaper even if it makes
+the failing case significantly more expensive. This asymmetry can be
+exploited by folding such safety checks into operations that can be
+made to fault reliably if the check would have failed, and recovering
+from such a fault by using a signal handler.</p>
+<p>For example, Java requires null checks on objects before they are read
+from or written to. If the object is <tt class="docutils literal"><span class="pre">null</span></tt> then a
+<tt class="docutils literal"><span class="pre">NullPointerException</span></tt> has to be thrown, interrupting normal
+execution. In practice, however, dereferencing a <tt class="docutils literal"><span class="pre">null</span></tt> pointer is
+extremely rare in well-behaved Java programs, and typically the null
+check can be folded into a nearby memory operation that operates on
+the same memory location.</p>
+</div>
+<div class="section" id="the-fault-map-section">
+<h2><a class="toc-backref" href="#id2">The Fault Map Section</a><a class="headerlink" href="#the-fault-map-section" title="Permalink to this headline">¶</a></h2>
+<p>Information about implicit checks generated by LLVM are put in a
+special “fault map” section. On Darwin this section is named
+<tt class="docutils literal"><span class="pre">__llvm_faultmaps</span></tt>.</p>
+<p>The format of this section is</p>
+<div class="highlight-none"><div class="highlight"><pre>Header {
+ uint8 : Fault Map Version (current version is 1)
+ uint8 : Reserved (expected to be 0)
+ uint16 : Reserved (expected to be 0)
+}
+uint32 : NumFunctions
+FunctionInfo[NumFunctions] {
+ uint64 : FunctionAddress
+ uint32 : NumFaultingPCs
+ uint32 : Reserved (expected to be 0)
+ FunctionFaultInfo[NumFaultingPCs] {
+ uint32 : FaultKind
+ uint32 : FaultingPCOffset
+ uint32 : HandlerPCOffset
+ }
+}
+</pre></div>
+</div>
+<p>FailtKind describes the reason of expected fault. Currently three kind
+of faults are supported:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li><tt class="docutils literal"><span class="pre">FaultMaps::FaultingLoad</span></tt> - fault due to load from memory.</li>
+<li><tt class="docutils literal"><span class="pre">FaultMaps::FaultingLoadStore</span></tt> - fault due to instruction load and store.</li>
+<li><tt class="docutils literal"><span class="pre">FaultMaps::FaultingStore</span></tt> - fault due to store to memory.</li>
+</ol>
+</div></blockquote>
+</div>
+<div class="section" id="the-implicitnullchecks-pass">
+<h2><a class="toc-backref" href="#id3">The <tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass</a><a class="headerlink" href="#the-implicitnullchecks-pass" title="Permalink to this headline">¶</a></h2>
+<p>The <tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass transforms explicit control flow for
+checking if a pointer is <tt class="docutils literal"><span class="pre">null</span></tt>, like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre> <span class="nv">%ptr</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@get_ptr</span><span class="p">()</span>
+ <span class="nv">%ptr_is_null</span> <span class="p">=</span> <span class="k">icmp</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%ptr</span><span class="p">,</span> <span class="k">null</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%ptr_is_null</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%is_null</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%not_null</span><span class="p">,</span> <span class="nv">!make.implicit</span> <span class="nv-Anonymous">!0</span>
+
+<span class="nl">not_null:</span>
+ <span class="nv">%t</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">%ptr</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%do_something_with_t</span>
+
+<span class="nl">is_null:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@HFC</span><span class="p">()</span>
+ <span class="k">unreachable</span>
+
+<span class="nv-Anonymous">!0</span> <span class="p">=</span> <span class="p">!{}</span>
+</pre></div>
+</div>
+<p>to control flow implicit in the instruction loading or storing through
+the pointer being null checked:</p>
+<div class="highlight-llvm"><div class="highlight"><pre> <span class="nv">%ptr</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span><span class="p">*</span> <span class="vg">@get_ptr</span><span class="p">()</span>
+ <span class="nv">%t</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">%ptr</span> <span class="c">;; handler-pc = label %is_null</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%do_something_with_t</span>
+
+<span class="nl">is_null:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@HFC</span><span class="p">()</span>
+ <span class="k">unreachable</span>
+</pre></div>
+</div>
+<p>This transform happens at the <tt class="docutils literal"><span class="pre">MachineInstr</span></tt> level, not the LLVM IR
+level (so the above example is only representative, not literal). The
+<tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass runs during codegen, if
+<tt class="docutils literal"><span class="pre">-enable-implicit-null-checks</span></tt> is passed to <tt class="docutils literal"><span class="pre">llc</span></tt>.</p>
+<p>The <tt class="docutils literal"><span class="pre">ImplicitNullChecks</span></tt> pass adds entries to the
+<tt class="docutils literal"><span class="pre">__llvm_faultmaps</span></tt> section described above as needed.</p>
+<div class="section" id="make-implicit-metadata">
+<h3><a class="toc-backref" href="#id4"><tt class="docutils literal"><span class="pre">make.implicit</span></tt> metadata</a><a class="headerlink" href="#make-implicit-metadata" title="Permalink to this headline">¶</a></h3>
+<p>Making null checks implicit is an aggressive optimization, and it can
+be a net performance pessimization if too many memory operations end
+up faulting because of it. A language runtime typically needs to
+ensure that only a negligible number of implicit null checks actually
+fault once the application has reached a steady state. A standard way
+of doing this is by healing failed implicit null checks into explicit
+null checks via code patching or recompilation. It follows that there
+are two requirements an explicit null check needs to satisfy for it to
+be profitable to convert it to an implicit null check:</p>
+<blockquote>
+<div><ol class="arabic simple">
+<li>The case where the pointer is actually null (i.e. the “failing”
+case) is extremely rare.</li>
+<li>The failing path heals the implicit null check into an explicit
+null check so that the application does not repeatedly page
+fault.</li>
+</ol>
+</div></blockquote>
+<p>The frontend is expected to mark branches that satisfy (1) and (2)
+using a <tt class="docutils literal"><span class="pre">!make.implicit</span></tt> metadata node (the actual content of the
+metadata node is ignored). Only branches that are marked with
+<tt class="docutils literal"><span class="pre">!make.implicit</span></tt> metadata are considered as candidates for
+conversion into implicit null checks.</p>
+<p>(Note that while we could deal with (1) using profiling data, dealing
+with (2) requires some information not present in branch profiles.)</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="MIRLangRef.html" title="Machine IR (MIR) Format Reference Manual"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="TypeMetadata.html" title="Type Metadata"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/Frontend/PerformanceTips.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/Frontend/PerformanceTips.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/Frontend/PerformanceTips.html (added)
+++ www-releases/trunk/7.0.1/docs/Frontend/PerformanceTips.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,374 @@
+
+
+<!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>Performance Tips for Frontend Authors — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="../index.html" />
+ <link rel="next" title="MCJIT Design and Implementation" href="../MCJITDesignAndImplementation.html" />
+ <link rel="prev" title="The Often Misunderstood GEP Instruction" href="../GetElementPtr.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../MCJITDesignAndImplementation.html" title="MCJIT Design and Implementation"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="../GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="performance-tips-for-frontend-authors">
+<h1>Performance Tips for Frontend Authors<a class="headerlink" href="#performance-tips-for-frontend-authors" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#abstract" id="id2">Abstract</a></li>
+<li><a class="reference internal" href="#ir-best-practices" id="id3">IR Best Practices</a><ul>
+<li><a class="reference internal" href="#the-basics" id="id4">The Basics</a></li>
+<li><a class="reference internal" href="#use-of-allocas" id="id5">Use of allocas</a></li>
+<li><a class="reference internal" href="#avoid-loads-and-stores-of-large-aggregate-type" id="id6">Avoid loads and stores of large aggregate type</a></li>
+<li><a class="reference internal" href="#prefer-zext-over-sext-when-legal" id="id7">Prefer zext over sext when legal</a></li>
+<li><a class="reference internal" href="#zext-gep-indices-to-machine-register-width" id="id8">Zext GEP indices to machine register width</a></li>
+<li><a class="reference internal" href="#when-to-specify-alignment" id="id9">When to specify alignment</a></li>
+<li><a class="reference internal" href="#other-things-to-consider" id="id10">Other Things to Consider</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#describing-language-specific-properties" id="id11">Describing Language Specific Properties</a><ul>
+<li><a class="reference internal" href="#restricted-operation-semantics" id="id12">Restricted Operation Semantics</a></li>
+<li><a class="reference internal" href="#describing-aliasing-properties" id="id13">Describing Aliasing Properties</a></li>
+<li><a class="reference internal" href="#modeling-memory-effects" id="id14">Modeling Memory Effects</a></li>
+<li><a class="reference internal" href="#pass-ordering" id="id15">Pass Ordering</a></li>
+<li><a class="reference internal" href="#i-still-can-t-find-what-i-m-looking-for" id="id16">I Still Can’t Find What I’m Looking For</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#adding-to-this-document" id="id17">Adding to this document</a></li>
+</ul>
+</div>
+<div class="section" id="abstract">
+<h2><a class="toc-backref" href="#id2">Abstract</a><a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>The intended audience of this document is developers of language frontends
+targeting LLVM IR. This document is home to a collection of tips on how to
+generate IR that optimizes well.</p>
+</div>
+<div class="section" id="ir-best-practices">
+<h2><a class="toc-backref" href="#id3">IR Best Practices</a><a class="headerlink" href="#ir-best-practices" title="Permalink to this headline">¶</a></h2>
+<p>As with any optimizer, LLVM has its strengths and weaknesses. In some cases,
+surprisingly small changes in the source IR can have a large effect on the
+generated code.</p>
+<p>Beyond the specific items on the list below, it’s worth noting that the most
+mature frontend for LLVM is Clang. As a result, the further your IR gets from what Clang might emit, the less likely it is to be effectively optimized. It
+can often be useful to write a quick C program with the semantics you’re trying
+to model and see what decisions Clang’s IRGen makes about what IR to emit.
+Studying Clang’s CodeGen directory can also be a good source of ideas. Note
+that Clang and LLVM are explicitly version locked so you’ll need to make sure
+you’re using a Clang built from the same svn revision or release as the LLVM
+library you’re using. As always, it’s <em>strongly</em> recommended that you track
+tip of tree development, particularly during bring up of a new project.</p>
+<div class="section" id="the-basics">
+<h3><a class="toc-backref" href="#id4">The Basics</a><a class="headerlink" href="#the-basics" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Make sure that your Modules contain both a data layout specification and
+target triple. Without these pieces, non of the target specific optimization
+will be enabled. This can have a major effect on the generated code quality.</li>
+<li>For each function or global emitted, use the most private linkage type
+possible (private, internal or linkonce_odr preferably). Doing so will
+make LLVM’s inter-procedural optimizations much more effective.</li>
+<li>Avoid high in-degree basic blocks (e.g. basic blocks with dozens or hundreds
+of predecessors). Among other issues, the register allocator is known to
+perform badly with confronted with such structures. The only exception to
+this guidance is that a unified return block with high in-degree is fine.</li>
+</ol>
+</div>
+<div class="section" id="use-of-allocas">
+<h3><a class="toc-backref" href="#id5">Use of allocas</a><a class="headerlink" href="#use-of-allocas" title="Permalink to this headline">¶</a></h3>
+<p>An alloca instruction can be used to represent a function scoped stack slot,
+but can also represent dynamic frame expansion. When representing function
+scoped variables or locations, placing alloca instructions at the beginning of
+the entry block should be preferred. In particular, place them before any
+call instructions. Call instructions might get inlined and replaced with
+multiple basic blocks. The end result is that a following alloca instruction
+would no longer be in the entry basic block afterward.</p>
+<p>The SROA (Scalar Replacement Of Aggregates) and Mem2Reg passes only attempt
+to eliminate alloca instructions that are in the entry basic block. Given
+SSA is the canonical form expected by much of the optimizer; if allocas can
+not be eliminated by Mem2Reg or SROA, the optimizer is likely to be less
+effective than it could be.</p>
+</div>
+<div class="section" id="avoid-loads-and-stores-of-large-aggregate-type">
+<h3><a class="toc-backref" href="#id6">Avoid loads and stores of large aggregate type</a><a class="headerlink" href="#avoid-loads-and-stores-of-large-aggregate-type" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently does not optimize well loads and stores of large <a class="reference internal" href="../LangRef.html#t-aggregate"><em>aggregate
+types</em></a> (i.e. structs and arrays). As an alternative, consider
+loading individual fields from memory.</p>
+<p>Aggregates that are smaller than the largest (performant) load or store
+instruction supported by the targeted hardware are well supported. These can
+be an effective way to represent collections of small packed fields.</p>
+</div>
+<div class="section" id="prefer-zext-over-sext-when-legal">
+<h3><a class="toc-backref" href="#id7">Prefer zext over sext when legal</a><a class="headerlink" href="#prefer-zext-over-sext-when-legal" title="Permalink to this headline">¶</a></h3>
+<p>On some architectures (X86_64 is one), sign extension can involve an extra
+instruction whereas zero extension can be folded into a load. LLVM will try to
+replace a sext with a zext when it can be proven safe, but if you have
+information in your source language about the range of a integer value, it can
+be profitable to use a zext rather than a sext.</p>
+<p>Alternatively, you can <a class="reference internal" href="../LangRef.html#range-metadata"><em>specify the range of the value using metadata</em></a> and LLVM can do the sext to zext conversion for you.</p>
+</div>
+<div class="section" id="zext-gep-indices-to-machine-register-width">
+<h3><a class="toc-backref" href="#id8">Zext GEP indices to machine register width</a><a class="headerlink" href="#zext-gep-indices-to-machine-register-width" title="Permalink to this headline">¶</a></h3>
+<p>Internally, LLVM often promotes the width of GEP indices to machine register
+width. When it does so, it will default to using sign extension (sext)
+operations for safety. If your source language provides information about
+the range of the index, you may wish to manually extend indices to machine
+register width using a zext instruction.</p>
+</div>
+<div class="section" id="when-to-specify-alignment">
+<h3><a class="toc-backref" href="#id9">When to specify alignment</a><a class="headerlink" href="#when-to-specify-alignment" title="Permalink to this headline">¶</a></h3>
+<p>LLVM will always generate correct code if you donât specify alignment, but may
+generate inefficient code. For example, if you are targeting MIPS (or older
+ARM ISAs) then the hardware does not handle unaligned loads and stores, and
+so you will enter a trap-and-emulate path if you do a load or store with
+lower-than-natural alignment. To avoid this, LLVM will emit a slower
+sequence of loads, shifts and masks (or load-right + load-left on MIPS) for
+all cases where the load / store does not have a sufficiently high alignment
+in the IR.</p>
+<p>The alignment is used to guarantee the alignment on allocas and globals,
+though in most cases this is unnecessary (most targets have a sufficiently
+high default alignment that theyâll be fine). It is also used to provide a
+contract to the back end saying âeither this load/store has this alignment, or
+it is undefined behaviorâ. This means that the back end is free to emit
+instructions that rely on that alignment (and mid-level optimizers are free to
+perform transforms that require that alignment). For x86, it doesnât make
+much difference, as almost all instructions are alignment-independent. For
+MIPS, it can make a big difference.</p>
+<p>Note that if your loads and stores are atomic, the backend will be unable to
+lower an under aligned access into a sequence of natively aligned accesses.
+As a result, alignment is mandatory for atomic loads and stores.</p>
+</div>
+<div class="section" id="other-things-to-consider">
+<h3><a class="toc-backref" href="#id10">Other Things to Consider</a><a class="headerlink" href="#other-things-to-consider" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Use ptrtoint/inttoptr sparingly (they interfere with pointer aliasing
+analysis), prefer GEPs</li>
+<li>Prefer globals over inttoptr of a constant address - this gives you
+dereferencability information. In MCJIT, use getSymbolAddress to provide
+actual address.</li>
+<li>Be wary of ordered and atomic memory operations. They are hard to optimize
+and may not be well optimized by the current optimizer. Depending on your
+source language, you may consider using fences instead.</li>
+<li>If calling a function which is known to throw an exception (unwind), use
+an invoke with a normal destination which contains an unreachable
+instruction. This form conveys to the optimizer that the call returns
+abnormally. For an invoke which neither returns normally or requires unwind
+code in the current function, you can use a noreturn call instruction if
+desired. This is generally not required because the optimizer will convert
+an invoke with an unreachable unwind destination to a call instruction.</li>
+<li>Use profile metadata to indicate statically known cold paths, even if
+dynamic profiling information is not available. This can make a large
+difference in code placement and thus the performance of tight loops.</li>
+<li>When generating code for loops, try to avoid terminating the header block of
+the loop earlier than necessary. If the terminator of the loop header
+block is a loop exiting conditional branch, the effectiveness of LICM will
+be limited for loads not in the header. (This is due to the fact that LLVM
+may not know such a load is safe to speculatively execute and thus can’t
+lift an otherwise loop invariant load unless it can prove the exiting
+condition is not taken.) It can be profitable, in some cases, to emit such
+instructions into the header even if they are not used along a rarely
+executed path that exits the loop. This guidance specifically does not
+apply if the condition which terminates the loop header is itself invariant,
+or can be easily discharged by inspecting the loop index variables.</li>
+<li>In hot loops, consider duplicating instructions from small basic blocks
+which end in highly predictable terminators into their successor blocks.
+If a hot successor block contains instructions which can be vectorized
+with the duplicated ones, this can provide a noticeable throughput
+improvement. Note that this is not always profitable and does involve a
+potentially large increase in code size.</li>
+<li>When checking a value against a constant, emit the check using a consistent
+comparison type. The GVN pass <em>will</em> optimize redundant equalities even if
+the type of comparison is inverted, but GVN only runs late in the pipeline.
+As a result, you may miss the opportunity to run other important
+optimizations. Improvements to EarlyCSE to remove this issue are tracked in
+Bug 23333.</li>
+<li>Avoid using arithmetic intrinsics unless you are <em>required</em> by your source
+language specification to emit a particular code sequence. The optimizer
+is quite good at reasoning about general control flow and arithmetic, it is
+not anywhere near as strong at reasoning about the various intrinsics. If
+profitable for code generation purposes, the optimizer will likely form the
+intrinsics itself late in the optimization pipeline. It is <em>very</em> rarely
+profitable to emit these directly in the language frontend. This item
+explicitly includes the use of the <a class="reference internal" href="../LangRef.html#int-overflow"><em>overflow intrinsics</em></a>.</li>
+<li>Avoid using the <a class="reference internal" href="../LangRef.html#int-assume"><em>assume intrinsic</em></a> until you’ve
+established that a) there’s no other way to express the given fact and b)
+that fact is critical for optimization purposes. Assumes are a great
+prototyping mechanism, but they can have negative effects on both compile
+time and optimization effectiveness. The former is fixable with enough
+effort, but the later is fairly fundamental to their designed purpose.</li>
+</ol>
+</div>
+</div>
+<div class="section" id="describing-language-specific-properties">
+<h2><a class="toc-backref" href="#id11">Describing Language Specific Properties</a><a class="headerlink" href="#describing-language-specific-properties" title="Permalink to this headline">¶</a></h2>
+<p>When translating a source language to LLVM, finding ways to express concepts
+and guarantees available in your source language which are not natively
+provided by LLVM IR will greatly improve LLVM’s ability to optimize your code.
+As an example, C/C++’s ability to mark every add as “no signed wrap (nsw)” goes
+a long way to assisting the optimizer in reasoning about loop induction
+variables and thus generating more optimal code for loops.</p>
+<p>The LLVM LangRef includes a number of mechanisms for annotating the IR with
+additional semantic information. It is <em>strongly</em> recommended that you become
+highly familiar with this document. The list below is intended to highlight a
+couple of items of particular interest, but is by no means exhaustive.</p>
+<div class="section" id="restricted-operation-semantics">
+<h3><a class="toc-backref" href="#id12">Restricted Operation Semantics</a><a class="headerlink" href="#restricted-operation-semantics" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Add nsw/nuw flags as appropriate. Reasoning about overflow is
+generally hard for an optimizer so providing these facts from the frontend
+can be very impactful.</li>
+<li>Use fast-math flags on floating point operations if legal. If you don’t
+need strict IEEE floating point semantics, there are a number of additional
+optimizations that can be performed. This can be highly impactful for
+floating point intensive computations.</li>
+</ol>
+</div>
+<div class="section" id="describing-aliasing-properties">
+<h3><a class="toc-backref" href="#id13">Describing Aliasing Properties</a><a class="headerlink" href="#describing-aliasing-properties" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Add noalias/align/dereferenceable/nonnull to function arguments and return
+values as appropriate</li>
+<li>Use pointer aliasing metadata, especially tbaa metadata, to communicate
+otherwise-non-deducible pointer aliasing facts</li>
+<li>Use inbounds on geps. This can help to disambiguate some aliasing queries.</li>
+</ol>
+</div>
+<div class="section" id="modeling-memory-effects">
+<h3><a class="toc-backref" href="#id14">Modeling Memory Effects</a><a class="headerlink" href="#modeling-memory-effects" title="Permalink to this headline">¶</a></h3>
+<ol class="arabic simple">
+<li>Mark functions as readnone/readonly/argmemonly or noreturn/nounwind when
+known. The optimizer will try to infer these flags, but may not always be
+able to. Manual annotations are particularly important for external
+functions that the optimizer can not analyze.</li>
+<li>Use the lifetime.start/lifetime.end and invariant.start/invariant.end
+intrinsics where possible. Common profitable uses are for stack like data
+structures (thus allowing dead store elimination) and for describing
+life times of allocas (thus allowing smaller stack sizes).</li>
+<li>Mark invariant locations using !invariant.load and TBAA’s constant flags</li>
+</ol>
+</div>
+<div class="section" id="pass-ordering">
+<h3><a class="toc-backref" href="#id15">Pass Ordering</a><a class="headerlink" href="#pass-ordering" title="Permalink to this headline">¶</a></h3>
+<p>One of the most common mistakes made by new language frontend projects is to
+use the existing -O2 or -O3 pass pipelines as is. These pass pipelines make a
+good starting point for an optimizing compiler for any language, but they have
+been carefully tuned for C and C++, not your target language. You will almost
+certainly need to use a custom pass order to achieve optimal performance. A
+couple specific suggestions:</p>
+<ol class="arabic simple">
+<li>For languages with numerous rarely executed guard conditions (e.g. null
+checks, type checks, range checks) consider adding an extra execution or
+two of LoopUnswith and LICM to your pass order. The standard pass order,
+which is tuned for C and C++ applications, may not be sufficient to remove
+all dischargeable checks from loops.</li>
+<li>If you language uses range checks, consider using the IRCE pass. It is not
+currently part of the standard pass order.</li>
+<li>A useful sanity check to run is to run your optimized IR back through the
+-O2 pipeline again. If you see noticeable improvement in the resulting IR,
+you likely need to adjust your pass order.</li>
+</ol>
+</div>
+<div class="section" id="i-still-can-t-find-what-i-m-looking-for">
+<h3><a class="toc-backref" href="#id16">I Still Can’t Find What I’m Looking For</a><a class="headerlink" href="#i-still-can-t-find-what-i-m-looking-for" title="Permalink to this headline">¶</a></h3>
+<p>If you didn’t find what you were looking for above, consider proposing an piece
+of metadata which provides the optimization hint you need. Such extensions are
+relatively common and are generally well received by the community. You will
+need to ensure that your proposal is sufficiently general so that it benefits
+others if you wish to contribute it upstream.</p>
+<p>You should also consider describing the problem you’re facing on <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a> and asking for advice.
+It’s entirely possible someone has encountered your problem before and can
+give good advice. If there are multiple interested parties, that also
+increases the chances that a metadata extension would be well received by the
+community as a whole.</p>
+</div>
+</div>
+<div class="section" id="adding-to-this-document">
+<h2><a class="toc-backref" href="#id17">Adding to this document</a><a class="headerlink" href="#adding-to-this-document" title="Permalink to this headline">¶</a></h2>
+<p>If you run across a case that you feel deserves to be covered here, please send
+a patch to <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-commits">llvm-commits</a> for review.</p>
+<p>If you have questions on these items, please direct them to <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a>. The more relevant
+context you are able to give to your question, the more likely it is to be
+answered.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../MCJITDesignAndImplementation.html" title="MCJIT Design and Implementation"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="../GetElementPtr.html" title="The Often Misunderstood GEP Instruction"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/FuzzingLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/FuzzingLLVM.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/FuzzingLLVM.html (added)
+++ www-releases/trunk/7.0.1/docs/FuzzingLLVM.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,310 @@
+
+
+<!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>Fuzzing LLVM libraries and tools — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Scudo Hardened Allocator" href="ScudoHardenedAllocator.html" />
+ <link rel="prev" title="libFuzzer â a library for coverage-guided fuzz testing." href="LibFuzzer.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="ScudoHardenedAllocator.html" title="Scudo Hardened Allocator"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="fuzzing-llvm-libraries-and-tools">
+<h1>Fuzzing LLVM libraries and tools<a class="headerlink" href="#fuzzing-llvm-libraries-and-tools" 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="id7">Introduction</a></li>
+<li><a class="reference internal" href="#available-fuzzers" id="id8">Available Fuzzers</a><ul>
+<li><a class="reference internal" href="#clang-fuzzer" id="id9">clang-fuzzer</a></li>
+<li><a class="reference internal" href="#clang-proto-fuzzer" id="id10">clang-proto-fuzzer</a></li>
+<li><a class="reference internal" href="#clang-format-fuzzer" id="id11">clang-format-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-as-fuzzer" id="id12">llvm-as-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-dwarfdump-fuzzer" id="id13">llvm-dwarfdump-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-demangle-fuzzer" id="id14">llvm-demangle-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-isel-fuzzer" id="id15">llvm-isel-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-opt-fuzzer" id="id16">llvm-opt-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-mc-assemble-fuzzer" id="id17">llvm-mc-assemble-fuzzer</a></li>
+<li><a class="reference internal" href="#llvm-mc-disassemble-fuzzer" id="id18">llvm-mc-disassemble-fuzzer</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#mutators-and-input-generators" id="id19">Mutators and Input Generators</a><ul>
+<li><a class="reference internal" href="#generic-random-fuzzing" id="id20">Generic Random Fuzzing</a></li>
+<li><a class="reference internal" href="#structured-fuzzing-using-libprotobuf-mutator" id="id21">Structured Fuzzing using <tt class="docutils literal"><span class="pre">libprotobuf-mutator</span></tt></a></li>
+<li><a class="reference internal" href="#structured-fuzzing-of-llvm-ir" id="id22">Structured Fuzzing of LLVM IR</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#building-and-running" id="id23">Building and Running</a><ul>
+<li><a class="reference internal" href="#configuring-llvm-to-build-fuzzers" id="id24">Configuring LLVM to Build Fuzzers</a></li>
+<li><a class="reference internal" href="#continuously-running-and-finding-bugs" id="id25">Continuously Running and Finding Bugs</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#utilities-for-writing-fuzzers" id="id26">Utilities for Writing Fuzzers</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id7">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>The LLVM tree includes a number of fuzzers for various components. These are
+built on top of <a class="reference internal" href="LibFuzzer.html"><em>LibFuzzer</em></a>.</p>
+</div>
+<div class="section" id="available-fuzzers">
+<h2><a class="toc-backref" href="#id8">Available Fuzzers</a><a class="headerlink" href="#available-fuzzers" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="clang-fuzzer">
+<h3><a class="toc-backref" href="#id9">clang-fuzzer</a><a class="headerlink" href="#clang-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><em>generic fuzzer</em></a> that tries to compile textual input as C++ code. Some of the
+bugs this fuzzer has reported are <a class="reference external" href="https://llvm.org/pr23057">on bugzilla</a> and <a class="reference external" href="https://bugs.chromium.org/p/oss-fuzz/issues/list?q=proj-llvm+clang-fuzzer">on OSS Fuzz’s
+tracker</a>.</p>
+</div>
+<div class="section" id="clang-proto-fuzzer">
+<h3><a class="toc-backref" href="#id10">clang-proto-fuzzer</a><a class="headerlink" href="#clang-proto-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-protobuf"><em>libprotobuf-mutator based fuzzer</em></a> that compiles valid C++ programs generated from a protobuf
+class that describes a subset of the C++ language.</p>
+<p>This fuzzer accepts clang command line options after <cite>ignore_remaining_args=1</cite>.
+For example, the following command will fuzz clang with a higher optimization
+level:</p>
+<div class="highlight-shell"><pre>% bin/clang-proto-fuzzer <corpus-dir> -ignore_remaining_args=1 -O3</pre>
+</div>
+</div>
+<div class="section" id="clang-format-fuzzer">
+<h3><a class="toc-backref" href="#id11">clang-format-fuzzer</a><a class="headerlink" href="#clang-format-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><em>generic fuzzer</em></a> that runs <a class="reference external" href="https://clang.llvm.org/docs/ClangFormat.html">clang-format</a> on C++ text fragments. Some of the
+bugs this fuzzer has reported are <a class="reference external" href="https://llvm.org/pr23052">on bugzilla</a>
+and <a class="reference external" href="https://bugs.chromium.org/p/oss-fuzz/issues/list?q=proj-llvm+clang-format-fuzzer">on OSS Fuzz’s tracker</a>.</p>
+</div>
+<div class="section" id="llvm-as-fuzzer">
+<h3><a class="toc-backref" href="#id12">llvm-as-fuzzer</a><a class="headerlink" href="#llvm-as-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><em>generic fuzzer</em></a> that tries to parse text as <a class="reference internal" href="LangRef.html"><em>LLVM assembly</em></a>.
+Some of the bugs this fuzzer has reported are <a class="reference external" href="https://llvm.org/pr24639">on bugzilla</a>.</p>
+</div>
+<div class="section" id="llvm-dwarfdump-fuzzer">
+<h3><a class="toc-backref" href="#id13">llvm-dwarfdump-fuzzer</a><a class="headerlink" href="#llvm-dwarfdump-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><em>generic fuzzer</em></a> that interprets inputs as object files and runs
+<a class="reference internal" href="CommandGuide/llvm-dwarfdump.html"><em>llvm-dwarfdump</em></a> on them. Some of the bugs
+this fuzzer has reported are <a class="reference external" href="https://bugs.chromium.org/p/oss-fuzz/issues/list?q=proj-llvm+llvm-dwarfdump-fuzzer">on OSS Fuzz’s tracker</a></p>
+</div>
+<div class="section" id="llvm-demangle-fuzzer">
+<h3><a class="toc-backref" href="#id14">llvm-demangle-fuzzer</a><a class="headerlink" href="#llvm-demangle-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><em>generic fuzzer</em></a> for the Itanium demangler used in various LLVM tools. We’ve
+fuzzed __cxa_demangle to death, why not fuzz LLVM’s implementation of the same
+function!</p>
+</div>
+<div class="section" id="llvm-isel-fuzzer">
+<h3><a class="toc-backref" href="#id15">llvm-isel-fuzzer</a><a class="headerlink" href="#llvm-isel-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-ir"><em>structured LLVM IR fuzzer</em></a> aimed at finding bugs in instruction selection.</p>
+<p>This fuzzer accepts flags after <cite>ignore_remaining_args=1</cite>. The flags match
+those of <a class="reference internal" href="CommandGuide/llc.html"><em>llc</em></a> and the triple is required. For example,
+the following command would fuzz AArch64 with <a class="reference internal" href="GlobalISel.html"><em>Global Instruction Selection</em></a>:</p>
+<div class="highlight-shell"><pre>% bin/llvm-isel-fuzzer <corpus-dir> -ignore_remaining_args=1 -mtriple aarch64 -global-isel -O0</pre>
+</div>
+<p>Some flags can also be specified in the binary name itself in order to support
+OSS Fuzz, which has trouble with required arguments. To do this, you can copy
+or move <tt class="docutils literal"><span class="pre">llvm-isel-fuzzer</span></tt> to <tt class="docutils literal"><span class="pre">llvm-isel-fuzzer--x-y-z</span></tt>, separating options
+from the binary name using “–”. The valid options are architecture names
+(<tt class="docutils literal"><span class="pre">aarch64</span></tt>, <tt class="docutils literal"><span class="pre">x86_64</span></tt>), optimization levels (<tt class="docutils literal"><span class="pre">O0</span></tt>, <tt class="docutils literal"><span class="pre">O2</span></tt>), or specific
+keywords, like <tt class="docutils literal"><span class="pre">gisel</span></tt> for enabling global instruction selection. In this
+mode, the same example could be run like so:</p>
+<div class="highlight-shell"><pre>% bin/llvm-isel-fuzzer--aarch64-O0-gisel <corpus-dir></pre>
+</div>
+</div>
+<div class="section" id="llvm-opt-fuzzer">
+<h3><a class="toc-backref" href="#id16">llvm-opt-fuzzer</a><a class="headerlink" href="#llvm-opt-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-ir"><em>structured LLVM IR fuzzer</em></a> aimed at finding bugs in optimization passes.</p>
+<p>It receives optimzation pipeline and runs it for each fuzzer input.</p>
+<p>Interface of this fuzzer almost directly mirrors <tt class="docutils literal"><span class="pre">llvm-isel-fuzzer</span></tt>. Both
+<tt class="docutils literal"><span class="pre">mtriple</span></tt> and <tt class="docutils literal"><span class="pre">passes</span></tt> arguments are required. Passes are specified in a
+format suitable for the new pass manager.</p>
+<div class="highlight-shell"><pre>% bin/llvm-opt-fuzzer <corpus-dir> -ignore_remaining_args=1 -mtriple x86_64 -passes instcombine</pre>
+</div>
+<p>Similarly to the <tt class="docutils literal"><span class="pre">llvm-isel-fuzzer</span></tt> arguments in some predefined configurations
+might be embedded directly into the binary file name:</p>
+<div class="highlight-shell"><pre>% bin/llvm-opt-fuzzer--x86_64-instcombine <corpus-dir></pre>
+</div>
+</div>
+<div class="section" id="llvm-mc-assemble-fuzzer">
+<h3><a class="toc-backref" href="#id17">llvm-mc-assemble-fuzzer</a><a class="headerlink" href="#llvm-mc-assemble-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><em>generic fuzzer</em></a> that fuzzes the MC layer’s assemblers by treating inputs as
+target specific assembly.</p>
+<p>Note that this fuzzer has an unusual command line interface which is not fully
+compatible with all of libFuzzer’s features. Fuzzer arguments must be passed
+after <tt class="docutils literal"><span class="pre">--fuzzer-args</span></tt>, and any <tt class="docutils literal"><span class="pre">llc</span></tt> flags must use two dashes. For
+example, to fuzz the AArch64 assembler you might use the following command:</p>
+<div class="highlight-console"><div class="highlight"><pre><span class="go">llvm-mc-fuzzer --triple=aarch64-linux-gnu --fuzzer-args -max_len=4</span>
+</pre></div>
+</div>
+<p>This scheme will likely change in the future.</p>
+</div>
+<div class="section" id="llvm-mc-disassemble-fuzzer">
+<h3><a class="toc-backref" href="#id18">llvm-mc-disassemble-fuzzer</a><a class="headerlink" href="#llvm-mc-disassemble-fuzzer" title="Permalink to this headline">¶</a></h3>
+<p>A <a class="reference internal" href="#fuzzing-llvm-generic"><em>generic fuzzer</em></a> that fuzzes the MC layer’s disassemblers by treating inputs
+as assembled binary data.</p>
+<p>Note that this fuzzer has an unusual command line interface which is not fully
+compatible with all of libFuzzer’s features. See the notes above about
+<tt class="docutils literal"><span class="pre">llvm-mc-assemble-fuzzer</span></tt> for details.</p>
+</div>
+</div>
+<div class="section" id="mutators-and-input-generators">
+<h2><a class="toc-backref" href="#id19">Mutators and Input Generators</a><a class="headerlink" href="#mutators-and-input-generators" title="Permalink to this headline">¶</a></h2>
+<p>The inputs for a fuzz target are generated via random mutations of a
+<a class="reference internal" href="LibFuzzer.html#libfuzzer-corpus"><em>corpus</em></a>. There are a few options for the kinds of
+mutations that a fuzzer in LLVM might want.</p>
+<div class="section" id="generic-random-fuzzing">
+<span id="fuzzing-llvm-generic"></span><h3><a class="toc-backref" href="#id20">Generic Random Fuzzing</a><a class="headerlink" href="#generic-random-fuzzing" title="Permalink to this headline">¶</a></h3>
+<p>The most basic form of input mutation is to use the built in mutators of
+LibFuzzer. These simply treat the input corpus as a bag of bits and make random
+mutations. This type of fuzzer is good for stressing the surface layers of a
+program, and is good at testing things like lexers, parsers, or binary
+protocols.</p>
+<p>Some of the in-tree fuzzers that use this type of mutator are <a class="reference internal" href="#clang-fuzzer">clang-fuzzer</a>,
+<a class="reference internal" href="#clang-format-fuzzer">clang-format-fuzzer</a>, <a class="reference internal" href="#llvm-as-fuzzer">llvm-as-fuzzer</a>, <a class="reference internal" href="#llvm-dwarfdump-fuzzer">llvm-dwarfdump-fuzzer</a>,
+<a class="reference internal" href="#llvm-mc-assemble-fuzzer">llvm-mc-assemble-fuzzer</a>, and <a class="reference internal" href="#llvm-mc-disassemble-fuzzer">llvm-mc-disassemble-fuzzer</a>.</p>
+</div>
+<div class="section" id="structured-fuzzing-using-libprotobuf-mutator">
+<span id="fuzzing-llvm-protobuf"></span><h3><a class="toc-backref" href="#id21">Structured Fuzzing using <tt class="docutils literal"><span class="pre">libprotobuf-mutator</span></tt></a><a class="headerlink" href="#structured-fuzzing-using-libprotobuf-mutator" title="Permalink to this headline">¶</a></h3>
+<p>We can use <a class="reference external" href="https://github.com/google/libprotobuf-mutator">libprotobuf-mutator</a> in order to perform structured fuzzing and
+stress deeper layers of programs. This works by defining a protobuf class that
+translates arbitrary data into structurally interesting input. Specifically, we
+use this to work with a subset of the C++ language and perform mutations that
+produce valid C++ programs in order to exercise parts of clang that are more
+interesting than parser error handling.</p>
+<p>To build this kind of fuzzer you need <a class="reference external" href="https://github.com/google/protobuf">protobuf</a> and its dependencies
+installed, and you need to specify some extra flags when configuring the build
+with <a class="reference internal" href="CMake.html"><em>CMake</em></a>. For example, <a class="reference internal" href="#clang-proto-fuzzer">clang-proto-fuzzer</a> can be enabled by
+adding <tt class="docutils literal"><span class="pre">-DCLANG_ENABLE_PROTO_FUZZER=ON</span></tt> to the flags described in
+<a class="reference internal" href="#building-fuzzers"><em>Configuring LLVM to Build Fuzzers</em></a>.</p>
+<p>The only in-tree fuzzer that uses <tt class="docutils literal"><span class="pre">libprotobuf-mutator</span></tt> today is
+<a class="reference internal" href="#clang-proto-fuzzer">clang-proto-fuzzer</a>.</p>
+</div>
+<div class="section" id="structured-fuzzing-of-llvm-ir">
+<span id="fuzzing-llvm-ir"></span><h3><a class="toc-backref" href="#id22">Structured Fuzzing of LLVM IR</a><a class="headerlink" href="#structured-fuzzing-of-llvm-ir" title="Permalink to this headline">¶</a></h3>
+<p>We also use a more direct form of structured fuzzing for fuzzers that take
+<a class="reference internal" href="LangRef.html"><em>LLVM IR</em></a> as input. This is achieved through the <tt class="docutils literal"><span class="pre">FuzzMutate</span></tt>
+library, which was <a class="reference external" href="https://www.youtube.com/watch?v=UBbQ_s6hNgg">discussed at EuroLLVM 2017</a>.</p>
+<p>The <tt class="docutils literal"><span class="pre">FuzzMutate</span></tt> library is used to structurally fuzz backends in
+<a class="reference internal" href="#llvm-isel-fuzzer">llvm-isel-fuzzer</a>.</p>
+</div>
+</div>
+<div class="section" id="building-and-running">
+<h2><a class="toc-backref" href="#id23">Building and Running</a><a class="headerlink" href="#building-and-running" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="configuring-llvm-to-build-fuzzers">
+<span id="building-fuzzers"></span><h3><a class="toc-backref" href="#id24">Configuring LLVM to Build Fuzzers</a><a class="headerlink" href="#configuring-llvm-to-build-fuzzers" title="Permalink to this headline">¶</a></h3>
+<p>Fuzzers will be built and linked to libFuzzer by default as long as you build
+LLVM with sanitizer coverage enabled. You would typically also enable at least
+one sanitizer to find bugs faster. The most common way to build the fuzzers is
+by adding the following two flags to your CMake invocation:
+<tt class="docutils literal"><span class="pre">-DLLVM_USE_SANITIZER=Address</span> <span class="pre">-DLLVM_USE_SANITIZE_COVERAGE=On</span></tt>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">If you have <tt class="docutils literal"><span class="pre">compiler-rt</span></tt> checked out in an LLVM tree when building
+with sanitizers, you’ll want to specify <tt class="docutils literal"><span class="pre">-DLLVM_BUILD_RUNTIME=Off</span></tt>
+to avoid building the sanitizers themselves with sanitizers enabled.</p>
+</div>
+</div>
+<div class="section" id="continuously-running-and-finding-bugs">
+<h3><a class="toc-backref" href="#id25">Continuously Running and Finding Bugs</a><a class="headerlink" href="#continuously-running-and-finding-bugs" title="Permalink to this headline">¶</a></h3>
+<p>There used to be a public buildbot running LLVM fuzzers continuously, and while
+this did find issues, it didn’t have a very good way to report problems in an
+actionable way. Because of this, we’re moving towards using <a class="reference external" href="https://github.com/google/oss-fuzz">OSS Fuzz</a> more
+instead.</p>
+<p>You can browse the <a class="reference external" href="https://bugs.chromium.org/p/oss-fuzz/issues/list?q=Proj-llvm">LLVM project issue list</a> for the bugs found by
+<a class="reference external" href="https://github.com/google/oss-fuzz/blob/master/projects/llvm">LLVM on OSS Fuzz</a>. These are also mailed to the <a class="reference external" href="http://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-bugs">llvm-bugs mailing
+list</a>.</p>
+</div>
+</div>
+<div class="section" id="utilities-for-writing-fuzzers">
+<h2><a class="toc-backref" href="#id26">Utilities for Writing Fuzzers</a><a class="headerlink" href="#utilities-for-writing-fuzzers" title="Permalink to this headline">¶</a></h2>
+<p>There are some utilities available for writing fuzzers in LLVM.</p>
+<p>Some helpers for handling the command line interface are available in
+<tt class="docutils literal"><span class="pre">include/llvm/FuzzMutate/FuzzerCLI.h</span></tt>, including functions to parse command
+line options in a consistent way and to implement standalone main functions so
+your fuzzer can be built and tested when not built against libFuzzer.</p>
+<p>There is also some handling of the CMake config for fuzzers, where you should
+use the <tt class="docutils literal"><span class="pre">add_llvm_fuzzer</span></tt> to set up fuzzer targets. This function works
+similarly to functions such as <tt class="docutils literal"><span class="pre">add_llvm_tool</span></tt>, but they take care of linking
+to LibFuzzer when appropriate and can be passed the <tt class="docutils literal"><span class="pre">DUMMY_MAIN</span></tt> argument to
+enable standalone testing.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="ScudoHardenedAllocator.html" title="Scudo Hardened Allocator"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="LibFuzzer.html" title="libFuzzer â a library for coverage-guided fuzz testing."
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/GarbageCollection.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/GarbageCollection.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/GarbageCollection.html (added)
+++ www-releases/trunk/7.0.1/docs/GarbageCollection.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,1227 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+
+ <title>Garbage Collection with LLVM — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Writing an LLVM Pass" href="WritingAnLLVMPass.html" />
+ <link rel="prev" title="How To Use Instruction Mappings" href="HowToUseInstrMappings.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="garbage-collection-with-llvm">
+<h1>Garbage Collection with LLVM<a class="headerlink" href="#garbage-collection-with-llvm" title="Permalink to this headline">¶</a></h1>
+<div class="contents local topic" id="contents">
+<ul class="simple">
+<li><a class="reference internal" href="#abstract" id="id1">Abstract</a></li>
+<li><a class="reference internal" href="#quick-start" id="id2">Quick Start</a></li>
+<li><a class="reference internal" href="#introduction" id="id3">Introduction</a><ul>
+<li><a class="reference internal" href="#what-is-garbage-collection" id="id4">What is Garbage Collection?</a></li>
+<li><a class="reference internal" href="#goals-and-non-goals" id="id5">Goals and non-goals</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#llvm-ir-features" id="id6">LLVM IR Features</a><ul>
+<li><a class="reference internal" href="#specifying-gc-code-generation-gc" id="id7">Specifying GC code generation: <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"..."</span></tt></a></li>
+<li><a class="reference internal" href="#gcroot" id="id8">Identifying GC roots on the stack</a><ul>
+<li><a class="reference internal" href="#using-gc-statepoint" id="id9">Using <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt></a></li>
+<li><a class="reference internal" href="#using-llvm-gcwrite" id="id10">Using <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reading-and-writing-references-in-the-heap" id="id11">Reading and writing references in the heap</a><ul>
+<li><a class="reference internal" href="#write-barrier-llvm-gcwrite" id="id12">Write barrier: <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a></li>
+<li><a class="reference internal" href="#read-barrier-llvm-gcread" id="id13">Read barrier: <tt class="docutils literal"><span class="pre">llvm.gcread</span></tt></a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#built-in-gc-strategies" id="id14">Built In GC Strategies</a><ul>
+<li><a class="reference internal" href="#the-shadow-stack-gc" id="id15">The Shadow Stack GC</a></li>
+<li><a class="reference internal" href="#the-erlang-and-ocaml-gcs" id="id16">The ‘Erlang’ and ‘Ocaml’ GCs</a></li>
+<li><a class="reference internal" href="#the-statepoint-example-gc" id="id17">The Statepoint Example GC</a></li>
+<li><a class="reference internal" href="#the-coreclr-gc" id="id18">The CoreCLR GC</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#custom-gc-strategies" id="id19">Custom GC Strategies</a><ul>
+<li><a class="reference internal" href="#collector-requirements" id="id20">Collector Requirements</a></li>
+<li><a class="reference internal" href="#implementing-a-collector-plugin" id="id21">Implementing a collector plugin</a></li>
+<li><a class="reference internal" href="#overview-of-available-features" id="id22">Overview of available features</a></li>
+<li><a class="reference internal" href="#computing-stack-maps" id="id23">Computing stack maps</a></li>
+<li><a class="reference internal" href="#initializing-roots-to-null-initroots" id="id24">Initializing roots to null: <tt class="docutils literal"><span class="pre">InitRoots</span></tt></a></li>
+<li><a class="reference internal" href="#custom-lowering-of-intrinsics-customroots-customreadbarriers-and-customwritebarriers" id="id25">Custom lowering of intrinsics: <tt class="docutils literal"><span class="pre">CustomRoots</span></tt>, <tt class="docutils literal"><span class="pre">CustomReadBarriers</span></tt>, and <tt class="docutils literal"><span class="pre">CustomWriteBarriers</span></tt></a></li>
+<li><a class="reference internal" href="#generating-safe-points-neededsafepoints" id="id26">Generating safe points: <tt class="docutils literal"><span class="pre">NeededSafePoints</span></tt></a></li>
+<li><a class="reference internal" href="#emitting-assembly-code-gcmetadataprinter" id="id27">Emitting assembly code: <tt class="docutils literal"><span class="pre">GCMetadataPrinter</span></tt></a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#references" id="id28">References</a></li>
+</ul>
+</div>
+<div class="section" id="abstract">
+<h2><a class="toc-backref" href="#id1">Abstract</a><a class="headerlink" href="#abstract" title="Permalink to this headline">¶</a></h2>
+<p>This document covers how to integrate LLVM into a compiler for a language which
+supports garbage collection. <strong>Note that LLVM itself does not provide a
+garbage collector.</strong> You must provide your own.</p>
+</div>
+<div class="section" id="quick-start">
+<h2><a class="toc-backref" href="#id2">Quick Start</a><a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
+<p>First, you should pick a collector strategy. LLVM includes a number of built
+in ones, but you can also implement a loadable plugin with a custom definition.
+Note that the collector strategy is a description of how LLVM should generate
+code such that it interacts with your collector and runtime, not a description
+of the collector itself.</p>
+<p>Next, mark your generated functions as using your chosen collector strategy.
+From c++, you can call:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="o"><</span><span class="n">collector</span> <span class="n">description</span> <span class="n">name</span><span class="o">></span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This will produce IR like the following fragment:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">define</span> <span class="kt">void</span> <span class="vg">@foo</span><span class="p">()</span> <span class="k">gc</span> <span class="s">"<collector description name>"</span> <span class="p">{</span> <span class="p">...</span> <span class="p">}</span>
+</pre></div>
+</div>
+<p>When generating LLVM IR for your functions, you will need to:</p>
+<ul class="simple">
+<li>Use <tt class="docutils literal"><span class="pre">@llvm.gcread</span></tt> and/or <tt class="docutils literal"><span class="pre">@llvm.gcwrite</span></tt> in place of standard load and
+store instructions. These intrinsics are used to represent load and store
+barriers. If you collector does not require such barriers, you can skip
+this step.</li>
+<li>Use the memory allocation routines provided by your garbage collector’s
+runtime library.</li>
+<li>If your collector requires them, generate type maps according to your
+runtime’s binary interface. LLVM is not involved in the process. In
+particular, the LLVM type system is not suitable for conveying such
+information though the compiler.</li>
+<li>Insert any coordination code required for interacting with your collector.
+Many collectors require running application code to periodically check a
+flag and conditionally call a runtime function. This is often referred to
+as a safepoint poll.</li>
+</ul>
+<p>You will need to identify roots (i.e. references to heap objects your collector
+needs to know about) in your generated IR, so that LLVM can encode them into
+your final stack maps. Depending on the collector strategy chosen, this is
+accomplished by using either the <tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> intrinsics or an
+<tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> relocation sequence.</p>
+<p>Don’t forget to create a root for each intermediate value that is generated when
+evaluating an expression. In <tt class="docutils literal"><span class="pre">h(f(),</span> <span class="pre">g())</span></tt>, the result of <tt class="docutils literal"><span class="pre">f()</span></tt> could
+easily be collected if evaluating <tt class="docutils literal"><span class="pre">g()</span></tt> triggers a collection.</p>
+<p>Finally, you need to link your runtime library with the generated program
+executable (for a static compiler) or ensure the appropriate symbols are
+available for the runtime linker (for a JIT compiler).</p>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id3">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-is-garbage-collection">
+<h3><a class="toc-backref" href="#id4">What is Garbage Collection?</a><a class="headerlink" href="#what-is-garbage-collection" title="Permalink to this headline">¶</a></h3>
+<p>Garbage collection is a widely used technique that frees the programmer from
+having to know the lifetimes of heap objects, making software easier to produce
+and maintain. Many programming languages rely on garbage collection for
+automatic memory management. There are two primary forms of garbage collection:
+conservative and accurate.</p>
+<p>Conservative garbage collection often does not require any special support from
+either the language or the compiler: it can handle non-type-safe programming
+languages (such as C/C++) and does not require any special information from the
+compiler. The <a class="reference external" href="http://www.hpl.hp.com/personal/Hans_Boehm/gc/">Boehm collector</a> is an example of a
+state-of-the-art conservative collector.</p>
+<p>Accurate garbage collection requires the ability to identify all pointers in the
+program at run-time (which requires that the source-language be type-safe in
+most cases). Identifying pointers at run-time requires compiler support to
+locate all places that hold live pointer variables at run-time, including the
+<a class="reference internal" href="#gcroot"><em>processor stack and registers</em></a>.</p>
+<p>Conservative garbage collection is attractive because it does not require any
+special compiler support, but it does have problems. In particular, because the
+conservative garbage collector cannot <em>know</em> that a particular word in the
+machine is a pointer, it cannot move live objects in the heap (preventing the
+use of compacting and generational GC algorithms) and it can occasionally suffer
+from memory leaks due to integer values that happen to point to objects in the
+program. In addition, some aggressive compiler transformations can break
+conservative garbage collectors (though these seem rare in practice).</p>
+<p>Accurate garbage collectors do not suffer from any of these problems, but they
+can suffer from degraded scalar optimization of the program. In particular,
+because the runtime must be able to identify and update all pointers active in
+the program, some optimizations are less effective. In practice, however, the
+locality and performance benefits of using aggressive garbage collection
+techniques dominates any low-level losses.</p>
+<p>This document describes the mechanisms and interfaces provided by LLVM to
+support accurate garbage collection.</p>
+</div>
+<div class="section" id="goals-and-non-goals">
+<h3><a class="toc-backref" href="#id5">Goals and non-goals</a><a class="headerlink" href="#goals-and-non-goals" title="Permalink to this headline">¶</a></h3>
+<p>LLVM’s intermediate representation provides <a class="reference internal" href="#gc-intrinsics"><em>garbage collection intrinsics</em></a> that offer support for a broad class of collector models. For
+instance, the intrinsics permit:</p>
+<ul class="simple">
+<li>semi-space collectors</li>
+<li>mark-sweep collectors</li>
+<li>generational collectors</li>
+<li>incremental collectors</li>
+<li>concurrent collectors</li>
+<li>cooperative collectors</li>
+<li>reference counting</li>
+</ul>
+<p>We hope that the support built into the LLVM IR is sufficient to support a
+broad class of garbage collected languages including Scheme, ML, Java, C#,
+Perl, Python, Lua, Ruby, other scripting languages, and more.</p>
+<p>Note that LLVM <strong>does not itself provide a garbage collector</strong> — this should
+be part of your language’s runtime library. LLVM provides a framework for
+describing the garbage collectors requirements to the compiler. In particular,
+LLVM provides support for generating stack maps at call sites, polling for a
+safepoint, and emitting load and store barriers. You can also extend LLVM -
+possibly through a loadable <a class="reference internal" href="#plugin"><em>code generation plugins</em></a> - to
+generate code and data structures which conforms to the <em>binary interface</em>
+specified by the <em>runtime library</em>. This is similar to the relationship between
+LLVM and DWARF debugging info, for example. The difference primarily lies in
+the lack of an established standard in the domain of garbage collection — thus
+the need for a flexible extension mechanism.</p>
+<p>The aspects of the binary interface with which LLVM’s GC support is
+concerned are:</p>
+<ul class="simple">
+<li>Creation of GC safepoints within code where collection is allowed to execute
+safely.</li>
+<li>Computation of the stack map. For each safe point in the code, object
+references within the stack frame must be identified so that the collector may
+traverse and perhaps update them.</li>
+<li>Write barriers when storing object references to the heap. These are commonly
+used to optimize incremental scans in generational collectors.</li>
+<li>Emission of read barriers when loading object references. These are useful
+for interoperating with concurrent collectors.</li>
+</ul>
+<p>There are additional areas that LLVM does not directly address:</p>
+<ul class="simple">
+<li>Registration of global roots with the runtime.</li>
+<li>Registration of stack map entries with the runtime.</li>
+<li>The functions used by the program to allocate memory, trigger a collection,
+etc.</li>
+<li>Computation or compilation of type maps, or registration of them with the
+runtime. These are used to crawl the heap for object references.</li>
+</ul>
+<p>In general, LLVM’s support for GC does not include features which can be
+adequately addressed with other features of the IR and does not specify a
+particular binary interface. On the plus side, this means that you should be
+able to integrate LLVM with an existing runtime. On the other hand, it can
+have the effect of leaving a lot of work for the developer of a novel
+language. We try to mitigate this by providing built in collector strategy
+descriptions that can work with many common collector designs and easy
+extension points. If you don’t already have a specific binary interface
+you need to support, we recommend trying to use one of these built in collector
+strategies.</p>
+</div>
+</div>
+<div class="section" id="llvm-ir-features">
+<span id="gc-intrinsics"></span><h2><a class="toc-backref" href="#id6">LLVM IR Features</a><a class="headerlink" href="#llvm-ir-features" title="Permalink to this headline">¶</a></h2>
+<p>This section describes the garbage collection facilities provided by the
+<a class="reference internal" href="LangRef.html"><em>LLVM intermediate representation</em></a>. The exact behavior of these
+IR features is specified by the selected <a class="reference internal" href="#plugin"><em>GC strategy description</em></a>.</p>
+<div class="section" id="specifying-gc-code-generation-gc">
+<h3><a class="toc-backref" href="#id7">Specifying GC code generation: <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"..."</span></tt></a><a class="headerlink" href="#specifying-gc-code-generation-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-text"><div class="highlight"><pre>define <returntype> @name(...) gc "name" { ... }
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">gc</span></tt> function attribute is used to specify the desired GC strategy to the
+compiler. Its programmatic equivalent is the <tt class="docutils literal"><span class="pre">setGC</span></tt> method of <tt class="docutils literal"><span class="pre">Function</span></tt>.</p>
+<p>Setting <tt class="docutils literal"><span class="pre">gc</span> <span class="pre">"name"</span></tt> on a function triggers a search for a matching subclass
+of GCStrategy. Some collector strategies are built in. You can add others
+using either the loadable plugin mechanism, or by patching your copy of LLVM.
+It is the selected GC strategy which defines the exact nature of the code
+generated to support GC. If none is found, the compiler will raise an error.</p>
+<p>Specifying the GC style on a per-function basis allows LLVM to link together
+programs that use different garbage collection algorithms (or none at all).</p>
+</div>
+<div class="section" id="gcroot">
+<span id="identifying-gc-roots-on-the-stack"></span><h3><a class="toc-backref" href="#id8">Identifying GC roots on the stack</a><a class="headerlink" href="#gcroot" title="Permalink to this headline">¶</a></h3>
+<p>LLVM currently supports two different mechanisms for describing references in
+compiled code at safepoints. <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> is the older mechanism;
+<tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> has been added more recently. At the moment, you can choose
+either implementation (on a per <a class="reference internal" href="#plugin"><em>GC strategy</em></a> basis). Longer
+term, we will probably either migrate away from <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> entirely, or
+substantially merge their implementations. Note that most new development
+work is focused on <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>.</p>
+<div class="section" id="using-gc-statepoint">
+<h4><a class="toc-backref" href="#id9">Using <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt></a><a class="headerlink" href="#using-gc-statepoint" title="Permalink to this headline">¶</a></h4>
+<p><a class="reference internal" href="Statepoints.html"><em>This page</em></a> contains detailed documentation for
+<tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>.</p>
+</div>
+<div class="section" id="using-llvm-gcwrite">
+<h4><a class="toc-backref" href="#id10">Using <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a><a class="headerlink" href="#using-llvm-gcwrite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.gcroot</span><span class="p">(</span><span class="k">i8</span><span class="p">**</span> <span class="nv">%ptrloc</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%metadata</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>The <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> intrinsic is used to inform LLVM that a stack variable
+references an object on the heap and is to be tracked for garbage collection.
+The exact impact on generated code is specified by the Function’s selected
+<a class="reference internal" href="#plugin"><em>GC strategy</em></a>. All calls to <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> <strong>must</strong> reside
+inside the first basic block.</p>
+<p>The first argument <strong>must</strong> be a value referring to an alloca instruction or a
+bitcast of an alloca. The second contains a pointer to metadata that should be
+associated with the pointer, and <strong>must</strong> be a constant or global value
+address. If your target collector uses tags, use a null pointer for metadata.</p>
+<p>A compiler which performs manual SSA construction <strong>must</strong> ensure that SSA
+values representing GC references are stored in to the alloca passed to the
+respective <tt class="docutils literal"><span class="pre">gcroot</span></tt> before every call site and reloaded after every call.
+A compiler which uses mem2reg to raise imperative code using <tt class="docutils literal"><span class="pre">alloca</span></tt> into
+SSA form need only add a call to <tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> for those variables which
+are pointers into the GC heap.</p>
+<p>It is also important to mark intermediate values with <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt>. For
+example, consider <tt class="docutils literal"><span class="pre">h(f(),</span> <span class="pre">g())</span></tt>. Beware leaking the result of <tt class="docutils literal"><span class="pre">f()</span></tt> in the
+case that <tt class="docutils literal"><span class="pre">g()</span></tt> triggers a collection. Note, that stack variables must be
+initialized and marked with <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> in function’s prologue.</p>
+<p>The <tt class="docutils literal"><span class="pre">%metadata</span></tt> argument can be used to avoid requiring heap objects to have
+‘isa’ pointers or tag bits. [<a class="reference internal" href="#appel89">Appel89</a>, <a class="reference internal" href="#goldberg91">Goldberg91</a>, <a class="reference internal" href="#tolmach94">Tolmach94</a>] If specified,
+its value will be tracked along with the location of the pointer in the stack
+frame.</p>
+<p>Consider the following fragment of Java code:</p>
+<div class="highlight-java"><div class="highlight"><pre><span class="o">{</span>
+ <span class="n">Object</span> <span class="n">X</span><span class="o">;</span> <span class="c1">// A null-initialized reference to an object</span>
+ <span class="o">...</span>
+<span class="o">}</span>
+</pre></div>
+</div>
+<p>This block (which may be located in the middle of a function or in a loop nest),
+could be compiled to this LLVM code:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nl">Entry:</span>
+ <span class="c">;; In the entry block for the function, allocate the</span>
+ <span class="c">;; stack space for X, which is an LLVM pointer.</span>
+ <span class="nv">%X</span> <span class="p">=</span> <span class="k">alloca</span> <span class="nv">%Object</span><span class="p">*</span>
+
+ <span class="c">;; Tell LLVM that the stack space is a stack root.</span>
+ <span class="c">;; Java has type-tags on objects, so we pass null as metadata.</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span> <span class="k">to</span> <span class="k">i8</span><span class="p">**</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.gcroot</span><span class="p">(</span><span class="k">i8</span><span class="p">**</span> <span class="nv">%tmp</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="k">null</span><span class="p">)</span>
+ <span class="p">...</span>
+
+ <span class="c">;; "CodeBlock" is the block corresponding to the start</span>
+ <span class="c">;; of the scope above.</span>
+<span class="nl">CodeBlock:</span>
+ <span class="c">;; Java null-initializes pointers.</span>
+ <span class="k">store</span> <span class="nv">%Object</span><span class="p">*</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span>
+
+ <span class="p">...</span>
+
+ <span class="c">;; As the pointer goes out of scope, store a null value into</span>
+ <span class="c">;; it, to indicate that the value is no longer live.</span>
+ <span class="k">store</span> <span class="nv">%Object</span><span class="p">*</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%Object</span><span class="p">**</span> <span class="nv">%X</span>
+ <span class="p">...</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="reading-and-writing-references-in-the-heap">
+<h3><a class="toc-backref" href="#id11">Reading and writing references in the heap</a><a class="headerlink" href="#reading-and-writing-references-in-the-heap" title="Permalink to this headline">¶</a></h3>
+<p>Some collectors need to be informed when the mutator (the program that needs
+garbage collection) either reads a pointer from or writes a pointer to a field
+of a heap object. The code fragments inserted at these points are called <em>read
+barriers</em> and <em>write barriers</em>, respectively. The amount of code that needs to
+be executed is usually quite small and not on the critical path of any
+computation, so the overall performance impact of the barrier is tolerable.</p>
+<p>Barriers often require access to the <em>object pointer</em> rather than the <em>derived
+pointer</em> (which is a pointer to the field within the object). Accordingly,
+these intrinsics take both pointers as separate arguments for completeness. In
+this snippet, <tt class="docutils literal"><span class="pre">%object</span></tt> is the object pointer, and <tt class="docutils literal"><span class="pre">%derived</span></tt> is the derived
+pointer:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="c">;; An array type.</span>
+<span class="nv">%class.Array</span> <span class="p">=</span> <span class="k">type</span> <span class="p">{</span> <span class="nv">%class.Object</span><span class="p">,</span> <span class="k">i32</span><span class="p">,</span> <span class="p">[</span><span class="m">0</span> <span class="k">x</span> <span class="nv">%class.Object</span><span class="p">*]</span> <span class="p">}</span>
+<span class="p">...</span>
+
+<span class="c">;; Load the object pointer from a gcroot.</span>
+<span class="nv">%object</span> <span class="p">=</span> <span class="k">load</span> <span class="nv">%class.Array</span><span class="p">**</span> <span class="nv">%object_addr</span>
+
+<span class="c">;; Compute the derived pointer.</span>
+<span class="nv">%derived</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%object</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">2</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%n</span>
+</pre></div>
+</div>
+<p>LLVM does not enforce this relationship between the object and derived pointer
+(although a particular <a class="reference internal" href="#plugin"><em>collector strategy</em></a> might). However, it
+would be an unusual collector that violated it.</p>
+<p>The use of these intrinsics is naturally optional if the target GC does not
+require the corresponding barrier. The GC strategy used with such a collector
+should replace the intrinsic calls with the corresponding <tt class="docutils literal"><span class="pre">load</span></tt> or
+<tt class="docutils literal"><span class="pre">store</span></tt> instruction if they are used.</p>
+<p>One known deficiency with the current design is that the barrier intrinsics do
+not include the size or alignment of the underlying operation performed. It is
+currently assumed that the operation is of pointer size and the alignment is
+assumed to be the target machine’s default alignment.</p>
+<div class="section" id="write-barrier-llvm-gcwrite">
+<h4><a class="toc-backref" href="#id12">Write barrier: <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt></a><a class="headerlink" href="#write-barrier-llvm-gcwrite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="vg">@llvm.gcwrite</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%value</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i8</span><span class="p">**</span> <span class="nv">%derived</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For write barriers, LLVM provides the <tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt> intrinsic function. It
+has exactly the same semantics as a non-volatile <tt class="docutils literal"><span class="pre">store</span></tt> to the derived
+pointer (the third argument). The exact code generated is specified by the
+Function’s selected <a class="reference internal" href="#plugin"><em>GC strategy</em></a>.</p>
+<p>Many important algorithms require write barriers, including generational and
+concurrent collectors. Additionally, write barriers could be used to implement
+reference counting.</p>
+</div>
+<div class="section" id="read-barrier-llvm-gcread">
+<h4><a class="toc-backref" href="#id13">Read barrier: <tt class="docutils literal"><span class="pre">llvm.gcread</span></tt></a><a class="headerlink" href="#read-barrier-llvm-gcread" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.gcread</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%object</span><span class="p">,</span> <span class="k">i8</span><span class="p">**</span> <span class="nv">%derived</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>For read barriers, LLVM provides the <tt class="docutils literal"><span class="pre">llvm.gcread</span></tt> intrinsic function. It has
+exactly the same semantics as a non-volatile <tt class="docutils literal"><span class="pre">load</span></tt> from the derived pointer
+(the second argument). The exact code generated is specified by the Function’s
+selected <a class="reference internal" href="#plugin"><em>GC strategy</em></a>.</p>
+<p>Read barriers are needed by fewer algorithms than write barriers, and may have a
+greater performance impact since pointer reads are more frequent than writes.</p>
+</div>
+</div>
+</div>
+<div class="section" id="built-in-gc-strategies">
+<span id="builtin-gc-strategies"></span><span id="plugin"></span><h2><a class="toc-backref" href="#id14">Built In GC Strategies</a><a class="headerlink" href="#built-in-gc-strategies" title="Permalink to this headline">¶</a></h2>
+<p>LLVM includes built in support for several varieties of garbage collectors.</p>
+<div class="section" id="the-shadow-stack-gc">
+<h3><a class="toc-backref" href="#id15">The Shadow Stack GC</a><a class="headerlink" href="#the-shadow-stack-gc" title="Permalink to this headline">¶</a></h3>
+<p>To use this collector strategy, mark your functions with:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"shadow-stack"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>Unlike many GC algorithms which rely on a cooperative code generator to compile
+stack maps, this algorithm carefully maintains a linked list of stack roots
+[<a class="reference internal" href="#henderson02"><em>Henderson2002</em></a>]. This so-called “shadow stack” mirrors the
+machine stack. Maintaining this data structure is slower than using a stack map
+compiled into the executable as constant data, but has a significant portability
+advantage because it requires no special support from the target code generator,
+and does not require tricky platform-specific code to crawl the machine stack.</p>
+<p>The tradeoff for this simplicity and portability is:</p>
+<ul class="simple">
+<li>High overhead per function call.</li>
+<li>Not thread-safe.</li>
+</ul>
+<p>Still, it’s an easy way to get started. After your compiler and runtime are up
+and running, writing a <a class="reference internal" href="#plugin"><em>plugin</em></a> will allow you to take advantage
+of <a class="reference internal" href="#collector-algos"><em>more advanced GC features</em></a> of LLVM in order to
+improve performance.</p>
+<p>The shadow stack doesn’t imply a memory allocation algorithm. A semispace
+collector or building atop <tt class="docutils literal"><span class="pre">malloc</span></tt> are great places to start, and can be
+implemented with very little code.</p>
+<p>When it comes time to collect, however, your runtime needs to traverse the stack
+roots, and for this it needs to integrate with the shadow stack. Luckily, doing
+so is very simple. (This code is heavily commented to help you understand the
+data structure, but there are only 20 lines of meaningful code.)</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="c1">/// The map for a single function's stack frame. One of these is</span>
+<span class="c1">/// compiled as constant data into the executable for each function.</span>
+<span class="c1">///</span>
+<span class="c1">/// Storage of metadata values is elided if the %metadata parameter to</span>
+<span class="c1">/// @llvm.gcroot is null.</span>
+<span class="k">struct</span> <span class="n">FrameMap</span> <span class="p">{</span>
+ <span class="n">int32_t</span> <span class="n">NumRoots</span><span class="p">;</span> <span class="c1">//< Number of roots in stack frame.</span>
+ <span class="n">int32_t</span> <span class="n">NumMeta</span><span class="p">;</span> <span class="c1">//< Number of metadata entries. May be < NumRoots.</span>
+ <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Meta</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> <span class="c1">//< Metadata for each root.</span>
+<span class="p">};</span>
+
+<span class="c1">/// A link in the dynamic shadow stack. One of these is embedded in</span>
+<span class="c1">/// the stack frame of each function on the call stack.</span>
+<span class="k">struct</span> <span class="n">StackEntry</span> <span class="p">{</span>
+ <span class="n">StackEntry</span> <span class="o">*</span><span class="n">Next</span><span class="p">;</span> <span class="c1">//< Link to next stack entry (the caller's).</span>
+ <span class="k">const</span> <span class="n">FrameMap</span> <span class="o">*</span><span class="n">Map</span><span class="p">;</span> <span class="c1">//< Pointer to constant FrameMap.</span>
+ <span class="kt">void</span> <span class="o">*</span><span class="n">Roots</span><span class="p">[</span><span class="mi">0</span><span class="p">];</span> <span class="c1">//< Stack roots (in-place array).</span>
+<span class="p">};</span>
+
+<span class="c1">/// The head of the singly-linked list of StackEntries. Functions push</span>
+<span class="c1">/// and pop onto this in their prologue and epilogue.</span>
+<span class="c1">///</span>
+<span class="c1">/// Since there is only a global list, this technique is not threadsafe.</span>
+<span class="n">StackEntry</span> <span class="o">*</span><span class="n">llvm_gc_root_chain</span><span class="p">;</span>
+
+<span class="c1">/// Calls Visitor(root, meta) for each GC root on the stack.</span>
+<span class="c1">/// root and meta are exactly the values passed to</span>
+<span class="c1">/// @llvm.gcroot.</span>
+<span class="c1">///</span>
+<span class="c1">/// Visitor could be a function to recursively mark live objects. Or it</span>
+<span class="c1">/// might copy them to another heap or generation.</span>
+<span class="c1">///</span>
+<span class="c1">/// @param Visitor A function to invoke for every GC root on the stack.</span>
+<span class="kt">void</span> <span class="n">visitGCRoots</span><span class="p">(</span><span class="kt">void</span> <span class="p">(</span><span class="o">*</span><span class="n">Visitor</span><span class="p">)(</span><span class="kt">void</span> <span class="o">**</span><span class="n">Root</span><span class="p">,</span> <span class="k">const</span> <span class="kt">void</span> <span class="o">*</span><span class="n">Meta</span><span class="p">))</span> <span class="p">{</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">StackEntry</span> <span class="o">*</span><span class="n">R</span> <span class="o">=</span> <span class="n">llvm_gc_root_chain</span><span class="p">;</span> <span class="n">R</span><span class="p">;</span> <span class="n">R</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Next</span><span class="p">)</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="c1">// For roots [0, NumMeta), the metadata pointer is in the FrameMap.</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">e</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">NumMeta</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">Visitor</span><span class="p">(</span><span class="o">&</span><span class="n">R</span><span class="o">-></span><span class="n">Roots</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">Meta</span><span class="p">[</span><span class="n">i</span><span class="p">]);</span>
+
+ <span class="c1">// For roots [NumMeta, NumRoots), the metadata pointer is null.</span>
+ <span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">e</span> <span class="o">=</span> <span class="n">R</span><span class="o">-></span><span class="n">Map</span><span class="o">-></span><span class="n">NumRoots</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">e</span><span class="p">;</span> <span class="o">++</span><span class="n">i</span><span class="p">)</span>
+ <span class="n">Visitor</span><span class="p">(</span><span class="o">&</span><span class="n">R</span><span class="o">-></span><span class="n">Roots</span><span class="p">[</span><span class="n">i</span><span class="p">],</span> <span class="nb">NULL</span><span class="p">);</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="the-erlang-and-ocaml-gcs">
+<h3><a class="toc-backref" href="#id16">The ‘Erlang’ and ‘Ocaml’ GCs</a><a class="headerlink" href="#the-erlang-and-ocaml-gcs" title="Permalink to this headline">¶</a></h3>
+<p>LLVM ships with two example collectors which leverage the <tt class="docutils literal"><span class="pre">gcroot</span></tt>
+mechanisms. To our knowledge, these are not actually used by any language
+runtime, but they do provide a reasonable starting point for someone interested
+in writing an <tt class="docutils literal"><span class="pre">gcroot</span></tt> compatible GC plugin. In particular, these are the
+only in tree examples of how to produce a custom binary stack map format using
+a <tt class="docutils literal"><span class="pre">gcroot</span></tt> strategy.</p>
+<p>As there names imply, the binary format produced is intended to model that
+used by the Erlang and OCaml compilers respectively.</p>
+</div>
+<div class="section" id="the-statepoint-example-gc">
+<span id="statepoint-example-gc"></span><h3><a class="toc-backref" href="#id17">The Statepoint Example GC</a><a class="headerlink" href="#the-statepoint-example-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"statepoint-example"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This GC provides an example of how one might use the infrastructure provided
+by <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt>. This example GC is compatible with the
+<a class="reference internal" href="Statepoints.html#placesafepoints"><em>PlaceSafepoints</em></a> and <a class="reference internal" href="Statepoints.html#rewritestatepointsforgc"><em>RewriteStatepointsForGC</em></a> utility passes
+which simplify <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> sequence insertion. If you need to build a
+custom GC strategy around the <tt class="docutils literal"><span class="pre">gc.statepoints</span></tt> mechanisms, it is recommended
+that you use this one as a starting point.</p>
+<p>This GC strategy does not support read or write barriers. As a result, these
+intrinsics are lowered to normal loads and stores.</p>
+<p>The stack map format generated by this GC strategy can be found in the
+<a class="reference internal" href="StackMaps.html#stackmap-section"><em>Stack Map Section</em></a> using a format documented <a class="reference internal" href="Statepoints.html#statepoint-stackmap-format"><em>here</em></a>. This format is intended to be the standard
+format supported by LLVM going forward.</p>
+</div>
+<div class="section" id="the-coreclr-gc">
+<h3><a class="toc-backref" href="#id18">The CoreCLR GC</a><a class="headerlink" href="#the-coreclr-gc" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">F</span><span class="p">.</span><span class="n">setGC</span><span class="p">(</span><span class="s">"coreclr"</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>This GC leverages the <tt class="docutils literal"><span class="pre">gc.statepoint</span></tt> mechanism to support the
+<a class="reference external" href="https://github.com/dotnet/coreclr">CoreCLR</a> runtime.</p>
+<p>Support for this GC strategy is a work in progress. This strategy will
+differ from
+<a class="reference internal" href="#statepoint-example-gc"><em>statepoint-example GC</em></a> strategy in
+certain aspects like:</p>
+<ul class="simple">
+<li>Base-pointers of interior pointers are not explicitly
+tracked and reported.</li>
+<li>A different format is used for encoding stack maps.</li>
+<li>Safe-point polls are only needed before loop-back edges
+and before tail-calls (not needed at function-entry).</li>
+</ul>
+</div>
+</div>
+<div class="section" id="custom-gc-strategies">
+<h2><a class="toc-backref" href="#id19">Custom GC Strategies</a><a class="headerlink" href="#custom-gc-strategies" title="Permalink to this headline">¶</a></h2>
+<p>If none of the built in GC strategy descriptions met your needs above, you will
+need to define a custom GCStrategy and possibly, a custom LLVM pass to perform
+lowering. Your best example of where to start defining a custom GCStrategy
+would be to look at one of the built in strategies.</p>
+<p>You may be able to structure this additional code as a loadable plugin library.
+Loadable plugins are sufficient if all you need is to enable a different
+combination of built in functionality, but if you need to provide a custom
+lowering pass, you will need to build a patched version of LLVM. If you think
+you need a patched build, please ask for advice on llvm-dev. There may be an
+easy way we can extend the support to make it work for your use case without
+requiring a custom build.</p>
+<div class="section" id="collector-requirements">
+<h3><a class="toc-backref" href="#id20">Collector Requirements</a><a class="headerlink" href="#collector-requirements" title="Permalink to this headline">¶</a></h3>
+<p>You should be able to leverage any existing collector library that includes the following elements:</p>
+<ol class="arabic simple">
+<li>A memory allocator which exposes an allocation function your compiled
+code can call.</li>
+<li>A binary format for the stack map. A stack map describes the location
+of references at a safepoint and is used by precise collectors to identify
+references within a stack frame on the machine stack. Note that collectors
+which conservatively scan the stack don’t require such a structure.</li>
+<li>A stack crawler to discover functions on the call stack, and enumerate the
+references listed in the stack map for each call site.</li>
+<li>A mechanism for identifying references in global locations (e.g. global
+variables).</li>
+<li>If you collector requires them, an LLVM IR implementation of your collectors
+load and store barriers. Note that since many collectors don’t require
+barriers at all, LLVM defaults to lowering such barriers to normal loads
+and stores unless you arrange otherwise.</li>
+</ol>
+</div>
+<div class="section" id="implementing-a-collector-plugin">
+<h3><a class="toc-backref" href="#id21">Implementing a collector plugin</a><a class="headerlink" href="#implementing-a-collector-plugin" title="Permalink to this headline">¶</a></h3>
+<p>User code specifies which GC code generation to use with the <tt class="docutils literal"><span class="pre">gc</span></tt> function
+attribute or, equivalently, with the <tt class="docutils literal"><span class="pre">setGC</span></tt> method of <tt class="docutils literal"><span class="pre">Function</span></tt>.</p>
+<p>To implement a GC plugin, it is necessary to subclass <tt class="docutils literal"><span class="pre">llvm::GCStrategy</span></tt>,
+which can be accomplished in a few lines of boilerplate code. LLVM’s
+infrastructure provides access to several important algorithms. For an
+uncontroversial collector, all that remains may be to compile LLVM’s computed
+stack map to assembly code (using the binary representation expected by the
+runtime library). This can be accomplished in about 100 lines of code.</p>
+<p>This is not the appropriate place to implement a garbage collected heap or a
+garbage collector itself. That code should exist in the language’s runtime
+library. The compiler plugin is responsible for generating code which conforms
+to the binary interface defined by library, most essentially the <a class="reference internal" href="#stack-map"><em>stack map</em></a>.</p>
+<p>To subclass <tt class="docutils literal"><span class="pre">llvm::GCStrategy</span></tt> and register it with the compiler:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">// lib/MyGC/MyGC.cpp - Example LLVM GC plugin</span>
+
+<span class="cp">#include "llvm/CodeGen/GCStrategy.h"</span>
+<span class="cp">#include "llvm/CodeGen/GCMetadata.h"</span>
+<span class="cp">#include "llvm/Support/Compiler.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">LLVM_LIBRARY_VISIBILITY</span> <span class="n">MyGC</span> <span class="o">:</span> <span class="k">public</span> <span class="n">GCStrategy</span> <span class="p">{</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="n">MyGC</span><span class="p">()</span> <span class="p">{}</span>
+ <span class="p">};</span>
+
+ <span class="n">GCRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyGC</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="s">"mygc"</span><span class="p">,</span> <span class="s">"My bespoke garbage collector."</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This boilerplate collector does nothing. More specifically:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">llvm.gcread</span></tt> calls are replaced with the corresponding <tt class="docutils literal"><span class="pre">load</span></tt>
+instruction.</li>
+<li><tt class="docutils literal"><span class="pre">llvm.gcwrite</span></tt> calls are replaced with the corresponding <tt class="docutils literal"><span class="pre">store</span></tt>
+instruction.</li>
+<li>No safe points are added to the code.</li>
+<li>The stack map is not compiled into the executable.</li>
+</ul>
+<p>Using the LLVM makefiles, this code
+can be compiled as a plugin using a simple makefile:</p>
+<div class="highlight-make"><div class="highlight"><pre><span class="c"># lib/MyGC/Makefile</span>
+
+<span class="nv">LEVEL</span> <span class="o">:=</span> ../..
+<span class="nv">LIBRARYNAME</span> <span class="o">=</span> MyGC
+<span class="nv">LOADABLE_MODULE</span> <span class="o">=</span> 1
+
+<span class="cp">include $(LEVEL)/Makefile.common</span>
+</pre></div>
+</div>
+<p>Once the plugin is compiled, code using it may be compiled using <tt class="docutils literal"><span class="pre">llc</span>
+<span class="pre">-load=MyGC.so</span></tt> (though MyGC.so may have some other platform-specific
+extension):</p>
+<div class="highlight-python"><pre>$ cat sample.ll
+define void @f() gc "mygc" {
+entry:
+ ret void
+}
+$ llvm-as < sample.ll | llc -load=MyGC.so</pre>
+</div>
+<p>It is also possible to statically link the collector plugin into tools, such as
+a language-specific compiler front-end.</p>
+</div>
+<div class="section" id="overview-of-available-features">
+<span id="collector-algos"></span><h3><a class="toc-backref" href="#id22">Overview of available features</a><a class="headerlink" href="#overview-of-available-features" title="Permalink to this headline">¶</a></h3>
+<p><tt class="docutils literal"><span class="pre">GCStrategy</span></tt> provides a range of features through which a plugin may do useful
+work. Some of these are callbacks, some are algorithms that can be enabled,
+disabled, or customized. This matrix summarizes the supported (and planned)
+features and correlates them with the collection techniques which typically
+require them.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="14%" />
+<col width="7%" />
+<col width="9%" />
+<col width="11%" />
+<col width="8%" />
+<col width="10%" />
+<col width="15%" />
+<col width="11%" />
+<col width="14%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Algorithm</th>
+<th class="head">Done</th>
+<th class="head">Shadow
+stack</th>
+<th class="head">refcount</th>
+<th class="head">mark-
+sweep</th>
+<th class="head">copying</th>
+<th class="head">incremental</th>
+<th class="head">threaded</th>
+<th class="head">concurrent</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>stack map</td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td>initialize
+roots</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>derived
+pointers</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong>*</td>
+<td><strong>N</strong>*</td>
+</tr>
+<tr class="row-odd"><td><strong>custom
+lowering</strong></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>gcroot</em></td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-odd"><td><em>gcwrite</em></td>
+<td>â</td>
+<td> </td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td> </td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td><em>gcread</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><strong>safe
+points</strong></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>in
+calls</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><em>before
+calls</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td><em>for
+loops</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong></td>
+<td><strong>N</strong></td>
+</tr>
+<tr class="row-odd"><td><em>before
+escape</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-even"><td>emit code
+at safe
+points</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td><strong>N</strong></td>
+<td><strong>N</strong></td>
+</tr>
+<tr class="row-odd"><td><strong>output</strong></td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+<td> </td>
+</tr>
+<tr class="row-even"><td><em>assembly</em></td>
+<td>â</td>
+<td> </td>
+<td> </td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+<td>â</td>
+</tr>
+<tr class="row-odd"><td><em>JIT</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-even"><td><em>obj</em></td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-odd"><td>live
+analysis</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-even"><td>register
+map</td>
+<td>NO</td>
+<td> </td>
+<td> </td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+<td><strong>?</strong></td>
+</tr>
+<tr class="row-odd"><td colspan="9">* Derived pointers only pose a hasard to copying collections.</td>
+</tr>
+<tr class="row-even"><td colspan="9"><strong>?</strong> denotes a feature which could be utilized if available.</td>
+</tr>
+</tbody>
+</table>
+<p>To be clear, the collection techniques above are defined as:</p>
+<dl class="docutils">
+<dt>Shadow Stack</dt>
+<dd>The mutator carefully maintains a linked list of stack roots.</dd>
+<dt>Reference Counting</dt>
+<dd>The mutator maintains a reference count for each object and frees an object
+when its count falls to zero.</dd>
+<dt>Mark-Sweep</dt>
+<dd>When the heap is exhausted, the collector marks reachable objects starting
+from the roots, then deallocates unreachable objects in a sweep phase.</dd>
+<dt>Copying</dt>
+<dd>As reachability analysis proceeds, the collector copies objects from one heap
+area to another, compacting them in the process. Copying collectors enable
+highly efficient “bump pointer” allocation and can improve locality of
+reference.</dd>
+<dt>Incremental</dt>
+<dd>(Including generational collectors.) Incremental collectors generally have all
+the properties of a copying collector (regardless of whether the mature heap
+is compacting), but bring the added complexity of requiring write barriers.</dd>
+<dt>Threaded</dt>
+<dd>Denotes a multithreaded mutator; the collector must still stop the mutator
+(“stop the world”) before beginning reachability analysis. Stopping a
+multithreaded mutator is a complicated problem. It generally requires highly
+platform-specific code in the runtime, and the production of carefully
+designed machine code at safe points.</dd>
+<dt>Concurrent</dt>
+<dd>In this technique, the mutator and the collector run concurrently, with the
+goal of eliminating pause times. In a <em>cooperative</em> collector, the mutator
+further aids with collection should a pause occur, allowing collection to take
+advantage of multiprocessor hosts. The “stop the world” problem of threaded
+collectors is generally still present to a limited extent. Sophisticated
+marking algorithms are necessary. Read barriers may be necessary.</dd>
+</dl>
+<p>As the matrix indicates, LLVM’s garbage collection infrastructure is already
+suitable for a wide variety of collectors, but does not currently extend to
+multithreaded programs. This will be added in the future as there is
+interest.</p>
+</div>
+<div class="section" id="computing-stack-maps">
+<span id="stack-map"></span><h3><a class="toc-backref" href="#id23">Computing stack maps</a><a class="headerlink" href="#computing-stack-maps" title="Permalink to this headline">¶</a></h3>
+<p>LLVM automatically computes a stack map. One of the most important features
+of a <tt class="docutils literal"><span class="pre">GCStrategy</span></tt> is to compile this information into the executable in
+the binary representation expected by the runtime library.</p>
+<p>The stack map consists of the location and identity of each GC root in the
+each function in the module. For each root:</p>
+<ul class="simple">
+<li><tt class="docutils literal"><span class="pre">RootNum</span></tt>: The index of the root.</li>
+<li><tt class="docutils literal"><span class="pre">StackOffset</span></tt>: The offset of the object relative to the frame pointer.</li>
+<li><tt class="docutils literal"><span class="pre">RootMetadata</span></tt>: The value passed as the <tt class="docutils literal"><span class="pre">%metadata</span></tt> parameter to the
+<tt class="docutils literal"><span class="pre">@llvm.gcroot</span></tt> intrinsic.</li>
+</ul>
+<p>Also, for the function as a whole:</p>
+<ul>
+<li><dl class="first docutils">
+<dt><tt class="docutils literal"><span class="pre">getFrameSize()</span></tt>: The overall size of the function’s initial stack frame,</dt>
+<dd><p class="first last">not accounting for any dynamic allocation.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first"><tt class="docutils literal"><span class="pre">roots_size()</span></tt>: The count of roots in the function.</p>
+</li>
+</ul>
+<p>To access the stack map, use <tt class="docutils literal"><span class="pre">GCFunctionMetadata::roots_begin()</span></tt> and
+-<tt class="docutils literal"><span class="pre">end()</span></tt> from the <a class="reference internal" href="#assembly"><em>GCMetadataPrinter</em></a>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">begin</span><span class="p">(),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">end</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GCFunctionInfo</span> <span class="o">*</span><span class="n">FI</span> <span class="o">=</span> <span class="o">*</span><span class="n">I</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">FrameSize</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">getFrameSize</span><span class="p">();</span>
+ <span class="n">size_t</span> <span class="n">RootCount</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_size</span><span class="p">();</span>
+
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">roots_iterator</span> <span class="n">RI</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_begin</span><span class="p">(),</span>
+ <span class="n">RE</span> <span class="o">=</span> <span class="n">FI</span><span class="o">-></span><span class="n">roots_end</span><span class="p">();</span>
+ <span class="n">RI</span> <span class="o">!=</span> <span class="n">RE</span><span class="p">;</span> <span class="o">++</span><span class="n">RI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">RootNum</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">Num</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">RootStackOffset</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">StackOffset</span><span class="p">;</span>
+ <span class="n">Constant</span> <span class="o">*</span><span class="n">RootMetadata</span> <span class="o">=</span> <span class="n">RI</span><span class="o">-></span><span class="n">Metadata</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>If the <tt class="docutils literal"><span class="pre">llvm.gcroot</span></tt> intrinsic is eliminated before code generation by a
+custom lowering pass, LLVM will compute an empty stack map. This may be useful
+for collector plugins which implement reference counting or a shadow stack.</p>
+</div>
+<div class="section" id="initializing-roots-to-null-initroots">
+<span id="init-roots"></span><h3><a class="toc-backref" href="#id24">Initializing roots to null: <tt class="docutils literal"><span class="pre">InitRoots</span></tt></a><a class="headerlink" href="#initializing-roots-to-null-initroots" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">InitRoots</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>When set, LLVM will automatically initialize each root to <tt class="docutils literal"><span class="pre">null</span></tt> upon entry to
+the function. This prevents the GC’s sweep phase from visiting uninitialized
+pointers, which will almost certainly cause it to crash. This initialization
+occurs before custom lowering, so the two may be used together.</p>
+<p>Since LLVM does not yet compute liveness information, there is no means of
+distinguishing an uninitialized stack root from an initialized one. Therefore,
+this feature should be used by all GC plugins. It is enabled by default.</p>
+</div>
+<div class="section" id="custom-lowering-of-intrinsics-customroots-customreadbarriers-and-customwritebarriers">
+<h3><a class="toc-backref" href="#id25">Custom lowering of intrinsics: <tt class="docutils literal"><span class="pre">CustomRoots</span></tt>, <tt class="docutils literal"><span class="pre">CustomReadBarriers</span></tt>, and <tt class="docutils literal"><span class="pre">CustomWriteBarriers</span></tt></a><a class="headerlink" href="#custom-lowering-of-intrinsics-customroots-customreadbarriers-and-customwritebarriers" title="Permalink to this headline">¶</a></h3>
+<p>For GCs which use barriers or unusual treatment of stack roots, these
+flags allow the collector to perform arbitrary transformations of the
+LLVM IR:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">class</span> <span class="nc">MyGC</span> <span class="o">:</span> <span class="k">public</span> <span class="n">GCStrategy</span> <span class="p">{</span>
+<span class="k">public</span><span class="o">:</span>
+ <span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">CustomRoots</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="n">CustomReadBarriers</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="n">CustomWriteBarriers</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">};</span>
+</pre></div>
+</div>
+<p>If any of these flags are set, LLVM suppresses its default lowering for
+the corresponding intrinsics. Instead, you must provide a custom Pass
+which lowers the intrinsics as desired. If you have opted in to custom
+lowering of a particular intrinsic your pass <strong>must</strong> eliminate all
+instances of the corresponding intrinsic in functions which opt in to
+your GC. The best example of such a pass is the ShadowStackGC and it’s
+ShadowStackGCLowering pass.</p>
+<p>There is currently no way to register such a custom lowering pass
+without building a custom copy of LLVM.</p>
+</div>
+<div class="section" id="generating-safe-points-neededsafepoints">
+<span id="safe-points"></span><h3><a class="toc-backref" href="#id26">Generating safe points: <tt class="docutils literal"><span class="pre">NeededSafePoints</span></tt></a><a class="headerlink" href="#generating-safe-points-neededsafepoints" title="Permalink to this headline">¶</a></h3>
+<p>LLVM can compute four kinds of safe points:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">namespace</span> <span class="n">GC</span> <span class="p">{</span>
+ <span class="c1">/// PointKind - The type of a collector-safe point.</span>
+ <span class="c1">///</span>
+ <span class="k">enum</span> <span class="n">PointKind</span> <span class="p">{</span>
+ <span class="n">Loop</span><span class="p">,</span> <span class="c1">//< Instr is a loop (backwards branch).</span>
+ <span class="n">Return</span><span class="p">,</span> <span class="c1">//< Instr is a return instruction.</span>
+ <span class="n">PreCall</span><span class="p">,</span> <span class="c1">//< Instr is a call instruction.</span>
+ <span class="n">PostCall</span> <span class="c1">//< Instr is the return address of a call.</span>
+ <span class="p">};</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>A collector can request any combination of the four by setting the
+<tt class="docutils literal"><span class="pre">NeededSafePoints</span></tt> mask:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">NeededSafePoints</span> <span class="o">=</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">Loop</span>
+ <span class="o">|</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">Return</span>
+ <span class="o">|</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">PreCall</span>
+ <span class="o">|</span> <span class="mi">1</span> <span class="o"><<</span> <span class="n">GC</span><span class="o">::</span><span class="n">PostCall</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>It can then use the following routines to access safe points.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">I</span> <span class="o">=</span> <span class="n">begin</span><span class="p">(),</span> <span class="n">E</span> <span class="o">=</span> <span class="n">end</span><span class="p">();</span> <span class="n">I</span> <span class="o">!=</span> <span class="n">E</span><span class="p">;</span> <span class="o">++</span><span class="n">I</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GCFunctionInfo</span> <span class="o">*</span><span class="n">MD</span> <span class="o">=</span> <span class="o">*</span><span class="n">I</span><span class="p">;</span>
+ <span class="n">size_t</span> <span class="n">PointCount</span> <span class="o">=</span> <span class="n">MD</span><span class="o">-></span><span class="n">size</span><span class="p">();</span>
+
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="o">-></span><span class="n">begin</span><span class="p">(),</span>
+ <span class="n">PE</span> <span class="o">=</span> <span class="n">MD</span><span class="o">-></span><span class="n">end</span><span class="p">();</span> <span class="n">PI</span> <span class="o">!=</span> <span class="n">PE</span><span class="p">;</span> <span class="o">++</span><span class="n">PI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GC</span><span class="o">::</span><span class="n">PointKind</span> <span class="n">PointKind</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Kind</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">PointNum</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Num</span><span class="p">;</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Almost every collector requires <tt class="docutils literal"><span class="pre">PostCall</span></tt> safe points, since these correspond
+to the moments when the function is suspended during a call to a subroutine.</p>
+<p>Threaded programs generally require <tt class="docutils literal"><span class="pre">Loop</span></tt> safe points to guarantee that the
+application will reach a safe point within a bounded amount of time, even if it
+is executing a long-running loop which contains no function calls.</p>
+<p>Threaded collectors may also require <tt class="docutils literal"><span class="pre">Return</span></tt> and <tt class="docutils literal"><span class="pre">PreCall</span></tt> safe points to
+implement “stop the world” techniques using self-modifying code, where it is
+important that the program not exit the function without reaching a safe point
+(because only the topmost function has been patched).</p>
+</div>
+<div class="section" id="emitting-assembly-code-gcmetadataprinter">
+<span id="assembly"></span><h3><a class="toc-backref" href="#id27">Emitting assembly code: <tt class="docutils literal"><span class="pre">GCMetadataPrinter</span></tt></a><a class="headerlink" href="#emitting-assembly-code-gcmetadataprinter" title="Permalink to this headline">¶</a></h3>
+<p>LLVM allows a plugin to print arbitrary assembly code before and after the rest
+of a module’s assembly code. At the end of the module, the GC can compile the
+LLVM stack map into assembly code. (At the beginning, this information is not
+yet computed.)</p>
+<p>Since AsmWriter and CodeGen are separate components of LLVM, a separate abstract
+base class and registry is provided for printing assembly code, the
+<tt class="docutils literal"><span class="pre">GCMetadaPrinter</span></tt> and <tt class="docutils literal"><span class="pre">GCMetadataPrinterRegistry</span></tt>. The AsmWriter will look
+for such a subclass if the <tt class="docutils literal"><span class="pre">GCStrategy</span></tt> sets <tt class="docutils literal"><span class="pre">UsesMetadata</span></tt>:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">MyGC</span><span class="o">::</span><span class="n">MyGC</span><span class="p">()</span> <span class="p">{</span>
+ <span class="n">UsesMetadata</span> <span class="o">=</span> <span class="kc">true</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>This separation allows JIT-only clients to be smaller.</p>
+<p>Note that LLVM does not currently have analogous APIs to support code generation
+in the JIT, nor using the object writers.</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">// lib/MyGC/MyGCPrinter.cpp - Example LLVM GC printer</span>
+
+<span class="cp">#include "llvm/CodeGen/GCMetadataPrinter.h"</span>
+<span class="cp">#include "llvm/Support/Compiler.h"</span>
+
+<span class="k">using</span> <span class="k">namespace</span> <span class="n">llvm</span><span class="p">;</span>
+
+<span class="k">namespace</span> <span class="p">{</span>
+ <span class="k">class</span> <span class="nc">LLVM_LIBRARY_VISIBILITY</span> <span class="n">MyGCPrinter</span> <span class="o">:</span> <span class="k">public</span> <span class="n">GCMetadataPrinter</span> <span class="p">{</span>
+ <span class="k">public</span><span class="o">:</span>
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">beginAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">);</span>
+
+ <span class="k">virtual</span> <span class="kt">void</span> <span class="n">finishAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">);</span>
+ <span class="p">};</span>
+
+ <span class="n">GCMetadataPrinterRegistry</span><span class="o">::</span><span class="n">Add</span><span class="o"><</span><span class="n">MyGCPrinter</span><span class="o">></span>
+ <span class="n">X</span><span class="p">(</span><span class="s">"mygc"</span><span class="p">,</span> <span class="s">"My bespoke garbage collector."</span><span class="p">);</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>The collector should use <tt class="docutils literal"><span class="pre">AsmPrinter</span></tt> to print portable assembly code. The
+collector itself contains the stack map for the entire module, and may access
+the <tt class="docutils literal"><span class="pre">GCFunctionInfo</span></tt> using its own <tt class="docutils literal"><span class="pre">begin()</span></tt> and <tt class="docutils literal"><span class="pre">end()</span></tt> methods. Here’s
+a realistic example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="cp">#include "llvm/CodeGen/AsmPrinter.h"</span>
+<span class="cp">#include "llvm/IR/Function.h"</span>
+<span class="cp">#include "llvm/IR/DataLayout.h"</span>
+<span class="cp">#include "llvm/Target/TargetAsmInfo.h"</span>
+<span class="cp">#include "llvm/Target/TargetMachine.h"</span>
+
+<span class="kt">void</span> <span class="n">MyGCPrinter</span><span class="o">::</span><span class="n">beginAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Nothing to do.</span>
+<span class="p">}</span>
+
+<span class="kt">void</span> <span class="n">MyGCPrinter</span><span class="o">::</span><span class="n">finishAssembly</span><span class="p">(</span><span class="n">AsmPrinter</span> <span class="o">&</span><span class="n">AP</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">MCStreamer</span> <span class="o">&</span><span class="n">OS</span> <span class="o">=</span> <span class="n">AP</span><span class="p">.</span><span class="n">OutStreamer</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">IntPtrSize</span> <span class="o">=</span> <span class="n">AP</span><span class="p">.</span><span class="n">getPointerSize</span><span class="p">();</span>
+
+ <span class="c1">// Put this in the data section.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">SwitchSection</span><span class="p">(</span><span class="n">AP</span><span class="p">.</span><span class="n">getObjFileLowering</span><span class="p">().</span><span class="n">getDataSection</span><span class="p">());</span>
+
+ <span class="c1">// For each function...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">iterator</span> <span class="n">FI</span> <span class="o">=</span> <span class="n">begin</span><span class="p">(),</span> <span class="n">FE</span> <span class="o">=</span> <span class="n">end</span><span class="p">();</span> <span class="n">FI</span> <span class="o">!=</span> <span class="n">FE</span><span class="p">;</span> <span class="o">++</span><span class="n">FI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">GCFunctionInfo</span> <span class="o">&</span><span class="n">MD</span> <span class="o">=</span> <span class="o">**</span><span class="n">FI</span><span class="p">;</span>
+
+ <span class="c1">// A compact GC layout. Emit this data structure:</span>
+ <span class="c1">//</span>
+ <span class="c1">// struct {</span>
+ <span class="c1">// int32_t PointCount;</span>
+ <span class="c1">// void *SafePointAddress[PointCount];</span>
+ <span class="c1">// int32_t StackFrameSize; // in words</span>
+ <span class="c1">// int32_t StackArity;</span>
+ <span class="c1">// int32_t LiveCount;</span>
+ <span class="c1">// int32_t LiveOffsets[LiveCount];</span>
+ <span class="c1">// } __gcmap_<FUNCTIONNAME>;</span>
+
+ <span class="c1">// Align to address width.</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitAlignment</span><span class="p">(</span><span class="n">IntPtrSize</span> <span class="o">==</span> <span class="mi">4</span> <span class="o">?</span> <span class="mi">2</span> <span class="o">:</span> <span class="mi">3</span><span class="p">);</span>
+
+ <span class="c1">// Emit PointCount.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"safe point count"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">size</span><span class="p">());</span>
+
+ <span class="c1">// And each safe point...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">begin</span><span class="p">(),</span>
+ <span class="n">PE</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">end</span><span class="p">();</span> <span class="n">PI</span> <span class="o">!=</span> <span class="n">PE</span><span class="p">;</span> <span class="o">++</span><span class="n">PI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Emit the address of the safe point.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"safe point address"</span><span class="p">);</span>
+ <span class="n">MCSymbol</span> <span class="o">*</span><span class="n">Label</span> <span class="o">=</span> <span class="n">PI</span><span class="o">-></span><span class="n">Label</span><span class="p">;</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">EmitLabelPlusOffset</span><span class="p">(</span><span class="n">Label</span><span class="cm">/*Hi*/</span><span class="p">,</span> <span class="mi">0</span><span class="cm">/*Offset*/</span><span class="p">,</span> <span class="mi">4</span><span class="cm">/*Size*/</span><span class="p">);</span>
+ <span class="p">}</span>
+
+ <span class="c1">// Stack information never change in safe points! Only print info from the</span>
+ <span class="c1">// first call-site.</span>
+ <span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">iterator</span> <span class="n">PI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">begin</span><span class="p">();</span>
+
+ <span class="c1">// Emit the stack frame size.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack frame size (in words)"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">getFrameSize</span><span class="p">()</span> <span class="o">/</span> <span class="n">IntPtrSize</span><span class="p">);</span>
+
+ <span class="c1">// Emit stack arity, i.e. the number of stacked arguments.</span>
+ <span class="kt">unsigned</span> <span class="n">RegisteredArgs</span> <span class="o">=</span> <span class="n">IntPtrSize</span> <span class="o">==</span> <span class="mi">4</span> <span class="o">?</span> <span class="mi">5</span> <span class="o">:</span> <span class="mi">6</span><span class="p">;</span>
+ <span class="kt">unsigned</span> <span class="n">StackArity</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">getFunction</span><span class="p">().</span><span class="n">arg_size</span><span class="p">()</span> <span class="o">></span> <span class="n">RegisteredArgs</span> <span class="o">?</span>
+ <span class="n">MD</span><span class="p">.</span><span class="n">getFunction</span><span class="p">().</span><span class="n">arg_size</span><span class="p">()</span> <span class="o">-</span> <span class="n">RegisteredArgs</span> <span class="o">:</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack arity"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">StackArity</span><span class="p">);</span>
+
+ <span class="c1">// Emit the number of live roots in the function.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"live root count"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">MD</span><span class="p">.</span><span class="n">live_size</span><span class="p">(</span><span class="n">PI</span><span class="p">));</span>
+
+ <span class="c1">// And for each live root...</span>
+ <span class="k">for</span> <span class="p">(</span><span class="n">GCFunctionInfo</span><span class="o">::</span><span class="n">live_iterator</span> <span class="n">LI</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">live_begin</span><span class="p">(</span><span class="n">PI</span><span class="p">),</span>
+ <span class="n">LE</span> <span class="o">=</span> <span class="n">MD</span><span class="p">.</span><span class="n">live_end</span><span class="p">(</span><span class="n">PI</span><span class="p">);</span>
+ <span class="n">LI</span> <span class="o">!=</span> <span class="n">LE</span><span class="p">;</span> <span class="o">++</span><span class="n">LI</span><span class="p">)</span> <span class="p">{</span>
+ <span class="c1">// Emit live root's offset within the stack frame.</span>
+ <span class="n">OS</span><span class="p">.</span><span class="n">AddComment</span><span class="p">(</span><span class="s">"stack index (offset / wordsize)"</span><span class="p">);</span>
+ <span class="n">AP</span><span class="p">.</span><span class="n">emitInt32</span><span class="p">(</span><span class="n">LI</span><span class="o">-></span><span class="n">StackOffset</span><span class="p">);</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+</div>
+<div class="section" id="references">
+<h2><a class="toc-backref" href="#id28">References</a><a class="headerlink" href="#references" title="Permalink to this headline">¶</a></h2>
+<p id="appel89">[Appel89] Runtime Tags Aren’t Necessary. Andrew W. Appel. Lisp and Symbolic
+Computation 19(7):703-705, July 1989.</p>
+<p id="goldberg91">[Goldberg91] Tag-free garbage collection for strongly typed programming
+languages. Benjamin Goldberg. ACM SIGPLAN PLDI‘91.</p>
+<p id="tolmach94">[Tolmach94] Tag-free garbage collection using explicit type parameters. Andrew
+Tolmach. Proceedings of the 1994 ACM conference on LISP and functional
+programming.</p>
+<p id="henderson02">[Henderson2002] <a class="reference external" href="http://citeseer.ist.psu.edu/henderson02accurate.html">Accurate Garbage Collection in an Uncooperative Environment</a></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="WritingAnLLVMPass.html" title="Writing an LLVM Pass"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="HowToUseInstrMappings.html" title="How To Use Instruction Mappings"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/7.0.1/docs/GetElementPtr.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/7.0.1/docs/GetElementPtr.html?rev=349965&view=auto
==============================================================================
--- www-releases/trunk/7.0.1/docs/GetElementPtr.html (added)
+++ www-releases/trunk/7.0.1/docs/GetElementPtr.html Fri Dec 21 13:53:02 2018
@@ -0,0 +1,572 @@
+
+
+<!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 Often Misunderstood GEP Instruction — LLVM 7 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: '7',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true
+ };
+ </script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="top" title="LLVM 7 documentation" href="index.html" />
+ <link rel="next" title="Performance Tips for Frontend Authors" href="Frontend/PerformanceTips.html" />
+ <link rel="prev" title="YAML I/O" href="YamlIO.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head>
+ <body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="YamlIO.html" title="YAML I/O"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body">
+
+ <div class="section" id="the-often-misunderstood-gep-instruction">
+<h1>The Often Misunderstood GEP Instruction<a class="headerlink" href="#the-often-misunderstood-gep-instruction" 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="#address-computation" id="id3">Address Computation</a><ul>
+<li><a class="reference internal" href="#what-is-the-first-index-of-the-gep-instruction" id="id4">What is the first index of the GEP instruction?</a></li>
+<li><a class="reference internal" href="#why-is-the-extra-0-index-required" id="id5">Why is the extra 0 index required?</a></li>
+<li><a class="reference internal" href="#what-is-dereferenced-by-gep" id="id6">What is dereferenced by GEP?</a></li>
+<li><a class="reference internal" href="#why-don-t-gep-x-0-0-1-and-gep-x-1-alias" id="id7">Why don’t GEP x,0,0,1 and GEP x,1 alias?</a></li>
+<li><a class="reference internal" href="#why-do-gep-x-1-0-0-and-gep-x-1-alias" id="id8">Why do GEP x,1,0,0 and GEP x,1 alias?</a></li>
+<li><a class="reference internal" href="#can-gep-index-into-vector-elements" id="id9">Can GEP index into vector elements?</a></li>
+<li><a class="reference internal" href="#what-effect-do-address-spaces-have-on-geps" id="id10">What effect do address spaces have on GEPs?</a></li>
+<li><a class="reference internal" href="#how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr" id="id11">How is GEP different from <tt class="docutils literal"><span class="pre">ptrtoint</span></tt>, arithmetic, and <tt class="docutils literal"><span class="pre">inttoptr</span></tt>?</a></li>
+<li><a class="reference internal" href="#i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this" id="id12">I’m writing a backend for a target which needs custom lowering for GEP. How do I do this?</a></li>
+<li><a class="reference internal" href="#how-does-vla-addressing-work-with-geps" id="id13">How does VLA addressing work with GEPs?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rules" id="id14">Rules</a><ul>
+<li><a class="reference internal" href="#what-happens-if-an-array-index-is-out-of-bounds" id="id15">What happens if an array index is out of bounds?</a></li>
+<li><a class="reference internal" href="#can-array-indices-be-negative" id="id16">Can array indices be negative?</a></li>
+<li><a class="reference internal" href="#can-i-compare-two-values-computed-with-geps" id="id17">Can I compare two values computed with GEPs?</a></li>
+<li><a class="reference internal" href="#can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object" id="id18">Can I do GEP with a different pointer type than the type of the underlying object?</a></li>
+<li><a class="reference internal" href="#can-i-cast-an-object-s-address-to-integer-and-add-it-to-null" id="id19">Can I cast an object’s address to integer and add it to null?</a></li>
+<li><a class="reference internal" href="#can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address" id="id20">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a></li>
+<li><a class="reference internal" href="#can-i-do-type-based-alias-analysis-on-llvm-ir" id="id21">Can I do type-based alias analysis on LLVM IR?</a></li>
+<li><a class="reference internal" href="#what-happens-if-a-gep-computation-overflows" id="id22">What happens if a GEP computation overflows?</a></li>
+<li><a class="reference internal" href="#how-can-i-tell-if-my-front-end-is-following-the-rules" id="id23">How can I tell if my front-end is following the rules?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#rationale" id="id24">Rationale</a><ul>
+<li><a class="reference internal" href="#why-is-gep-designed-this-way" id="id25">Why is GEP designed this way?</a></li>
+<li><a class="reference internal" href="#why-do-struct-member-indices-always-use-i32" id="id26">Why do struct member indices always use <tt class="docutils literal"><span class="pre">i32</span></tt>?</a></li>
+<li><a class="reference internal" href="#what-s-an-uglygep" id="id27">What’s an uglygep?</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#summary" id="id28">Summary</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id2">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document seeks to dispel the mystery and confusion surrounding LLVM’s
+<a class="reference external" href="LangRef.html#getelementptr-instruction">GetElementPtr</a> (GEP) instruction.
+Questions about the wily GEP instruction are probably the most frequently
+occurring questions once a developer gets down to coding with LLVM. Here we lay
+out the sources of confusion and show that the GEP instruction is really quite
+simple.</p>
+</div>
+<div class="section" id="address-computation">
+<h2><a class="toc-backref" href="#id3">Address Computation</a><a class="headerlink" href="#address-computation" title="Permalink to this headline">¶</a></h2>
+<p>When people are first confronted with the GEP instruction, they tend to relate
+it to known concepts from other programming paradigms, most notably C array
+indexing and field selection. GEP closely resembles C array indexing and field
+selection, however it is a little different and this leads to the following
+questions.</p>
+<div class="section" id="what-is-the-first-index-of-the-gep-instruction">
+<h3><a class="toc-backref" href="#id4">What is the first index of the GEP instruction?</a><a class="headerlink" href="#what-is-the-first-index-of-the-gep-instruction" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: The index stepping through the second operand.</p>
+<p>The confusion with the first index usually arises from thinking about the
+GetElementPtr instruction as if it was a C index operator. They aren’t the
+same. For example, when we write, in “C”:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">AType</span> <span class="o">*</span><span class="n">Foo</span><span class="p">;</span>
+<span class="p">...</span>
+<span class="n">X</span> <span class="o">=</span> <span class="o">&</span><span class="n">Foo</span><span class="o">-></span><span class="n">F</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>it is natural to think that there is only one index, the selection of the field
+<tt class="docutils literal"><span class="pre">F</span></tt>. However, in this example, <tt class="docutils literal"><span class="pre">Foo</span></tt> is a pointer. That pointer
+must be indexed explicitly in LLVM. C, on the other hand, indices through it
+transparently. To arrive at the same address location as the C code, you would
+provide the GEP instruction with two index operands. The first operand indexes
+through the pointer; the second operand indexes the field <tt class="docutils literal"><span class="pre">F</span></tt> of the
+structure, just as if you wrote:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">X</span> <span class="o">=</span> <span class="o">&</span><span class="n">Foo</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">F</span><span class="p">;</span>
+</pre></div>
+</div>
+<p>Sometimes this question gets rephrased as:</p>
+<blockquote id="gep-index-through-first-pointer">
+<div><em>Why is it okay to index through the first pointer, but subsequent pointers
+won’t be dereferenced?</em></div></blockquote>
+<p>The answer is simply because memory does not have to be accessed to perform the
+computation. The second operand to the GEP instruction must be a value of a
+pointer type. The value of the pointer is provided directly to the GEP
+instruction as an operand without any need for accessing memory. It must,
+therefore be indexed and requires an index operand. Consider this example:</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="k">struct</span> <span class="n">munger_struct</span> <span class="p">{</span>
+ <span class="kt">int</span> <span class="n">f1</span><span class="p">;</span>
+ <span class="kt">int</span> <span class="n">f2</span><span class="p">;</span>
+<span class="p">};</span>
+<span class="kt">void</span> <span class="n">munge</span><span class="p">(</span><span class="k">struct</span> <span class="n">munger_struct</span> <span class="o">*</span><span class="n">P</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">P</span><span class="p">[</span><span class="mi">0</span><span class="p">].</span><span class="n">f1</span> <span class="o">=</span> <span class="n">P</span><span class="p">[</span><span class="mi">1</span><span class="p">].</span><span class="n">f1</span> <span class="o">+</span> <span class="n">P</span><span class="p">[</span><span class="mi">2</span><span class="p">].</span><span class="n">f2</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="p">...</span>
+<span class="n">munger_struct</span> <span class="n">Array</span><span class="p">[</span><span class="mi">3</span><span class="p">];</span>
+<span class="p">...</span>
+<span class="n">munge</span><span class="p">(</span><span class="n">Array</span><span class="p">);</span>
+</pre></div>
+</div>
+<p>In this “C” example, the front end compiler (Clang) will generate three GEP
+instructions for the three indices through “P” in the assignment statement. The
+function argument <tt class="docutils literal"><span class="pre">P</span></tt> will be the second operand of each of these GEP
+instructions. The third operand indexes through that pointer. The fourth
+operand will be the field offset into the <tt class="docutils literal"><span class="pre">struct</span> <span class="pre">munger_struct</span></tt> type, for
+either the <tt class="docutils literal"><span class="pre">f1</span></tt> or <tt class="docutils literal"><span class="pre">f2</span></tt> field. So, in LLVM assembly the <tt class="docutils literal"><span class="pre">munge</span></tt> function
+looks like:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="kt">void</span> <span class="nv">%munge</span><span class="p">(</span><span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">,</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</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">0</span>
+ <span class="nv">%tmp</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp</span>
+ <span class="nv">%tmp6</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">,</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%P</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">1</span>
+ <span class="nv">%tmp7</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp6</span>
+ <span class="nv">%tmp8</span> <span class="p">=</span> <span class="k">add</span> <span class="k">i32</span> <span class="nv">%tmp7</span><span class="p">,</span> <span class="nv">%tmp</span>
+ <span class="nv">%tmp9</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="nv">%struct.munger_struct</span><span class="p">,</span> <span class="nv">%struct.munger_struct</span><span class="p">*</span> <span class="nv">%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">0</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%tmp8</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%tmp9</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>In each case the second operand is the pointer through which the GEP instruction
+starts. The same is true whether the second operand is an argument, allocated
+memory, or a global variable.</p>
+<p>To make this clear, let’s consider a more obtuse example:</p>
+<div class="highlight-text"><div class="highlight"><pre>%MyVar = uninitialized global i32
+...
+%idx1 = getelementptr i32, i32* %MyVar, i64 0
+%idx2 = getelementptr i32, i32* %MyVar, i64 1
+%idx3 = getelementptr i32, i32* %MyVar, i64 2
+</pre></div>
+</div>
+<p>These GEP instructions are simply making address computations from the base
+address of <tt class="docutils literal"><span class="pre">MyVar</span></tt>. They compute, as follows (using C syntax):</p>
+<div class="highlight-c++"><div class="highlight"><pre><span class="n">idx1</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">0</span>
+<span class="n">idx2</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">4</span>
+<span class="n">idx3</span> <span class="o">=</span> <span class="p">(</span><span class="kt">char</span><span class="o">*</span><span class="p">)</span> <span class="o">&</span><span class="n">MyVar</span> <span class="o">+</span> <span class="mi">8</span>
+</pre></div>
+</div>
+<p>Since the type <tt class="docutils literal"><span class="pre">i32</span></tt> is known to be four bytes long, the indices 0, 1 and 2
+translate into memory offsets of 0, 4, and 8, respectively. No memory is
+accessed to make these computations because the address of <tt class="docutils literal"><span class="pre">%MyVar</span></tt> is passed
+directly to the GEP instructions.</p>
+<p>The obtuse part of this example is in the cases of <tt class="docutils literal"><span class="pre">%idx2</span></tt> and <tt class="docutils literal"><span class="pre">%idx3</span></tt>. They
+result in the computation of addresses that point to memory past the end of the
+<tt class="docutils literal"><span class="pre">%MyVar</span></tt> global, which is only one <tt class="docutils literal"><span class="pre">i32</span></tt> long, not three <tt class="docutils literal"><span class="pre">i32</span></tt>s long.
+While this is legal in LLVM, it is inadvisable because any load or store with
+the pointer that results from these GEP instructions would produce undefined
+results.</p>
+</div>
+<div class="section" id="why-is-the-extra-0-index-required">
+<h3><a class="toc-backref" href="#id5">Why is the extra 0 index required?</a><a class="headerlink" href="#why-is-the-extra-0-index-required" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: there are no superfluous indices.</p>
+<p>This question arises most often when the GEP instruction is applied to a global
+variable which is always a pointer type. For example, consider this:</p>
+<div class="highlight-text"><div class="highlight"><pre>%MyStruct = uninitialized global { float*, i32 }
+...
+%idx = getelementptr { float*, i32 }, { float*, i32 }* %MyStruct, i64 0, i32 1
+</pre></div>
+</div>
+<p>The GEP above yields an <tt class="docutils literal"><span class="pre">i32*</span></tt> by indexing the <tt class="docutils literal"><span class="pre">i32</span></tt> typed field of the
+structure <tt class="docutils literal"><span class="pre">%MyStruct</span></tt>. When people first look at it, they wonder why the <tt class="docutils literal"><span class="pre">i64</span>
+<span class="pre">0</span></tt> index is needed. However, a closer inspection of how globals and GEPs work
+reveals the need. Becoming aware of the following facts will dispel the
+confusion:</p>
+<ol class="arabic simple">
+<li>The type of <tt class="docutils literal"><span class="pre">%MyStruct</span></tt> is <em>not</em> <tt class="docutils literal"><span class="pre">{</span> <span class="pre">float*,</span> <span class="pre">i32</span> <span class="pre">}</span></tt> but rather <tt class="docutils literal"><span class="pre">{</span> <span class="pre">float*,</span>
+<span class="pre">i32</span> <span class="pre">}*</span></tt>. That is, <tt class="docutils literal"><span class="pre">%MyStruct</span></tt> is a pointer to a structure containing a
+pointer to a <tt class="docutils literal"><span class="pre">float</span></tt> and an <tt class="docutils literal"><span class="pre">i32</span></tt>.</li>
+<li>Point #1 is evidenced by noticing the type of the second operand of the GEP
+instruction (<tt class="docutils literal"><span class="pre">%MyStruct</span></tt>) which is <tt class="docutils literal"><span class="pre">{</span> <span class="pre">float*,</span> <span class="pre">i32</span> <span class="pre">}*</span></tt>.</li>
+<li>The first index, <tt class="docutils literal"><span class="pre">i64</span> <span class="pre">0</span></tt> is required to step over the global variable
+<tt class="docutils literal"><span class="pre">%MyStruct</span></tt>. Since the second argument to the GEP instruction must always
+be a value of pointer type, the first index steps through that pointer. A
+value of 0 means 0 elements offset from that pointer.</li>
+<li>The second index, <tt class="docutils literal"><span class="pre">i32</span> <span class="pre">1</span></tt> selects the second field of the structure (the
+<tt class="docutils literal"><span class="pre">i32</span></tt>).</li>
+</ol>
+</div>
+<div class="section" id="what-is-dereferenced-by-gep">
+<h3><a class="toc-backref" href="#id6">What is dereferenced by GEP?</a><a class="headerlink" href="#what-is-dereferenced-by-gep" title="Permalink to this headline">¶</a></h3>
+<p>Quick answer: nothing.</p>
+<p>The GetElementPtr instruction dereferences nothing. That is, it doesn’t access
+memory in any way. That’s what the Load and Store instructions are for. GEP is
+only involved in the computation of addresses. For example, consider this:</p>
+<div class="highlight-text"><div class="highlight"><pre>%MyVar = uninitialized global { [40 x i32 ]* }
+...
+%idx = getelementptr { [40 x i32]* }, { [40 x i32]* }* %MyVar, i64 0, i32 0, i64 0, i64 17
+</pre></div>
+</div>
+<p>In this example, we have a global variable, <tt class="docutils literal"><span class="pre">%MyVar</span></tt> that is a pointer to a
+structure containing a pointer to an array of 40 ints. The GEP instruction seems
+to be accessing the 18th integer of the structure’s array of ints. However, this
+is actually an illegal GEP instruction. It won’t compile. The reason is that the
+pointer in the structure <em>must</em> be dereferenced in order to index into the
+array of 40 ints. Since the GEP instruction never accesses memory, it is
+illegal.</p>
+<p>In order to access the 18th integer in the array, you would need to do the
+following:</p>
+<div class="highlight-text"><div class="highlight"><pre>%idx = getelementptr { [40 x i32]* }, { [40 x i32]* }* %, i64 0, i32 0
+%arr = load [40 x i32]** %idx
+%idx = getelementptr [40 x i32], [40 x i32]* %arr, i64 0, i64 17
+</pre></div>
+</div>
+<p>In this case, we have to load the pointer in the structure with a load
+instruction before we can index into the array. If the example was changed to:</p>
+<div class="highlight-text"><div class="highlight"><pre>%MyVar = uninitialized global { [40 x i32 ] }
+...
+%idx = getelementptr { [40 x i32] }, { [40 x i32] }*, i64 0, i32 0, i64 17
+</pre></div>
+</div>
+<p>then everything works fine. In this case, the structure does not contain a
+pointer and the GEP instruction can index through the global variable, into the
+first field of the structure and access the 18th <tt class="docutils literal"><span class="pre">i32</span></tt> in the array there.</p>
+</div>
+<div class="section" id="why-don-t-gep-x-0-0-1-and-gep-x-1-alias">
+<h3><a class="toc-backref" href="#id7">Why don’t GEP x,0,0,1 and GEP x,1 alias?</a><a class="headerlink" href="#why-don-t-gep-x-0-0-1-and-gep-x-1-alias" title="Permalink to this headline">¶</a></h3>
+<p>Quick Answer: They compute different address locations.</p>
+<p>If you look at the first indices in these GEP instructions you find that they
+are different (0 and 1), therefore the address computation diverges with that
+index. Consider this example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%MyVar</span> <span class="p">=</span> <span class="k">global</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}</span>
+<span class="nv">%idx1</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+<span class="nv">%idx2</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>In this example, <tt class="docutils literal"><span class="pre">idx1</span></tt> computes the address of the second integer in the
+array that is in the structure in <tt class="docutils literal"><span class="pre">%MyVar</span></tt>, that is <tt class="docutils literal"><span class="pre">MyVar+4</span></tt>. The type of
+<tt class="docutils literal"><span class="pre">idx1</span></tt> is <tt class="docutils literal"><span class="pre">i32*</span></tt>. However, <tt class="docutils literal"><span class="pre">idx2</span></tt> computes the address of <em>the next</em>
+structure after <tt class="docutils literal"><span class="pre">%MyVar</span></tt>. The type of <tt class="docutils literal"><span class="pre">idx2</span></tt> is <tt class="docutils literal"><span class="pre">{</span> <span class="pre">[10</span> <span class="pre">x</span> <span class="pre">i32]</span> <span class="pre">}*</span></tt> and its
+value is equivalent to <tt class="docutils literal"><span class="pre">MyVar</span> <span class="pre">+</span> <span class="pre">40</span></tt> because it indexes past the ten 4-byte
+integers in <tt class="docutils literal"><span class="pre">MyVar</span></tt>. Obviously, in such a situation, the pointers don’t
+alias.</p>
+</div>
+<div class="section" id="why-do-gep-x-1-0-0-and-gep-x-1-alias">
+<h3><a class="toc-backref" href="#id8">Why do GEP x,1,0,0 and GEP x,1 alias?</a><a class="headerlink" href="#why-do-gep-x-1-0-0-and-gep-x-1-alias" title="Permalink to this headline">¶</a></h3>
+<p>Quick Answer: They compute the same address location.</p>
+<p>These two GEP instructions will compute the same address because indexing
+through the 0th element does not change the address. However, it does change the
+type. Consider this example:</p>
+<div class="highlight-llvm"><div class="highlight"><pre><span class="nv">%MyVar</span> <span class="p">=</span> <span class="k">global</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}</span>
+<span class="nv">%idx1</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i64</span> <span class="m">0</span>
+<span class="nv">%idx2</span> <span class="p">=</span> <span class="k">getelementptr</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">},</span> <span class="p">{</span> <span class="p">[</span><span class="m">10</span> <span class="k">x</span> <span class="k">i32</span><span class="p">]</span> <span class="p">}*</span> <span class="nv">%MyVar</span><span class="p">,</span> <span class="k">i64</span> <span class="m">1</span>
+</pre></div>
+</div>
+<p>In this example, the value of <tt class="docutils literal"><span class="pre">%idx1</span></tt> is <tt class="docutils literal"><span class="pre">%MyVar+40</span></tt> and its type is
+<tt class="docutils literal"><span class="pre">i32*</span></tt>. The value of <tt class="docutils literal"><span class="pre">%idx2</span></tt> is also <tt class="docutils literal"><span class="pre">MyVar+40</span></tt> but its type is <tt class="docutils literal"><span class="pre">{</span> <span class="pre">[10</span> <span class="pre">x</span>
+<span class="pre">i32]</span> <span class="pre">}*</span></tt>.</p>
+</div>
+<div class="section" id="can-gep-index-into-vector-elements">
+<h3><a class="toc-backref" href="#id9">Can GEP index into vector elements?</a><a class="headerlink" href="#can-gep-index-into-vector-elements" title="Permalink to this headline">¶</a></h3>
+<p>This hasn’t always been forcefully disallowed, though it’s not recommended. It
+leads to awkward special cases in the optimizers, and fundamental inconsistency
+in the IR. In the future, it will probably be outright disallowed.</p>
+</div>
+<div class="section" id="what-effect-do-address-spaces-have-on-geps">
+<h3><a class="toc-backref" href="#id10">What effect do address spaces have on GEPs?</a><a class="headerlink" href="#what-effect-do-address-spaces-have-on-geps" title="Permalink to this headline">¶</a></h3>
+<p>None, except that the address space qualifier on the second operand pointer type
+always matches the address space qualifier on the result type.</p>
+</div>
+<div class="section" id="how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr">
+<h3><a class="toc-backref" href="#id11">How is GEP different from <tt class="docutils literal"><span class="pre">ptrtoint</span></tt>, arithmetic, and <tt class="docutils literal"><span class="pre">inttoptr</span></tt>?</a><a class="headerlink" href="#how-is-gep-different-from-ptrtoint-arithmetic-and-inttoptr" title="Permalink to this headline">¶</a></h3>
+<p>It’s very similar; there are only subtle differences.</p>
+<p>With ptrtoint, you have to pick an integer type. One approach is to pick i64;
+this is safe on everything LLVM supports (LLVM internally assumes pointers are
+never wider than 64 bits in many places), and the optimizer will actually narrow
+the i64 arithmetic down to the actual pointer size on targets which don’t
+support 64-bit arithmetic in most cases. However, there are some cases where it
+doesn’t do this. With GEP you can avoid this problem.</p>
+<p>Also, GEP carries additional pointer aliasing rules. It’s invalid to take a GEP
+from one object, address into a different separately allocated object, and
+dereference it. IR producers (front-ends) must follow this rule, and consumers
+(optimizers, specifically alias analysis) benefit from being able to rely on
+it. See the <a class="reference internal" href="#rules">Rules</a> section for more information.</p>
+<p>And, GEP is more concise in common cases.</p>
+<p>However, for the underlying integer computation implied, there is no
+difference.</p>
+</div>
+<div class="section" id="i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this">
+<h3><a class="toc-backref" href="#id12">I’m writing a backend for a target which needs custom lowering for GEP. How do I do this?</a><a class="headerlink" href="#i-m-writing-a-backend-for-a-target-which-needs-custom-lowering-for-gep-how-do-i-do-this" title="Permalink to this headline">¶</a></h3>
+<p>You don’t. The integer computation implied by a GEP is target-independent.
+Typically what you’ll need to do is make your backend pattern-match expressions
+trees involving ADD, MUL, etc., which are what GEP is lowered into. This has the
+advantage of letting your code work correctly in more cases.</p>
+<p>GEP does use target-dependent parameters for the size and layout of data types,
+which targets can customize.</p>
+<p>If you require support for addressing units which are not 8 bits, you’ll need to
+fix a lot of code in the backend, with GEP lowering being only a small piece of
+the overall picture.</p>
+</div>
+<div class="section" id="how-does-vla-addressing-work-with-geps">
+<h3><a class="toc-backref" href="#id13">How does VLA addressing work with GEPs?</a><a class="headerlink" href="#how-does-vla-addressing-work-with-geps" title="Permalink to this headline">¶</a></h3>
+<p>GEPs don’t natively support VLAs. LLVM’s type system is entirely static, and GEP
+address computations are guided by an LLVM type.</p>
+<p>VLA indices can be implemented as linearized indices. For example, an expression
+like <tt class="docutils literal"><span class="pre">X[a][b][c]</span></tt>, must be effectively lowered into a form like
+<tt class="docutils literal"><span class="pre">X[a*m+b*n+c]</span></tt>, so that it appears to the GEP as a single-dimensional array
+reference.</p>
+<p>This means if you want to write an analysis which understands array indices and
+you want to support VLAs, your code will have to be prepared to reverse-engineer
+the linearization. One way to solve this problem is to use the ScalarEvolution
+library, which always presents VLA and non-VLA indexing in the same manner.</p>
+</div>
+</div>
+<div class="section" id="rules">
+<span id="id1"></span><h2><a class="toc-backref" href="#id14">Rules</a><a class="headerlink" href="#rules" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="what-happens-if-an-array-index-is-out-of-bounds">
+<h3><a class="toc-backref" href="#id15">What happens if an array index is out of bounds?</a><a class="headerlink" href="#what-happens-if-an-array-index-is-out-of-bounds" title="Permalink to this headline">¶</a></h3>
+<p>There are two senses in which an array index can be out of bounds.</p>
+<p>First, there’s the array type which comes from the (static) type of the first
+operand to the GEP. Indices greater than the number of elements in the
+corresponding static array type are valid. There is no problem with out of
+bounds indices in this sense. Indexing into an array only depends on the size of
+the array element, not the number of elements.</p>
+<p>A common example of how this is used is arrays where the size is not known.
+It’s common to use array types with zero length to represent these. The fact
+that the static type says there are zero elements is irrelevant; it’s perfectly
+valid to compute arbitrary element indices, as the computation only depends on
+the size of the array element, not the number of elements. Note that zero-sized
+arrays are not a special case here.</p>
+<p>This sense is unconnected with <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword. The <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword is
+designed to describe low-level pointer arithmetic overflow conditions, rather
+than high-level array indexing rules.</p>
+<p>Analysis passes which wish to understand array indexing should not assume that
+the static array type bounds are respected.</p>
+<p>The second sense of being out of bounds is computing an address that’s beyond
+the actual underlying allocated object.</p>
+<p>With the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, the result value of the GEP is undefined if the
+address is outside the actual underlying allocated object and not the address
+one-past-the-end.</p>
+<p>Without the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, there are no restrictions on computing
+out-of-bounds addresses. Obviously, performing a load or a store requires an
+address of allocated and sufficiently aligned memory. But the GEP itself is only
+concerned with computing addresses.</p>
+</div>
+<div class="section" id="can-array-indices-be-negative">
+<h3><a class="toc-backref" href="#id16">Can array indices be negative?</a><a class="headerlink" href="#can-array-indices-be-negative" title="Permalink to this headline">¶</a></h3>
+<p>Yes. This is basically a special case of array indices being out of bounds.</p>
+</div>
+<div class="section" id="can-i-compare-two-values-computed-with-geps">
+<h3><a class="toc-backref" href="#id17">Can I compare two values computed with GEPs?</a><a class="headerlink" href="#can-i-compare-two-values-computed-with-geps" title="Permalink to this headline">¶</a></h3>
+<p>Yes. If both addresses are within the same allocated object, or
+one-past-the-end, you’ll get the comparison result you expect. If either is
+outside of it, integer arithmetic wrapping may occur, so the comparison may not
+be meaningful.</p>
+</div>
+<div class="section" id="can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object">
+<h3><a class="toc-backref" href="#id18">Can I do GEP with a different pointer type than the type of the underlying object?</a><a class="headerlink" href="#can-i-do-gep-with-a-different-pointer-type-than-the-type-of-the-underlying-object" title="Permalink to this headline">¶</a></h3>
+<p>Yes. There are no restrictions on bitcasting a pointer value to an arbitrary
+pointer type. The types in a GEP serve only to define the parameters for the
+underlying integer computation. They need not correspond with the actual type of
+the underlying object.</p>
+<p>Furthermore, loads and stores don’t have to use the same types as the type of
+the underlying object. Types in this context serve only to specify memory size
+and alignment. Beyond that there are merely a hint to the optimizer indicating
+how the value will likely be used.</p>
+</div>
+<div class="section" id="can-i-cast-an-object-s-address-to-integer-and-add-it-to-null">
+<h3><a class="toc-backref" href="#id19">Can I cast an object’s address to integer and add it to null?</a><a class="headerlink" href="#can-i-cast-an-object-s-address-to-integer-and-add-it-to-null" title="Permalink to this headline">¶</a></h3>
+<p>You can compute an address that way, but if you use GEP to do the add, you can’t
+use that pointer to actually access the object, unless the object is managed
+outside of LLVM.</p>
+<p>The underlying integer computation is sufficiently defined; null has a defined
+value — zero — and you can add whatever value you want to it.</p>
+<p>However, it’s invalid to access (load from or store to) an LLVM-aware object
+with such a pointer. This includes <tt class="docutils literal"><span class="pre">GlobalVariables</span></tt>, <tt class="docutils literal"><span class="pre">Allocas</span></tt>, and objects
+pointed to by noalias pointers.</p>
+<p>If you really need this functionality, you can do the arithmetic with explicit
+integer instructions, and use inttoptr to convert the result to an address. Most
+of GEP’s special aliasing rules do not apply to pointers computed from ptrtoint,
+arithmetic, and inttoptr sequences.</p>
+</div>
+<div class="section" id="can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address">
+<h3><a class="toc-backref" href="#id20">Can I compute the distance between two objects, and add that value to one address to compute the other address?</a><a class="headerlink" href="#can-i-compute-the-distance-between-two-objects-and-add-that-value-to-one-address-to-compute-the-other-address" title="Permalink to this headline">¶</a></h3>
+<p>As with arithmetic on null, you can use GEP to compute an address that way, but
+you can’t use that pointer to actually access the object if you do, unless the
+object is managed outside of LLVM.</p>
+<p>Also as above, ptrtoint and inttoptr provide an alternative way to do this which
+do not have this restriction.</p>
+</div>
+<div class="section" id="can-i-do-type-based-alias-analysis-on-llvm-ir">
+<h3><a class="toc-backref" href="#id21">Can I do type-based alias analysis on LLVM IR?</a><a class="headerlink" href="#can-i-do-type-based-alias-analysis-on-llvm-ir" title="Permalink to this headline">¶</a></h3>
+<p>You can’t do type-based alias analysis using LLVM’s built-in type system,
+because LLVM has no restrictions on mixing types in addressing, loads or stores.</p>
+<p>LLVM’s type-based alias analysis pass uses metadata to describe a different type
+system (such as the C type system), and performs type-based aliasing on top of
+that. Further details are in the
+<a class="reference external" href="LangRef.html#tbaa-metadata">language reference</a>.</p>
+</div>
+<div class="section" id="what-happens-if-a-gep-computation-overflows">
+<h3><a class="toc-backref" href="#id22">What happens if a GEP computation overflows?</a><a class="headerlink" href="#what-happens-if-a-gep-computation-overflows" title="Permalink to this headline">¶</a></h3>
+<p>If the GEP lacks the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, the value is the result from
+evaluating the implied two’s complement integer computation. However, since
+there’s no guarantee of where an object will be allocated in the address space,
+such values have limited meaning.</p>
+<p>If the GEP has the <tt class="docutils literal"><span class="pre">inbounds</span></tt> keyword, the result value is undefined (a “trap
+value”) if the GEP overflows (i.e. wraps around the end of the address space).</p>
+<p>As such, there are some ramifications of this for inbounds GEPs: scales implied
+by array/vector/pointer indices are always known to be “nsw” since they are
+signed values that are scaled by the element size. These values are also
+allowed to be negative (e.g. “<tt class="docutils literal"><span class="pre">gep</span> <span class="pre">i32</span> <span class="pre">*%P,</span> <span class="pre">i32</span> <span class="pre">-1</span></tt>”) but the pointer itself
+is logically treated as an unsigned value. This means that GEPs have an
+asymmetric relation between the pointer base (which is treated as unsigned) and
+the offset applied to it (which is treated as signed). The result of the
+additions within the offset calculation cannot have signed overflow, but when
+applied to the base pointer, there can be signed overflow.</p>
+</div>
+<div class="section" id="how-can-i-tell-if-my-front-end-is-following-the-rules">
+<h3><a class="toc-backref" href="#id23">How can I tell if my front-end is following the rules?</a><a class="headerlink" href="#how-can-i-tell-if-my-front-end-is-following-the-rules" title="Permalink to this headline">¶</a></h3>
+<p>There is currently no checker for the getelementptr rules. Currently, the only
+way to do this is to manually check each place in your front-end where
+GetElementPtr operators are created.</p>
+<p>It’s not possible to write a checker which could find all rule violations
+statically. It would be possible to write a checker which works by instrumenting
+the code with dynamic checks though. Alternatively, it would be possible to
+write a static checker which catches a subset of possible problems. However, no
+such checker exists today.</p>
+</div>
+</div>
+<div class="section" id="rationale">
+<h2><a class="toc-backref" href="#id24">Rationale</a><a class="headerlink" href="#rationale" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="why-is-gep-designed-this-way">
+<h3><a class="toc-backref" href="#id25">Why is GEP designed this way?</a><a class="headerlink" href="#why-is-gep-designed-this-way" title="Permalink to this headline">¶</a></h3>
+<p>The design of GEP has the following goals, in rough unofficial order of
+priority:</p>
+<ul class="simple">
+<li>Support C, C-like languages, and languages which can be conceptually lowered
+into C (this covers a lot).</li>
+<li>Support optimizations such as those that are common in C compilers. In
+particular, GEP is a cornerstone of LLVM’s <a class="reference external" href="LangRef.html#pointeraliasing">pointer aliasing
+model</a>.</li>
+<li>Provide a consistent method for computing addresses so that address
+computations don’t need to be a part of load and store instructions in the IR.</li>
+<li>Support non-C-like languages, to the extent that it doesn’t interfere with
+other goals.</li>
+<li>Minimize target-specific information in the IR.</li>
+</ul>
+</div>
+<div class="section" id="why-do-struct-member-indices-always-use-i32">
+<h3><a class="toc-backref" href="#id26">Why do struct member indices always use <tt class="docutils literal"><span class="pre">i32</span></tt>?</a><a class="headerlink" href="#why-do-struct-member-indices-always-use-i32" title="Permalink to this headline">¶</a></h3>
+<p>The specific type i32 is probably just a historical artifact, however it’s wide
+enough for all practical purposes, so there’s been no need to change it. It
+doesn’t necessarily imply i32 address arithmetic; it’s just an identifier which
+identifies a field in a struct. Requiring that all struct indices be the same
+reduces the range of possibilities for cases where two GEPs are effectively the
+same but have distinct operand types.</p>
+</div>
+<div class="section" id="what-s-an-uglygep">
+<h3><a class="toc-backref" href="#id27">What’s an uglygep?</a><a class="headerlink" href="#what-s-an-uglygep" title="Permalink to this headline">¶</a></h3>
+<p>Some LLVM optimizers operate on GEPs by internally lowering them into more
+primitive integer expressions, which allows them to be combined with other
+integer expressions and/or split into multiple separate integer expressions. If
+they’ve made non-trivial changes, translating back into LLVM IR can involve
+reverse-engineering the structure of the addressing in order to fit it into the
+static type of the original first operand. It isn’t always possibly to fully
+reconstruct this structure; sometimes the underlying addressing doesn’t
+correspond with the static type at all. In such cases the optimizer instead will
+emit a GEP with the base pointer casted to a simple address-unit pointer, using
+the name “uglygep”. This isn’t pretty, but it’s just as valid, and it’s
+sufficient to preserve the pointer aliasing guarantees that GEP provides.</p>
+</div>
+</div>
+<div class="section" id="summary">
+<h2><a class="toc-backref" href="#id28">Summary</a><a class="headerlink" href="#summary" title="Permalink to this headline">¶</a></h2>
+<p>In summary, here’s some things to always remember about the GetElementPtr
+instruction:</p>
+<ol class="arabic simple">
+<li>The GEP instruction never accesses memory, it only provides pointer
+computations.</li>
+<li>The second operand to the GEP instruction is always a pointer and it must be
+indexed.</li>
+<li>There are no superfluous indices for the GEP instruction.</li>
+<li>Trailing zero indices are superfluous for pointer aliasing, but not for the
+types of the pointers.</li>
+<li>Leading zero indices are not superfluous for pointer aliasing nor the types
+of the pointers.</li>
+</ol>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="Frontend/PerformanceTips.html" title="Performance Tips for Frontend Authors"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="YamlIO.html" title="YAML I/O"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer">
+ © Copyright 2003-2018, LLVM Project.
+ Last updated on 2018-12-21.
+ Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list