[www-releases] r372328 - Check in 9.0.0 source and docs
Hans Wennborg via llvm-commits
llvm-commits at lists.llvm.org
Thu Sep 19 07:32:55 PDT 2019
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-nm.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-nm.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-nm.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-nm.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,414 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-nm - list LLVM bitcode and object fileâs symbol table — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-objcopy - object copying and editing tool" href="llvm-objcopy.html" />
+ <link rel="prev" title="llvm-cxxfilt - LLVM symbol name demangler" href="llvm-cxxfilt.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-objcopy.html" title="llvm-objcopy - object copying and editing tool"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-cxxfilt.html" title="llvm-cxxfilt - LLVM symbol name demangler"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-nm-list-llvm-bitcode-and-object-file-s-symbol-table">
+<h1>llvm-nm - list LLVM bitcode and object fileâs symbol table<a class="headerlink" href="#llvm-nm-list-llvm-bitcode-and-object-file-s-symbol-table" 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-nm</strong> [<em>options</em>] [<em>filenamesâ¦</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-nm</strong> utility lists the names of symbols from LLVM bitcode
+files, object files, and archives. Each symbol is listed along with some simple
+information about its provenance. If no filename is specified, <em>a.out</em> is used
+as the input. If <em>-</em> is used as a filename, <strong class="program">llvm-nm</strong> will read a file
+from its standard input stream.</p>
+<p><strong class="program">llvm-nm</strong>âs default output format is the traditional BSD <strong class="program">nm</strong>
+output format. Each such output record consists of an (optional) 8-digit
+hexadecimal address, followed by a type code character, followed by a name, for
+each symbol. One record is printed per line; fields are separated by spaces.
+When the address is omitted, it is replaced by 8 spaces.</p>
+<p>The supported type code characters are as follows. Where both lower and
+upper-case characters are listed for the same meaning, a lower-case character
+represents a local symbol, whilst an upper-case character represents a global
+(external) symbol:</p>
+<p>a, A</p>
+<blockquote>
+<div>Absolute symbol.</div></blockquote>
+<p>b, B</p>
+<blockquote>
+<div>Unitialized data (bss) object.</div></blockquote>
+<p>C</p>
+<blockquote>
+<div>Common symbol. Multiple definitions link together into one definition.</div></blockquote>
+<p>d, D</p>
+<blockquote>
+<div>Writable data object.</div></blockquote>
+<p>i, I</p>
+<blockquote>
+<div>COFF: .idata symbol or symbol in a section with IMAGE_SCN_LNK_INFO set.</div></blockquote>
+<p>n</p>
+<blockquote>
+<div><p>ELF: local symbol from non-alloc section.</p>
+<p>COFF: debug symbol.</p>
+</div></blockquote>
+<p>N</p>
+<blockquote>
+<div>ELF: debug section symbol, or global symbol from non-alloc section.</div></blockquote>
+<p>s, S</p>
+<blockquote>
+<div><p>COFF: section symbol.</p>
+<p>Mach-O: absolute symbol or symbol from a section other than __TEXT_EXEC __text,
+__TEXT __text, __DATA __data, or __DATA __bss.</p>
+</div></blockquote>
+<p>r, R</p>
+<blockquote>
+<div>Read-only data object.</div></blockquote>
+<p>t, T</p>
+<blockquote>
+<div>Code (text) object.</div></blockquote>
+<p>u</p>
+<blockquote>
+<div>ELF: GNU unique symbol.</div></blockquote>
+<p>U</p>
+<blockquote>
+<div>Named object is undefined in this file.</div></blockquote>
+<p>v</p>
+<blockquote>
+<div>ELF: Undefined weak object. It is not a link failure if the object is not
+defined.</div></blockquote>
+<p>V</p>
+<blockquote>
+<div>ELF: Defined weak object symbol. This definition will only be used if no
+regular definitions exist in a link. If multiple weak definitions and no
+regular definitons exist, one of the weak definitions will be used.</div></blockquote>
+<p>w</p>
+<blockquote>
+<div>Undefined weak symbol other than an ELF object symbol. It is not a link failure
+if the symbol is not defined.</div></blockquote>
+<p>W</p>
+<blockquote>
+<div>Defined weak symbol other than an ELF object symbol. This definition will only
+be used if no regular definitions exist in a link. If multiple weak definitions
+and no regular definitons exist, one of the weak definitions will be used.</div></blockquote>
+<p>-</p>
+<blockquote>
+<div>Mach-O: N_STAB symbol.</div></blockquote>
+<p>?</p>
+<blockquote>
+<div>Something unrecognizable.</div></blockquote>
+<p>Because LLVM bitcode files typically contain objects that are not considered to
+have addresses until they are linked into an executable image or dynamically
+compiled âjust-in-timeâ, <strong class="program">llvm-nm</strong> does not print an address for any
+symbol in an LLVM bitcode file, even symbols which are defined in the bitcode
+file.</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-llvm-nm-b">
+<code class="descname">-B</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-b" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use BSD output format. Alias for <code class="docutils literal notranslate"><span class="pre">--format=bsd</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-debug-syms">
+<code class="descname">--debug-syms</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-a</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-debug-syms" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show all symbols, even those usually suppressed.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-defined-only">
+<code class="descname">--defined-only</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-U</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-defined-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print only symbols defined in this file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-demangle">
+<code class="descname">--demangle</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-C</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-demangle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Demangle symbol names.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-dynamic">
+<code class="descname">--dynamic</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-D</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-dynamic" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display dynamic symbols instead of normal symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-extern-only">
+<code class="descname">--extern-only</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-g</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-extern-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print only symbols whose definitions are external; that is, accessible from
+other files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-format">
+<code class="descname">--format</code><code class="descclassname">=<format></code><code class="descclassname">, </code><code class="descname">-f</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-format" title="Permalink to this definition">¶</a></dt>
+<dd><p>Select an output format; <em>format</em> may be <em>sysv</em>, <em>posix</em>, <em>darwin</em>, or <em>bsd</em>.
+The default is <em>bsd</em>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-help">
+<code class="descname">--help</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-h</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command-line options and their meanings.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-help-list">
+<code class="descname">--help-list</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-help-list" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print an uncategorized summary of command-line options and their meanings.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-just-symbol-name">
+<code class="descname">--just-symbol-name</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-j</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-just-symbol-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print just the symbol names.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-m">
+<code class="descname">-m</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-m" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use Darwin format. Alias for <code class="docutils literal notranslate"><span class="pre">--format=darwin</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-no-demangle">
+<code class="descname">--no-demangle</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-no-demangle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Donât demangle symbol names. This is the default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-no-llvm-bc">
+<code class="descname">--no-llvm-bc</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-no-llvm-bc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable the LLVM bitcode reader.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-no-sort">
+<code class="descname">--no-sort</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-p</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-no-sort" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show symbols in the order encountered.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-no-weak">
+<code class="descname">--no-weak</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-W</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-no-weak" title="Permalink to this definition">¶</a></dt>
+<dd><p>Donât print weak symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-numeric-sort">
+<code class="descname">--numeric-sort</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-n</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-v</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-numeric-sort" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sort symbols by address.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-portability">
+<code class="descname">--portability</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-P</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-portability" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use POSIX.2 output format. Alias for <code class="docutils literal notranslate"><span class="pre">--format=posix</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-print-armap">
+<code class="descname">--print-armap</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-M</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-print-armap" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the archive symbol table, in addition to the symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-print-file-name">
+<code class="descname">--print-file-name</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-A</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-o</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-print-file-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Precede each symbol with the file it came from.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-print-size">
+<code class="descname">--print-size</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-S</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-print-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show symbol size as well as address (not applicable for Mach-O).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-radix">
+<code class="descname">--radix</code><code class="descclassname">=<RADIX></code><code class="descclassname">, </code><code class="descname">-t</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-radix" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the radix of the symbol address(es). Values accepted are <em>d</em> (decimal),
+<em>x</em> (hexadecimal) and <em>o</em> (octal).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-reverse-sort">
+<code class="descname">--reverse-sort</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-r</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-reverse-sort" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sort symbols in reverse order.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-size-sort">
+<code class="descname">--size-sort</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-size-sort" title="Permalink to this definition">¶</a></dt>
+<dd><p>Sort symbols by size.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-special-syms">
+<code class="descname">--special-syms</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-special-syms" title="Permalink to this definition">¶</a></dt>
+<dd><p>Ignored. For GNU compatibility only.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-undefined-only">
+<code class="descname">--undefined-only</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-u</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-undefined-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print only undefined symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-version">
+<code class="descname">--version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of this program. Does not stack with other commands.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-without-aliases">
+<code class="descname">--without-aliases</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-without-aliases" title="Permalink to this definition">¶</a></dt>
+<dd><p>Exclude aliases from the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-arg-file">
+<code class="descname">@<FILE></code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-arg-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>Read command-line options from response file <cite><FILE></cite>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="mach-o-specific-options">
+<h2>MACH-O SPECIFIC OPTIONS<a class="headerlink" href="#mach-o-specific-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-llvm-nm-add-dyldinfo">
+<code class="descname">--add-dyldinfo</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-add-dyldinfo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add symbols from the dyldinfo, if they are not already in the symbol table.
+This is the default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-arch">
+<code class="descname">--arch</code><code class="descclassname">=<arch1[,arch2,...]></code><a class="headerlink" href="#cmdoption-llvm-nm-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the symbols from the specified architecture(s).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-dyldinfo-only">
+<code class="descname">--dyldinfo-only</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-dyldinfo-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump only symbols from the dyldinfo.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-no-dyldinfo">
+<code class="descname">--no-dyldinfo</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-no-dyldinfo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not add any symbols from the dyldinfo.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-s">
+<code class="descname">-s</code><code class="descclassname">=<segment section></code><a class="headerlink" href="#cmdoption-llvm-nm-s" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump only symbols from this segment and section name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-x">
+<code class="descname">-x</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-x" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print symbol entry in hex.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="bugs">
+<h2>BUGS<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h2>
+<blockquote>
+<div><ul class="simple">
+<li><strong class="program">llvm-nm</strong> does not support the full set of arguments that GNU
+<strong class="program">nm</strong> does.</li>
+</ul>
+</div></blockquote>
+</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-nm</strong> exits with an exit code of zero.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-ar.html">llvm-ar(1)</a></em>, <em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-objdump.html">llvm-objdump(1)</a></em>, <em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-readelf.html">llvm-readelf(1)</a></em>,
+<em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-readobj.html">llvm-readobj(1)</a></em></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-objcopy.html" title="llvm-objcopy - object copying and editing tool"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-cxxfilt.html" title="llvm-cxxfilt - LLVM symbol name demangler"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-objcopy.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-objcopy.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-objcopy.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-objcopy.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,691 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-objcopy - object copying and editing tool — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-objdump - LLVMâs object file dumper" href="llvm-objdump.html" />
+ <link rel="prev" title="llvm-nm - list LLVM bitcode and object fileâs symbol table" href="llvm-nm.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-objdump.html" title="llvm-objdump - LLVMâs object file dumper"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-nm.html" title="llvm-nm - list LLVM bitcode and object fileâs symbol table"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-objcopy-object-copying-and-editing-tool">
+<h1>llvm-objcopy - object copying and editing tool<a class="headerlink" href="#llvm-objcopy-object-copying-and-editing-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-objcopy</strong> [<em>options</em>] <em>input</em> [<em>output</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">llvm-objcopy</strong> is a tool to copy and manipulate objects. In basic
+usage, it makes a semantic copy of the input to the output. If any options are
+specified, the output may be modified along the way, e.g. by removing sections.</p>
+<p>If no output file is specified, the input file is modified in-place. If â-â is
+specified for the input file, the input is read from the programâs standard
+input stream. If â-â is specified for the output file, the output is written to
+the standard output stream of the program.</p>
+<p>If the input is an archive, any requested operations will be applied to each
+archive member individually.</p>
+<p>The tool is still in active development, but in most scenarios it works as a
+drop-in replacement for GNUâs <strong class="program">objcopy</strong>.</p>
+</div>
+<div class="section" id="generic-and-cross-platform-options">
+<h2>GENERIC AND CROSS-PLATFORM OPTIONS<a class="headerlink" href="#generic-and-cross-platform-options" title="Permalink to this headline">¶</a></h2>
+<p>The following options are either agnostic of the file format, or apply to
+multiple file formats.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-add-gnu-debuglink">
+<code class="descname">--add-gnu-debuglink</code><code class="descclassname"> <debug-file></code><a class="headerlink" href="#cmdoption-llvm-objcopy-add-gnu-debuglink" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add a .gnu_debuglink section for <code class="docutils literal notranslate"><span class="pre"><debug-file></span></code> to the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-disable-deterministic-archives">
+<code class="descname">--disable-deterministic-archives</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-U</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-disable-deterministic-archives" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use real values for UIDs, GIDs and timestamps when updating archive member
+headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-discard-all">
+<code class="descname">--discard-all</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-x</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-discard-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove most local symbols from the output. Different file formats may limit
+this to a subset of the local symbols. For example, file and section symbols in
+ELF objects will not be discarded.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-enable-deterministic-archives">
+<code class="descname">--enable-deterministic-archives</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-D</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-enable-deterministic-archives" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable deterministic mode when copying archives, i.e. use 0 for archive member
+header UIDs, GIDs and timestamp fields. On by default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-help">
+<code class="descname">--help</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-h</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-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-objcopy-only-section">
+<code class="descname">--only-section</code><code class="descclassname"> <section></code><code class="descclassname">, </code><code class="descname">-j</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-only-section" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove all sections from the output, except for sections named <code class="docutils literal notranslate"><span class="pre"><section></span></code>.
+Can be specified multiple times to keep multiple sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-regex">
+<code class="descname">--regex</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-regex" title="Permalink to this definition">¶</a></dt>
+<dd><p>If specified, symbol and section names specified by other switches are treated
+as extended POSIX regular expression patterns.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-remove-section">
+<code class="descname">--remove-section</code><code class="descclassname"> <section></code><code class="descclassname">, </code><code class="descname">-R</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-remove-section" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove the specified section from the output. Can be specified multiple times
+to remove multiple sections simultaneously.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-all-gnu">
+<code class="descname">--strip-all-gnu</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-all-gnu" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove all symbols, debug sections and relocations from the output. This option
+is equivalent to GNU <strong class="program">objcopy</strong>âs <code class="docutils literal notranslate"><span class="pre">--strip-all</span></code> switch.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-all">
+<code class="descname">--strip-all</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-S</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>For ELF objects, remove from the output all symbols and non-alloc sections not
+within segments, except for .gnu.warning sections and the section name table.</p>
+<p>For COFF objects, remove all symbols, debug sections, and relocations from the
+output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-debug">
+<code class="descname">--strip-debug</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-g</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove all debug sections from the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-symbol">
+<code class="descname">--strip-symbol</code><code class="descclassname"> <symbol></code><code class="descclassname">, </code><code class="descname">-N</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-symbol" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove all symbols named <code class="docutils literal notranslate"><span class="pre"><symbol></span></code> from the output. Can be specified
+multiple times to remove multiple symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-symbols">
+<code class="descname">--strip-symbols</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove all symbols whose names appear in the file <code class="docutils literal notranslate"><span class="pre"><filename></span></code>, from the
+output. In the file, each line represents a single symbol name, with leading
+and trailing whitespace ignored, as is anything following a â#â. Can be
+specified multiple times to read names from multiple files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-unneeded-symbol">
+<code class="descname">--strip-unneeded-symbol</code><code class="descclassname"> <symbol></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-unneeded-symbol" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove from the output all symbols named <code class="docutils literal notranslate"><span class="pre"><symbol></span></code> that are local or
+undefined and are not required by any relocation.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-unneeded-symbols">
+<code class="descname">--strip-unneeded-symbols</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-unneeded-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove all symbols whose names appear in the file <code class="docutils literal notranslate"><span class="pre"><filename></span></code>, from the
+output, if they are local or undefined and are not required by any relocation.
+In the file, each line represents a single symbol name, with leading and
+trailing whitespace ignored, as is anything following a â#â. Can be specified
+multiple times to read names from multiple files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-unneeded">
+<code class="descname">--strip-unneeded</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-unneeded" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove from the output all local or undefined symbols that are not required by
+relocations.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-version">
+<code class="descname">--version</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-V</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of this program.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="coff-specific-options">
+<h2>COFF-SPECIFIC OPTIONS<a class="headerlink" href="#coff-specific-options" title="Permalink to this headline">¶</a></h2>
+<p>The following options are implemented only for COFF objects. If used with other
+objects, <strong class="program">llvm-objcopy</strong> will either emit an error or silently ignore
+them.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-only-keep-debug">
+<code class="descname">--only-keep-debug</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-only-keep-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove the contents of non-debug sections from the output, but keep the section
+headers.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="elf-specific-options">
+<h2>ELF-SPECIFIC OPTIONS<a class="headerlink" href="#elf-specific-options" title="Permalink to this headline">¶</a></h2>
+<p>The following options are implemented only for ELF objects. If used with other
+objects, <strong class="program">llvm-objcopy</strong> will either emit an error or silently ignore
+them.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-add-section">
+<code class="descname">--add-section</code><code class="descclassname"> <section=file></code><a class="headerlink" href="#cmdoption-llvm-objcopy-add-section" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add a section named <code class="docutils literal notranslate"><span class="pre"><section></span></code> with the contents of <code class="docutils literal notranslate"><span class="pre"><file></span></code> to the
+output. The section will be of type <cite>SHT_NOTE</cite>, if the name starts with
+â.noteâ. Otherwise, it will have type <cite>SHT_PROGBITS</cite>. Can be specified multiple
+times to add multiple sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-add-symbol">
+<code class="descname">--add-symbol</code><code class="descclassname"> <name>=[<section>:]<value>[,<flags>]</code><a class="headerlink" href="#cmdoption-llvm-objcopy-add-symbol" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add a new symbol called <code class="docutils literal notranslate"><span class="pre"><name></span></code> to the output symbol table, in the section
+named <code class="docutils literal notranslate"><span class="pre"><section></span></code>, with value <code class="docutils literal notranslate"><span class="pre"><value></span></code>. If <code class="docutils literal notranslate"><span class="pre"><section></span></code> is not specified,
+the symbol is added as an absolute symbol. The <code class="docutils literal notranslate"><span class="pre"><flags></span></code> affect the symbol
+properties. Accepted values are:</p>
+<ul class="simple">
+<li><cite>global</cite> = the symbol will have global binding.</li>
+<li><cite>local</cite> = the symbol will have local binding.</li>
+<li><cite>weak</cite> = the symbol will have weak binding.</li>
+<li><cite>default</cite> = the symbol will have default visibility.</li>
+<li><cite>hidden</cite> = the symbol will have hidden visibility.</li>
+<li><cite>file</cite> = the symbol will be an <cite>STT_FILE</cite> symbol.</li>
+<li><cite>section</cite> = the symbol will be an <cite>STT_SECTION</cite> symbol.</li>
+<li><cite>object</cite> = the symbol will be an <cite>STT_OBJECT</cite> symbol.</li>
+<li><cite>function</cite> = the symbol will be an <cite>STT_FUNC</cite> symbol.</li>
+<li><cite>indirect-function</cite> = the symbol will be an <cite>STT_GNU_IFUNC</cite> symbol.</li>
+</ul>
+<p>Additionally, the following flags are accepted but ignored: <cite>debug</cite>,
+<cite>constructor</cite>, <cite>warning</cite>, <cite>indirect</cite>, <cite>synthetic</cite>, <cite>unique-object</cite>, <cite>before</cite>.</p>
+<p>Can be specified multiple times to add multiple symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-allow-broken-links">
+<code class="descname">--allow-broken-links</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-allow-broken-links" title="Permalink to this definition">¶</a></dt>
+<dd><p>Allow llvm-objcopy to remove sections even if it would leave invalid section
+references. Any invalid sh_link fields will be set to zero.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-binary-architecture">
+<code class="descname">--binary-architecture</code><code class="descclassname"> <arch></code><code class="descclassname">, </code><code class="descname">-B</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-binary-architecture" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the architecture to use, when transforming an architecture-less format
+(e.g. binary) to another format. Valid options are:</p>
+<ul class="simple">
+<li><cite>aarch64</cite></li>
+<li><cite>arm</cite></li>
+<li><cite>i386</cite></li>
+<li><cite>i386:x86-64</cite></li>
+<li><cite>mips</cite></li>
+<li><cite>powerpc:common64</cite></li>
+<li><cite>riscv:rv32</cite></li>
+<li><cite>riscv:rv64</cite></li>
+<li><cite>sparc</cite></li>
+<li><cite>sparcel</cite></li>
+<li><cite>x86-64</cite></li>
+</ul>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-build-id-link-dir">
+<code class="descname">--build-id-link-dir</code><code class="descclassname"> <dir></code><a class="headerlink" href="#cmdoption-llvm-objcopy-build-id-link-dir" title="Permalink to this definition">¶</a></dt>
+<dd><p>Set the directory used by <a class="reference internal" href="#cmdoption-llvm-objcopy-build-id-link-input"><code class="xref std std-option docutils literal notranslate"><span class="pre">--build-id-link-input</span></code></a> and
+<a class="reference internal" href="#cmdoption-llvm-objcopy-build-id-link-output"><code class="xref std std-option docutils literal notranslate"><span class="pre">--build-id-link-output</span></code></a>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-build-id-link-input">
+<code class="descname">--build-id-link-input</code><code class="descclassname"> <suffix></code><a class="headerlink" href="#cmdoption-llvm-objcopy-build-id-link-input" title="Permalink to this definition">¶</a></dt>
+<dd><p>Hard-link the input to <code class="docutils literal notranslate"><span class="pre"><dir>/xx/xxx<suffix></span></code>, where <code class="docutils literal notranslate"><span class="pre"><dir></span></code> is the directory
+specified by <a class="reference internal" href="#cmdoption-llvm-objcopy-build-id-link-dir"><code class="xref std std-option docutils literal notranslate"><span class="pre">--build-id-link-dir</span></code></a>. The path used is derived from the
+hex build ID.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-build-id-link-output">
+<code class="descname">--build-id-link-output</code><code class="descclassname"> <suffix></code><a class="headerlink" href="#cmdoption-llvm-objcopy-build-id-link-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Hard-link the output to <code class="docutils literal notranslate"><span class="pre"><dir>/xx/xxx<suffix></span></code>, where <code class="docutils literal notranslate"><span class="pre"><dir></span></code> is the directory
+specified by <a class="reference internal" href="#cmdoption-llvm-objcopy-build-id-link-dir"><code class="xref std std-option docutils literal notranslate"><span class="pre">--build-id-link-dir</span></code></a>. The path used is derived from the
+hex build ID.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-change-start">
+<code class="descname">--change-start</code><code class="descclassname"> <incr></code><code class="descclassname">, </code><code class="descname">--adjust-start</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-change-start" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add <code class="docutils literal notranslate"><span class="pre"><incr></span></code> to the programâs start address. Can be specified multiple
+times, in which case the values will be applied cumulatively.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-compress-debug-sections">
+<code class="descname">--compress-debug-sections</code><code class="descclassname"> [<style>]</code><a class="headerlink" href="#cmdoption-llvm-objcopy-compress-debug-sections" title="Permalink to this definition">¶</a></dt>
+<dd><p>Compress DWARF debug sections in the output, using the specified style.
+Supported styles are <cite>zlib-gnu</cite> and <cite>zlib</cite>. Defaults to <cite>zlib</cite> if no style is
+specified.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-decompress-debug-sections">
+<code class="descname">--decompress-debug-sections</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-decompress-debug-sections" title="Permalink to this definition">¶</a></dt>
+<dd><p>Decompress any compressed DWARF debug sections in the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-discard-locals">
+<code class="descname">--discard-locals</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-X</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-discard-locals" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove local symbols starting with â.Lâ from the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-dump-section">
+<code class="descname">--dump-section</code><code class="descclassname"> <section>=<file></code><a class="headerlink" href="#cmdoption-llvm-objcopy-dump-section" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the contents of section <code class="docutils literal notranslate"><span class="pre"><section></span></code> into the file <code class="docutils literal notranslate"><span class="pre"><file></span></code>. Can be
+specified multiple times to dump multiple sections to different files.
+<code class="docutils literal notranslate"><span class="pre"><file></span></code> is unrelated to the input and output files provided to
+<strong class="program">llvm-objcopy</strong> and as such the normal copying and editing
+operations will still be performed. No operations are performed on the sections
+prior to dumping them.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-extract-dwo">
+<code class="descname">--extract-dwo</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-extract-dwo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove all sections that are not DWARF .dwo sections from the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-extract-main-partition">
+<code class="descname">--extract-main-partition</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-extract-main-partition" title="Permalink to this definition">¶</a></dt>
+<dd><p>Extract the main partition from the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-extract-partition">
+<code class="descname">--extract-partition</code><code class="descclassname"> <name></code><a class="headerlink" href="#cmdoption-llvm-objcopy-extract-partition" title="Permalink to this definition">¶</a></dt>
+<dd><p>Extract the named partition from the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-globalize-symbol">
+<code class="descname">--globalize-symbol</code><code class="descclassname"> <symbol></code><a class="headerlink" href="#cmdoption-llvm-objcopy-globalize-symbol" title="Permalink to this definition">¶</a></dt>
+<dd><p>Mark any defined symbols named <code class="docutils literal notranslate"><span class="pre"><symbol></span></code> as global symbols in the output.
+Can be specified multiple times to mark multiple symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-globalize-symbols">
+<code class="descname">--globalize-symbols</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-llvm-objcopy-globalize-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Read a list of names from the file <code class="docutils literal notranslate"><span class="pre"><filename></span></code> and mark defined symbols with
+those names as global in the output. In the file, each line represents a single
+symbol, with leading and trailing whitespace ignored, as is anything following
+a â#â. Can be specified multiple times to read names from multiple files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-input-target">
+<code class="descname">--input-target</code><code class="descclassname"> <format></code><code class="descclassname">, </code><code class="descname">-I</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-input-target" title="Permalink to this definition">¶</a></dt>
+<dd><p>Read the input as the specified format. See <a class="reference internal" href="#supported-formats">SUPPORTED FORMATS</a> for a list of
+valid <code class="docutils literal notranslate"><span class="pre"><format></span></code> values. If unspecified, <strong class="program">llvm-objcopy</strong> will attempt
+to determine the format automatically.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-keep-file-symbols">
+<code class="descname">--keep-file-symbols</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-keep-file-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Keep symbols of type <cite>STT_FILE</cite>, even if they would otherwise be stripped.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-keep-global-symbol">
+<code class="descname">--keep-global-symbol</code><code class="descclassname"> <symbol></code><a class="headerlink" href="#cmdoption-llvm-objcopy-keep-global-symbol" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make all symbols local in the output, except for symbols with the name
+<code class="docutils literal notranslate"><span class="pre"><symbol></span></code>. Can be specified multiple times to ignore multiple symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-keep-global-symbols">
+<code class="descname">--keep-global-symbols</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-llvm-objcopy-keep-global-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make all symbols local in the output, except for symbols named in the file
+<code class="docutils literal notranslate"><span class="pre"><filename></span></code>. In the file, each line represents a single symbol, with leading
+and trailing whitespace ignored, as is anything following a â#â. Can be
+specified multiple times to read names from multiple files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-keep-section">
+<code class="descname">--keep-section</code><code class="descclassname"> <section></code><a class="headerlink" href="#cmdoption-llvm-objcopy-keep-section" title="Permalink to this definition">¶</a></dt>
+<dd><p>When removing sections from the output, do not remove sections named
+<code class="docutils literal notranslate"><span class="pre"><section></span></code>. Can be specified multiple times to keep multiple sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-keep-symbol">
+<code class="descname">--keep-symbol</code><code class="descclassname"> <symbol></code><code class="descclassname">, </code><code class="descname">-K</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-keep-symbol" title="Permalink to this definition">¶</a></dt>
+<dd><p>When removing symbols from the output, do not remove symbols named
+<code class="docutils literal notranslate"><span class="pre"><symbol></span></code>. Can be specified multiple times to keep multiple symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-keep-symbols">
+<code class="descname">--keep-symbols</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-llvm-objcopy-keep-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When removing symbols from the output do not remove symbols named in the file
+<code class="docutils literal notranslate"><span class="pre"><filename></span></code>. In the file, each line represents a single symbol, with leading
+and trailing whitespace ignored, as is anything following a â#â. Can be
+specified multiple times to read names from multiple files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-localize-hidden">
+<code class="descname">--localize-hidden</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-localize-hidden" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make all symbols with hidden or internal visibility local in the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-localize-symbol">
+<code class="descname">--localize-symbol</code><code class="descclassname"> <symbol></code><code class="descclassname">, </code><code class="descname">-L</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-localize-symbol" title="Permalink to this definition">¶</a></dt>
+<dd><p>Mark any defined non-common symbol named <code class="docutils literal notranslate"><span class="pre"><symbol></span></code> as a local symbol in the
+output. Can be specified multiple times to mark multiple symbols as local.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-localize-symbols">
+<code class="descname">--localize-symbols</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-llvm-objcopy-localize-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Read a list of names from the file <code class="docutils literal notranslate"><span class="pre"><filename></span></code> and mark defined non-common
+symbols with those names as local in the output. In the file, each line
+represents a single symbol, with leading and trailing whitespace ignored, as is
+anything following a â#â. Can be specified multiple times to read names from
+multiple files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-output-target">
+<code class="descname">--output-target</code><code class="descclassname"> <format></code><code class="descclassname">, </code><code class="descname">-O</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-output-target" title="Permalink to this definition">¶</a></dt>
+<dd><p>Write the output as the specified format. See <a class="reference internal" href="#supported-formats">SUPPORTED FORMATS</a> for a list
+of valid <code class="docutils literal notranslate"><span class="pre"><format></span></code> values. If unspecified, the output format is assumed to
+be the same as the input fileâs format.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-prefix-alloc-sections">
+<code class="descname">--prefix-alloc-sections</code><code class="descclassname"> <prefix></code><a class="headerlink" href="#cmdoption-llvm-objcopy-prefix-alloc-sections" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add <code class="docutils literal notranslate"><span class="pre"><prefix></span></code> to the front of the names of all allocatable sections in the
+output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-prefix-symbols">
+<code class="descname">--prefix-symbols</code><code class="descclassname"> <prefix></code><a class="headerlink" href="#cmdoption-llvm-objcopy-prefix-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add <code class="docutils literal notranslate"><span class="pre"><prefix></span></code> to the front of every symbol name in the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-preserve-dates">
+<code class="descname">--preserve-dates</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-p</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-preserve-dates" title="Permalink to this definition">¶</a></dt>
+<dd><p>Preserve access and modification timestamps in the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-redefine-sym">
+<code class="descname">--redefine-sym</code><code class="descclassname"> <old>=<new></code><a class="headerlink" href="#cmdoption-llvm-objcopy-redefine-sym" title="Permalink to this definition">¶</a></dt>
+<dd><p>Rename symbols called <code class="docutils literal notranslate"><span class="pre"><old></span></code> to <code class="docutils literal notranslate"><span class="pre"><new></span></code> in the output. Can be specified
+multiple times to rename multiple symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-redefine-syms">
+<code class="descname">--redefine-syms</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-llvm-objcopy-redefine-syms" title="Permalink to this definition">¶</a></dt>
+<dd><p>Rename symbols in the output as described in the file <code class="docutils literal notranslate"><span class="pre"><filename></span></code>. In the
+file, each line represents a single symbol to rename, with the old name and new
+name separated by an equals sign. Leading and trailing whitespace is ignored,
+as is anything following a â#â. Can be specified multiple times to read names
+from multiple files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-rename-section">
+<code class="descname">--rename-section</code><code class="descclassname"> <old>=<new>[,<flag>,...]</code><a class="headerlink" href="#cmdoption-llvm-objcopy-rename-section" title="Permalink to this definition">¶</a></dt>
+<dd><p>Rename sections called <code class="docutils literal notranslate"><span class="pre"><old></span></code> to <code class="docutils literal notranslate"><span class="pre"><new></span></code> in the output, and apply any
+specified <code class="docutils literal notranslate"><span class="pre"><flag></span></code> values. See <a class="reference internal" href="#cmdoption-llvm-objcopy-set-section-flags"><code class="xref std std-option docutils literal notranslate"><span class="pre">--set-section-flags</span></code></a> for a list of
+supported flags. Can be specified multiple times to rename multiple sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-set-section-flags">
+<code class="descname">--set-section-flags</code><code class="descclassname"> <section>=<flag>[,<flag>,...]</code><a class="headerlink" href="#cmdoption-llvm-objcopy-set-section-flags" title="Permalink to this definition">¶</a></dt>
+<dd><p>Set section properties in the output of section <code class="docutils literal notranslate"><span class="pre"><section></span></code> based on the
+specified <code class="docutils literal notranslate"><span class="pre"><flag></span></code> values. Can be specified multiple times to update multiple
+sections.</p>
+<p>Following is a list of supported flags and their effects:</p>
+<ul class="simple">
+<li><cite>alloc</cite> = add the <cite>SHF_ALLOC</cite> flag.</li>
+<li><cite>load</cite> = if the section has <cite>SHT_NOBITS</cite> type, mark it as a <cite>SHT_PROGBITS</cite>
+section.</li>
+<li><cite>readonly</cite> = if this flag is not specified, add the <cite>SHF_WRITE</cite> flag.</li>
+<li><cite>code</cite> = add the <cite>SHF_EXECINSTR</cite> flag.</li>
+<li><cite>merge</cite> = add the <cite>SHF_MERGE</cite> flag.</li>
+<li><cite>strings</cite> = add the <cite>SHF_STRINGS</cite> flag.</li>
+<li><cite>contents</cite> = if the section has <cite>SHT_NOBITS</cite> type, mark it as a <cite>SHT_PROGBITS</cite>
+section.</li>
+</ul>
+<p>The following flags are also accepted, but are ignored for GNU compatibility:
+<cite>noload</cite>, <cite>debug</cite>, <cite>data</cite>, <cite>rom</cite>, <cite>share</cite>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-set-start-addr">
+<code class="descname">--set-start-addr</code><code class="descclassname"> <addr></code><a class="headerlink" href="#cmdoption-llvm-objcopy-set-start-addr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Set the start address of the output to <code class="docutils literal notranslate"><span class="pre"><addr></span></code>. Overrides any previously
+specified <a class="reference internal" href="#cmdoption-llvm-objcopy-change-start"><code class="xref std std-option docutils literal notranslate"><span class="pre">--change-start</span></code></a> or <a class="reference internal" href="#cmdoption-llvm-objcopy-change-start"><code class="xref std std-option docutils literal notranslate"><span class="pre">--adjust-start</span></code></a> options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-split-dwo">
+<code class="descname">--split-dwo</code><code class="descclassname"> <dwo-file></code><a class="headerlink" href="#cmdoption-llvm-objcopy-split-dwo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Equivalent to running <strong class="program">llvm-objcopy</strong> with <a class="reference internal" href="#cmdoption-llvm-objcopy-extract-dwo"><code class="xref std std-option docutils literal notranslate"><span class="pre">--extract-dwo</span></code></a> and
+<code class="docutils literal notranslate"><span class="pre"><dwo-file></span></code> as the output file and no other options, and then with
+<a class="reference internal" href="#cmdoption-llvm-objcopy-strip-dwo"><code class="xref std std-option docutils literal notranslate"><span class="pre">--strip-dwo</span></code></a> on the input file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-dwo">
+<code class="descname">--strip-dwo</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-dwo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove all DWARF .dwo sections from the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-non-alloc">
+<code class="descname">--strip-non-alloc</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-non-alloc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove from the output all non-allocatable sections that are not within
+segments.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-strip-sections">
+<code class="descname">--strip-sections</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-strip-sections" title="Permalink to this definition">¶</a></dt>
+<dd><p>Remove from the output all section headers and all section data not within
+segments. Note that many tools will not be able to use an object without
+section headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-target">
+<code class="descname">--target</code><code class="descclassname"> <format></code><code class="descclassname">, </code><code class="descname">-F</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-target" title="Permalink to this definition">¶</a></dt>
+<dd><p>Equivalent to <a class="reference internal" href="#cmdoption-llvm-objcopy-input-target"><code class="xref std std-option docutils literal notranslate"><span class="pre">--input-target</span></code></a> and <a class="reference internal" href="#cmdoption-llvm-objcopy-output-target"><code class="xref std std-option docutils literal notranslate"><span class="pre">--output-target</span></code></a> for the
+specified format. See <a class="reference internal" href="#supported-formats">SUPPORTED FORMATS</a> for a list of valid <code class="docutils literal notranslate"><span class="pre"><format></span></code>
+values.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-weaken-symbol">
+<code class="descname">--weaken-symbol</code><code class="descclassname"> <symbol></code><code class="descclassname">, </code><code class="descname">-W</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-weaken-symbol" title="Permalink to this definition">¶</a></dt>
+<dd><p>Mark any global symbol named <code class="docutils literal notranslate"><span class="pre"><symbol></span></code> as a weak symbol in the output. Can
+be specified multiple times to mark multiple symbols as weak.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-weaken-symbols">
+<code class="descname">--weaken-symbols</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-llvm-objcopy-weaken-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Read a list of names from the file <code class="docutils literal notranslate"><span class="pre"><filename></span></code> and mark global symbols with
+those names as weak in the output. In the file, each line represents a single
+symbol, with leading and trailing whitespace ignored, as is anything following
+a â#â. Can be specified multiple times to read names from multiple files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objcopy-weaken">
+<code class="descname">--weaken</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objcopy-weaken" title="Permalink to this definition">¶</a></dt>
+<dd><p>Mark all defined global symbols as weak in the output.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="supported-formats">
+<h2>SUPPORTED FORMATS<a class="headerlink" href="#supported-formats" title="Permalink to this headline">¶</a></h2>
+<p>The following values are currently supported by <strong class="program">llvm-objcopy</strong> for the
+<a class="reference internal" href="#cmdoption-llvm-objcopy-input-target"><code class="xref std std-option docutils literal notranslate"><span class="pre">--input-target</span></code></a>, <a class="reference internal" href="#cmdoption-llvm-objcopy-output-target"><code class="xref std std-option docutils literal notranslate"><span class="pre">--output-target</span></code></a>, and <a class="reference internal" href="#cmdoption-llvm-objcopy-target"><code class="xref std std-option docutils literal notranslate"><span class="pre">--target</span></code></a>
+options. For GNU <strong class="program">objcopy</strong> compatibility, the values are all bfdnames.</p>
+<ul class="simple">
+<li><cite>binary</cite></li>
+<li><cite>ihex</cite></li>
+<li><cite>elf32-i386</cite></li>
+<li><cite>elf32-x86-64</cite></li>
+<li><cite>elf64-x86-64</cite></li>
+<li><cite>elf32-iamcu</cite></li>
+<li><cite>elf32-littlearm</cite></li>
+<li><cite>elf64-aarch64</cite></li>
+<li><cite>elf64-littleaarch64</cite></li>
+<li><cite>elf32-littleriscv</cite></li>
+<li><cite>elf64-littleriscv</cite></li>
+<li><cite>elf32-powerpc</cite></li>
+<li><cite>elf32-powerpcle</cite></li>
+<li><cite>elf64-powerpc</cite></li>
+<li><cite>elf64-powerpcle</cite></li>
+<li><cite>elf32-bigmips</cite></li>
+<li><cite>elf32-ntradbigmips</cite></li>
+<li><cite>elf32-ntradlittlemips</cite></li>
+<li><cite>elf32-tradbigmips</cite></li>
+<li><cite>elf32-tradlittlemips</cite></li>
+<li><cite>elf64-tradbigmips</cite></li>
+<li><cite>elf64-tradlittlemips</cite></li>
+<li><cite>elf32-sparc</cite></li>
+<li><cite>elf32-sparcel</cite></li>
+</ul>
+<p>Additionally, all targets except <cite>binary</cite> and <cite>ihex</cite> can have <cite>-freebsd</cite> as a
+suffix.</p>
+</div>
+<div class="section" id="binary-input-and-output">
+<h2>BINARY INPUT AND OUTPUT<a class="headerlink" href="#binary-input-and-output" title="Permalink to this headline">¶</a></h2>
+<p>If <cite>binary</cite> is used as the value for <a class="reference internal" href="#cmdoption-llvm-objcopy-input-target"><code class="xref std std-option docutils literal notranslate"><span class="pre">--input-target</span></code></a>, the input file
+will be embedded as a data section in an ELF relocatable object, with symbols
+<code class="docutils literal notranslate"><span class="pre">_binary_<file_name>_start</span></code>, <code class="docutils literal notranslate"><span class="pre">_binary_<file_name>_end</span></code>, and
+<code class="docutils literal notranslate"><span class="pre">_binary_<file_name>_size</span></code> representing the start, end and size of the data,
+where <code class="docutils literal notranslate"><span class="pre"><file_name></span></code> is the path of the input file as specified on the command
+line with non-alphanumeric characters converted to <code class="docutils literal notranslate"><span class="pre">_</span></code>.</p>
+<p>If <cite>binary</cite> is used as the value for <a class="reference internal" href="#cmdoption-llvm-objcopy-output-target"><code class="xref std std-option docutils literal notranslate"><span class="pre">--output-target</span></code></a>, the output file
+will be a raw binary file, containing the memory image of the input file.
+Symbols and relocation information will be discarded. The image will start at
+the address of the first loadable section in the output.</p>
+</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-objcopy</strong> exits with a non-zero exit code if there is an error.
+Otherwise, it exits with code 0.</p>
+</div>
+<div class="section" id="bugs">
+<h2>BUGS<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h2>
+<p>To report bugs, please visit <<a class="reference external" href="http://llvm.org/bugs/">http://llvm.org/bugs/</a>>.</p>
+<p>There is a known issue with <a class="reference internal" href="#cmdoption-llvm-objcopy-input-target"><code class="xref std std-option docutils literal notranslate"><span class="pre">--input-target</span></code></a> and <a class="reference internal" href="#cmdoption-llvm-objcopy-target"><code class="xref std std-option docutils literal notranslate"><span class="pre">--target</span></code></a>
+causing only <code class="docutils literal notranslate"><span class="pre">binary</span></code> and <code class="docutils literal notranslate"><span class="pre">ihex</span></code> formats to have any effect. Other values
+will be ignored and <strong class="program">llvm-objcopy</strong> will attempt to guess the input
+format.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-strip.html">llvm-strip(1)</a></em></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-objdump.html" title="llvm-objdump - LLVMâs object file dumper"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-nm.html" title="llvm-nm - list LLVM bitcode and object fileâs symbol table"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-objdump.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-objdump.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-objdump.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-objdump.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,540 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-objdump - LLVMâs object file dumper — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-ranlib - generates an archive index" href="llvm-ranlib.html" />
+ <link rel="prev" title="llvm-objcopy - object copying and editing tool" href="llvm-objcopy.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-ranlib.html" title="llvm-ranlib - generates an archive index"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-objcopy.html" title="llvm-objcopy - object copying and editing 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 class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-objdump-llvm-s-object-file-dumper">
+<h1>llvm-objdump - LLVMâs object file dumper<a class="headerlink" href="#llvm-objdump-llvm-s-object-file-dumper" 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-objdump</strong> [<em>commands</em>] [<em>options</em>] [<em>filenamesâ¦</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-objdump</strong> utility prints the contents of object files and
+final linked images named on the command line. If no file name is specified,
+<strong class="program">llvm-objdump</strong> will attempt to read from <em>a.out</em>. If <em>-</em> is used as a
+file name, <strong class="program">llvm-objdump</strong> will process a file on its standard input
+stream.</p>
+</div>
+<div class="section" id="commands">
+<h2>COMMANDS<a class="headerlink" href="#commands" title="Permalink to this headline">¶</a></h2>
+<p>At least one of the following commands are required, and some commands can be
+combined with other commands:</p>
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-a">
+<code class="descname">-a</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--archive-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-a" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the information contained within an archiveâs headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-d">
+<code class="descname">-d</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--disassemble</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-d" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disassemble all text sections found in the input files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-disassemble-all">
+<code class="descname">-D</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--disassemble-all</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-disassemble-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disassemble all sections found in the input files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-disassemble-functions">
+<code class="descname">--disassemble-functions</code><code class="descclassname">=<symbol1[,symbol2,...]></code><a class="headerlink" href="#cmdoption-llvm-objdump-disassemble-functions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disassemble only the specified symbols. Takes demangled symbol names when
+<a class="reference internal" href="#cmdoption-llvm-objdump-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">--demangle</span></code></a> is specified, otherwise takes mangled symbol names.
+Implies <a class="reference internal" href="#cmdoption-llvm-objdump-d"><code class="xref std std-option docutils literal notranslate"><span class="pre">--disassemble</span></code></a>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-dwarf">
+<code class="descname">--dwarf</code><code class="descclassname">=<value></code><a class="headerlink" href="#cmdoption-llvm-objdump-dwarf" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the specified DWARF debug sections. The supported values are:</p>
+<p><cite>frames</cite> - .debug_frame</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-f">
+<code class="descname">-f</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--file-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the contents of the overall file header.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-fault-map-section">
+<code class="descname">--fault-map-section</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-fault-map-section" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the content of the fault map section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-h">
+<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--headers</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--section-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-h" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display summaries of the headers for each section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-help">
+<code class="descname">--help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display usage information and exit. Does not stack with other commands.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-p">
+<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--private-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-p" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display format-specific file headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-r">
+<code class="descname">-r</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--reloc</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-r" 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-llvm-objdump-dynamic-reloc">
+<code class="descname">-R</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--dynamic-reloc</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-dynamic-reloc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic relocation entries in the file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-raw-clang-ast">
+<code class="descname">--raw-clang-ast</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-raw-clang-ast" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the raw binary contents of the clang AST section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-s">
+<code class="descname">-s</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--full-contents</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-s" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the contents of each section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-t">
+<code class="descname">-t</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--syms</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-t" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-u">
+<code class="descname">-u</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--unwind-info</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-u" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the unwind info of the input(s).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-version">
+<code class="descname">--version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of this program. Does not stack with other commands.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-x">
+<code class="descname">-x</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--all-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-x" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all available header information. Equivalent to specifying
+<a class="reference internal" href="#cmdoption-llvm-objdump-a"><code class="xref std std-option docutils literal notranslate"><span class="pre">--archive-headers</span></code></a>, <a class="reference internal" href="#cmdoption-llvm-objdump-f"><code class="xref std std-option docutils literal notranslate"><span class="pre">--file-headers</span></code></a>,
+<a class="reference internal" href="#cmdoption-llvm-objdump-p"><code class="xref std std-option docutils literal notranslate"><span class="pre">--private-headers</span></code></a>, <a class="reference internal" href="#cmdoption-llvm-objdump-r"><code class="xref std std-option docutils literal notranslate"><span class="pre">--reloc</span></code></a>, <a class="reference internal" href="#cmdoption-llvm-objdump-h"><code class="xref std std-option docutils literal notranslate"><span class="pre">--section-headers</span></code></a>,
+and <a class="reference internal" href="#cmdoption-llvm-objdump-t"><code class="xref std std-option docutils literal notranslate"><span class="pre">--syms</span></code></a>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-objdump</strong> supports the following options:</p>
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-adjust-vma">
+<code class="descname">--adjust-vma</code><code class="descclassname">=<offset></code><a class="headerlink" href="#cmdoption-llvm-objdump-adjust-vma" title="Permalink to this definition">¶</a></dt>
+<dd><p>Increase the displayed address in disassembly or section header printing by
+the specified offset.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-arch-name">
+<code class="descname">--arch-name</code><code class="descclassname">=<string></code><a class="headerlink" href="#cmdoption-llvm-objdump-arch-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the target architecture when disassembling. Use <a class="reference internal" href="#cmdoption-llvm-objdump-version"><code class="xref std std-option docutils literal notranslate"><span class="pre">--version</span></code></a>
+for a list of available targets.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-c">
+<code class="descname">-C</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--demangle</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-c" title="Permalink to this definition">¶</a></dt>
+<dd><p>Demangle symbol names in the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-j">
+<code class="descname">-j</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--section</code><code class="descclassname">=<section1[,section2,...]></code><a class="headerlink" href="#cmdoption-llvm-objdump-j" title="Permalink to this definition">¶</a></dt>
+<dd><p>Perform commands on the specified sections only. For Mach-O use
+<cite>segment,section</cite> to specify the section name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-l">
+<code class="descname">-l</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--line-numbers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-l" title="Permalink to this definition">¶</a></dt>
+<dd><p>When disassembling, display source line numbers. Implies
+<a class="reference internal" href="#cmdoption-llvm-objdump-d"><code class="xref std std-option docutils literal notranslate"><span class="pre">--disassemble</span></code></a>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-m">
+<code class="descname">-M</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--disassembler-options</code><code class="descclassname">=<opt1[,opt2,...]></code><a class="headerlink" href="#cmdoption-llvm-objdump-m" title="Permalink to this definition">¶</a></dt>
+<dd><p>Pass target-specific disassembler options. Currently supported for ARM targets
+only. Available options are <code class="docutils literal notranslate"><span class="pre">reg-names-std</span></code> and <code class="docutils literal notranslate"><span class="pre">reg-names-raw</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-mcpu">
+<code class="descname">--mcpu</code><code class="descclassname">=<cpu-name></code><a class="headerlink" href="#cmdoption-llvm-objdump-mcpu" title="Permalink to this definition">¶</a></dt>
+<dd><p>Target a specific CPU type for disassembly. Specify <code class="docutils literal notranslate"><span class="pre">--mcpu=help</span></code> to display
+available CPUs.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-mattr">
+<code class="descname">--mattr</code><code class="descclassname">=<a1,+a2,-a3,...></code><a class="headerlink" href="#cmdoption-llvm-objdump-mattr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable/disable target-specific attributes. Specify <code class="docutils literal notranslate"><span class="pre">--mcpu=help</span></code> to display
+the available attributes.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-no-leading-addr">
+<code class="descname">--no-leading-addr</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-no-leading-addr" title="Permalink to this definition">¶</a></dt>
+<dd><p>When disassembling, do not print leading addresses.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-no-show-raw-insn">
+<code class="descname">--no-show-raw-insn</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-no-show-raw-insn" title="Permalink to this definition">¶</a></dt>
+<dd><p>When disassembling, do not print the raw bytes of each instruction.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-print-imm-hex">
+<code class="descname">--print-imm-hex</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-print-imm-hex" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use hex format when printing immediate values in disassembly output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-source">
+<code class="descname">-S</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--source</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-source" title="Permalink to this definition">¶</a></dt>
+<dd><p>When disassembling, display source interleaved with the disassembly. Implies
+<a class="reference internal" href="#cmdoption-llvm-objdump-d"><code class="xref std std-option docutils literal notranslate"><span class="pre">--disassemble</span></code></a>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-show-lma">
+<code class="descname">--show-lma</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-show-lma" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the LMA column when dumping ELF section headers. Defaults to off
+unless any section has different VMA and LMAs.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-start-address">
+<code class="descname">--start-address</code><code class="descclassname">=<address></code><a class="headerlink" href="#cmdoption-llvm-objdump-start-address" title="Permalink to this definition">¶</a></dt>
+<dd><p>When disassembling, only disassemble from the specified address.</p>
+<p>When printing relocations, only print the relocations patching offsets from at least <code class="docutils literal notranslate"><span class="pre">address</span></code>.</p>
+<p>When printing symbols, only print symbols with a value of at least <code class="docutils literal notranslate"><span class="pre">address</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-stop-address">
+<code class="descname">--stop-address</code><code class="descclassname">=<address></code><a class="headerlink" href="#cmdoption-llvm-objdump-stop-address" title="Permalink to this definition">¶</a></dt>
+<dd><p>When disassembling, only disassemble up to, but not including the specified address.</p>
+<p>When printing relocations, only print the relocations patching offsets up to <code class="docutils literal notranslate"><span class="pre">address</span></code>.</p>
+<p>When printing symbols, only print symbols with a value up to <code class="docutils literal notranslate"><span class="pre">address</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-triple">
+<code class="descname">--triple</code><code class="descclassname">=<string></code><a class="headerlink" href="#cmdoption-llvm-objdump-triple" title="Permalink to this definition">¶</a></dt>
+<dd><p>Target triple to disassemble for, see <code class="docutils literal notranslate"><span class="pre">--version</span></code> for available targets.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-w">
+<code class="descname">-w</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--wide</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-w" title="Permalink to this definition">¶</a></dt>
+<dd><p>Ignored for compatibility with GNU objdump.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-x86-asm-syntax">
+<code class="descname">--x86-asm-syntax</code><code class="descclassname">=<style></code><a class="headerlink" href="#cmdoption-llvm-objdump-x86-asm-syntax" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <a class="reference internal" href="#cmdoption-llvm-objdump-d"><code class="xref std std-option docutils literal notranslate"><span class="pre">--disassemble</span></code></a>, choose style of code to emit from
+X86 backend. Supported values are:</p>
+<blockquote>
+<div><dl class="option">
+<dt id="cmdoption-llvm-objdump-arg-att">
+<code class="descname">att</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-arg-att" title="Permalink to this definition">¶</a></dt>
+<dd><p>AT&T-style assembly</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-arg-intel">
+<code class="descname">intel</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-arg-intel" title="Permalink to this definition">¶</a></dt>
+<dd><p>Intel-style assembly</p>
+</dd></dl>
+
+</div></blockquote>
+<p>The default disassembly style is <strong>att</strong>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-z">
+<code class="descname">-z</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--disassemble-zeroes</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-z" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not skip blocks of zeroes when disassembling.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-arg-file">
+<code class="descname">@<FILE></code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-arg-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>Read command-line options and commands from response file <cite><FILE></cite>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="mach-o-only-options-and-commands">
+<h2>MACH-O ONLY OPTIONS AND COMMANDS<a class="headerlink" href="#mach-o-only-options-and-commands" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-arch">
+<code class="descname">--arch</code><code class="descclassname">=<architecture></code><a class="headerlink" href="#cmdoption-llvm-objdump-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the architecture to disassemble. see <code class="docutils literal notranslate"><span class="pre">--version</span></code> for available
+architectures.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-archive-member-offsets">
+<code class="descname">--archive-member-offsets</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-archive-member-offsets" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the offset to each archive member for Mach-O archives (requires
+<a class="reference internal" href="#cmdoption-llvm-objdump-a"><code class="xref std std-option docutils literal notranslate"><span class="pre">--archive-headers</span></code></a>).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-bind">
+<code class="descname">--bind</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-bind" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display binding info</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-cfg">
+<code class="descname">--cfg</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-cfg" title="Permalink to this definition">¶</a></dt>
+<dd><p>Create a CFG for every symbol in the object file and write it to a graphviz
+file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-data-in-code">
+<code class="descname">--data-in-code</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-data-in-code" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the data in code table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-dis-symname">
+<code class="descname">--dis-symname</code><code class="descclassname">=<name></code><a class="headerlink" href="#cmdoption-llvm-objdump-dis-symname" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disassemble just the specified symbolâs instructions.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-dylibs-used">
+<code class="descname">--dylibs-used</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-dylibs-used" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the shared libraries used for linked files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-dsym">
+<code class="descname">--dsym</code><code class="descclassname">=<string></code><a class="headerlink" href="#cmdoption-llvm-objdump-dsym" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use .dSYM file for debug info.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-dylib-id">
+<code class="descname">--dylib-id</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-dylib-id" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the shared libraryâs ID for dylib files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-exports-trie">
+<code class="descname">--exports-trie</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-exports-trie" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display exported symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-g">
+<code class="descname">-g</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-g" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print line information from debug info if available.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-full-leading-addr">
+<code class="descname">--full-leading-addr</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-full-leading-addr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print the full leading address when disassembling.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-indirect-symbols">
+<code class="descname">--indirect-symbols</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-indirect-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the indirect symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-info-plist">
+<code class="descname">--info-plist</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-info-plist" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the info plist section as strings.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-lazy-bind">
+<code class="descname">--lazy-bind</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-lazy-bind" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display lazy binding info.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-link-opt-hints">
+<code class="descname">--link-opt-hints</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-link-opt-hints" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the linker optimization hints.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-macho">
+<code class="descname">-m</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--macho</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-macho" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use Mach-O specific object file parser. Commands and other options may behave
+differently when used with <code class="docutils literal notranslate"><span class="pre">--macho</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-no-leading-headers">
+<code class="descname">--no-leading-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-no-leading-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not print any leading headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-no-symbolic-operands">
+<code class="descname">--no-symbolic-operands</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-no-symbolic-operands" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not print symbolic operands when disassembling.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-non-verbose">
+<code class="descname">--non-verbose</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-non-verbose" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the information for Mach-O objects in non-verbose or numeric form.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-objc-meta-data">
+<code class="descname">--objc-meta-data</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-objc-meta-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the Objective-C runtime meta data.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-private-header">
+<code class="descname">--private-header</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-private-header" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display only the first format specific file header.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-rebase">
+<code class="descname">--rebase</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-rebase" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display rebasing information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-universal-headers">
+<code class="descname">--universal-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-universal-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display universal headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-objdump-weak-bind">
+<code class="descname">--weak-bind</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-objdump-weak-bind" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display weak binding information.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="bugs">
+<h2>BUGS<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h2>
+<p>To report bugs, please visit <<a class="reference external" href="http://llvm.org/bugs/">http://llvm.org/bugs/</a>>.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-nm.html">llvm-nm(1)</a></em>, <em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-readelf.html">llvm-readelf(1)</a></em>, <em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-readobj.html">llvm-readobj(1)</a></em></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-ranlib.html" title="llvm-ranlib - generates an archive index"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-objcopy.html" title="llvm-objcopy - object copying and editing tool"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-pdbutil.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-pdbutil.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-pdbutil.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-pdbutil.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,850 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-pdbutil - PDB File forensics and diagnostics — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Getting Started with the LLVM System" href="../GettingStarted.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="../GettingStarted.html" title="Getting Started with the LLVM System"
+ 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 class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <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"><span class="std std-ref">pretty</span></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"><span class="std std-ref">dump</span></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"><span class="std std-ref">bytes</span></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"><span class="std std-ref">yaml2pdb</span></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"><span class="std std-ref">pdb2yaml</span></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"><span class="std std-ref">merge</span></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">
+<code class="descname">-exclude-compilands</code><code class="descclassname">=<string></code><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">
+<code class="descname">-exclude-symbols</code><code class="descclassname">=<string></code><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">
+<code class="descname">-exclude-types</code><code class="descclassname">=<string></code><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">
+<code class="descname">-include-compilands</code><code class="descclassname">=<string></code><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">
+<code class="descname">-include-symbols</code><code class="descclassname">=<string></code><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">
+<code class="descname">-include-types</code><code class="descclassname">=<string></code><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">
+<code class="descname">-min-class-padding</code><code class="descclassname">=<uint></code><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">
+<code class="descname">-min-class-padding-imm</code><code class="descclassname">=<uint></code><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">
+<code class="descname">-min-type-size</code><code class="descclassname">=<uint></code><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">
+<code class="descname">-no-compiler-generated</code><code class="descclassname"></code><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">
+<code class="descname">-no-enum-definitions</code><code class="descclassname"></code><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">
+<code class="descname">-no-system-libs</code><code class="descclassname"></code><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">
+<code class="descname">-all</code><code class="descclassname"></code><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">
+<code class="descname">-class-definitions</code><code class="descclassname">=<format></code><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 notranslate"><div class="highlight"><pre><span></span>=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">
+<code class="descname">-class-order</code><code class="descclassname"></code><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 notranslate"><div class="highlight"><pre><span></span>=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">
+<code class="descname">-class-recurse-depth</code><code class="descclassname">=<uint></code><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">
+<code class="descname">-classes</code><code class="descclassname"></code><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">
+<code class="descname">-compilands</code><code class="descclassname"></code><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">
+<code class="descname">-enums</code><code class="descclassname"></code><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">
+<code class="descname">-externals</code><code class="descclassname"></code><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">
+<code class="descname">-globals</code><code class="descclassname"></code><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">
+<code class="descname">-lines</code><code class="descclassname"></code><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">
+<code class="descname">-module-syms</code><code class="descclassname"></code><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">
+<code class="descname">-sym-types</code><code class="descclassname">=<types></code><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 notranslate"><div class="highlight"><pre><span></span>=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">
+<code class="descname">-symbol-order</code><code class="descclassname">=<order></code><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 notranslate"><div class="highlight"><pre><span></span>=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">
+<code class="descname">-typedefs</code><code class="descclassname"></code><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">
+<code class="descname">-types</code><code class="descclassname"></code><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">
+<code class="descname">-color-output</code><code class="descclassname"></code><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">
+<code class="descname">-load-address</code><code class="descclassname">=<uint></code><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"><span class="doc">The PDB File Format</span></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">
+<code class="descname">-streams</code><code class="descclassname"></code><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">
+<code class="descname">-stream-blocks</code><code class="descclassname"></code><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"><code class="xref std std-option docutils literal notranslate"><span class="pre">-streams</span></code></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">
+<code class="descname">-summary</code><code class="descclassname"></code><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">
+<code class="descname">-modi</code><code class="descclassname">=<uint></code><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">
+<code class="descname">-files</code><code class="descclassname"></code><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">
+<code class="descname">-il</code><code class="descclassname"></code><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">
+<code class="descname">-l</code><code class="descclassname"></code><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">
+<code class="descname">-modules</code><code class="descclassname"></code><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">
+<code class="descname">-xme</code><code class="descclassname"></code><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">
+<code class="descname">-xmi</code><code class="descclassname"></code><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">
+<code class="descname">-globals</code><code class="descclassname"></code><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">
+<code class="descname">-global-extras</code><code class="descclassname"></code><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">
+<code class="descname">-publics</code><code class="descclassname"></code><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">
+<code class="descname">-public-extras</code><code class="descclassname"></code><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">
+<code class="descname">-symbols</code><code class="descclassname"></code><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">
+<code class="descname">-sym-data</code><code class="descclassname"></code><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"><code class="xref std std-option docutils literal notranslate"><span class="pre">-symbols</span></code></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">
+<code class="descname">-types</code><code class="descclassname"></code><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">
+<code class="descname">-type-extras</code><code class="descclassname"></code><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">
+<code class="descname">-type-data</code><code class="descclassname"></code><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">
+<code class="descname">-type-index</code><code class="descclassname">=<uint></code><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">
+<code class="descname">-ids</code><code class="descclassname"></code><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">
+<code class="descname">-id-extras</code><code class="descclassname"></code><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">
+<code class="descname">-id-data</code><code class="descclassname"></code><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">
+<code class="descname">-id-index</code><code class="descclassname">=<uint></code><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">
+<code class="descname">-dependents</code><code class="descclassname"></code><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"><code class="xref std std-option docutils literal notranslate"><span class="pre">-type-index</span></code></a> or <a class="reference internal" href="#cmdoption-llvm-pdbutil-dump-id-index"><code class="xref std std-option docutils literal notranslate"><span class="pre">-id-index</span></code></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">
+<code class="descname">-all</code><code class="descclassname"></code><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">
+<code class="descname">-section-contribs</code><code class="descclassname"></code><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">
+<code class="descname">-section-headers</code><code class="descclassname"></code><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">
+<code class="descname">-section-map</code><code class="descclassname"></code><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">
+<code class="descname">-string-table</code><code class="descclassname"></code><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">
+<code class="descname">-block-range</code><code class="descclassname">=<start[-end]></code><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">
+<code class="descname">-byte-range</code><code class="descclassname">=<start[-end]></code><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">
+<code class="descname">-fpm</code><code class="descclassname"></code><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">
+<code class="descname">-stream-data</code><code class="descclassname">=<string></code><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">
+<code class="descname">-name-map</code><code class="descclassname"></code><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">
+<code class="descname">-ec</code><code class="descclassname"></code><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">
+<code class="descname">-files</code><code class="descclassname"></code><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">
+<code class="descname">-modi</code><code class="descclassname"></code><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">
+<code class="descname">-sc</code><code class="descclassname"></code><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">
+<code class="descname">-sm</code><code class="descclassname"></code><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">
+<code class="descname">-type-server</code><code class="descclassname"></code><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">
+<code class="descname">-mod</code><code class="descclassname">=<uint></code><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">
+<code class="descname">-chunks</code><code class="descclassname"></code><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">
+<code class="descname">-split-chunks</code><code class="descclassname"></code><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"><code class="xref std std-option docutils literal notranslate"><span class="pre">-chunks</span></code></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">
+<code class="descname">-syms</code><code class="descclassname"></code><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">
+<code class="descname">-id</code><code class="descclassname">=<uint></code><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">
+<code class="descname">-type</code><code class="descclassname">=<uint></code><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"><span class="std std-ref">llvm-pdbutil pdb2yaml</span></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">
+<code class="descname">-pdb</code><code class="descclassname">=<file-name></code><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">
+<code class="descname">-pdb</code><code class="descclassname">=<file-name></code><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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="../GettingStarted.html" title="Getting Started with the LLVM System"
+ >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 class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-profdata.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-profdata.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-profdata.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-profdata.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,421 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-profdata - Profile data tool — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <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"><span class="std std-ref">merge</span></a></li>
+<li><a class="reference internal" href="#profdata-show"><span class="std std-ref">show</span></a></li>
+<li><a class="reference internal" href="#profdata-overlap"><span class="std std-ref">overlap</span></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 <code class="docutils literal notranslate"><span class="pre">-weighted-input</span></code> option.</p>
+<p>Profiles passed in via <code class="docutils literal notranslate"><span class="pre">-weighted-input</span></code>, <code class="docutils literal notranslate"><span class="pre">-input-files</span></code>, 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">
+<code class="descname">-help</code><code class="descclassname"></code><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">
+<code class="descname">-output</code><code class="descclassname">=output</code><code class="descclassname">, </code><code class="descname">-o</code><code class="descclassname">=output</code><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 <code class="docutils literal notranslate"><span class="pre">-</span></code> 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">
+<code class="descname">-weighted-input</code><code class="descclassname">=weight,filename</code><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 <code class="docutils literal notranslate"><span class="pre">filename</span></code> will be scaled (multiplied) by the supplied
+<code class="docutils literal notranslate"><span class="pre">weight</span></code>, where where <code class="docutils literal notranslate"><span class="pre">weight</span></code> 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">
+<code class="descname">-input-files</code><code class="descclassname">=path</code><code class="descclassname">, </code><code class="descname">-f</code><code class="descclassname">=path</code><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-remapping-file">
+<code class="descname">-remapping-file</code><code class="descclassname">=path</code><code class="descclassname">, </code><code class="descname">-r</code><code class="descclassname">=path</code><a class="headerlink" href="#cmdoption-llvm-profdata-merge-remapping-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a file which contains a remapping from symbol names in the input
+profile to the symbol names that should be used in the output profile. The
+file should consist of lines of the form <code class="docutils literal notranslate"><span class="pre"><input-symbol></span> <span class="pre"><output-symbol></span></code>.
+Blank lines and lines starting with <code class="docutils literal notranslate"><span class="pre">#</span></code> are skipped.</p>
+<p>The <a class="reference internal" href="llvm-cxxmap.html"><span class="doc">llvm-cxxmap</span></a> tool can be used to generate the symbol
+remapping file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-merge-instr">
+<code class="descname">-instr</code><code class="descclassname"> (default)</code><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">
+<code class="descname">-sample</code><code class="descclassname"></code><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">
+<code class="descname">-binary</code><code class="descclassname"> (default)</code><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">
+<code class="descname">-text</code><code class="descclassname"></code><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">
+<code class="descname">-gcc</code><code class="descclassname"></code><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">
+<code class="descname">-sparse[</code><code class="descclassname">=true|false]</code><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">
+<code class="descname">-num-threads</code><code class="descclassname">=N</code><code class="descclassname">, </code><code class="descname">-j</code><code class="descclassname">=N</code><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-default notranslate"><div class="highlight"><pre><span></span><span class="n">llvm</span><span class="o">-</span><span class="n">profdata</span> <span class="n">merge</span> <span class="n">foo</span><span class="o">.</span><span class="n">profdata</span> <span class="n">bar</span><span class="o">.</span><span class="n">profdata</span> <span class="n">baz</span><span class="o">.</span><span class="n">profdata</span> <span class="o">-</span><span class="n">output</span> <span class="n">merged</span><span class="o">.</span><span class="n">profdata</span>
+</pre></div>
+</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">llvm</span><span class="o">-</span><span class="n">profdata</span> <span class="n">merge</span> <span class="o">-</span><span class="n">weighted</span><span class="o">-</span><span class="nb">input</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span><span class="n">foo</span><span class="o">.</span><span class="n">profdata</span> <span class="n">bar</span><span class="o">.</span><span class="n">profdata</span> <span class="n">baz</span><span class="o">.</span><span class="n">profdata</span> <span class="o">-</span><span class="n">output</span> <span class="n">merged</span><span class="o">.</span><span class="n">profdata</span>
+</pre></div>
+</div>
+<p>Exactly equivalent to the previous invocation (explicit form; useful for programmatic invocation):</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">llvm</span><span class="o">-</span><span class="n">profdata</span> <span class="n">merge</span> <span class="o">-</span><span class="n">weighted</span><span class="o">-</span><span class="nb">input</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span><span class="n">foo</span><span class="o">.</span><span class="n">profdata</span> <span class="o">-</span><span class="n">weighted</span><span class="o">-</span><span class="nb">input</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span><span class="n">bar</span><span class="o">.</span><span class="n">profdata</span> <span class="o">-</span><span class="n">weighted</span><span class="o">-</span><span class="nb">input</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span><span class="n">baz</span><span class="o">.</span><span class="n">profdata</span> <span class="o">-</span><span class="n">output</span> <span class="n">merged</span><span class="o">.</span><span class="n">profdata</span>
+</pre></div>
+</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 <code class="docutils literal notranslate"><span class="pre">-</span></code>, 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">
+<code class="descname">-all-functions</code><code class="descclassname"></code><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">
+<code class="descname">-counts</code><code class="descclassname"></code><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">
+<code class="descname">-function</code><code class="descclassname">=string</code><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">
+<code class="descname">-help</code><code class="descclassname"></code><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">
+<code class="descname">-output</code><code class="descclassname">=output</code><code class="descclassname">, </code><code class="descname">-o</code><code class="descclassname">=output</code><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 <code class="docutils literal notranslate"><span class="pre">-</span></code> 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">
+<code class="descname">-instr</code><code class="descclassname"> (default)</code><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">
+<code class="descname">-text</code><code class="descclassname"></code><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">
+<code class="descname">-topn</code><code class="descclassname">=n</code><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 <code class="docutils literal notranslate"><span class="pre">n</span></code> 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">
+<code class="descname">-sample</code><code class="descclassname"></code><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">
+<code class="descname">-memop-sizes</code><code class="descclassname"></code><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>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-value-cutoff">
+<code class="descname">-value-cutoff</code><code class="descclassname">=n</code><a class="headerlink" href="#cmdoption-llvm-profdata-show-value-cutoff" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show only those functions whose max count values are greater or equal to <code class="docutils literal notranslate"><span class="pre">n</span></code>.
+By default, the value-cutoff is set to 0.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-list-below-cutoff">
+<code class="descname">-list-below-cutoff</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-profdata-show-list-below-cutoff" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only output names of functions whose max count value are below the cutoff
+value.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-show-showcs">
+<code class="descname">-showcs</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-profdata-show-showcs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only show context sensitive profile counts. The default is to filter all
+context sensitive profile counts.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="overlap">
+<span id="profdata-overlap"></span><h2>OVERLAP<a class="headerlink" href="#overlap" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id6">
+<h3>SYNOPSIS<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata overlap</strong> [<em>options</em>] [<em>base profile file</em>] [<em>test profile file</em>]</p>
+</div>
+<div class="section" id="id7">
+<h3>DESCRIPTION<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-profdata overlap</strong> takes two profile data files and displays the
+<em>overlap</em> of counter distribution between the whole files and between any of the
+specified functions.</p>
+<p>In this command, <em>overlap</em> is defined as follows:
+Suppose <em>base profile file</em> has the following counts:
+{c1_1, c1_2, â¦, c1_n, c1_u_1, c2_u_2, â¦, c2_u_s},
+and <em>test profile file</em> has
+{c2_1, c2_2, â¦, c2_n, c2_v_1, c2_v_2, â¦, c2_v_t}.
+Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and
+c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in)
+<em>base profile file</em> and <em>test profile file</em>, respectively.
+Let sum_1 = c1_1 + c1_2 + ⦠+ c1_n + c1_u_1 + c2_u_2 + ⦠+ c2_u_s, and
+sum_2 = c2_1 + c2_2 + ⦠+ c2_n + c2_v_1 + c2_v_2 + ⦠+ c2_v_t.
+<em>overlap</em> = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + â¦
++ min(c1_n/sum_1, c2_n/sum_2).</p>
+<p>The result overlap distribution is a percentage number, ranging from 0.0% to
+100.0%, where 0.0% means there is no overlap and 100.0% means a perfect
+overlap.</p>
+<p>Here is an example, if <em>base profile file</em> has counts of {400, 600}, and
+<em>test profile file</em> has matched counts of {60000, 40000}. The <em>overlap</em> is 80%.</p>
+</div>
+<div class="section" id="id8">
+<h3>OPTIONS<a class="headerlink" href="#id8" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-overlap-function">
+<code class="descname">-function</code><code class="descclassname">=string</code><a class="headerlink" href="#cmdoption-llvm-profdata-overlap-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-overlap-help">
+<code class="descname">-help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-profdata-overlap-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-overlap-o">
+<code class="descname">-o</code><code class="descclassname">=output or -o output</code><a class="headerlink" href="#cmdoption-llvm-profdata-overlap-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output file name. If <em>output</em> is <code class="docutils literal notranslate"><span class="pre">-</span></code> or it isnât specified,
+then the output is sent to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-overlap-value-cutoff">
+<code class="descname">-value-cutoff</code><code class="descclassname">=n</code><a class="headerlink" href="#cmdoption-llvm-profdata-overlap-value-cutoff" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show only those functions whose max count values are greater or equal to <code class="docutils literal notranslate"><span class="pre">n</span></code>.
+By default, the value-cutoff is set to max of unsigned long long.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-profdata-overlap-cs">
+<code class="descname">-cs</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-profdata-overlap-cs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only show overlap for the context sensitive profile counts. The default is to show
+non-context sensitive profile counts.</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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-ranlib.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-ranlib.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-ranlib.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-ranlib.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,106 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-ranlib - generates an archive index — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-readelf - GNU-style LLVM Object Reader" href="llvm-readelf.html" />
+ <link rel="prev" title="llvm-objdump - LLVMâs object file dumper" href="llvm-objdump.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-readelf.html" title="llvm-readelf - GNU-style LLVM Object Reader"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-objdump.html" title="llvm-objdump - LLVMâs object file dumper"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-ranlib-generates-an-archive-index">
+<span id="llvm-ranlib-generates-an-archive-index"></span><h1>llvm-ranlib - generates an archive index<a class="headerlink" href="#llvm-ranlib-generates-an-archive-index" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<span id="synopsis"></span><h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-ranlib</strong> [<em>options</em>]</p>
+</div>
+<div class="section" id="description">
+<span id="description"></span><h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-ranlib</strong> is an alias for the <a class="reference external" href="llvm-ar.html">llvm-ar</a> tool that generates
+an index for an archive. It can be used as a replacement for GNUâs <strong>ranlib</strong>
+tool.</p>
+<p>Running <strong>llvm-ranlib</strong> is equivalent to running <strong>llvm-ar s</strong>.</p>
+</div>
+<div class="section" id="see-also">
+<span id="see-also"></span><h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p>Refer to <a class="reference external" href="llvm-ar.html">llvm-ar</a> for additional information.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-readelf.html" title="llvm-readelf - GNU-style LLVM Object Reader"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-objdump.html" title="llvm-objdump - LLVMâs object file dumper"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-readelf.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-readelf.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-readelf.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-readelf.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,357 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-readelf - GNU-style LLVM Object Reader — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-size - print segment sizes" href="llvm-size.html" />
+ <link rel="prev" title="llvm-ranlib - generates an archive index" href="llvm-ranlib.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-size.html" title="llvm-size - print segment sizes"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-ranlib.html" title="llvm-ranlib - generates an archive index"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-readelf-gnu-style-llvm-object-reader">
+<h1>llvm-readelf - GNU-style LLVM Object Reader<a class="headerlink" href="#llvm-readelf-gnu-style-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-readelf</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-readelf</strong> tool displays low-level format-specific information
+about one or more object files.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">input</span></code> is â<code class="docutils literal notranslate"><span class="pre">-</span></code>â or omitted, <strong class="program">llvm-readelf</strong> reads from standard
+input. Otherwise, it will read from the specified <code class="docutils literal notranslate"><span class="pre">filenames</span></code>.</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-llvm-readelf-all">
+<code class="descname">--all</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>Equivalent to specifying all the main display options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-addrsig">
+<code class="descname">--addrsig</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-addrsig" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the address-significance table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-arm-attributes">
+<code class="descname">--arm-attributes</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-arm-attributes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the ARM attributes section. Only applicable for ARM architectures.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-color">
+<code class="descname">--color</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-color" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use colors in the output for warnings and errors.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-demangle">
+<code class="descname">--demangle</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-C</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-demangle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display demangled symbol names in the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-dyn-relocations">
+<code class="descname">--dyn-relocations</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-dyn-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic relocation entries.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-dyn-symbols">
+<code class="descname">--dyn-symbols</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--dyn-syms</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-dyn-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-dynamic-table">
+<code class="descname">--dynamic-table</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--dynamic</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-d</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-dynamic-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-elf-cg-profile">
+<code class="descname">--elf-cg-profile</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-elf-cg-profile" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the callgraph profile section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-elf-hash-histogram">
+<code class="descname">--elf-hash-histogram</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--histogram</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-I</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-elf-hash-histogram" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display a bucket list histogram for dynamic symbol hash tables.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-elf-linker-options">
+<code class="descname">--elf-linker-options</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-elf-linker-options" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the linker options section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-elf-output-style">
+<code class="descname">--elf-output-style</code><code class="descclassname">=<value></code><a class="headerlink" href="#cmdoption-llvm-readelf-elf-output-style" title="Permalink to this definition">¶</a></dt>
+<dd><p>Format ELF information in the specified style. Valid options are <code class="docutils literal notranslate"><span class="pre">LLVM</span></code> and
+<code class="docutils literal notranslate"><span class="pre">GNU</span></code>. <code class="docutils literal notranslate"><span class="pre">LLVM</span></code> output is an expanded and structured format, whilst <code class="docutils literal notranslate"><span class="pre">GNU</span></code>
+(the default) output mimics the equivalent GNU <strong class="program">readelf</strong> output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-elf-section-groups">
+<code class="descname">--elf-section-groups</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--section-groups</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-g</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-elf-section-groups" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display section groups.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-expand-relocs">
+<code class="descname">--expand-relocs</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-expand-relocs" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <a class="reference internal" href="#cmdoption-llvm-readelf-relocations"><code class="xref std std-option docutils literal notranslate"><span class="pre">--relocations</span></code></a>, display each relocation in an expanded
+multi-line format.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-file-headers">
+<code class="descname">--file-headers</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-h</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-file-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display file headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-gnu-hash-table">
+<code class="descname">--gnu-hash-table</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-gnu-hash-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the GNU hash table for dynamic symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-hash-symbols">
+<code class="descname">--hash-symbols</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-hash-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the expanded hash table with dynamic symbol data.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-hash-table">
+<code class="descname">--hash-table</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-hash-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the hash table for dynamic symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-headers">
+<code class="descname">--headers</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-e</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Equivalent to setting: <a class="reference internal" href="#cmdoption-llvm-readelf-file-headers"><code class="xref std std-option docutils literal notranslate"><span class="pre">--file-headers</span></code></a>, <a class="reference internal" href="#cmdoption-llvm-readelf-program-headers"><code class="xref std std-option docutils literal notranslate"><span class="pre">--program-headers</span></code></a>,
+and <a class="reference internal" href="#cmdoption-llvm-readelf-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">--sections</span></code></a>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-help">
+<code class="descname">--help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-help-list">
+<code class="descname">--help-list</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-help-list" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display an uncategorized summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-hex-dump">
+<code class="descname">--hex-dump</code><code class="descclassname">=<section[,section,...]></code><code class="descclassname">, </code><code class="descname">-x</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-hex-dump" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the specified section(s) as hexadecimal bytes. <code class="docutils literal notranslate"><span class="pre">section</span></code> may be a
+section index or section name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-needed-libs">
+<code class="descname">--needed-libs</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-needed-libs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the needed libraries.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-notes">
+<code class="descname">--notes</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-n</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-notes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all notes.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-program-headers">
+<code class="descname">--program-headers</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--segments</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-l</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-program-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the program headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-raw-relr">
+<code class="descname">--raw-relr</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-raw-relr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not decode relocations in RELR relocation sections when displaying them.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-relocations">
+<code class="descname">--relocations</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--relocs</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-r</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-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-llvm-readelf-sections">
+<code class="descname">--sections</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--section-headers</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-S</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-sections" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-section-data">
+<code class="descname">--section-data</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-section-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <a class="reference internal" href="#cmdoption-llvm-readelf-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">--sections</span></code></a>, display section data for each section
+shown. This option has no effect for GNU style output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-section-mapping">
+<code class="descname">--section-mapping</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-section-mapping" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the section to segment mapping.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-section-relocations">
+<code class="descname">--section-relocations</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-section-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <a class="reference internal" href="#cmdoption-llvm-readelf-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">--sections</span></code></a>, display relocations for each section
+shown. This option has no effect for GNU style output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-section-symbols">
+<code class="descname">--section-symbols</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-section-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <a class="reference internal" href="#cmdoption-llvm-readelf-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">--sections</span></code></a>, display symbols for each section shown.
+This option has no effect for GNU style output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-stackmap">
+<code class="descname">--stackmap</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-stackmap" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display contents of the stackmap section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-string-dump">
+<code class="descname">--string-dump</code><code class="descclassname">=<section[,section,...]></code><code class="descclassname">, </code><code class="descname">-p</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-string-dump" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the specified section(s) as a list of strings. <code class="docutils literal notranslate"><span class="pre">section</span></code> may be a
+section index or section name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-symbols">
+<code class="descname">--symbols</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--syms</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-s</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-unwind">
+<code class="descname">--unwind</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-u</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-unwind" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display unwind information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-version">
+<code class="descname">--version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-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-llvm-readelf-version-info">
+<code class="descname">--version-info</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-V</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-version-info" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display version sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readelf-arg-file">
+<code class="descname">@<FILE></code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readelf-arg-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>Read command-line options from response file <cite><FILE></cite>.</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-readelf</strong> returns 0 under normal operation. It returns a non-zero
+exit code if there were any errors.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-nm.html">llvm-nm(1)</a></em>, <em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-objdump.html">llvm-objdump(1)</a></em>, <em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-readobj.html">llvm-readobj(1)</a></em></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-size.html" title="llvm-size - print segment sizes"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-ranlib.html" title="llvm-ranlib - generates an archive index"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-readobj.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-readobj.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-readobj.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-readobj.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,498 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-readobj - LLVM Object Reader — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-addr2line - a drop-in replacement for addr2line" href="llvm-addr2line.html" />
+ <link rel="prev" title="llvm-mca - LLVM Machine Code Analyzer" href="llvm-mca.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-addr2line.html" title="llvm-addr2line - a drop-in replacement for addr2line"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-mca.html" title="llvm-mca - LLVM Machine Code Analyzer"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <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.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">input</span></code> is â<code class="docutils literal notranslate"><span class="pre">-</span></code>â or omitted, <strong class="program">llvm-readobj</strong> reads from standard
+input. Otherwise, it will read from the specified <code class="docutils literal notranslate"><span class="pre">filenames</span></code>.</p>
+</div>
+<div class="section" id="differences-to-llvm-readelf">
+<h2>DIFFERENCES TO LLVM-READELF<a class="headerlink" href="#differences-to-llvm-readelf" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-readelf</strong> is an alias for the <em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-readobj.html">llvm-readobj</a></em> tool with a
+slightly different command-line interface and output that is GNU compatible.
+Following is a list of differences between <strong class="program">llvm-readelf</strong> and
+<strong class="program">llvm-readobj</strong>:</p>
+<ul class="simple">
+<li><strong class="program">llvm-readelf</strong> uses <cite>GNU</cite> for the <a class="reference internal" href="#cmdoption-llvm-readobj-elf-output-style"><code class="xref std std-option docutils literal notranslate"><span class="pre">--elf-output-style</span></code></a> option
+by default. <strong class="program">llvm-readobj</strong> uses <cite>LLVM</cite>.</li>
+<li><strong class="program">llvm-readelf</strong> allows single-letter grouped flags (e.g.
+<code class="docutils literal notranslate"><span class="pre">llvm-readelf</span> <span class="pre">-SW</span></code> is the same as <code class="docutils literal notranslate"><span class="pre">llvm-readelf</span> <span class="pre">-S</span> <span class="pre">-W</span></code>).
+<strong class="program">llvm-readobj</strong> does not allow grouping.</li>
+<li><strong class="program">llvm-readelf</strong> provides <a class="reference internal" href="#cmdoption-llvm-readobj-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">-s</span></code></a> as an alias for
+<a class="reference internal" href="#cmdoption-llvm-readobj-symbols"><code class="xref std std-option docutils literal notranslate"><span class="pre">--symbols</span></code></a>, for GNU <strong class="program">readelf</strong> compatibility, whereas it is
+an alias for <a class="reference internal" href="#cmdoption-llvm-readobj-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">--section-headers</span></code></a> in <strong class="program">llvm-readobj</strong>.</li>
+<li><strong class="program">llvm-readobj</strong> provides <code class="docutils literal notranslate"><span class="pre">-t</span></code> as an alias for <a class="reference internal" href="#cmdoption-llvm-readobj-symbols"><code class="xref std std-option docutils literal notranslate"><span class="pre">--symbols</span></code></a>.
+<strong class="program">llvm-readelf</strong> does not.</li>
+<li><strong class="program">llvm-readobj</strong> provides <code class="docutils literal notranslate"><span class="pre">--sr</span></code>, <code class="docutils literal notranslate"><span class="pre">--sd</span></code>, <code class="docutils literal notranslate"><span class="pre">--st</span></code> and <code class="docutils literal notranslate"><span class="pre">--dt</span></code> as
+aliases for <a class="reference internal" href="#cmdoption-llvm-readobj-section-relocations"><code class="xref std std-option docutils literal notranslate"><span class="pre">--section-relocations</span></code></a>, <a class="reference internal" href="#cmdoption-llvm-readobj-section-data"><code class="xref std std-option docutils literal notranslate"><span class="pre">--section-data</span></code></a>,
+<a class="reference internal" href="#cmdoption-llvm-readobj-section-symbols"><code class="xref std std-option docutils literal notranslate"><span class="pre">--section-symbols</span></code></a> and <a class="reference internal" href="#cmdoption-llvm-readobj-dyn-symbols"><code class="xref std std-option docutils literal notranslate"><span class="pre">--dyn-symbols</span></code></a> respectively.
+<strong class="program">llvm-readelf</strong> does not provide these aliases, to avoid conflicting
+with grouped flags.</li>
+</ul>
+</div>
+<div class="section" id="general-and-multi-format-options">
+<h2>GENERAL AND MULTI-FORMAT OPTIONS<a class="headerlink" href="#general-and-multi-format-options" title="Permalink to this headline">¶</a></h2>
+<p>These options are applicable to more than one file format, or are unrelated to
+file formats.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-all">
+<code class="descname">--all</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>Equivalent to specifying all the main display options relevant to the file
+format.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-addrsig">
+<code class="descname">--addrsig</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-addrsig" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the address-significance table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-color">
+<code class="descname">--color</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-color" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use colors in the output for warnings and errors.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-expand-relocs">
+<code class="descname">--expand-relocs</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-expand-relocs" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <a class="reference internal" href="#cmdoption-llvm-readobj-relocations"><code class="xref std std-option docutils literal notranslate"><span class="pre">--relocations</span></code></a>, display each relocation in an expanded
+multi-line format.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-file-headers">
+<code class="descname">--file-headers</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-h</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-file-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display file headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-headers">
+<code class="descname">--headers</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-e</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Equivalent to setting: <a class="reference internal" href="#cmdoption-llvm-readobj-file-headers"><code class="xref std std-option docutils literal notranslate"><span class="pre">--file-headers</span></code></a>, <a class="reference internal" href="#cmdoption-llvm-readobj-program-headers"><code class="xref std std-option docutils literal notranslate"><span class="pre">--program-headers</span></code></a>,
+and <a class="reference internal" href="#cmdoption-llvm-readobj-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">--sections</span></code></a>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-help">
+<code class="descname">--help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-help-list">
+<code class="descname">--help-list</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-help-list" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display an uncategorized summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-hex-dump">
+<code class="descname">--hex-dump</code><code class="descclassname">=<section[,section,...]></code><code class="descclassname">, </code><code class="descname">-x</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-hex-dump" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the specified section(s) as hexadecimal bytes. <code class="docutils literal notranslate"><span class="pre">section</span></code> may be a
+section index or section name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-needed-libs">
+<code class="descname">--needed-libs</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-needed-libs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the needed libraries.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-relocations">
+<code class="descname">--relocations</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--relocs</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-r</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-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-llvm-readobj-sections">
+<code class="descname">--sections</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--section-headers</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-s</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-S</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-sections" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-section-data">
+<code class="descname">--section-data</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--sd</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-section-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <a class="reference internal" href="#cmdoption-llvm-readobj-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">--sections</span></code></a>, display section data for each section
+shown. This option has no effect for GNU style output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-section-relocations">
+<code class="descname">--section-relocations</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--sr</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-section-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <a class="reference internal" href="#cmdoption-llvm-readobj-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">--sections</span></code></a>, display relocations for each section
+shown. This option has no effect for GNU style output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-section-symbols">
+<code class="descname">--section-symbols</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--st</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-section-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <a class="reference internal" href="#cmdoption-llvm-readobj-sections"><code class="xref std std-option docutils literal notranslate"><span class="pre">--sections</span></code></a>, display symbols for each section shown.
+This option has no effect for GNU style output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-stackmap">
+<code class="descname">--stackmap</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-stackmap" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display contents of the stackmap section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-string-dump">
+<code class="descname">--string-dump</code><code class="descclassname">=<section[,section,...]></code><code class="descclassname">, </code><code class="descname">-p</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-string-dump" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the specified section(s) as a list of strings. <code class="docutils literal notranslate"><span class="pre">section</span></code> may be a
+section index or section name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-symbols">
+<code class="descname">--symbols</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--syms</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-t</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-unwind">
+<code class="descname">--unwind</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-u</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-unwind" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display unwind information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-version">
+<code class="descname">--version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-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-llvm-readobj-arg-file">
+<code class="descname">@<FILE></code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-arg-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>Read command-line options from response file <cite><FILE></cite>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="elf-specific-options">
+<h2>ELF SPECIFIC OPTIONS<a class="headerlink" href="#elf-specific-options" title="Permalink to this headline">¶</a></h2>
+<p>The following options are implemented only for the ELF file format.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-arm-attributes">
+<code class="descname">--arm-attributes</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-arm-attributes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the ARM attributes section. Only applicable for ARM architectures.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-demangle">
+<code class="descname">--demangle</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-C</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-demangle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display demangled symbol names in the output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-dyn-relocations">
+<code class="descname">--dyn-relocations</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-dyn-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic relocation entries.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-dyn-symbols">
+<code class="descname">--dyn-symbols</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--dyn-syms</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--dt</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-dyn-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-dynamic-table">
+<code class="descname">--dynamic-table</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--dynamic</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-d</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-dynamic-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-elf-cg-profile">
+<code class="descname">--elf-cg-profile</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-elf-cg-profile" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the callgraph profile section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-elf-hash-histogram">
+<code class="descname">--elf-hash-histogram</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--histogram</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-I</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-elf-hash-histogram" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display a bucket list histogram for dynamic symbol hash tables.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-elf-linker-options">
+<code class="descname">--elf-linker-options</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-elf-linker-options" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the linker options section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-elf-output-style">
+<code class="descname">--elf-output-style</code><code class="descclassname">=<value></code><a class="headerlink" href="#cmdoption-llvm-readobj-elf-output-style" title="Permalink to this definition">¶</a></dt>
+<dd><p>Format ELF information in the specified style. Valid options are <code class="docutils literal notranslate"><span class="pre">LLVM</span></code> and
+<code class="docutils literal notranslate"><span class="pre">GNU</span></code>. <code class="docutils literal notranslate"><span class="pre">LLVM</span></code> output (the default) is an expanded and structured format,
+whilst <code class="docutils literal notranslate"><span class="pre">GNU</span></code> output mimics the equivalent GNU <strong class="program">readelf</strong> output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-elf-section-groups">
+<code class="descname">--elf-section-groups</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--section-groups</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-g</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-elf-section-groups" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display section groups.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-gnu-hash-table">
+<code class="descname">--gnu-hash-table</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-gnu-hash-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the GNU hash table for dynamic symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-hash-symbols">
+<code class="descname">--hash-symbols</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-hash-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the expanded hash table with dynamic symbol data.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-hash-table">
+<code class="descname">--hash-table</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-hash-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the hash table for dynamic symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-notes">
+<code class="descname">--notes</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-n</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-notes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all notes.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-program-headers">
+<code class="descname">--program-headers</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--segments</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-l</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-program-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the program headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-raw-relr">
+<code class="descname">--raw-relr</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-raw-relr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not decode relocations in RELR relocation sections when displaying them.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-section-mapping">
+<code class="descname">--section-mapping</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-section-mapping" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the section to segment mapping.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-version-info">
+<code class="descname">--version-info</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-V</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-version-info" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display version sections.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="mach-o-specific-options">
+<h2>MACH-O SPECIFIC OPTIONS<a class="headerlink" href="#mach-o-specific-options" title="Permalink to this headline">¶</a></h2>
+<p>The following options are implemented only for the Mach-O file format.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-macho-data-in-code">
+<code class="descname">--macho-data-in-code</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-macho-data-in-code" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the Data in Code command.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-macho-dsymtab">
+<code class="descname">--macho-dsymtab</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-macho-dsymtab" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the Dsymtab command.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-macho-indirect-symbols">
+<code class="descname">--macho-indirect-symbols</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-macho-indirect-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display indirect symbols.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-macho-linker-options">
+<code class="descname">--macho-linker-options</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-macho-linker-options" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the Mach-O-specific linker options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-macho-segment">
+<code class="descname">--macho-segment</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-macho-segment" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the Segment command.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-macho-version-min">
+<code class="descname">--macho-version-min</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-macho-version-min" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version min command.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="pe-coff-specific-options">
+<h2>PE/COFF SPECIFIC OPTIONS<a class="headerlink" href="#pe-coff-specific-options" title="Permalink to this headline">¶</a></h2>
+<p>The following options are implemented only for the PE/COFF file format.</p>
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-codeview">
+<code class="descname">--codeview</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-codeview" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display CodeView debug information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-codeview-ghash">
+<code class="descname">--codeview-ghash</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-codeview-ghash" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable global hashing for CodeView type stream de-duplication.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-codeview-merged-types">
+<code class="descname">--codeview-merged-types</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-codeview-merged-types" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the merged CodeView type stream.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-codeview-subsection-bytes">
+<code class="descname">--codeview-subsection-bytes</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-codeview-subsection-bytes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump raw contents of CodeView debug sections and records.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-coff-basereloc">
+<code class="descname">--coff-basereloc</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-coff-basereloc" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the .reloc section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-coff-debug-directory">
+<code class="descname">--coff-debug-directory</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-coff-debug-directory" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the debug directory.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-coff-directives">
+<code class="descname">--coff-directives</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-coff-directives" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the .drectve section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-coff-exports">
+<code class="descname">--coff-exports</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-coff-exports" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the export table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-coff-imports">
+<code class="descname">--coff-imports</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-coff-imports" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the import table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-coff-load-config">
+<code class="descname">--coff-load-config</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-coff-load-config" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the load config.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-readobj-coff-resources">
+<code class="descname">--coff-resources</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-readobj-coff-resources" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the .rsrc section.</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 under normal operation. It returns a non-zero
+exit code if there were any errors.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-nm.html">llvm-nm(1)</a></em>, <em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-objdump.html">llvm-objdump(1)</a></em>, <em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-readelf.html">llvm-readelf(1)</a></em></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-addr2line.html" title="llvm-addr2line - a drop-in replacement for addr2line"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-mca.html" title="llvm-mca - LLVM Machine Code Analyzer"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-size.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-size.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-size.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-size.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,100 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-size - print segment sizes — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-strings - print strings" href="llvm-strings.html" />
+ <link rel="prev" title="llvm-readelf - GNU-style LLVM Object Reader" href="llvm-readelf.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-strings.html" title="llvm-strings - print strings"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-readelf.html" title="llvm-readelf - GNU-style LLVM Object Reader"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-size-print-segment-sizes">
+<span id="llvm-size-print-segment-sizes"></span><h1>llvm-size - print segment sizes<a class="headerlink" href="#llvm-size-print-segment-sizes" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<span id="synopsis"></span><h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-size</strong> [<em>options</em>]</p>
+</div>
+<div class="section" id="description">
+<span id="description"></span><h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-size</strong> is a tool that prints segment sizes in object files. The goal is
+to make it a drop-in replacement for GNUâs <strong>size</strong>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-strings.html" title="llvm-strings - print strings"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-readelf.html" title="llvm-readelf - GNU-style LLVM Object Reader"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-stress.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-stress.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-stress.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-stress.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,125 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-stress - generate random .ll files — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <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 <code class="docutils literal notranslate"><span class="pre">.ll</span></code> 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-llvm-stress-o">
+<code class="descname">-o</code><code class="descclassname"> filename</code><a class="headerlink" href="#cmdoption-llvm-stress-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output filename.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-stress-size">
+<code class="descname">-size</code><code class="descclassname"> size</code><a class="headerlink" href="#cmdoption-llvm-stress-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the size of the generated <code class="docutils literal notranslate"><span class="pre">.ll</span></code> file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-stress-seed">
+<code class="descname">-seed</code><code class="descclassname"> seed</code><a class="headerlink" href="#cmdoption-llvm-stress-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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-strings.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-strings.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-strings.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-strings.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,100 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-strings - print strings — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-strip - object stripping tool" href="llvm-strip.html" />
+ <link rel="prev" title="llvm-size - print segment sizes" href="llvm-size.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="llvm-strip.html" title="llvm-strip - object stripping tool"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-size.html" title="llvm-size - print segment sizes"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-strings-print-strings">
+<span id="llvm-strings-print-strings"></span><h1>llvm-strings - print strings<a class="headerlink" href="#llvm-strings-print-strings" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<span id="synopsis"></span><h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-strings</strong> [<em>options</em>]</p>
+</div>
+<div class="section" id="description">
+<span id="description"></span><h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-strings</strong> is a tool that prints strings in object files. The goal is to
+make it a drop-in replacement for GNUâs <strong>size</strong>.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-strip.html" title="llvm-strip - object stripping tool"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-size.html" title="llvm-size - print segment sizes"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-strip.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-strip.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-strip.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-strip.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,105 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-strip - object stripping tool — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="bugpoint - automatic test case reduction tool" href="bugpoint.html" />
+ <link rel="prev" title="llvm-strings - print strings" href="llvm-strings.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="bugpoint.html" title="bugpoint - automatic test case reduction tool"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-strings.html" title="llvm-strings - print strings"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="llvm-strip-object-stripping-tool">
+<span id="llvm-strip-object-stripping-tool"></span><h1>llvm-strip - object stripping tool<a class="headerlink" href="#llvm-strip-object-stripping-tool" title="Permalink to this headline">¶</a></h1>
+<div class="section" id="synopsis">
+<span id="synopsis"></span><h2>SYNOPSIS<a class="headerlink" href="#synopsis" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-strip</strong> [<em>options</em>]</p>
+</div>
+<div class="section" id="description">
+<span id="description"></span><h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-strip</strong> is a tool to strip sections and symbols from object files.</p>
+<p>The tool is still in active development, but in most scenarios it works as a
+drop-in replacement for GNUâs <strong>strip</strong>.</p>
+</div>
+<div class="section" id="see-also">
+<span id="see-also"></span><h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference external" href="llvm-objcopy.html">llvm-objcopy</a></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="bugpoint.html" title="bugpoint - automatic test case reduction tool"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-strings.html" title="llvm-strings - print strings"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/llvm-symbolizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/llvm-symbolizer.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/llvm-symbolizer.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/llvm-symbolizer.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,446 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-symbolizer - convert addresses into source code locations — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <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> [<em>options</em>] [<em>addressesâ¦</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">llvm-symbolizer</strong> reads object file names and addresses from the
+command-line and prints corresponding source code locations to standard output.</p>
+<p>If no address is specified on the command-line, it reads the addresses from
+standard input. If no object file is specified on the command-line, but
+addresses are, or if at any time an input value is not recognized, the input is
+simply echoed to the output.</p>
+<p>A positional argument or standard input value can be preceded by âDATAâ or
+âCODEâ to indicate that the address should be symbolized as data or executable
+code respectively. If neither is specified, âCODEâ is assumed. DATA is
+symbolized as address and symbol size rather than line number.</p>
+<p>Object files can be specified together with the addresses either on standard
+input or as positional arguments on the command-line, following any âDATAâ or
+âCODEâ prefix.</p>
+</div>
+<div class="section" id="examples">
+<h2>EXAMPLES<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
+<p>All of the following examples use the following two source files as input. They
+use a mixture of C-style and C++-style linkage to illustrate how these names are
+printed differently (see <a class="reference internal" href="#cmdoption-llvm-symbolizer-demangle"><code class="xref std std-option docutils literal notranslate"><span class="pre">--demangle</span></code></a>).</p>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// test.h</span>
+<span class="k">extern</span> <span class="s">"C"</span> <span class="kr">inline</span> <span class="kt">int</span> <span class="n">foz</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="mi">1234</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="c1">// test.cpp</span>
+<span class="cp">#include</span> <span class="cpf">"test.h"</span><span class="cp"></span>
+<span class="kt">int</span> <span class="n">bar</span><span class="o">=</span><span class="mi">42</span><span class="p">;</span>
+
+<span class="kt">int</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">bar</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="nf">baz</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">volatile</span> <span class="kt">int</span> <span class="n">k</span> <span class="o">=</span> <span class="mi">42</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">foz</span><span class="p">()</span> <span class="o">+</span> <span class="n">k</span><span class="p">;</span>
+<span class="p">}</span>
+
+<span class="kt">int</span> <span class="nf">main</span><span class="p">()</span> <span class="p">{</span>
+ <span class="k">return</span> <span class="n">foo</span><span class="p">()</span> <span class="o">+</span> <span class="n">baz</span><span class="p">();</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>These files are built as follows:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang -g test.cpp -o test.elf
+<span class="gp">$</span> clang -g -O2 test.cpp -o inlined.elf
+</pre></div>
+</div>
+<p>Example 1 - addresses and object on command-line:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-symbolizer --obj<span class="o">=</span>test.elf 0x4004d0 0x400490
+<span class="go">foz</span>
+<span class="go">/tmp/test.h:1:0</span>
+
+<span class="go">baz()</span>
+<span class="go">/tmp/test.cpp:11:0</span>
+</pre></div>
+</div>
+<p>Example 2 - addresses on standard input:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> cat addr.txt
+<span class="go">0x4004a0</span>
+<span class="go">0x400490</span>
+<span class="go">0x4004d0</span>
+<span class="gp">$</span> llvm-symbolizer --obj<span class="o">=</span>test.elf < addr.txt
+<span class="go">main</span>
+<span class="go">/tmp/test.cpp:15:0</span>
+
+<span class="go">baz()</span>
+<span class="go">/tmp/test.cpp:11:0</span>
+
+<span class="go">foz</span>
+<span class="go">/tmp/./test.h:1:0</span>
+</pre></div>
+</div>
+<p>Example 3 - object specified with address:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-symbolizer <span class="s2">"test.elf 0x400490"</span> <span class="s2">"inlined.elf 0x400480"</span>
+<span class="go">baz()</span>
+<span class="go">/tmp/test.cpp:11:0</span>
+
+<span class="go">foo()</span>
+<span class="go">/tmp/test.cpp:8:10</span>
+
+<span class="gp">$</span> cat addr2.txt
+<span class="go">test.elf 0x4004a0</span>
+<span class="go">inlined.elf 0x400480</span>
+
+<span class="gp">$</span> llvm-symbolizer < addr2.txt
+<span class="go">main</span>
+<span class="go">/tmp/test.cpp:15:0</span>
+
+<span class="go">foo()</span>
+<span class="go">/tmp/test.cpp:8:10</span>
+</pre></div>
+</div>
+<p>Example 4 - CODE and DATA prefixes:</p>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-symbolizer --obj<span class="o">=</span>test.elf <span class="s2">"CODE 0x400490"</span> <span class="s2">"DATA 0x601028"</span>
+<span class="go">baz()</span>
+<span class="go">/tmp/test.cpp:11:0</span>
+
+<span class="go">bar</span>
+<span class="go">6295592 4</span>
+
+<span class="gp">$</span> cat addr3.txt
+<span class="go">CODE test.elf 0x4004a0</span>
+<span class="go">DATA inlined.elf 0x601028</span>
+
+<span class="gp">$</span> llvm-symbolizer < addr3.txt
+<span class="go">main</span>
+<span class="go">/tmp/test.cpp:15:0</span>
+
+<span class="go">bar</span>
+<span class="go">6295592 4</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-llvm-symbolizer-adjust-vma">
+<code class="descname">--adjust-vma</code><code class="descclassname"> <offset></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-adjust-vma" title="Permalink to this definition">¶</a></dt>
+<dd><p>Add the specified offset to object file addresses when performing lookups.
+This can be used to perform lookups as if the object were relocated by the
+offset.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-basenames">
+<code class="descname">--basenames</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-s</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-basenames" title="Permalink to this definition">¶</a></dt>
+<dd><p>Strip directories when printing the file path.</p>
+</dd></dl>
+
+<span class="target" id="llvm-symbolizer-opt-c"></span><dl class="option">
+<dt id="cmdoption-llvm-symbolizer-demangle">
+<code class="descname">--demangle</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-C</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-demangle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print demangled function names, if the names are mangled (e.g. the mangled
+name <cite>_Z3bazv</cite> becomes <cite>baz()</cite>, whilst the non-mangled name <cite>foz</cite> is printed
+as is). Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-dwp">
+<code class="descname">--dwp</code><code class="descclassname"> <path></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-dwp" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use the specified DWP file at <code class="docutils literal notranslate"><span class="pre"><path></span></code> for any CUs that have split DWARF
+debug data.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-fallback-debug-path">
+<code class="descname">--fallback-debug-path</code><code class="descclassname"> <path></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-fallback-debug-path" title="Permalink to this definition">¶</a></dt>
+<dd><p>When a separate file contains debug data, and is referenced by a GNU debug
+link section, use the specified path as a basis for locating the debug data if
+it cannot be found relative to the object.</p>
+</dd></dl>
+
+<span class="target" id="llvm-symbolizer-opt-f"></span><dl class="option">
+<dt id="cmdoption-llvm-symbolizer-functions">
+<code class="descname">--functions</code><code class="descclassname"> [<none|short|linkage>]</code><code class="descclassname">, </code><code class="descname">-f</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-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
+<code class="docutils literal notranslate"><span class="pre">linkage</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-help">
+<code class="descname">--help</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-h</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show help and usage for this command.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-help-list">
+<code class="descname">--help-list</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-help-list" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show help and usage for this command without grouping the options into categories.</p>
+</dd></dl>
+
+<span class="target" id="llvm-symbolizer-opt-i"></span><dl class="option">
+<dt id="cmdoption-llvm-symbolizer-inlining">
+<code class="descname">--inlining</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--inlines</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-i</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-inlining" title="Permalink to this definition">¶</a></dt>
+<dd><p>If a source code location is in an inlined function, prints all the inlined
+frames. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-no-demangle">
+<code class="descname">--no-demangle</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-no-demangle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Donât print demangled function names.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-obj">
+<code class="descname">--obj</code><code class="descclassname"> <path></code><code class="descclassname">, </code><code class="descname">--exe</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-e</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-obj" title="Permalink to this definition">¶</a></dt>
+<dd><p>Path to object file to be symbolized. If <code class="docutils literal notranslate"><span class="pre">-</span></code> is specified, read the object
+directly from the standard input stream.</p>
+</dd></dl>
+
+<span class="target" id="llvm-symbolizer-opt-output-style"></span><dl class="option">
+<dt id="cmdoption-llvm-symbolizer-output-style">
+<code class="descname">--output-style</code><code class="descclassname"> <LLVM|GNU></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-output-style" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the preferred output style. Defaults to <code class="docutils literal notranslate"><span class="pre">LLVM</span></code>. When the output
+style is set to <code class="docutils literal notranslate"><span class="pre">GNU</span></code>, the tool follows the style of GNUâs <strong>addr2line</strong>.
+The differences from the <code class="docutils literal notranslate"><span class="pre">LLVM</span></code> style are:</p>
+<ul class="simple">
+<li>Does not print the column of a source code location.</li>
+<li>Does not add an empty line after the report for an address.</li>
+<li>Does not replace the name of an inlined function with the name of the
+topmost caller when inlined frames are not shown and <a class="reference internal" href="#cmdoption-llvm-symbolizer-use-symbol-table"><code class="xref std std-option docutils literal notranslate"><span class="pre">--use-symbol-table</span></code></a>
+is on.</li>
+</ul>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-symbolizer --obj<span class="o">=</span>inlined.elf 0x4004be 0x400486 -p
+<span class="go">baz() at /tmp/test.cpp:11:18</span>
+<span class="go"> (inlined by) main at /tmp/test.cpp:15:0</span>
+
+<span class="go">foo() at /tmp/test.cpp:6:3</span>
+
+<span class="gp">$</span> llvm-symbolizer --output-style<span class="o">=</span>LLVM --obj<span class="o">=</span>inlined.elf 0x4004be 0x400486 -p -i<span class="o">=</span><span class="m">0</span>
+<span class="go">main at /tmp/test.cpp:11:18</span>
+
+<span class="go">foo() at /tmp/test.cpp:6:3</span>
+
+<span class="gp">$</span> llvm-symbolizer --output-style<span class="o">=</span>GNU --obj<span class="o">=</span>inlined.elf 0x4004be 0x400486 -p -i<span class="o">=</span><span class="m">0</span>
+<span class="go">baz() at /tmp/test.cpp:11</span>
+<span class="go">foo() at /tmp/test.cpp:6</span>
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-pretty-print">
+<code class="descname">--pretty-print</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-p</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-pretty-print" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print human readable output. If <a class="reference internal" href="#cmdoption-llvm-symbolizer-inlining"><code class="xref std std-option docutils literal notranslate"><span class="pre">--inlining</span></code></a> is specified, the
+enclosing scope is prefixed by (inlined by).</p>
+</dd></dl>
+
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-symbolizer --obj<span class="o">=</span>inlined.elf 0x4004be --inlining --pretty-print
+<span class="go">baz() at /tmp/test.cpp:11:18</span>
+<span class="go"> (inlined by) main at /tmp/test.cpp:15:0</span>
+</pre></div>
+</div>
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-print-address">
+<code class="descname">--print-address</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--addresses</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-a</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-print-address" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print address before the source code location. Defaults to false.</p>
+</dd></dl>
+
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-symbolizer --obj<span class="o">=</span>inlined.elf --print-address 0x4004be
+<span class="go">0x4004be</span>
+<span class="go">baz()</span>
+<span class="go">/tmp/test.cpp:11:18</span>
+<span class="go">main</span>
+<span class="go">/tmp/test.cpp:15:0</span>
+
+<span class="gp">$</span> llvm-symbolizer --obj<span class="o">=</span>inlined.elf 0x4004be --pretty-print --print-address
+<span class="go">0x4004be: baz() at /tmp/test.cpp:11:18</span>
+<span class="go"> (inlined by) main at /tmp/test.cpp:15:0</span>
+</pre></div>
+</div>
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-print-source-context-lines">
+<code class="descname">--print-source-context-lines</code><code class="descclassname"> <N></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-print-source-context-lines" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print <code class="docutils literal notranslate"><span class="pre">N</span></code> lines of source context for each symbolized address.</p>
+</dd></dl>
+
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-symbolizer --obj<span class="o">=</span>test.elf 0x400490 --print-source-context-lines<span class="o">=</span><span class="m">2</span>
+<span class="go">baz()</span>
+<span class="go">/tmp/test.cpp:11:0</span>
+<span class="go">10 : volatile int k = 42;</span>
+<span class="go">11 >: return foz() + k;</span>
+<span class="go">12 : }</span>
+</pre></div>
+</div>
+<span class="target" id="llvm-symbolizer-opt-use-symbol-table"></span><dl class="option">
+<dt id="cmdoption-llvm-symbolizer-use-symbol-table">
+<code class="descname">--use-symbol-table</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-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-llvm-symbolizer-verbose">
+<code class="descname">--verbose</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-verbose" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print verbose line and column information.</p>
+</dd></dl>
+
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> llvm-symbolizer --obj<span class="o">=</span>inlined.elf --verbose 0x4004be
+<span class="go">baz()</span>
+<span class="go"> Filename: /tmp/test.cpp</span>
+<span class="go">Function start line: 9</span>
+<span class="go"> Line: 11</span>
+<span class="go"> Column: 18</span>
+<span class="go">main</span>
+<span class="go"> Filename: /tmp/test.cpp</span>
+<span class="go">Function start line: 14</span>
+<span class="go"> Line: 15</span>
+<span class="go"> Column: 0</span>
+</pre></div>
+</div>
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-version">
+<code class="descname">--version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print version information for the tool.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-arg-file">
+<code class="descname">@<FILE></code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-arg-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>Read command-line options from response file <cite><FILE></cite>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="mach-o-specific-options">
+<h2>MACH-O SPECIFIC OPTIONS<a class="headerlink" href="#mach-o-specific-options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-default-arch">
+<code class="descname">--default-arch</code><code class="descclassname"> <arch></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-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 the architecture by writing <code class="docutils literal notranslate"><span class="pre">binary_name:arch_name</span></code> in
+the input (see example below). If the architecture is not specified in either
+way, the address will not be symbolized. Defaults to empty string.</p>
+</dd></dl>
+
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> cat addr.txt
+<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/source_i386.cc:8</span>
+
+<span class="go">_main</span>
+<span class="go">/tmp/source_x86_64.cc:8</span>
+</pre></div>
+</div>
+<dl class="option">
+<dt id="cmdoption-llvm-symbolizer-dsym-hint">
+<code class="descname">--dsym-hint</code><code class="descclassname"> <path/to/file.dSYM></code><a class="headerlink" href="#cmdoption-llvm-symbolizer-dsym-hint" title="Permalink to this definition">¶</a></dt>
+<dd><p>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 this option. This flag can be
+used multiple times.</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 an internal program
+error.</p>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><em class="manpage"><a class="manpage reference external" href="https://llvm.org/docs/CommandGuide/llvm-addr2line.html">llvm-addr2line(1)</a></em></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/opt.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/opt.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/opt.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/opt.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,230 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>opt - LLVM optimizer — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <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-opt-load"><code class="xref std std-option docutils literal notranslate"><span class="pre">-load</span></code></a> option. Use the <a class="reference internal" href="#cmdoption-opt-help"><code class="xref std std-option docutils literal notranslate"><span class="pre">-help</span></code></a>
+option to determine what optimizations you can use.</p>
+<p>If <code class="docutils literal notranslate"><span class="pre">filename</span></code> is omitted from the command line or is â<code class="docutils literal notranslate"><span class="pre">-</span></code>â, <strong class="program">opt</strong>
+reads its input from standard input. Inputs can be in either the LLVM assembly
+language format (<code class="docutils literal notranslate"><span class="pre">.ll</span></code>) or the LLVM bitcode format (<code class="docutils literal notranslate"><span class="pre">.bc</span></code>).</p>
+<p>If an output filename is not specified with the <a class="reference internal" href="#cmdoption-opt-o"><code class="xref std std-option docutils literal notranslate"><span class="pre">-o</span></code></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-opt-f">
+<code class="descname">-f</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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-opt-help">
+<code class="descname">-help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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-opt-o">
+<code class="descname">-o</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-opt-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output filename.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-opt-s">
+<code class="descname">-S</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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 id="cmdoption-opt-passname">
+<code class="descname">-{passname}</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-passname" title="Permalink to this definition">¶</a></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-opt-help"><code class="xref std std-option docutils literal notranslate"><span class="pre">-help</span></code></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-opt-disable-inlining">
+<code class="descname">-disable-inlining</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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-opt-disable-opt">
+<code class="descname">-disable-opt</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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-opt-strip-debug">
+<code class="descname">-strip-debug</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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-opt-verify-each">
+<code class="descname">-verify-each</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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-opt-stats">
+<code class="descname">-stats</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print statistics.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-opt-time-passes">
+<code class="descname">-time-passes</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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-opt-debug">
+<code class="descname">-debug</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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 <code class="docutils literal notranslate"><span class="pre">LLVM_DEBUG()</span></code> macro. See the <a class="reference external" href="../ProgrammersManual.html">LLVM Programmerâs Manual</a>, section <code class="docutils literal notranslate"><span class="pre">#DEBUG</span></code> for more information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-opt-load">
+<code class="descname">-load</code><code class="descclassname">=<plugin></code><a class="headerlink" href="#cmdoption-opt-load" title="Permalink to this definition">¶</a></dt>
+<dd><p>Load the dynamic object <code class="docutils literal notranslate"><span class="pre">plugin</span></code>. 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-opt-help"><code class="xref std std-option docutils literal notranslate"><span class="pre">-help</span></code></a> and <a class="reference internal" href="#cmdoption-opt-load"><code class="xref std std-option docutils literal notranslate"><span class="pre">-load</span></code></a>
+options together. For example:</p>
+<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>opt -load<span class="o">=</span>plugin.so -help
+</pre></div>
+</div>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-opt-p">
+<code class="descname">-p</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-opt-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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandGuide/tblgen.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandGuide/tblgen.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandGuide/tblgen.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandGuide/tblgen.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,280 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>tblgen - Target Description To C++ Code Generator — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" accesskey="U">LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <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 (<code class="docutils literal notranslate"><span class="pre">.td</span></code>) 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"><span class="doc">introduction to TableGen</span></a>.</p>
+<p>The <em>filename</em> argument specifies the name of a Target Description (<code class="docutils literal notranslate"><span class="pre">.td</span></code>)
+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">
+<code class="descname">-help</code><code class="descclassname"></code><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">
+<code class="descname">-o</code><code class="descclassname"> filename</code><a class="headerlink" href="#cmdoption-tblgen-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output file name. If <code class="docutils literal notranslate"><span class="pre">filename</span></code> is <code class="docutils literal notranslate"><span class="pre">-</span></code>, then
+<strong class="program">tblgen</strong> sends its output to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-i">
+<code class="descname">-I</code><code class="descclassname"> directory</code><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
+<code class="docutils literal notranslate"><span class="pre">directory</span></code> 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">
+<code class="descname">-asmparsernum</code><code class="descclassname"> N</code><a class="headerlink" href="#cmdoption-tblgen-asmparsernum" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make -gen-asm-parser emit assembly writer number <code class="docutils literal notranslate"><span class="pre">N</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-asmwriternum">
+<code class="descname">-asmwriternum</code><code class="descclassname"> N</code><a class="headerlink" href="#cmdoption-tblgen-asmwriternum" title="Permalink to this definition">¶</a></dt>
+<dd><p>Make -gen-asm-writer emit assembly writer number <code class="docutils literal notranslate"><span class="pre">N</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-class">
+<code class="descname">-class</code><code class="descclassname"> className</code><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">
+<code class="descname">-print-records</code><code class="descclassname"></code><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">
+<code class="descname">-dump-json</code><code class="descclassname"></code><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">
+<code class="descname">-print-enums</code><code class="descclassname"></code><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">
+<code class="descname">-print-sets</code><code class="descclassname"></code><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">
+<code class="descname">-gen-emitter</code><code class="descclassname"></code><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">
+<code class="descname">-gen-register-info</code><code class="descclassname"></code><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">
+<code class="descname">-gen-instr-info</code><code class="descclassname"></code><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">
+<code class="descname">-gen-asm-writer</code><code class="descclassname"></code><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">
+<code class="descname">-gen-disassembler</code><code class="descclassname"></code><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">
+<code class="descname">-gen-pseudo-lowering</code><code class="descclassname"></code><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">
+<code class="descname">-gen-dag-isel</code><code class="descclassname"></code><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">
+<code class="descname">-gen-asm-matcher</code><code class="descclassname"></code><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">
+<code class="descname">-gen-dfa-packetizer</code><code class="descclassname"></code><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">
+<code class="descname">-gen-fast-isel</code><code class="descclassname"></code><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">
+<code class="descname">-gen-subtarget</code><code class="descclassname"></code><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">
+<code class="descname">-gen-intrinsic-enums</code><code class="descclassname"></code><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">
+<code class="descname">-gen-intrinsic-impl</code><code class="descclassname"></code><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">
+<code class="descname">-gen-tgt-intrinsic</code><code class="descclassname"></code><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">
+<code class="descname">-gen-enhanced-disassembly-info</code><code class="descclassname"></code><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-gen-exegesis">
+<code class="descname">-gen-exegesis</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-tblgen-gen-exegesis" title="Permalink to this definition">¶</a></dt>
+<dd><p>Generate llvm-exegesis tables.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-tblgen-version">
+<code class="descname">-version</code><code class="descclassname"></code><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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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 class="nav-item nav-item-1"><a href="index.html" >LLVM Command Guide</a> »</li>
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CommandLine.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CommandLine.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CommandLine.html (added)
+++ www-releases/trunk/9.0.0/docs/CommandLine.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,1576 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>CommandLine 2.0 Library Manual — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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" role="main">
+
+ <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 <code class="docutils literal notranslate"><span class="pre">cl::ConsumeAfter</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> 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="#controlling-options-grouping" id="id30">Controlling options grouping</a></li>
+<li><a class="reference internal" href="#miscellaneous-option-modifiers" id="id31">Miscellaneous option modifiers</a></li>
+<li><a class="reference internal" href="#response-files" id="id32">Response files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#top-level-classes-and-functions" id="id33">Top-Level Classes and Functions</a><ul>
+<li><a class="reference internal" href="#the-cl-getregisteredoptions-function" id="id34">The <code class="docutils literal notranslate"><span class="pre">cl::getRegisteredOptions</span></code> function</a></li>
+<li><a class="reference internal" href="#the-cl-parsecommandlineoptions-function" id="id35">The <code class="docutils literal notranslate"><span class="pre">cl::ParseCommandLineOptions</span></code> function</a></li>
+<li><a class="reference internal" href="#the-cl-parseenvironmentoptions-function" id="id36">The <code class="docutils literal notranslate"><span class="pre">cl::ParseEnvironmentOptions</span></code> function</a></li>
+<li><a class="reference internal" href="#the-cl-setversionprinter-function" id="id37">The <code class="docutils literal notranslate"><span class="pre">cl::SetVersionPrinter</span></code> function</a></li>
+<li><a class="reference internal" href="#the-cl-opt-class" id="id38">The <code class="docutils literal notranslate"><span class="pre">cl::opt</span></code> class</a></li>
+<li><a class="reference internal" href="#the-cl-list-class" id="id39">The <code class="docutils literal notranslate"><span class="pre">cl::list</span></code> class</a></li>
+<li><a class="reference internal" href="#the-cl-bits-class" id="id40">The <code class="docutils literal notranslate"><span class="pre">cl::bits</span></code> class</a></li>
+<li><a class="reference internal" href="#the-cl-alias-class" id="id41">The <code class="docutils literal notranslate"><span class="pre">cl::alias</span></code> class</a></li>
+<li><a class="reference internal" href="#the-cl-extrahelp-class" id="id42">The <code class="docutils literal notranslate"><span class="pre">cl::extrahelp</span></code> class</a></li>
+<li><a class="reference internal" href="#the-cl-optioncategory-class" id="id43">The <code class="docutils literal notranslate"><span class="pre">cl::OptionCategory</span></code> class</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#builtin-parsers" id="id44">Builtin parsers</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#extending-the-library" id="id45">Extension Guide</a><ul>
+<li><a class="reference internal" href="#writing-a-custom-parser" id="id46">Writing a custom parser</a></li>
+<li><a class="reference internal" href="#exploiting-external-storage" id="id47">Exploiting external storage</a></li>
+<li><a class="reference internal" href="#dynamically-adding-command-line-options" id="id48">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
+<code class="docutils literal notranslate"><span class="pre">-help</span></code> 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,
+<code class="docutils literal notranslate"><span class="pre">ls</span></code> style <a class="reference internal" href="#grouping">grouping</a> options (to allow processing â<code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">-lad</span></code>â
+naturally), <code class="docutils literal notranslate"><span class="pre">ld</span></code> style <a class="reference internal" href="#prefix">prefix</a> options (to parse â<code class="docutils literal notranslate"><span class="pre">-lmalloc</span>
+<span class="pre">-L/usr/lib</span></code>â), 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++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf">"llvm/Support/CommandLine.h"</span><span class="cp"></span>
+</pre></div>
+</div>
+<p>Additionally, you need to add this as the first line of your main program:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">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 â<code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre"><filename></span></code>â option to specify
+where to put the output. With the CommandLine library, this is represented like
+this:</p>
+<div class="highlight-c++ notranslate" id="here"><span id="scalars-arguments"></span><div class="highlight"><pre><span></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">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 â<code class="docutils literal notranslate"><span class="pre">OutputFilename</span></code>â that is used to capture the
+result of the â<code class="docutils literal notranslate"><span class="pre">o</span></code>â argument (first parameter). We specify that this is a
+simple scalar option by using the â<code class="docutils literal notranslate"><span class="pre">cl::opt</span></code>â template (as opposed to the
+â<code class="docutils literal notranslate"><span class="pre">cl::list</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">-help</span></code>â option. In this case, we get a line that looks like
+this:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">USAGE</span><span class="p">:</span> <span class="n">compiler</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="o">-</span><span class="n">h</span> <span class="o">-</span> <span class="n">Alias</span> <span class="k">for</span> <span class="o">-</span><span class="n">help</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+ <span class="o">-</span><span class="n">o</span> <span class="o"><</span><span class="n">filename</span><span class="o">></span> <span class="o">-</span> <span class="n">Specify</span> <span class="n">output</span> <span class="n">filename</span>
+</pre></div>
+</div>
+<p>Because we specified that the command line option should parse using the
+<code class="docutils literal notranslate"><span class="pre">string</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">-filename.c</span></code>). 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++ notranslate"><div class="highlight"><pre><span></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">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++ notranslate"><div class="highlight"><pre><span></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">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++ notranslate"><div class="highlight"><pre><span></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">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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> option synopsis is now extended to:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">USAGE</span><span class="p">:</span> <span class="n">compiler</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="nb">input</span> <span class="n">file</span><span class="o">></span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="o">-</span><span class="n">h</span> <span class="o">-</span> <span class="n">Alias</span> <span class="k">for</span> <span class="o">-</span><span class="n">help</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+ <span class="o">-</span><span class="n">o</span> <span class="o"><</span><span class="n">filename</span><span class="o">></span> <span class="o">-</span> <span class="n">Specify</span> <span class="n">output</span> <span class="n">filename</span>
+</pre></div>
+</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: â<code class="docutils literal notranslate"><span class="pre">-f</span></code>â to force writing binary output to a
+terminal, â<code class="docutils literal notranslate"><span class="pre">--quiet</span></code>â to enable quiet mode, and â<code class="docutils literal notranslate"><span class="pre">-q</span></code>â 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++ notranslate"><div class="highlight"><pre><span></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">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
+(â<code class="docutils literal notranslate"><span class="pre">Force</span></code>â, â<code class="docutils literal notranslate"><span class="pre">Quiet</span></code>â, and â<code class="docutils literal notranslate"><span class="pre">Quiet2</span></code>â) to recognize these options. Note
+that the â<code class="docutils literal notranslate"><span class="pre">-q</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">-help</span></code>â output (note
+that it is still shown in the â<code class="docutils literal notranslate"><span class="pre">-help-hidden</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">true</span></code>â or â<code class="docutils literal notranslate"><span class="pre">false</span></code>â to be
+specified, allowing any of the following inputs:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">compiler</span> <span class="o">-</span><span class="n">f</span> <span class="c1"># 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="c1"># 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="c1"># 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="c1"># 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 â<code class="docutils literal notranslate"><span class="pre">compiler</span> <span class="pre">-f=foo</span></code>â. 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
+â<code class="docutils literal notranslate"><span class="pre">strtol</span></code>â and â<code class="docutils literal notranslate"><span class="pre">strtod</span></code>â C library calls to parse the string value into the
+specified data type.</p>
+<p>With the declarations above, â<code class="docutils literal notranslate"><span class="pre">compiler</span> <span class="pre">-help</span></code>â emits this:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">USAGE</span><span class="p">:</span> <span class="n">compiler</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="nb">input</span> <span class="n">file</span><span class="o">></span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="o">-</span><span class="n">f</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">binary</span> <span class="n">output</span> <span class="n">on</span> <span class="n">terminals</span>
+ <span class="o">-</span><span class="n">o</span> <span class="o">-</span> <span class="n">Override</span> <span class="n">output</span> <span class="n">filename</span>
+ <span class="o">-</span><span class="n">quiet</span> <span class="o">-</span> <span class="n">Don</span><span class="s1">'t print informational messages</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>and â<code class="docutils literal notranslate"><span class="pre">compiler</span> <span class="pre">-help-hidden</span></code>â prints this:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">USAGE</span><span class="p">:</span> <span class="n">compiler</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="nb">input</span> <span class="n">file</span><span class="o">></span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="o">-</span><span class="n">f</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">binary</span> <span class="n">output</span> <span class="n">on</span> <span class="n">terminals</span>
+ <span class="o">-</span><span class="n">o</span> <span class="o">-</span> <span class="n">Override</span> <span class="n">output</span> <span class="n">filename</span>
+ <span class="o">-</span><span class="n">q</span> <span class="o">-</span> <span class="n">Don</span><span class="s1">'t print informational messages</span>
+ <span class="o">-</span><span class="n">quiet</span> <span class="o">-</span> <span class="n">Don</span><span class="s1">'t print informational messages</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+</pre></div>
+</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++ notranslate"><div class="highlight"><pre><span></span><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 â<code class="docutils literal notranslate"><span class="pre">-q</span></code>â option an
+<strong>alias</strong> for the â<code class="docutils literal notranslate"><span class="pre">-quiet</span></code>â option, instead of providing a value itself:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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">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 â<code class="docutils literal notranslate"><span class="pre">-q</span></code>â
+alias that updates the â<code class="docutils literal notranslate"><span class="pre">Quiet</span></code>â 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 <code class="docutils literal notranslate"><span class="pre">Quiet</span></code> variable now. Another nice
+feature of aliases is that they automatically hide themselves from the <code class="docutils literal notranslate"><span class="pre">-help</span></code>
+output (although, again, they are still visible in the <code class="docutils literal notranslate"><span class="pre">-help-hidden</span> <span class="pre">output</span></code>).</p>
+<p>Now the application code can simply use:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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
+<code class="docutils literal notranslate"><span class="pre">std::string</span></code>, <code class="docutils literal notranslate"><span class="pre">bool</span></code> and <code class="docutils literal notranslate"><span class="pre">int</span></code>, but how does it handle things it doesnât
+know about, like enums or â<code class="docutils literal notranslate"><span class="pre">int*</span></code>â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 â<code class="docutils literal notranslate"><span class="pre">-g</span></code>â, â<code class="docutils literal notranslate"><span class="pre">-O0</span></code>â, â<code class="docutils literal notranslate"><span class="pre">-O1</span></code>â, and â<code class="docutils literal notranslate"><span class="pre">-O2</span></code>â. 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,
+â<code class="docutils literal notranslate"><span class="pre">compiler</span> <span class="pre">-O3</span> <span class="pre">-O2</span></code>â. 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 >= â<code class="docutils literal notranslate"><span class="pre">-O1</span></code>â 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++ notranslate"><div class="highlight"><pre><span></span><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 â<code class="docutils literal notranslate"><span class="pre">OptimizationLevel</span></code>â of the
+â<code class="docutils literal notranslate"><span class="pre">OptLevel</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">clEnumVal</span></code>â macros ensure that the command
+line arguments matched the enum values. With this option added, our help output
+now is:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">USAGE</span><span class="p">:</span> <span class="n">compiler</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="nb">input</span> <span class="n">file</span><span class="o">></span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="n">Choose</span> <span class="n">optimization</span> <span class="n">level</span><span class="p">:</span>
+ <span class="o">-</span><span class="n">g</span> <span class="o">-</span> <span class="n">No</span> <span class="n">optimizations</span><span class="p">,</span> <span class="n">enable</span> <span class="n">debugging</span>
+ <span class="o">-</span><span class="n">O1</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">trivial</span> <span class="n">optimizations</span>
+ <span class="o">-</span><span class="n">O2</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">default</span> <span class="n">optimizations</span>
+ <span class="o">-</span><span class="n">O3</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">expensive</span> <span class="n">optimizations</span>
+ <span class="o">-</span><span class="n">f</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">binary</span> <span class="n">output</span> <span class="n">on</span> <span class="n">terminals</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+ <span class="o">-</span><span class="n">o</span> <span class="o"><</span><span class="n">filename</span><span class="o">></span> <span class="o">-</span> <span class="n">Specify</span> <span class="n">output</span> <span class="n">filename</span>
+ <span class="o">-</span><span class="n">quiet</span> <span class="o">-</span> <span class="n">Don</span><span class="s1">'t print informational messages</span>
+</pre></div>
+</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 â<code class="docutils literal notranslate"><span class="pre">g</span></code>â in our
+program. Because of this, we can alternatively write this example like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 â<code class="docutils literal notranslate"><span class="pre">clEnumValN</span></code>â macro instead of â<code class="docutils literal notranslate"><span class="pre">clEnumVal</span></code>â, 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:
+â<code class="docutils literal notranslate"><span class="pre">--debug-level=none</span></code>â, â<code class="docutils literal notranslate"><span class="pre">--debug-level=quick</span></code>â,
+â<code class="docutils literal notranslate"><span class="pre">--debug-level=detailed</span></code>â. 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++ notranslate"><div class="highlight"><pre><span></span><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 â<code class="docutils literal notranslate"><span class="pre">enum</span>
+<span class="pre">DebugLev</span></code>â, 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 â<code class="docutils literal notranslate"><span class="pre">-help</span></code>â option:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">USAGE</span><span class="p">:</span> <span class="n">compiler</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="nb">input</span> <span class="n">file</span><span class="o">></span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="n">Choose</span> <span class="n">optimization</span> <span class="n">level</span><span class="p">:</span>
+ <span class="o">-</span><span class="n">g</span> <span class="o">-</span> <span class="n">No</span> <span class="n">optimizations</span><span class="p">,</span> <span class="n">enable</span> <span class="n">debugging</span>
+ <span class="o">-</span><span class="n">O1</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">trivial</span> <span class="n">optimizations</span>
+ <span class="o">-</span><span class="n">O2</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">default</span> <span class="n">optimizations</span>
+ <span class="o">-</span><span class="n">O3</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">expensive</span> <span class="n">optimizations</span>
+ <span class="o">-</span><span class="n">debug_level</span> <span class="o">-</span> <span class="n">Set</span> <span class="n">the</span> <span class="n">debugging</span> <span class="n">level</span><span class="p">:</span>
+ <span class="o">=</span><span class="n">none</span> <span class="o">-</span> <span class="n">disable</span> <span class="n">debug</span> <span class="n">information</span>
+ <span class="o">=</span><span class="n">quick</span> <span class="o">-</span> <span class="n">enable</span> <span class="n">quick</span> <span class="n">debug</span> <span class="n">information</span>
+ <span class="o">=</span><span class="n">detailed</span> <span class="o">-</span> <span class="n">enable</span> <span class="n">detailed</span> <span class="n">debug</span> <span class="n">information</span>
+ <span class="o">-</span><span class="n">f</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">binary</span> <span class="n">output</span> <span class="n">on</span> <span class="n">terminals</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+ <span class="o">-</span><span class="n">o</span> <span class="o"><</span><span class="n">filename</span><span class="o">></span> <span class="o">-</span> <span class="n">Specify</span> <span class="n">output</span> <span class="n">filename</span>
+ <span class="o">-</span><span class="n">quiet</span> <span class="o">-</span> <span class="n">Don</span><span class="s1">'t print informational messages</span>
+</pre></div>
+</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 (<code class="docutils literal notranslate"><span class="pre">"debug_level"</span></code>), 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: â<code class="docutils literal notranslate"><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></code>â. In this
+case, the order of the arguments and the number of appearances is very
+important. This is what the â<code class="docutils literal notranslate"><span class="pre">cl::list</span></code>â template is for. First, start by
+defining an enum of the optimizations that you would like to perform:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 â<code class="docutils literal notranslate"><span class="pre">cl::list</span></code>â variable:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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
+â<code class="docutils literal notranslate"><span class="pre">std::vector<enum</span> <span class="pre">Opts></span></code>â. Thus, you can access it with standard vector
+methods:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">!=</span> <span class="n">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 â<code class="docutils literal notranslate"><span class="pre">cl::list</span></code>â template is completely general and may be used with
+any data types or other arguments that you can use with the â<code class="docutils literal notranslate"><span class="pre">cl::opt</span></code>â
+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 â<code class="docutils literal notranslate"><span class="pre">.o</span></code>â files, and
+needs to capture them into a list. This is naturally specified as:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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">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 â<code class="docutils literal notranslate"><span class="pre">vector<string></span></code>â 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 <code class="docutils literal notranslate"><span class="pre">.o</span></code> 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 <code class="docutils literal notranslate"><span class="pre">unsigned</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><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++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">constprop</span></code> was specified, we can use the <code class="docutils literal notranslate"><span class="pre">cl:bits::isSet</span></code>
+function:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">cl::bits::getBits</span></code>
+function:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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> <code class="docutils literal notranslate"><span class="pre">unsigned</span></code>. 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 <code class="docutils literal notranslate"><span class="pre">man</span></code> page, providing concise information about a
+program. Unix <code class="docutils literal notranslate"><span class="pre">man</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">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-default notranslate"><div class="highlight"><pre><span></span><span class="o">**</span><span class="n">OVERVIEW</span><span class="p">:</span> <span class="n">CommandLine</span> <span class="n">compiler</span> <span class="n">example</span>
+
+ <span class="n">This</span> <span class="n">program</span> <span class="n">blah</span> <span class="n">blah</span> <span class="n">blah</span><span class="o">...**</span>
+
+<span class="n">USAGE</span><span class="p">:</span> <span class="n">compiler</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="nb">input</span> <span class="n">file</span><span class="o">></span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="o">...</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+ <span class="o">-</span><span class="n">o</span> <span class="o"><</span><span class="n">filename</span><span class="o">></span> <span class="o">-</span> <span class="n">Specify</span> <span class="n">output</span> <span class="n">filename</span>
+</pre></div>
+</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 <code class="docutils literal notranslate"><span class="pre">-help</span></code>. 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++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> will become categorized if an option category is
+declared. The output looks something like</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">OVERVIEW</span><span class="p">:</span> <span class="n">This</span> <span class="ow">is</span> <span class="n">a</span> <span class="n">small</span> <span class="n">program</span> <span class="n">to</span> <span class="n">demo</span> <span class="n">the</span> <span class="n">LLVM</span> <span class="n">CommandLine</span> <span class="n">API</span>
+<span class="n">USAGE</span><span class="p">:</span> <span class="n">Sample</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+
+ <span class="n">General</span> <span class="n">options</span><span class="p">:</span>
+
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">Display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+ <span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="nb">list</span> <span class="o">-</span> <span class="n">Display</span> <span class="nb">list</span> <span class="n">of</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="nb">list</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+
+
+ <span class="n">Stage</span> <span class="n">Selection</span> <span class="n">Options</span><span class="p">:</span>
+ <span class="n">These</span> <span class="n">control</span> <span class="n">which</span> <span class="n">stages</span> <span class="n">are</span> <span class="n">run</span><span class="o">.</span>
+
+ <span class="o">-</span><span class="n">E</span> <span class="o">-</span> <span class="n">Run</span> <span class="n">preprocessor</span> <span class="n">stage</span><span class="o">.</span>
+ <span class="o">-</span><span class="n">c</span> <span class="o">-</span> <span class="n">Run</span> <span class="nb">all</span> <span class="n">stages</span> <span class="k">except</span> <span class="n">linking</span><span class="o">.</span>
+</pre></div>
+</div>
+<p>In addition to the behaviour of <code class="docutils literal notranslate"><span class="pre">-help</span></code> changing when an option category is
+declared, the command line option <code class="docutils literal notranslate"><span class="pre">-help-list</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">cl::GeneralCategory</span></code> 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 <code class="docutils literal notranslate"><span class="pre">grep</span></code> 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++ notranslate"><div class="highlight"><pre><span></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">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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> output for our grep
+replacement would look like this:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">USAGE</span><span class="p">:</span> <span class="n">spiffygrep</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="n">regular</span> <span class="n">expression</span><span class="o">></span> <span class="o"><</span><span class="nb">input</span> <span class="n">file</span><span class="o">></span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>⦠and the resultant program could be used just like the standard <code class="docutils literal notranslate"><span class="pre">grep</span></code>
+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 â<code class="docutils literal notranslate"><span class="pre">-foo</span></code>â in a file). At
+first, you will have trouble doing this, because it will try to find an argument
+named â<code class="docutils literal notranslate"><span class="pre">-foo</span></code>â, and will fail (and single quotes will not save you). Note
+that the system <code class="docutils literal notranslate"><span class="pre">grep</span></code> has the same problem:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ 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>
+</div>
+<p>The solution for this problem is the same for both your tool and the system
+version: use the â<code class="docutils literal notranslate"><span class="pre">--</span></code>â marker. When the user specifies â<code class="docutils literal notranslate"><span class="pre">--</span></code>â on the
+command line, it is telling the program that all options after the â<code class="docutils literal notranslate"><span class="pre">--</span></code>â
+should be treated as positional arguments, not options. Thus, we can use it
+like this:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ spiffygrep -- -foo test.txt
+ ...output...
+</pre></div>
+</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 <code class="docutils literal notranslate"><span class="pre">gcc</span></code>âs <code class="docutils literal notranslate"><span class="pre">-x</span> <span class="pre">LANG</span></code> option. This tells <code class="docutils literal notranslate"><span class="pre">gcc</span></code> to ignore the
+suffix of subsequent positional arguments and force the file to be interpreted
+as if it contained source code in language <code class="docutils literal notranslate"><span class="pre">LANG</span></code>. 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 <code class="docutils literal notranslate"><span class="pre">-llibname</span></code> which is actually a positional argument
+that starts with a dash.</p>
+<p>So, generally, the problem is that you have two <code class="docutils literal notranslate"><span class="pre">cl::list</span></code> variables that
+interact in some way. To ensure the correct interaction, you can use the
+<code class="docutils literal notranslate"><span class="pre">cl::list::getPosition(optnum)</span></code> method. This method returns the absolute
+position (as found on the command line) of the <code class="docutils literal notranslate"><span class="pre">optnum</span></code> item in the
+<code class="docutils literal notranslate"><span class="pre">cl::list</span></code>.</p>
+<p>The idiom for usage is like this:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></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">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="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="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 <code class="docutils literal notranslate"><span class="pre">cl::opt</span></code> also supports an
+<code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">getPosition()</span></code> option that will provide the absolute position of
+that option. You can apply the same approach as above with a <code class="docutils literal notranslate"><span class="pre">cl::opt</span></code> and a
+<code class="docutils literal notranslate"><span class="pre">cl::list</span></code> 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 <code class="docutils literal notranslate"><span class="pre">cl::ConsumeAfter</span></code> modifier</a><a class="headerlink" href="#the-cl-consumeafter-modifier" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::ConsumeAfter</span></code> <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 (<code class="docutils literal notranslate"><span class="pre">/bin/sh</span></code>). To run <code class="docutils literal notranslate"><span class="pre">/bin/sh</span></code>, first you specify options
+to the shell itself (like <code class="docutils literal notranslate"><span class="pre">-x</span></code> 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++ notranslate"><div class="highlight"><pre><span></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">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-default notranslate"><div class="highlight"><pre><span></span><span class="n">USAGE</span><span class="p">:</span> <span class="n">spiffysh</span> <span class="p">[</span><span class="n">options</span><span class="p">]</span> <span class="o"><</span><span class="nb">input</span> <span class="n">script</span><span class="o">></span> <span class="o"><</span><span class="n">program</span> <span class="n">arguments</span><span class="o">>...</span>
+
+<span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+ <span class="o">-</span><span class="n">x</span> <span class="o">-</span> <span class="n">Enable</span> <span class="n">trace</span> <span class="n">output</span>
+</pre></div>
+</div>
+<p>At runtime, if we run our new shell replacement as <code class="docutils literal notranslate"><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></code>â, the <code class="docutils literal notranslate"><span class="pre">Trace</span></code> variable will be set to true, the <code class="docutils literal notranslate"><span class="pre">Script</span></code> variable
+will be set to â<code class="docutils literal notranslate"><span class="pre">test.sh</span></code>â, and the <code class="docutils literal notranslate"><span class="pre">Argv</span></code> list will contain <code class="docutils literal notranslate"><span class="pre">["-a",</span> <span class="pre">"-x",</span>
+<span class="pre">"-y",</span> <span class="pre">"bar"]</span></code>, because they were specified after the last positional argument
+(which is the script name).</p>
+<p>There are several limitations to when <code class="docutils literal notranslate"><span class="pre">cl::ConsumeAfter</span></code> options can be
+specified. For example, only one <code class="docutils literal notranslate"><span class="pre">cl::ConsumeAfter</span></code> 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 <code class="docutils literal notranslate"><span class="pre">cl::ConsumeAfter</span></code> 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
+â<code class="docutils literal notranslate"><span class="pre">-debug</span></code>â 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 <code class="docutils literal notranslate"><span class="pre">#include</span> <span class="pre">CommandLine.h</span></code>).</p>
+<p>To do this, set up your .h file with your option, like this for example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="c1">// DEBUG macro - This macro should be used by code to emit debug information.</span>
+<span class="c1">// In the '-debug' option is specified on the command line, and if this is a</span>
+<span class="c1">// debug build, then the code specified as the option to the macro will be</span>
+<span class="c1">// 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 <code class="docutils literal notranslate"><span class="pre">LLVM_DEBUG()</span></code> macro, or the
+<code class="docutils literal notranslate"><span class="pre">DebugFlag</span></code> explicitly if they want to. Now we just need to be able to set
+the <code class="docutils literal notranslate"><span class="pre">DebugFlag</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><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="nb">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 â<code class="docutils literal notranslate"><span class="pre">true</span></code>â 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 <code class="docutils literal notranslate"><span class="pre">DebugFlag</span></code> 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++ notranslate"><div class="highlight"><pre><span></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>
+</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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> 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: <code class="docutils literal notranslate"><span class="pre">-sectalign</span> <span class="pre">segname</span> <span class="pre">sectname</span> <span class="pre">sectvalue</span></code>). This attribute
+takes one unsigned argument - the number of values for the option. This
+attribute is valid only on <code class="docutils literal notranslate"><span class="pre">cl::list</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">cl::ValueDisallowed</span></code>, 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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> output</a><a class="headerlink" href="#hiding-an-option-from-help-output" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::NotHidden</span></code>, <code class="docutils literal notranslate"><span class="pre">cl::Hidden</span></code>, and <code class="docutils literal notranslate"><span class="pre">cl::ReallyHidden</span></code> modifiers are
+used to control whether or not an option appears in the <code class="docutils literal notranslate"><span class="pre">-help</span></code> and
+<code class="docutils literal notranslate"><span class="pre">-help-hidden</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> output, but
+should appear in the <code class="docutils literal notranslate"><span class="pre">-help-hidden</span></code> 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 <code class="docutils literal notranslate"><span class="pre">cl::init</span></code> 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. â<code class="docutils literal notranslate"><span class="pre">-index-depth=17</span></code>â) or as a trailing
+string (e.g. â<code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">a.out</span></code>â).</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 <code class="docutils literal notranslate"><span class="pre">bool</span></code> 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 â<code class="docutils literal notranslate"><span class="pre">-foo=true</span></code>â. If an option is specified with this mode, it is
+illegal for the value to be provided without the equal sign. Therefore
+â<code class="docutils literal notranslate"><span class="pre">-foo</span> <span class="pre">true</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">a.out</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">-foo=true</span></code>â).</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>
+<span id="prefix"></span><ul class="simple" id="cl-prefix">
+<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 <code class="docutils literal notranslate"><span class="pre">-lmalloc</span></code> and <code class="docutils literal notranslate"><span class="pre">-L/usr/lib</span></code> in a linker tool or
+<code class="docutils literal notranslate"><span class="pre">-DNAME=value</span></code> in a compiler tool. Here, the â<code class="docutils literal notranslate"><span class="pre">l</span></code>â, â<code class="docutils literal notranslate"><span class="pre">D</span></code>â and â<code class="docutils literal notranslate"><span class="pre">L</span></code>â
+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>
+</div>
+<div class="section" id="controlling-options-grouping">
+<span id="cl-grouping"></span><span id="grouping"></span><h4><a class="toc-backref" href="#id30">Controlling options grouping</a><a class="headerlink" href="#controlling-options-grouping" title="Permalink to this headline">¶</a></h4>
+<p>The <strong>cl::Grouping</strong> modifier can be combined with any formatting types except
+for <a class="reference internal" href="#cl-positional">cl::Positional</a>. It is used to implement Unix-style tools (like <code class="docutils literal notranslate"><span class="pre">ls</span></code>)
+that have lots of single letter arguments, but only require a single dash.
+For example, the â<code class="docutils literal notranslate"><span class="pre">ls</span> <span class="pre">-labF</span></code>â command actually enables four different options,
+all of which are single letters.</p>
+<p>Note that <strong>cl::Grouping</strong> options can have values only if they are used
+separately or at the end of the groups. For <a class="reference internal" href="#cl-valuerequired">cl::ValueRequired</a>, it is
+a runtime error if such an option is used elsewhere in the group.</p>
+<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-default notranslate"><div class="highlight"><pre><span></span>parse(string OrigInput) {
+
+1. string Input = OrigInput;
+2. if (isOption(Input)) return getOption(Input).parse(); // Normal option
+3. while (!Input.empty() && !isOption(Input)) Input.pop_back(); // Remove the last letter
+4. while (!Input.empty()) {
+ string MaybeValue = OrigInput.substr(Input.length())
+ if (getOption(Input).isPrefix())
+ return getOption(Input).parse(MaybeValue)
+ if (!MaybeValue.empty() && MaybeValue[0] == '=')
+ return getOption(Input).parse(MaybeValue.substr(1))
+ if (!getOption(Input).isGrouping())
+ return error()
+ getOption(Input).parse()
+ Input = OrigInput = MaybeValue
+ while (!Input.empty() && !isOption(Input)) Input.pop_back();
+ if (!Input.empty() && !getOption(Input).isGrouping())
+ return error()
+ }
+5. if (!OrigInput.empty()) error();
+
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="miscellaneous-option-modifiers">
+<h4><a class="toc-backref" href="#id31">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
+<code class="docutils literal notranslate"><span class="pre">cl::CommaSeparated</span></code> is specified: â<code class="docutils literal notranslate"><span class="pre">-foo=a</span> <span class="pre">-foo=b</span> <span class="pre">-foo=c</span></code>â and
+â<code class="docutils literal notranslate"><span class="pre">-foo=a,b,c</span></code>â. 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-defaultoption">
+<li>The <strong>cl::DefaultOption</strong> modifier is used to specify that the option is a
+default that can be overridden by application specific parsers. For example,
+the <code class="docutils literal notranslate"><span class="pre">-help</span></code> alias, <code class="docutils literal notranslate"><span class="pre">-h</span></code>, is registered this way, so it can be overridden
+by applications that need to use the <code class="docutils literal notranslate"><span class="pre">-h</span></code> option for another purpose,
+either as a regular option or an alias for another 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, â<code class="docutils literal notranslate"><span class="pre">pos1</span></code>â and â<code class="docutils literal notranslate"><span class="pre">pos2</span></code>â, the string â<code class="docutils literal notranslate"><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></code>â would cause the â<code class="docutils literal notranslate"><span class="pre">-foo</span> <span class="pre">-bar</span> <span class="pre">-baz</span></code>â strings to
+be applied to the â<code class="docutils literal notranslate"><span class="pre">-pos1</span></code>â option and the â<code class="docutils literal notranslate"><span class="pre">-bork</span></code>â string to be applied
+to the â<code class="docutils literal notranslate"><span class="pre">-pos2</span></code>â 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 <code class="docutils literal notranslate"><span class="pre">cl::Sink</span></code> modifier specified, the parser passes
+unrecognized option strings to it as values instead of signaling an error. As
+with <code class="docutils literal notranslate"><span class="pre">cl::CommaSeparated</span></code>, this modifier only makes sense with a <a class="reference internal" href="#cl-list">cl::list</a>
+option.</li>
+</ul>
+</div>
+<div class="section" id="response-files">
+<span id="id5"></span><h4><a class="toc-backref" href="#id32">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="#id33">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="#id34">The <code class="docutils literal notranslate"><span class="pre">cl::getRegisteredOptions</span></code> function</a><a class="headerlink" href="#the-cl-getregisteredoptions-function" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::getRegisteredOptions</span></code> function is designed to give a programmer
+access to declared non-positional command line options so that how they appear
+in <code class="docutils literal notranslate"><span class="pre">-help</span></code> 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 <code class="docutils literal notranslate"><span class="pre">main</span></code>.</p>
+<p>This function can be used to gain access to options declared in libraries that
+the tool writer may not have direct access to.</p>
+<p>The function retrieves a <a class="reference internal" href="ProgrammersManual.html#dss-stringmap"><span class="std std-ref">StringMap</span></a> that maps the option
+string (e.g. <code class="docutils literal notranslate"><span class="pre">-help</span></code>) to an <code class="docutils literal notranslate"><span class="pre">Option*</span></code>.</p>
+<p>Here is an example of how the function could be used:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span> <span class="o">**</span><span class="n">argv</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">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="#id35">The <code class="docutils literal notranslate"><span class="pre">cl::ParseCommandLineOptions</span></code> function</a><a class="headerlink" href="#the-cl-parsecommandlineoptions-function" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::ParseCommandLineOptions</span></code> function is designed to be called directly
+from <code class="docutils literal notranslate"><span class="pre">main</span></code>, and is used to fill in the values of all of the command line
+option variables once <code class="docutils literal notranslate"><span class="pre">argc</span></code> and <code class="docutils literal notranslate"><span class="pre">argv</span></code> are available.</p>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::ParseCommandLineOptions</span></code> function requires two parameters (<code class="docutils literal notranslate"><span class="pre">argc</span></code>
+and <code class="docutils literal notranslate"><span class="pre">argv</span></code>), 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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> option is invoked.</p>
+</div>
+<div class="section" id="the-cl-parseenvironmentoptions-function">
+<span id="cl-parseenvironmentoptions"></span><h4><a class="toc-backref" href="#id36">The <code class="docutils literal notranslate"><span class="pre">cl::ParseEnvironmentOptions</span></code> function</a><a class="headerlink" href="#the-cl-parseenvironmentoptions-function" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::ParseEnvironmentOptions</span></code> 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 <code class="docutils literal notranslate"><span class="pre">argv</span></code> may not be
+available, it canât just look in <code class="docutils literal notranslate"><span class="pre">argv[0]</span></code>), 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
+<code class="docutils literal notranslate"><span class="pre">-help</span></code> option is invoked.</p>
+<p><code class="docutils literal notranslate"><span class="pre">cl::ParseEnvironmentOptions</span></code> 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 <code class="docutils literal notranslate"><span class="pre">cl::ParseEnvironmentOptions</span></code> does not support quoting, so
+an environment variable containing <code class="docutils literal notranslate"><span class="pre">-option</span> <span class="pre">"foo</span> <span class="pre">bar"</span></code> will be parsed as three
+words, <code class="docutils literal notranslate"><span class="pre">-option</span></code>, <code class="docutils literal notranslate"><span class="pre">"foo</span></code>, and <code class="docutils literal notranslate"><span class="pre">bar"</span></code>, 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="#id37">The <code class="docutils literal notranslate"><span class="pre">cl::SetVersionPrinter</span></code> function</a><a class="headerlink" href="#the-cl-setversionprinter-function" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::SetVersionPrinter</span></code> function is designed to be called directly from
+<code class="docutils literal notranslate"><span class="pre">main</span></code> and <em>before</em> <code class="docutils literal notranslate"><span class="pre">cl::ParseCommandLineOptions</span></code>. Its use is optional. It
+simply arranges for a function to be called in response to the <code class="docutils literal notranslate"><span class="pre">--version</span></code>
+option instead of having the <code class="docutils literal notranslate"><span class="pre">CommandLine</span></code> 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 <code class="docutils literal notranslate"><span class="pre">CommandLine</span></code> facilities. Such programs should just define a small
+function that takes no arguments and returns <code class="docutils literal notranslate"><span class="pre">void</span></code> and that prints out
+whatever version information is appropriate for the program. Pass the address of
+that function to <code class="docutils literal notranslate"><span class="pre">cl::SetVersionPrinter</span></code> to arrange for it to be called when
+the <code class="docutils literal notranslate"><span class="pre">--version</span></code> 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="#id38">The <code class="docutils literal notranslate"><span class="pre">cl::opt</span></code> class</a><a class="headerlink" href="#the-cl-opt-class" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::opt</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><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="nb">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 <code class="docutils literal notranslate"><span class="pre">parser</span></code> 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="#id39">The <code class="docutils literal notranslate"><span class="pre">cl::list</span></code> class</a><a class="headerlink" href="#the-cl-list-class" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::list</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><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 â<code class="docutils literal notranslate"><span class="pre">bool</span></code>â 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="#id40">The <code class="docutils literal notranslate"><span class="pre">cl::bits</span></code> class</a><a class="headerlink" href="#the-cl-bits-class" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::bits</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><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> <code class="docutils literal notranslate"><span class="pre">unsigned</span></code> 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="#id41">The <code class="docutils literal notranslate"><span class="pre">cl::alias</span></code> class</a><a class="headerlink" href="#the-cl-alias-class" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::alias</span></code> class is a nontemplated class that is used to form aliases for
+other arguments.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="#id42">The <code class="docutils literal notranslate"><span class="pre">cl::extrahelp</span></code> class</a><a class="headerlink" href="#the-cl-extrahelp-class" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::extrahelp</span></code> class is a nontemplated class that allows extra help text
+to be printed out for the <code class="docutils literal notranslate"><span class="pre">-help</span></code> option.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code> parameter to
+the constructor. The text passed to the constructor will be printed at the
+bottom of the help message, verbatim. Note that multiple <code class="docutils literal notranslate"><span class="pre">cl::extrahelp</span></code>
+<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 <code class="docutils literal notranslate"><span class="pre">cl::extrahelp</span></code>
+instance.</p>
+<p>For example:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="#id43">The <code class="docutils literal notranslate"><span class="pre">cl::OptionCategory</span></code> class</a><a class="headerlink" href="#the-cl-optioncategory-class" title="Permalink to this headline">¶</a></h4>
+<p>The <code class="docutils literal notranslate"><span class="pre">cl::OptionCategory</span></code> class is a simple class for declaring
+option categories.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">char*</span></code>.</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 <code class="docutils literal notranslate"><span class="pre">-help</span></code> 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 <code class="docutils literal notranslate"><span class="pre">-help</span></code>
+but will be shown in the output of <code class="docutils literal notranslate"><span class="pre">-help-hidden</span></code>.</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="#id44">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 <code class="docutils literal notranslate"><span class="pre">parser<type></span></code> if the command line
+option specifies that it uses values of type â<code class="docutils literal notranslate"><span class="pre">type</span></code>â. Because of this,
+custom option processing is specified with specializations of the â<code class="docutils literal notranslate"><span class="pre">parser</span></code>â
+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>
+<span id="enums"></span><ul class="simple" id="cl-parser">
+<li>The generic <code class="docutils literal notranslate"><span class="pre">parser<t></span></code> 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>
+<span id="boolean-flags"></span><ul class="simple" id="bool-parser">
+<li>The <strong>parser<bool> specialization</strong> is used to convert boolean strings to a
+boolean value. Currently accepted strings are â<code class="docutils literal notranslate"><span class="pre">true</span></code>â, â<code class="docutils literal notranslate"><span class="pre">TRUE</span></code>â,
+â<code class="docutils literal notranslate"><span class="pre">True</span></code>â, â<code class="docutils literal notranslate"><span class="pre">1</span></code>â, â<code class="docutils literal notranslate"><span class="pre">false</span></code>â, â<code class="docutils literal notranslate"><span class="pre">FALSE</span></code>â, â<code class="docutils literal notranslate"><span class="pre">False</span></code>â, and â<code class="docutils literal notranslate"><span class="pre">0</span></code>â.</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>
+<span id="integers"></span><ul class="simple" id="int">
+<li>The <strong>parser<int> specialization</strong> uses the C <code class="docutils literal notranslate"><span class="pre">strtol</span></code> 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 â<code class="docutils literal notranslate"><span class="pre">0</span></code>â prefix digit, and hexadecimal
+numbers with a prefix of â<code class="docutils literal notranslate"><span class="pre">0x</span></code>â or â<code class="docutils literal notranslate"><span class="pre">0X</span></code>â.</li>
+</ul>
+<span id="float"></span><span id="doubles"></span><ul class="simple" id="double">
+<li>The <strong>parser<double></strong> and <strong>parser<float> specializations</strong> use the standard
+C <code class="docutils literal notranslate"><span class="pre">strtod</span></code> function to convert floating point strings into floating point
+values. As such, a broad range of string formats is supported, including
+exponential notation (ex: <code class="docutils literal notranslate"><span class="pre">1.7e15</span></code>) 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="#id45">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="#id46">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 â<code class="docutils literal notranslate"><span class="pre">unsigned</span></code>â. We
+choose approach #2 above because we donât want to make this the default for all
+<code class="docutils literal notranslate"><span class="pre">unsigned</span></code> options.</p>
+<p>To start out, we declare our new <code class="docutils literal notranslate"><span class="pre">FileSizeParser</span></code> class:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span> <span class="nl">FileSizeParser</span> <span class="p">:</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 <code class="docutils literal notranslate"><span class="pre">cl::parser</span></code> 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 <code class="docutils literal notranslate"><span class="pre">parse</span></code> 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 â<code class="docutils literal notranslate"><span class="pre">unsigned</span></code>â variables.)</p>
+<p>For most purposes, the only method that must be implemented in a custom parser
+is the <code class="docutils literal notranslate"><span class="pre">parse</span></code> method. The <code class="docutils literal notranslate"><span class="pre">parse</span></code> 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 â<code class="docutils literal notranslate"><span class="pre">Val</span></code>â to the parsed value. In our example, we
+implement <code class="docutils literal notranslate"><span class="pre">parse</span></code> as:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><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="nb">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 â<code class="docutils literal notranslate"><span class="pre">123KKK</span></code>â for example),
+it is good enough for this example. Note that we use the option itself to print
+out the error message (the <code class="docutils literal notranslate"><span class="pre">error</span></code> 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++ notranslate"><div class="highlight"><pre><span></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">unsigned</span><span class="p">,</span> <span class="nb">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-default notranslate"><div class="highlight"><pre><span></span><span class="n">OPTIONS</span><span class="p">:</span>
+ <span class="o">-</span><span class="n">help</span> <span class="o">-</span> <span class="n">display</span> <span class="n">available</span> <span class="n">options</span> <span class="p">(</span><span class="o">-</span><span class="n">help</span><span class="o">-</span><span class="n">hidden</span> <span class="k">for</span> <span class="n">more</span><span class="p">)</span>
+ <span class="o">...</span>
+ <span class="o">-</span><span class="nb">max</span><span class="o">-</span><span class="n">file</span><span class="o">-</span><span class="n">size</span><span class="o">=<</span><span class="n">size</span><span class="o">></span> <span class="o">-</span> <span class="n">Maximum</span> <span class="n">file</span> <span class="n">size</span> <span class="n">to</span> <span class="n">accept</span>
+</pre></div>
+</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-default notranslate"><div class="highlight"><pre><span></span>$ ./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>
+</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="#id47">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 <code class="docutils literal notranslate"><span class="pre">cl::opt</span></code> 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 <code class="docutils literal notranslate"><span class="pre">llvm::DebugFlag</span></code> exported by the
+<code class="docutils literal notranslate"><span class="pre">lib/Support/Debug.cpp</span></code> file and the <code class="docutils literal notranslate"><span class="pre">llvm::TimePassesIsEnabled</span></code> flag
+exported by the <code class="docutils literal notranslate"><span class="pre">lib/IR/PassManager.cpp</span></code> file.</p>
+</div>
+<div class="section" id="dynamically-adding-command-line-options">
+<span id="dynamically-loaded-options"></span><h3><a class="toc-backref" href="#id48">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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CompileCudaWithLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CompileCudaWithLLVM.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CompileCudaWithLLVM.html (added)
+++ www-releases/trunk/9.0.0/docs/CompileCudaWithLLVM.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,603 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Compiling CUDA with clang — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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" role="main">
+
+ <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"><code class="docutils literal notranslate"><span class="pre"><math.h></span></code> and <code class="docutils literal notranslate"><span class="pre"><cmath></span></code></a></li>
+<li><a class="reference internal" href="#std-complex" id="id8"><code class="docutils literal notranslate"><span class="pre"><std::complex></span></code></a></li>
+<li><a class="reference internal" href="#algorithm" id="id9"><code class="docutils literal notranslate"><span class="pre"><algorithm></span></code></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 <code class="docutils literal notranslate"><span class="pre">__host__</span></code> and <code class="docutils literal notranslate"><span class="pre">__device__</span></code> 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 since llvm 3.9. Current release of clang (7.0.0) supports CUDA
+7.0 through 9.2. If you need support for CUDA 10, you will need to use clang
+built from r342924 or newer.</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 CUDA in a single
+directory from NVIDIAâs package.</p>
+<p>CUDA compilation is supported on Linux. Compilation on MacOS and Windows may or
+may not work and currently have no maintainers. Compilation with CUDA-9.x is
+<a class="reference external" href="https://bugs.llvm.org/show_bug.cgi?id=38811">currently broken on Windows</a>.</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 <code class="docutils literal notranslate"><span class="pre">axpy.cu</span></code>. (Clang detects that youâre
+compiling CUDA code by noticing that your filename ends with <code class="docutils literal notranslate"><span class="pre">.cu</span></code>.
+Alternatively, you can pass <code class="docutils literal notranslate"><span class="pre">-x</span> <span class="pre">cuda</span></code>.)</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 notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> clang++ axpy.cu -o axpy --cuda-gpu-arch<span class="o">=</span><GPU arch> <span class="se">\</span>
+ -L<CUDA install path>/<lib64 or lib> <span class="se">\</span>
+ -lcudart_static -ldl -lrt -pthread
+<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"><code class="docutils literal notranslate"><span class="pre"><CUDA</span> <span class="pre">install</span> <span class="pre">path></span></code> â the directory where you installed CUDA SDK.
+Typically, <code class="docutils literal notranslate"><span class="pre">/usr/local/cuda</span></code>.</p>
+<p>Pass e.g. <code class="docutils literal notranslate"><span class="pre">-L/usr/local/cuda/lib64</span></code> if compiling in 64-bit mode; otherwise,
+pass e.g. <code class="docutils literal notranslate"><span class="pre">-L/usr/local/cuda/lib</span></code>. (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.) Note that as of
+v10.0 CUDA SDK <a class="reference external" href="https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html#deprecated-features">no longer supports compilation of 32-bit
+applications</a>.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre"><GPU</span> <span class="pre">arch></span></code> â 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
+<code class="docutils literal notranslate"><span class="pre">--cuda-gpu-arch=sm_35</span></code>.</p>
+<p>Note: You cannot pass <code class="docutils literal notranslate"><span class="pre">compute_XX</span></code> as an argument to <code class="docutils literal notranslate"><span class="pre">--cuda-gpu-arch</span></code>;
+only <code class="docutils literal notranslate"><span class="pre">sm_XX</span></code> is currently supported. However, clang always includes PTX in
+its binaries, so e.g. a binary compiled with <code class="docutils literal notranslate"><span class="pre">--cuda-gpu-arch=sm_30</span></code> would be
+forwards-compatible with e.g. <code class="docutils literal notranslate"><span class="pre">sm_35</span></code> GPUs.</p>
+<p>You can pass <code class="docutils literal notranslate"><span class="pre">--cuda-gpu-arch</span></code> 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 <code class="docutils literal notranslate"><span class="pre">--cuda-path=/path/to/cuda</span></code> if you didnât install
+the CUDA SDK into <code class="docutils literal notranslate"><span class="pre">/usr/local/cuda</span></code> or <code class="docutils literal notranslate"><span class="pre">/usr/local/cuda-X.Y</span></code>.</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"><code class="docutils literal notranslate"><span class="pre">-ffp-contract={on,off,fast}</span></code> (defaults to <code class="docutils literal notranslate"><span class="pre">fast</span></code> on host and device when
+compiling CUDA) Controls whether the compiler emits fused multiply-add
+operations.</p>
+<ul class="simple">
+<li><code class="docutils literal notranslate"><span class="pre">off</span></code>: never emit fma operations, and prevent ptxas from fusing multiply
+and add instructions.</li>
+<li><code class="docutils literal notranslate"><span class="pre">on</span></code>: fuse multiplies and adds within a single statement, but never
+across statements (C11 semantics). Prevent ptxas from fusing other
+multiplies and adds.</li>
+<li><code class="docutils literal notranslate"><span class="pre">fast</span></code>: 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"><code class="docutils literal notranslate"><span class="pre">-fcuda-flush-denormals-to-zero</span></code> (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"><code class="docutils literal notranslate"><span class="pre">-fcuda-approx-transcendentals</span></code> (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 <code class="docutils literal notranslate"><span class="pre">sin.approx.f32</span></code>
+instruction.</p>
+<p>This is implied by <code class="docutils literal notranslate"><span class="pre">-ffast-math</span></code>.</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"><code class="docutils literal notranslate"><span class="pre"><math.h></span></code> and <code class="docutils literal notranslate"><span class="pre"><cmath></span></code></a><a class="headerlink" href="#math-h-and-cmath" title="Permalink to this headline">¶</a></h3>
+<p>In clang, <code class="docutils literal notranslate"><span class="pre">math.h</span></code> and <code class="docutils literal notranslate"><span class="pre">cmath</span></code> are available and <a class="reference external" href="https://github.com/llvm/llvm-test-suite/blob/master/External/CUDA/math_h.cu">pass</a>
+<a class="reference external" href="https://github.com/llvm/llvm-test-suite/blob/master/External/CUDA/cmath.cu">tests</a>
+adapted from libc++âs test suite.</p>
+<p>In nvcc <code class="docutils literal notranslate"><span class="pre">math.h</span></code> and <code class="docutils literal notranslate"><span class="pre">cmath</span></code> are mostly available. Versions of <code class="docutils literal notranslate"><span class="pre">::foof</span></code>
+in namespace std (e.g. <code class="docutils literal notranslate"><span class="pre">std::sinf</span></code>) are not available, and where the standard
+calls for overloads that take integral arguments, these are usually not
+available.</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span> <span class="cpf"><math.h></span><span class="cp"></span>
+<span class="cp">#include</span> <span class="cpf"><cmath.h></span><span class="cp"></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="nf">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"><code class="docutils literal notranslate"><span class="pre"><std::complex></span></code></a><a class="headerlink" href="#std-complex" title="Permalink to this headline">¶</a></h3>
+<p>nvcc does not officially support <code class="docutils literal notranslate"><span class="pre">std::complex</span></code>. Itâs an error to use
+<code class="docutils literal notranslate"><span class="pre">std::complex</span></code> in <code class="docutils literal notranslate"><span class="pre">__device__</span></code> code, but it often works in <code class="docutils literal notranslate"><span class="pre">__host__</span>
+<span class="pre">__device__</span></code> 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 <code class="docutils literal notranslate"><span class="pre">std::complex</span></code> function,
+especially when compiling without optimizations.</p>
+<p>As of 2016-11-16, clang supports <code class="docutils literal notranslate"><span class="pre">std::complex</span></code> 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"><code class="docutils literal notranslate"><span class="pre"><algorithm></span></code></a><a class="headerlink" href="#algorithm" title="Permalink to this headline">¶</a></h3>
+<p>In C++14, many useful functions from <code class="docutils literal notranslate"><span class="pre"><algorithm></span></code> (notably, <code class="docutils literal notranslate"><span class="pre">std::min</span></code> and
+<code class="docutils literal notranslate"><span class="pre">std::max</span></code>) 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 <code class="docutils literal notranslate"><span class="pre">__CUDA__</span></code> macro. <code class="docutils literal notranslate"><span class="pre">__CUDA_ARCH__</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><span class="cp">#if defined(__clang__) && defined(__CUDA__) && !defined(__CUDA_ARCH__)</span>
+<span class="c1">// 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="c1">// clang compiling CUDA code, device mode.</span>
+<span class="cp">#endif</span>
+</pre></div>
+</div>
+<p>Both clang and nvcc define <code class="docutils literal notranslate"><span class="pre">__CUDACC__</span></code> during CUDA compilation. You can
+detect NVCC specifically by looking for <code class="docutils literal notranslate"><span class="pre">__NVCC__</span></code>.</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 <code class="docutils literal notranslate"><span class="pre">.cu</span></code> file to split it into two source
+files: <code class="docutils literal notranslate"><span class="pre">H</span></code>, containing source code for the host, and <code class="docutils literal notranslate"><span class="pre">D</span></code>, containing
+source code for the device.</li>
+<li>For each GPU architecture <code class="docutils literal notranslate"><span class="pre">arch</span></code> that weâre compiling for, do:<ul>
+<li>Compile <code class="docutils literal notranslate"><span class="pre">D</span></code> using nvcc proper. The result of this is a <code class="docutils literal notranslate"><span class="pre">ptx</span></code> file for
+<code class="docutils literal notranslate"><span class="pre">P_arch</span></code>.</li>
+<li>Optionally, invoke <code class="docutils literal notranslate"><span class="pre">ptxas</span></code>, the PTX assembler, to generate a file,
+<code class="docutils literal notranslate"><span class="pre">S_arch</span></code>, containing GPU machine code (SASS) for <code class="docutils literal notranslate"><span class="pre">arch</span></code>.</li>
+</ul>
+</li>
+<li>Invoke <code class="docutils literal notranslate"><span class="pre">fatbin</span></code> to combine all <code class="docutils literal notranslate"><span class="pre">P_arch</span></code> and <code class="docutils literal notranslate"><span class="pre">S_arch</span></code> files into a
+single âfat binaryâ file, <code class="docutils literal notranslate"><span class="pre">F</span></code>.</li>
+<li>Compile <code class="docutils literal notranslate"><span class="pre">H</span></code> using an external host compiler (gcc, clang, or whatever you
+like). <code class="docutils literal notranslate"><span class="pre">F</span></code> is packaged up into a header file which is force-included into
+<code class="docutils literal notranslate"><span class="pre">H</span></code>; 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 <code class="docutils literal notranslate"><span class="pre">arch</span></code> that weâre compiling for, do:</p>
+<ul>
+<li><p class="first">Compile the input <code class="docutils literal notranslate"><span class="pre">.cu</span></code> file for device, using clang. <code class="docutils literal notranslate"><span class="pre">__host__</span></code> 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 <code class="docutils literal notranslate"><span class="pre">ptx</span></code> file <code class="docutils literal notranslate"><span class="pre">P_arch</span></code>.</p>
+</li>
+<li><p class="first">Invoke <code class="docutils literal notranslate"><span class="pre">ptxas</span></code> to generate a SASS file, <code class="docutils literal notranslate"><span class="pre">S_arch</span></code>. Note that, unlike
+nvcc, clang always generates SASS code.</p>
+</li>
+</ul>
+</li>
+<li><p class="first">Invoke <code class="docutils literal notranslate"><span class="pre">fatbin</span></code> to combine all <code class="docutils literal notranslate"><span class="pre">P_arch</span></code> and <code class="docutils literal notranslate"><span class="pre">S_arch</span></code> files into a
+single fat binary file, <code class="docutils literal notranslate"><span class="pre">F</span></code>.</p>
+</li>
+<li><p class="first">Compile <code class="docutils literal notranslate"><span class="pre">H</span></code> using clang. <code class="docutils literal notranslate"><span class="pre">__device__</span></code> code is parsed and must be
+semantically correct, even though weâre not generating code for the device
+at this time.</p>
+<p><code class="docutils literal notranslate"><span class="pre">F</span></code> is passed to this compilation, and clang includes it in a special ELF
+section, where it can be found by tools like <code class="docutils literal notranslate"><span class="pre">cuobjdump</span></code>.</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 <code class="docutils literal notranslate"><span class="pre">__host__</span></code> and <code class="docutils literal notranslate"><span class="pre">__device__</span></code> 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 â<code class="docutils literal notranslate"><span class="pre">__host__</span></code> functionsâ, â<code class="docutils literal notranslate"><span class="pre">__device__</span></code>
+functionsâ, and â<code class="docutils literal notranslate"><span class="pre">__host__</span> <span class="pre">__device__</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// nvcc: error - function "foo" has already been defined</span>
+<span class="n">__host__</span> <span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="nf">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++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// nvcc: no error</span>
+<span class="n">__host__</span> <span class="kt">void</span> <span class="nf">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="nf">foo</span><span class="p">()</span> <span class="p">{}</span>
+</pre></div>
+</div>
+<p>In clang, the <code class="docutils literal notranslate"><span class="pre">__host__</span></code> and <code class="docutils literal notranslate"><span class="pre">__device__</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// clang: no error</span>
+<span class="n">__host__</span> <span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="nf">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++ notranslate"><div class="highlight"><pre><span></span><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="nf">foo</span><span class="p">()</span> <span class="p">{}</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="nf">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="nf">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="nf">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 <code class="docutils literal notranslate"><span class="pre">__global__</span></code> 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++ notranslate"><div class="highlight"><pre><span></span><span class="n">__host__</span> <span class="kt">void</span> <span class="nf">foo</span><span class="p">();</span>
+<span class="n">__device__</span> <span class="kt">void</span> <span class="nf">foo</span><span class="p">();</span>
+
+<span class="n">__host__</span> <span class="kt">void</span> <span class="nf">bar</span><span class="p">();</span>
+<span class="n">__host__</span> <span class="n">__device__</span> <span class="kt">void</span> <span class="nf">bar</span><span class="p">();</span>
+
+<span class="n">__host__</span> <span class="kt">void</span> <span class="nf">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="nf">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="nf">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++ notranslate"><div class="highlight"><pre><span></span><span class="n">__host__</span> <span class="kt">void</span> <span class="nf">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="nf">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="nf">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="nf">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="nf">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="nf">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
+<code class="docutils literal notranslate"><span class="pre">inline</span></code> 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 <code class="docutils literal notranslate"><span class="pre">not_inline_hd</span></code>; device code is allowed to call
+<code class="docutils literal notranslate"><span class="pre">not_inline_hd</span></code>. In its generated code, nvcc may omit <code class="docutils literal notranslate"><span class="pre">not_inline_hd</span></code>âs
+call to <code class="docutils literal notranslate"><span class="pre">host_only</span></code> entirely, or it may try to generate code for
+<code class="docutils literal notranslate"><span class="pre">host_only</span></code> on the device. What you get seems to depend on whether or not
+the compiler chooses to inline <code class="docutils literal notranslate"><span class="pre">host_only</span></code>.</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++ notranslate"><div class="highlight"><pre><span></span><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="nf">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++ notranslate"><div class="highlight"><pre><span></span><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="nf">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="nf">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++ notranslate"><div class="highlight"><pre><span></span><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="nf">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="nf">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="nf">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="nf">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 <code class="docutils literal notranslate"><span class="pre">__attribute__((always_inline))</span></code>.)</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.github.io/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.github.io/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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CompilerWriterInfo.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CompilerWriterInfo.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CompilerWriterInfo.html (added)
+++ www-releases/trunk/9.0.0/docs/CompilerWriterInfo.html Thu Sep 19 07:32:46 2019
@@ -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="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Architecture & Platform Information for Compiler Writers — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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" role="main">
+
+ <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="#macos" id="id19">macOS</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="https://developer.arm.com/docs/ddi0487/latest">ARMv8-A Architecture Reference Manual</a> This document covers both AArch64 and ARM instructions</li>
+<li><a class="reference external" href="https://developer.arm.com/docs/ddi0406/latest">ARMv7-A Architecture Reference Manual</a> This has some useful info on what is supported by older architecture versions.</li>
+<li><a class="reference external" href="https://developer.arm.com/docs/ddi0403/latest">ARMv7-M Architecture Reference Manual</a> This covers the Thumb2-only microcontrollers</li>
+<li><a class="reference external" href="https://developer.arm.com/docs/ddi0419/latest">ARMv6-M Architecture Reference Manual</a> 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><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073b/IHI0073B_arm_neon_intrinsics_ref.pdf">ARM NEON Intrinsics Reference</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>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf">Cortex-A57 Software Optimization Guide</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0043d/IHI0043D_rtabi.pdf">Run-time ABI for the ARM Architecture</a> This documents the __aeabi_* helper functions.</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"><span class="doc">User Guide for AMDGPU Backend</span></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> (This is used for all non-Windows targets.)</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="https://developer.arm.com/docs/ihi0042/latest">Procedure Call Standard for the ARM 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="macos">
+<h3><a class="toc-backref" href="#id19">macOS</a><a class="headerlink" href="#macos" 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>
+<li><a class="reference external" href="https://developer.apple.com/library/archive/documentation/Xcode/Conceptual/iPhoneOSABIReference/Articles/ARM64FunctionCallingConventions.html">ARM64 Function Calling Conventions</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>
+<li><a class="reference external" href="https://docs.microsoft.com/en-us/cpp/build/arm64-exception-handling">ARM64 exception handling</a></li>
+<li><a class="reference external" href="https://docs.microsoft.com/en-us/cpp/build/arm-exception-handling">ARM exception handling</a></li>
+<li><a class="reference external" href="https://docs.microsoft.com/en-us/cpp/build/arm64-windows-abi-conventions">Overview of ARM64 ABI conventions</a></li>
+<li><a class="reference external" href="https://docs.microsoft.com/en-us/cpp/build/overview-of-arm-abi-conventions">Overview of ARM32 ABI Conventions</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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/Contributing.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/Contributing.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/Contributing.html (added)
+++ www-releases/trunk/9.0.0/docs/Contributing.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,194 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Contributing to LLVM — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVM Developer Policy" href="DeveloperPolicy.html" />
+ <link rel="prev" title="Stack Safety Analysis" href="StackSafetyAnalysis.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="DeveloperPolicy.html" title="LLVM Developer Policy"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="StackSafetyAnalysis.html" title="Stack Safety Analysis"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="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"><span class="doc">LLVM Developer Policy</span></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"><span class="doc">How to submit an LLVM bug report</span></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"><span class="doc">Getting Started with the LLVM System</span></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"><span class="doc">LLVM Coding Standards</span></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"><span class="std std-ref">Phabricator#requesting-a-review-via-the-web-interface</span></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"><span class="doc">LLVMâs documentation</span></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"><span class="doc">Getting Started with the LLVM System</span></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"><span class="doc">LLVM Language Reference Manual</span></a></dt>
+<dd>Defines the LLVM intermediate representation.</dd>
+<dt><a class="reference internal" href="ProgrammersManual.html"><span class="doc">LLVM Programmerâs Manual</span></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"><span class="std std-ref">Subsystem Documentation</span></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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="DeveloperPolicy.html" title="LLVM Developer Policy"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="StackSafetyAnalysis.html" title="Stack Safety Analysis"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/Coroutines.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/Coroutines.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/Coroutines.html (added)
+++ www-releases/trunk/9.0.0/docs/Coroutines.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,1272 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Coroutines in LLVM — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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" role="main">
+
+ <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 notranslate"><div class="highlight"><pre><span></span><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++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="o">*</span><span class="nf">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 notranslate"><div class="highlight"><pre><span></span><span class="k">define</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="nv">%n</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%id</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">token</span> <span class="vg">@llvm.coro.id</span><span class="p">(</span><span class="k">i32</span> <span class="m">0</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="k">i8</span><span class="p">*</span> <span class="k">null</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="nv">%size</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.coro.size.i32</span><span class="p">()</span>
+ <span class="nv">%alloc</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@malloc</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%size</span><span class="p">)</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">noalias</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.begin</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%alloc</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%loop</span>
+<span class="nl">loop:</span>
+ <span class="nv">%n.val</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i32</span> <span class="p">[</span> <span class="nv">%n</span><span class="p">,</span> <span class="nv">%entry</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%inc</span><span class="p">,</span> <span class="nv">%loop</span> <span class="p">]</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.val</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">%n.val</span><span class="p">)</span>
+ <span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span> <span class="vg">@llvm.coro.suspend</span><span class="p">(</span><span class="kt">token</span> <span class="k">none</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="k">switch</span> <span class="k">i8</span> <span class="nv nv-Anonymous">%0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%suspend</span> <span class="p">[</span><span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%loop</span>
+ <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup</span><span class="p">]</span>
+<span class="nl">cleanup:</span>
+ <span class="nv">%mem</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.free</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</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">@free</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%mem</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">%unused</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.end</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">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span>
+<span class="p">}</span>
+</pre></div>
+</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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><span class="k">define</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="nv">%n</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%id</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">token</span> <span class="vg">@llvm.coro.id</span><span class="p">(</span><span class="k">i32</span> <span class="m">0</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="k">i8</span><span class="p">*</span> <span class="k">null</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="nv">%alloc</span> <span class="p">=</span> <span class="k">call</span> <span class="k">noalias</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@malloc</span><span class="p">(</span><span class="k">i32</span> <span class="m">24</span><span class="p">)</span>
+ <span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">call</span> <span class="k">noalias</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.begin</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%alloc</span><span class="p">)</span>
+ <span class="nv">%frame</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i8</span><span class="p">*</span> <span class="nv nv-Anonymous">%0</span> <span class="k">to</span> <span class="nv">%f.frame</span><span class="p">*</span>
+ <span class="nv nv-Anonymous">%1</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</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="kt">void</span> <span class="p">(</span><span class="nv">%f.frame</span><span class="p">*)*</span> <span class="vg">@f.resume</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="nv nv-Anonymous">%1</span>
+ <span class="nv nv-Anonymous">%2</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</span><span class="p">,</span> <span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">1</span>
+ <span class="k">store</span> <span class="kt">void</span> <span class="p">(</span><span class="nv">%f.frame</span><span class="p">*)*</span> <span class="vg">@f.destroy</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="nv nv-Anonymous">%2</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="nv">%inc.spill.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">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i32</span> <span class="m">2</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="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">%n</span><span class="p">)</span>
+
+ <span class="k">ret</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%frame</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+<p>Outlined resume part of the coroutine will reside in function <cite>f.resume</cite>:</p>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><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 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 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 notranslate"><div class="highlight"><pre><span></span><span class="nl">entry:</span>
+ <span class="nv">%id</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">token</span> <span class="vg">@llvm.coro.id</span><span class="p">(</span><span class="k">i32</span> <span class="m">0</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="k">i8</span><span class="p">*</span> <span class="k">null</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="nv">%need.dyn.alloc</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.alloc</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">)</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%need.dyn.alloc</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%dyn.alloc</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%coro.begin</span>
+<span class="nl">dyn.alloc:</span>
+ <span class="nv">%size</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.coro.size.i32</span><span class="p">()</span>
+ <span class="nv">%alloc</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@CustomAlloc</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%size</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%coro.begin</span>
+<span class="nl">coro.begin:</span>
+ <span class="nv">%phi</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i8</span><span class="p">*</span> <span class="p">[</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%entry</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%alloc</span><span class="p">,</span> <span class="nv">%dyn.alloc</span> <span class="p">]</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">noalias</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.begin</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%phi</span><span class="p">)</span>
+</pre></div>
+</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 notranslate"><div class="highlight"><pre><span></span><span class="nl">cleanup:</span>
+ <span class="nv">%mem</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.free</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</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">%need.dyn.free</span> <span class="p">=</span> <span class="k">icmp</span> <span class="k">ne</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%mem</span><span class="p">,</span> <span class="k">null</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%need.dyn.free</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%dyn.free</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+<span class="nl">dyn.free:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@CustomFree</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%mem</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+<span class="nl">if.end:</span>
+ <span class="p">...</span>
+</pre></div>
+</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 notranslate"><div class="highlight"><pre><span></span><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++ notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="o">*</span><span class="nf">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 notranslate"><div class="highlight"><pre><span></span><span class="nl">loop:</span>
+ <span class="nv">%n.addr</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i32</span> <span class="p">[</span> <span class="nv">%n</span><span class="p">,</span> <span class="nv">%entry</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%inc</span><span class="p">,</span> <span class="nv">%loop.resume</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="nv">%n.addr</span><span class="p">)</span> <span class="vg">#4</span>
+ <span class="nv nv-Anonymous">%2</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span> <span class="vg">@llvm.coro.suspend</span><span class="p">(</span><span class="kt">token</span> <span class="k">none</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="k">switch</span> <span class="k">i8</span> <span class="nv nv-Anonymous">%2</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%suspend</span> <span class="p">[</span><span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%loop.resume</span>
+ <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup</span><span class="p">]</span>
+<span class="nl">loop.resume:</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.addr</span><span class="p">,</span> <span class="m">1</span>
+ <span class="nv">%sub</span> <span class="p">=</span> <span class="k">xor</span> <span class="k">i32</span> <span class="nv">%n.addr</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="nv nv-Anonymous">%3</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span> <span class="vg">@llvm.coro.suspend</span><span class="p">(</span><span class="kt">token</span> <span class="k">none</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="k">switch</span> <span class="k">i8</span> <span class="nv nv-Anonymous">%3</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%suspend</span> <span class="p">[</span><span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%loop</span>
+ <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup</span><span class="p">]</span>
+</pre></div>
+</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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span>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 notranslate"><div class="highlight"><pre><span></span><span class="nl">if.true:</span>
+ <span class="nv">%save1</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">token</span> <span class="vg">@llvm.coro.save</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">@async_op1</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">%suspend1</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.suspend</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%save1</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="k">switch</span> <span class="k">i8</span> <span class="nv">%suspend1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%suspend</span> <span class="p">[</span><span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%resume1</span>
+ <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup</span><span class="p">]</span>
+<span class="nl">if.false:</span>
+ <span class="nv">%save2</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">token</span> <span class="vg">@llvm.coro.save</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">@async_op2</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">%suspend2</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.suspend</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%save2</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="k">switch</span> <span class="k">i8</span> <span class="nv">%suspend1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%suspend</span> <span class="p">[</span><span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%resume2</span>
+ <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup</span><span class="p">]</span>
+</pre></div>
+</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 notranslate"><div class="highlight"><pre><span></span><span class="k">define</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="nv">%n</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%promise</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span>
+ <span class="nv">%pv</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%promise</span> <span class="k">to</span> <span class="k">i8</span><span class="p">*</span>
+ <span class="nv">%id</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">token</span> <span class="vg">@llvm.coro.id</span><span class="p">(</span><span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%pv</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="k">i8</span><span class="p">*</span> <span class="k">null</span><span class="p">)</span>
+ <span class="nv">%need.dyn.alloc</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.alloc</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">)</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%need.dyn.alloc</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%dyn.alloc</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%coro.begin</span>
+<span class="nl">dyn.alloc:</span>
+ <span class="nv">%size</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.coro.size.i32</span><span class="p">()</span>
+ <span class="nv">%alloc</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@malloc</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%size</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%coro.begin</span>
+<span class="nl">coro.begin:</span>
+ <span class="nv">%phi</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i8</span><span class="p">*</span> <span class="p">[</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%entry</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%alloc</span><span class="p">,</span> <span class="nv">%dyn.alloc</span> <span class="p">]</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">noalias</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.begin</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%phi</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%loop</span>
+<span class="nl">loop:</span>
+ <span class="nv">%n.val</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i32</span> <span class="p">[</span> <span class="nv">%n</span><span class="p">,</span> <span class="nv">%coro.begin</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%inc</span><span class="p">,</span> <span class="nv">%loop</span> <span class="p">]</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.val</span><span class="p">,</span> <span class="m">1</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="nv">%n.val</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%promise</span>
+ <span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span> <span class="vg">@llvm.coro.suspend</span><span class="p">(</span><span class="kt">token</span> <span class="k">none</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="k">switch</span> <span class="k">i8</span> <span class="nv nv-Anonymous">%0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%suspend</span> <span class="p">[</span><span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%loop</span>
+ <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup</span><span class="p">]</span>
+<span class="nl">cleanup:</span>
+ <span class="nv">%mem</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.free</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</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">@free</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%mem</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">%unused</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.end</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">i1</span> <span class="k">false</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span>
+<span class="p">}</span>
+</pre></div>
+</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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><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++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">__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="nb">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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">void</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">destroy</span><span class="p">(</span><span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">handle</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="overview">
+<h5>Overview:<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.destroy</span></code>â 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">void</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">resume</span><span class="p">(</span><span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">handle</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id3">
+<h5>Overview:<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.resume</span></code>â 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i1</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">done</span><span class="p">(</span><span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">handle</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id6">
+<h5>Overview:<a class="headerlink" href="#id6" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.done</span></code>â 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i8</span><span class="o">*</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">promise</span><span class="p">(</span><span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">ptr</span><span class="o">></span><span class="p">,</span> <span class="n">i32</span> <span class="o"><</span><span class="n">alignment</span><span class="o">></span><span class="p">,</span> <span class="n">i1</span> <span class="o"><</span><span class="n">from</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id9">
+<h5>Overview:<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.promise</span></code>â 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 notranslate"><div class="highlight"><pre><span></span><span class="k">define</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="nv">%n</span><span class="p">)</span> <span class="p">{</span>
+<span class="nl">entry:</span>
+ <span class="nv">%promise</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span>
+ <span class="nv">%pv</span> <span class="p">=</span> <span class="k">bitcast</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%promise</span> <span class="k">to</span> <span class="k">i8</span><span class="p">*</span>
+ <span class="c">; the second argument to coro.id points to the coroutine promise.</span>
+ <span class="nv">%id</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">token</span> <span class="vg">@llvm.coro.id</span><span class="p">(</span><span class="k">i32</span> <span class="m">0</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%pv</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="k">i8</span><span class="p">*</span> <span class="k">null</span><span class="p">)</span>
+ <span class="p">...</span>
+ <span class="nv">%hdl</span> <span class="p">=</span> <span class="k">call</span> <span class="k">noalias</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.begin</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%alloc</span><span class="p">)</span>
+ <span class="p">...</span>
+ <span class="k">store</span> <span class="k">i32</span> <span class="m">42</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%promise</span> <span class="c">; store something into the promise</span>
+ <span class="p">...</span>
+ <span class="k">ret</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%hdl</span>
+<span class="p">}</span>
+
+<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="c">; starts the coroutine and returns its handle</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">%val</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="c">; load a value from the promise</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">%val</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>
+</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i32</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">size</span><span class="o">.</span><span class="n">i32</span><span class="p">()</span>
+<span class="n">declare</span> <span class="n">i64</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">size</span><span class="o">.</span><span class="n">i64</span><span class="p">()</span>
+</pre></div>
+</div>
+<div class="section" id="id12">
+<h5>Overview:<a class="headerlink" href="#id12" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.size</span></code>â 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i8</span><span class="o">*</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">begin</span><span class="p">(</span><span class="n">token</span> <span class="o"><</span><span class="nb">id</span><span class="o">></span><span class="p">,</span> <span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">mem</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id15">
+<h5>Overview:<a class="headerlink" href="#id15" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.begin</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">llvm.coro.id</span></code>â
+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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i8</span><span class="o">*</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">free</span><span class="p">(</span><span class="n">token</span> <span class="o">%</span><span class="nb">id</span><span class="p">,</span> <span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">frame</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id18">
+<h5>Overview:<a class="headerlink" href="#id18" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.free</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">llvm.coro.id</span></code>â
+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 notranslate"><div class="highlight"><pre><span></span><span class="nl">cleanup:</span>
+ <span class="nv">%mem</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.free</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%frame</span><span class="p">)</span>
+ <span class="nv">%mem_not_null</span> <span class="p">=</span> <span class="k">icmp</span> <span class="k">ne</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%mem</span><span class="p">,</span> <span class="k">null</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%mem_not_null</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%if.then</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+<span class="nl">if.then:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@CustomFree</span><span class="p">(</span><span class="k">i8</span><span class="p">*</span> <span class="nv">%mem</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%if.end</span>
+<span class="nl">if.end:</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+</pre></div>
+</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 notranslate"><div class="highlight"><pre><span></span><span class="nl">cleanup:</span>
+ <span class="nv">%mem</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.free</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%frame</span><span class="p">)</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">%mem</span><span class="p">)</span>
+ <span class="k">ret</span> <span class="kt">void</span>
+</pre></div>
+</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i1</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">alloc</span><span class="p">(</span><span class="n">token</span> <span class="o"><</span><span class="nb">id</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id20">
+<h5>Overview:<a class="headerlink" href="#id20" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.alloc</span></code>â 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 â<code class="docutils literal notranslate"><span class="pre">llvm.coro.id</span></code>â
+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 notranslate"><div class="highlight"><pre><span></span><span class="nl">entry:</span>
+ <span class="nv">%id</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">token</span> <span class="vg">@llvm.coro.id</span><span class="p">(</span><span class="k">i32</span> <span class="m">0</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="k">i8</span><span class="p">*</span> <span class="k">null</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="nv">%dyn.alloc.required</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.alloc</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">)</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%dyn.alloc.required</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%coro.alloc</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%coro.begin</span>
+
+<span class="nl">coro.alloc:</span>
+ <span class="nv">%frame.size</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i32</span> <span class="vg">@llvm.coro.size</span><span class="p">()</span>
+ <span class="nv">%alloc</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@MyAlloc</span><span class="p">(</span><span class="k">i32</span> <span class="nv">%frame.size</span><span class="p">)</span>
+ <span class="k">br</span> <span class="kt">label</span> <span class="nv">%coro.begin</span>
+
+<span class="nl">coro.begin:</span>
+ <span class="nv">%phi</span> <span class="p">=</span> <span class="k">phi</span> <span class="k">i8</span><span class="p">*</span> <span class="p">[</span> <span class="k">null</span><span class="p">,</span> <span class="nv">%entry</span> <span class="p">],</span> <span class="p">[</span> <span class="nv">%alloc</span><span class="p">,</span> <span class="nv">%coro.alloc</span> <span class="p">]</span>
+ <span class="nv">%frame</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span><span class="p">*</span> <span class="vg">@llvm.coro.begin</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%id</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%phi</span><span class="p">)</span>
+</pre></div>
+</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i8</span><span class="o">*</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">noop</span><span class="p">()</span>
+</pre></div>
+</div>
+<div class="section" id="id24">
+<h5>Overview:<a class="headerlink" href="#id24" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.noop</span></code>â 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i8</span><span class="o">*</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">frame</span><span class="p">()</span>
+</pre></div>
+</div>
+<div class="section" id="id27">
+<h5>Overview:<a class="headerlink" href="#id27" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.frame</span></code>â 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">token</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">id</span><span class="p">(</span><span class="n">i32</span> <span class="o"><</span><span class="n">align</span><span class="o">></span><span class="p">,</span> <span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">promise</span><span class="o">></span><span class="p">,</span> <span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">coroaddr</span><span class="o">></span><span class="p">,</span>
+ <span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">fnaddrs</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id30">
+<h5>Overview:<a class="headerlink" href="#id30" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.id</span></code>â 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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i1</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">end</span><span class="p">(</span><span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">handle</span><span class="o">></span><span class="p">,</span> <span class="n">i1</span> <span class="o"><</span><span class="n">unwind</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id33">
+<h5>Overview:<a class="headerlink" href="#id33" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.end</span></code>â 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 notranslate"><div class="highlight"><pre><span></span><span class="nl">ehcleanup:</span>
+ <span class="nv">%InResumePart</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.end</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="k">i1</span> <span class="k">true</span><span class="p">)</span>
+ <span class="k">br</span> <span class="k">i1</span> <span class="nv">%InResumePart</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%eh.resume</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup.cont</span>
+
+<span class="nl">cleanup.cont:</span>
+ <span class="c">; rest of the cleanup</span>
+
+<span class="nl">eh.resume:</span>
+ <span class="nv">%exn</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">%exn.slot</span><span class="p">,</span> <span class="k">align</span> <span class="m">8</span>
+ <span class="nv">%sel</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">%ehselector.slot</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
+ <span class="nv">%lpad.val</span> <span class="p">=</span> <span class="k">insertvalue</span> <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">undef</span><span class="p">,</span> <span class="k">i8</span><span class="p">*</span> <span class="nv">%exn</span><span class="p">,</span> <span class="m">0</span>
+ <span class="nv">%lpad.val29</span> <span class="p">=</span> <span class="k">insertvalue</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i32</span> <span class="p">}</span> <span class="nv">%lpad.val</span><span class="p">,</span> <span class="k">i32</span> <span class="nv">%sel</span><span class="p">,</span> <span class="m">1</span>
+ <span class="k">resume</span> <span class="p">{</span> <span class="k">i8</span><span class="p">*,</span> <span class="k">i32</span> <span class="p">}</span> <span class="nv">%lpad.val29</span>
+</pre></div>
+</div>
+<p>The <cite>CoroSpit</cite> pass replaces <cite>coro.end</cite> with <code class="docutils literal notranslate"><span class="pre">True</span></code> in the resume functions,
+thus leading to immediate unwind to the caller, whereas in start function it
+is replaced with <code class="docutils literal notranslate"><span class="pre">False</span></code>, 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 notranslate"><div class="highlight"><pre><span></span><span class="nl">ehcleanup:</span>
+ <span class="nv">%tok</span> <span class="p">=</span> <span class="k">cleanuppad</span> <span class="k">within</span> <span class="k">none</span> <span class="p">[]</span>
+ <span class="nv">%unused</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.end</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="k">i1</span> <span class="k">true</span><span class="p">)</span> <span class="p">[</span> <span class="s">"funclet"</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%tok</span><span class="p">)</span> <span class="p">]</span>
+ <span class="k">cleanupret</span> <span class="k">from</span> <span class="nv">%tok</span> <span class="k">unwind</span> <span class="kt">label</span> <span class="nv">%RestOfTheCleanup</span>
+</pre></div>
+</div>
+<p>The <cite>CoroSplit</cite> pass, if the funclet bundle is present, will insert
+<code class="docutils literal notranslate"><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></code> 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><code class="docutils literal notranslate"><span class="pre">ret</span> <span class="pre">void</span></code></td>
+</tr>
+<tr class="row-odd"><td rowspan="2">unwind=true</td>
+<td>WinEH</td>
+<td>nothing</td>
+<td><code class="docutils literal notranslate"><span class="pre">cleanupret</span> <span class="pre">unwind</span> <span class="pre">to</span> <span class="pre">caller</span></code></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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i8</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">suspend</span><span class="p">(</span><span class="n">token</span> <span class="o"><</span><span class="n">save</span><span class="o">></span><span class="p">,</span> <span class="n">i1</span> <span class="o"><</span><span class="n">final</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id36">
+<h5>Overview:<a class="headerlink" href="#id36" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.suspend</span></code>â 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 notranslate"><div class="highlight"><pre><span></span><span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span> <span class="vg">@llvm.coro.suspend</span><span class="p">(</span><span class="kt">token</span> <span class="k">none</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+<span class="k">switch</span> <span class="k">i8</span> <span class="nv nv-Anonymous">%0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%suspend</span> <span class="p">[</span><span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%resume</span>
+ <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup</span><span class="p">]</span>
+</pre></div>
+</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 notranslate"><div class="highlight"><pre><span></span><span class="nl">while.end:</span>
+ <span class="nv">%s.final</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i8</span> <span class="vg">@llvm.coro.suspend</span><span class="p">(</span><span class="kt">token</span> <span class="k">none</span><span class="p">,</span> <span class="k">i1</span> <span class="k">true</span><span class="p">)</span>
+ <span class="k">switch</span> <span class="k">i8</span> <span class="nv">%s.final</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%suspend</span> <span class="p">[</span><span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%trap</span>
+ <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup</span><span class="p">]</span>
+<span class="nl">trap:</span>
+ <span class="k">call</span> <span class="kt">void</span> <span class="vg">@llvm.trap</span><span class="p">()</span>
+ <span class="k">unreachable</span>
+</pre></div>
+</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">token</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">handle</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id39">
+<h5>Overview:<a class="headerlink" href="#id39" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.save</span></code>â 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 notranslate"><div class="highlight"><pre><span></span><span class="nv">%save1</span> <span class="p">=</span> <span class="k">call</span> <span class="kt">token</span> <span class="vg">@llvm.coro.save</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">@async_op1</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">%suspend1</span> <span class="p">=</span> <span class="k">call</span> <span class="k">i1</span> <span class="vg">@llvm.coro.suspend</span><span class="p">(</span><span class="kt">token</span> <span class="nv">%save1</span><span class="p">,</span> <span class="k">i1</span> <span class="k">false</span><span class="p">)</span>
+<span class="k">switch</span> <span class="k">i8</span> <span class="nv">%suspend1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%suspend</span> <span class="p">[</span><span class="k">i8</span> <span class="m">0</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%resume1</span>
+ <span class="k">i8</span> <span class="m">1</span><span class="p">,</span> <span class="kt">label</span> <span class="nv">%cleanup</span><span class="p">]</span>
+</pre></div>
+</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-default notranslate"><div class="highlight"><pre><span></span><span class="n">declare</span> <span class="n">i1</span> <span class="nd">@llvm</span><span class="o">.</span><span class="n">coro</span><span class="o">.</span><span class="n">param</span><span class="p">(</span><span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">original</span><span class="o">></span><span class="p">,</span> <span class="n">i8</span><span class="o">*</span> <span class="o"><</span><span class="n">copy</span><span class="o">></span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="id43">
+<h5>Overview:<a class="headerlink" href="#id43" title="Permalink to this headline">¶</a></h5>
+<p>The â<code class="docutils literal notranslate"><span class="pre">llvm.coro.param</span></code>â 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++ notranslate"><div class="highlight"><pre><span></span><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="nf">foo</span><span class="p">();</span> <span class="kt">void</span> <span class="nf">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="nf">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 notranslate"><div class="highlight"><pre><span></span>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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/CoverageMappingFormat.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/CoverageMappingFormat.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/CoverageMappingFormat.html (added)
+++ www-releases/trunk/9.0.0/docs/CoverageMappingFormat.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,654 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>LLVM Code Coverage Mapping Format — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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" role="main">
+
+ <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 <code class="docutils literal notranslate"><span class="pre">-fprofile-instr-generate</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">-fprofile-instr-generate</span></code> option with the additional <code class="docutils literal notranslate"><span class="pre">-fcoverage-mapping</span></code>
+option:</p>
+<p><code class="docutils literal notranslate"><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></code></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><code class="docutils literal notranslate"><span class="pre">./test</span></code></p>
+</li>
+<li><p class="first">After that, merge the profile data using the <em>llvm-profdata</em> tool:</p>
+<p><code class="docutils literal notranslate"><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></code></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><code class="docutils literal notranslate"><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></code></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 <code class="docutils literal notranslate"><span class="pre">-fcoverage-mapping</span></code>, 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 notranslate" id="coverage-mapping-sample"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></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>
+</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><code class="docutils literal notranslate"><span class="pre">[filenames,</span> <span class="pre">coverageMappingDataForFunctionRecord0,</span> <span class="pre">coverageMappingDataForFunctionRecord1,</span> <span class="pre">...,</span> <span class="pre">padding]</span></code></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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">0x01</span></code>. 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 notranslate"><div class="highlight"><pre><span></span><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><code class="docutils literal notranslate"><span class="pre">0x01</span></code></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><code class="docutils literal notranslate"><span class="pre">0x00</span></code></td>
+<td>An index into the filenames array which corresponds to the file â/Users/alex/test.câ.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">0x00</span></code></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><code class="docutils literal notranslate"><span class="pre">0x01</span></code></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><code class="docutils literal notranslate"><span class="pre">0x01</span></code></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><code class="docutils literal notranslate"><span class="pre">0x01</span></code></td>
+<td>The starting line of the first mapping region in this function.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">0x0C</span></code></td>
+<td>The starting column of the first mapping region in this function.</td>
+</tr>
+<tr class="row-even"><td><code class="docutils literal notranslate"><span class="pre">0x02</span></code></td>
+<td>The ending line of the first mapping region in this function.</td>
+</tr>
+<tr class="row-odd"><td><code class="docutils literal notranslate"><span class="pre">0x02</span></code></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><code class="docutils literal notranslate"><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></code></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><code class="docutils literal notranslate"><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></code></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 <code class="docutils literal notranslate"><span class="pre">:</span></code> in the <code class="docutils literal notranslate"><span class="pre">[foo</span> <span class="pre">:</span> <span class="pre">type]</span></code> 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><code class="docutils literal notranslate"><span class="pre">[length</span> <span class="pre">:</span> <span class="pre">LEB128,</span> <span class="pre">characters...]</span></code></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><code class="docutils literal notranslate"><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></code></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><code class="docutils literal notranslate"><span class="pre">[value</span> <span class="pre">:</span> <span class="pre">LEB128]</span></code></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><code class="docutils literal notranslate"><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></code></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><code class="docutils literal notranslate"><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></code></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><code class="docutils literal notranslate"><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></code></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><code class="docutils literal notranslate"><span class="pre">[header,</span> <span class="pre">source</span> <span class="pre">range]</span></code></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><code class="docutils literal notranslate"><span class="pre">[counter]</span></code></p>
+<p>or</p>
+<p><code class="docutils literal notranslate"><span class="pre">[pseudo-counter]</span></code></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><code class="docutils literal notranslate"><span class="pre">[value</span> <span class="pre">:</span> <span class="pre">LEB128]</span></code></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><code class="docutils literal notranslate"><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></code></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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/DebuggingJITedCode.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/DebuggingJITedCode.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/DebuggingJITedCode.html (added)
+++ www-releases/trunk/9.0.0/docs/DebuggingJITedCode.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,212 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Debugging JIT-ed Code With GDB — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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" role="main">
+
+ <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
+(<code class="docutils literal notranslate"><span class="pre">__jit_debug_register_code</span></code>) 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 macOS.</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 <code class="docutils literal notranslate"><span class="pre">-use-mcjit</span></code> 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 notranslate"><div class="highlight"><pre><span></span><span class="mi">1</span> <span class="kt">int</span> <span class="nf">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="nf">main</span><span class="p">(</span><span class="kt">int</span> <span class="n">argc</span><span class="p">,</span> <span class="kt">char</span><span class="o">**</span> <span class="n">argv</span><span class="p">)</span>
+<span class="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 <code class="docutils literal notranslate"><span class="pre">lli</span></code> inside GDB:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nv">$BINPATH</span>/clang -cc1 -O0 -g -emit-llvm showdebug.c
+$ gdb --quiet --args <span class="nv">$BINPATH</span>/lli -use-mcjit showdebug.ll <span class="m">5</span>
+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 <span class="m">1</span> <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 <span class="m">5</span>
+<span class="o">[</span>Thread debugging using libthread_db enabled<span class="o">]</span>
+
+Breakpoint <span class="m">1</span>, compute_factorial <span class="o">(</span><span class="nv">n</span><span class="o">=</span><span class="m">5</span><span class="o">)</span> at showdebug.c:6
+<span class="m">6</span> int <span class="nv">f</span> <span class="o">=</span> n<span class="p">;</span>
+<span class="o">(</span>gdb<span class="o">)</span> p n
+<span class="nv">$1</span> <span class="o">=</span> <span class="m">5</span>
+<span class="o">(</span>gdb<span class="o">)</span> p f
+<span class="nv">$2</span> <span class="o">=</span> <span class="m">0</span>
+<span class="o">(</span>gdb<span class="o">)</span> n
+<span class="m">7</span> <span class="k">while</span> <span class="o">(</span>--n > <span class="m">1</span><span class="o">)</span>
+<span class="o">(</span>gdb<span class="o">)</span> p f
+<span class="nv">$3</span> <span class="o">=</span> <span class="m">5</span>
+<span class="o">(</span>gdb<span class="o">)</span> b showdebug.c:9
+Breakpoint <span class="m">2</span> at 0x7ffff7ed404c: file showdebug.c, line <span class="m">9</span>.
+<span class="o">(</span>gdb<span class="o">)</span> c
+Continuing.
+
+Breakpoint <span class="m">2</span>, compute_factorial <span class="o">(</span><span class="nv">n</span><span class="o">=</span><span class="m">1</span><span class="o">)</span> at showdebug.c:9
+<span class="m">9</span> <span class="k">return</span> f<span class="p">;</span>
+<span class="o">(</span>gdb<span class="o">)</span> p f
+<span class="nv">$4</span> <span class="o">=</span> <span class="m">120</span>
+<span class="o">(</span>gdb<span class="o">)</span> bt
+<span class="c1">#0 compute_factorial (n=1) at showdebug.c:9</span>
+<span class="c1">#1 0x00007ffff7ed40a9 in main (argc=2, argv=0x16677e0) at showdebug.c:18</span>
+<span class="c1">#2 0x3500000001652748 in ?? ()</span>
+<span class="c1">#3 0x00000000016677e0 in ?? ()</span>
+<span class="c1">#4 0x0000000000000002 in ?? ()</span>
+<span class="c1">#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="c1">#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="c1">#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="c1">#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><span class="m">2</span>, <span class="nv">argv</span><span class="o">=</span>0x16677e0<span class="o">)</span> at showdebug.c:18
+<span class="m">18</span> 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><span class="p">;</span>
+Value returned is <span class="nv">$5</span> <span class="o">=</span> <span class="m">120</span>
+<span class="o">(</span>gdb<span class="o">)</span> p result
+<span class="nv">$6</span> <span class="o">=</span> <span class="m">23406408</span>
+<span class="o">(</span>gdb<span class="o">)</span> n
+<span class="m">21</span> <span class="k">return</span> result<span class="p">;</span>
+<span class="o">(</span>gdb<span class="o">)</span> p result
+<span class="nv">$7</span> <span class="o">=</span> <span class="m">120</span>
+<span class="o">(</span>gdb<span class="o">)</span> c
+Continuing.
+
+Program exited with code <span class="m">0170</span>.
+<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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/DeveloperPolicy.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/DeveloperPolicy.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/DeveloperPolicy.html (added)
+++ www-releases/trunk/9.0.0/docs/DeveloperPolicy.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,900 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>LLVM Developer Policy — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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" role="main">
+
+ <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="id7">Introduction</a></li>
+<li><a class="reference internal" href="#developer-policies" id="id8">Developer Policies</a><ul>
+<li><a class="reference internal" href="#stay-informed" id="id9">Stay Informed</a></li>
+<li><a class="reference internal" href="#making-and-submitting-a-patch" id="id10">Making and Submitting a Patch</a></li>
+<li><a class="reference internal" href="#code-reviews" id="id11">Code Reviews</a></li>
+<li><a class="reference internal" href="#code-owners" id="id12">Code Owners</a></li>
+<li><a class="reference internal" href="#test-cases" id="id13">Test Cases</a></li>
+<li><a class="reference internal" href="#quality" id="id14">Quality</a></li>
+<li><a class="reference internal" href="#commit-messages" id="id15">Commit messages</a></li>
+<li><a class="reference internal" href="#obtaining-commit-access" id="id16">Obtaining Commit Access</a></li>
+<li><a class="reference internal" href="#making-a-major-change" id="id17">Making a Major Change</a></li>
+<li><a class="reference internal" href="#incremental-development" id="id18">Incremental Development</a></li>
+<li><a class="reference internal" href="#attribution-of-changes" id="id19">Attribution of Changes</a></li>
+<li><a class="reference internal" href="#ir-backwards-compatibility" id="id20">IR Backwards Compatibility</a></li>
+<li><a class="reference internal" href="#c-api-changes" id="id21">C API Changes</a></li>
+<li><a class="reference internal" href="#new-targets" id="id22">New Targets</a></li>
+<li><a class="reference internal" href="#updating-toolchain-requirements" id="id23">Updating Toolchain Requirements</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#copyright-license-and-patents" id="id24">Copyright, License, and Patents</a><ul>
+<li><a class="reference internal" href="#copyright" id="id25">Copyright</a></li>
+<li><a class="reference internal" href="#relicensing" id="id26">Relicensing</a></li>
+<li><a class="reference internal" href="#new-llvm-project-license-framework" id="id27">New LLVM Project License Framework</a></li>
+<li><a class="reference internal" href="#patents" id="id28">Patents</a></li>
+<li><a class="reference internal" href="#legacy-license-structure" id="id29">Legacy License Structure</a></li>
+</ul>
+</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>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 tree as stable as possible.</li>
+<li>Establish awareness of the projectâs <a class="reference internal" href="#copyright-license-patents"><span class="std std-ref">copyright, license, and patent
+policies</span></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="#id8">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="#id9">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="#id10">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 git master, not a branch, and not an old version
+of LLVM. This makes it easy to apply the patch. For information on how to
+clone from git, please see the <a class="reference internal" href="GettingStarted.html#checkout"><span class="std std-ref">Getting Started Guide</span></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 <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">format-patch</span></code>, or similar. If you use a
+different tool, make sure it uses the <code class="docutils literal notranslate"><span class="pre">diff</span> <span class="pre">-u</span></code> format and that it
+doesnât contain clutter which makes it hard to read.</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
+<code class="docutils literal notranslate"><span class="pre">mail.content_disposition_type</span></code>, and set its value to <code class="docutils literal notranslate"><span class="pre">1</span></code>. Without this
+setting, Thunderbird sends your attachment using <code class="docutils literal notranslate"><span class="pre">Content-Disposition:</span> <span class="pre">inline</span></code>
+rather than <code class="docutils literal notranslate"><span class="pre">Content-Disposition:</span> <span class="pre">attachment</span></code>. 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 LLVM
+licensing terms 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="#id11">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"><span class="doc">Code Reviews with Phabricator</span></a>.</p>
+</div>
+<div class="section" id="code-owners">
+<span id="id1"></span><h3><a class="toc-backref" href="#id12">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="https://github.com/llvm/llvm-project/blob/master/llvm/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="#id13">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 <code class="docutils literal notranslate"><span class="pre">llvm/test</span></code>
+directory. The appropriate sub-directory should be selected (see the
+<a class="reference internal" href="TestingGuide.html"><span class="doc">Testing Guide</span></a> for details).</li>
+<li>Test cases should be written in <a class="reference internal" href="LangRef.html"><span class="doc">LLVM assembly language</span></a>.</li>
+<li>Test cases, especially for regressions, should be reduced as much as possible,
+by <a class="reference internal" href="Bugpoint.html"><span class="doc">bugpoint</span></a> or manually. It is unacceptable to place an
+entire failing program into <code class="docutils literal notranslate"><span class="pre">llvm/test</span></code> 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 <code class="docutils literal notranslate"><span class="pre">llvm-test</span></code> 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="#id14">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 <code class="docutils literal notranslate"><span class="pre">llvm/test</span></code> 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 â<code class="docutils literal notranslate"><span class="pre">llvm-test/MultiSource/Benchmarks</span></code>â.</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 <code class="docutils literal notranslate"><span class="pre">llvm-test</span></code>
+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="#id15">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="#id16">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. â<code class="docutils literal notranslate"><span class="pre">2ACR96qjUqsyM</span></code>â.
+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 â<code class="docutils literal notranslate"><span class="pre">htpasswd</span></code>â (a utility that
+comes with apache) in <em>crypt</em> mode (often enabled with â<code class="docutils literal notranslate"><span class="pre">-d</span></code>â), 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.
+â<code class="docutils literal notranslate"><span class="pre">$apr1$vea6bBV2$Z8IFx.AfeD8LhqlZFqJer0</span></code>â, 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
+moderator of the 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. Avoid committing formatting- or whitespace-only changes outside of
+code you plan to make subsequent changes to. Also, try to separate
+formatting or whitespace changes from functional changes, either by
+correcting the format first (ideally) or afterward. Such changes should be
+highly localized and the commit message should clearly state that the commit
+is not intended to change functionality, usually by stating it is
+<a class="reference internal" href="Lexicon.html#nfc"><span class="std std-ref">NFC</span></a>.</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="#id17">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="#id18">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="#id19">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="#id20">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
+<code class="docutils literal notranslate"><span class="pre">test/Bitcode/compatibility.ll</span></code>.</li>
+<li>The current LLVM version supports loading any bitcode since version 3.0.</li>
+<li>After each X.Y release, <code class="docutils literal notranslate"><span class="pre">compatibility.ll</span></code> must be copied to
+<code class="docutils literal notranslate"><span class="pre">compatibility-X.Y.ll</span></code>. The corresponding bitcode file should be assembled
+using the X.Y build and committed as <code class="docutils literal notranslate"><span class="pre">compatibility-X.Y.ll.bc</span></code>.</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="#id21">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="#id22">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"><span class="std std-ref">code owner</span></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"><span class="doc">IR standard</span></a>) <strong>before</strong> the merge of the new target changes,
+following the <a class="reference internal" href="#ir-backwards-compatibility"><span class="std std-ref">IR Backwards Compatibility</span></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"><span class="doc">coding standards</span></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 <code class="docutils literal notranslate"><span class="pre">check-all</span></code> must pass with the
+new target built, and where applicable, the <code class="docutils literal notranslate"><span class="pre">test-suite</span></code> 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. <code class="docutils literal notranslate"><span class="pre">check-all</span></code> 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 class="section" id="updating-toolchain-requirements">
+<span id="toolchain"></span><h3><a class="toc-backref" href="#id23">Updating Toolchain Requirements</a><a class="headerlink" href="#updating-toolchain-requirements" title="Permalink to this headline">¶</a></h3>
+<p>We intend to require newer toolchains as time goes by. This means LLVMâs
+codebase can use newer versions of C++ as they get standardized. Requiring newer
+toolchains to build LLVM can be painful for those building LLVM; therefore, it
+will only be done through the following process:</p>
+<blockquote>
+<div><ul class="simple">
+<li>Generally, try to support LLVM and GCC versions from the last 3 years at a
+minimum. This time-based guideline is not strict: we may support much older
+compilers, or decide to support fewer versions.</li>
+<li>An RFC is sent to the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev mailing list</a><ul>
+<li>Detail upsides of the version increase (e.g. which newer C++ language or
+library features LLVM should use; avoid miscompiles in particular compiler
+versions, etc).</li>
+<li>Detail downsides on important platforms (e.g. Ubuntu LTS status).</li>
+</ul>
+</li>
+<li>Once the RFC reaches consensus, update the CMake toolchain version checks as
+well as the <a class="reference internal" href="GettingStarted.html"><span class="doc">getting started</span></a> guide. We want to
+soft-error when developers compile LLVM. We say âsoft-errorâ because the
+error can be turned into a warning using a CMake flag. This is an important
+step: LLVM still doesnât have code which requires the new toolchains, but it
+soon will. If you compile LLVM but donât read the mailing list, we should
+tell you!</li>
+<li>Ensure that at least one LLVM release has had this soft-error. Not all
+developers compile LLVM top-of-tree. These release-bound developers should
+also be told about upcoming changes.</li>
+<li>Turn the soft-error into a hard-error after said LLVM release has branched.</li>
+<li>Update the <a class="reference internal" href="CodingStandards.html"><span class="doc">coding standards</span></a> to allow the new
+features weâve explicitly approved in the RFC.</li>
+<li>Start using the new features in LLVMâs codebase.</li>
+</ul>
+</div></blockquote>
+<p>Hereâs a <a class="reference external" href="http://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html">sample RFC</a> and the
+<a class="reference external" href="https://reviews.llvm.org/D57264">corresponding change</a>.</p>
+</div>
+</div>
+<div class="section" id="copyright-license-and-patents">
+<span id="copyright-license-patents"></span><h2><a class="toc-backref" href="#id24">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 a licensed 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 contributors of
+the code. The code is licensed under permissive <a class="reference internal" href="#open-source-licensing-terms">open source licensing terms</a>,
+namely the Apache 2 license, which includes a copyright and <a class="reference internal" href="#patent-license">patent license</a>.
+When you contribute code to the LLVM project, you license it under these terms.</p>
+<p>If you have questions or comments about these topics, please contact the
+<a class="reference external" href="mailto:llvm-dev%40lists.llvm.org">LLVM Developerâs Mailing List</a>. However,
+please realize that most compiler developers are not lawyers, and therefore you
+will not be getting official legal advice.</p>
+<div class="section" id="copyright">
+<h3><a class="toc-backref" href="#id25">Copyright</a><a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM project does not collect copyright assignments, which means that the
+copyright for the code in the project is held by the respective contributors.
+Because you (or your company)
+retain ownership of the code you contribute, you know it may only be used under
+the terms of the open source license you contributed it under: the license for
+your contributions cannot be changed in the future without your approval.</p>
+<p>Because the LLVM project does not require copyright assignments, changing the
+LLVM license requires tracking down the
+contributors to LLVM and getting them to agree that a license change is
+acceptable for their contributions. We feel that a high burden for relicensing
+is good for the project, because contributors do not have to fear that their
+code will be used in a way with which they disagree.</p>
+</div>
+<div class="section" id="relicensing">
+<h3><a class="toc-backref" href="#id26">Relicensing</a><a class="headerlink" href="#relicensing" title="Permalink to this headline">¶</a></h3>
+<p>The last paragraph notwithstanding, the LLVM Project is in the middle of a large
+effort to change licenses, which aims to solve several problems:</p>
+<ul class="simple">
+<li>The old licenses made it difficult to move code from (e.g.) the compiler to
+runtime libraries, because runtime libraries used a different license from the
+rest of the compiler.</li>
+<li>Some contributions were not submitted to LLVM due to concerns that
+the patent grant required by the project was overly broad.</li>
+<li>The patent grant was unique to the LLVM Project, not written by a lawyer, and
+was difficult to determine what protection was provided (if any).</li>
+</ul>
+<p>The scope of relicensing is all code that is considered part of the LLVM
+project, including the main LLVM repository, runtime libraries (compiler_rt,
+OpenMP, etc), Polly, and all other subprojects. There are a few exceptions:</p>
+<ul class="simple">
+<li>Code imported from other projects (e.g. Google Test, Autoconf, etc) will
+remain as it is. This code isnât developed as part of the LLVM project, it
+is used by LLVM.</li>
+<li>Some subprojects are impractical or uninteresting to relicense (e.g. llvm-gcc
+and dragonegg). These will be split off from the LLVM project (e.g. to
+separate Github projects), allowing interested people to continue their
+development elsewhere.</li>
+</ul>
+<p>To relicense LLVM, we will be seeking approval from all of the copyright holders
+of code in the repository, or potentially remove/rewrite code if we cannot.
+This is a large
+and challenging project which will take a significant amount of time to
+complete. In the interim, <strong>all contributions to the project will be made under
+the terms of both the new license and the legacy license scheme</strong> (each of which
+is described below). The exception to this is the legacy patent grant, which
+will not be required for new contributions.</p>
+<p>When all of the code in the project has been converted to the new license or
+removed, we will drop the requirement to contribute under the legacy license.
+This will achieve the goal of having
+a single standardized license for the entire codebase.</p>
+<p>If you are a prior contributor to LLVM and have not done so already, please do
+<em>TODO</em> to allow us to use your code. <em>Add a link to a separate page here, which
+is probably a click through web form or something like that. Details to be
+determined later</em>.</p>
+</div>
+<div class="section" id="new-llvm-project-license-framework">
+<span id="open-source-licensing-terms"></span><h3><a class="toc-backref" href="#id27">New LLVM Project License Framework</a><a class="headerlink" href="#new-llvm-project-license-framework" title="Permalink to this headline">¶</a></h3>
+<p>Contributions to LLVM are licensed under the <a class="reference external" href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>, with two limited
+exceptions intended to ensure that LLVM is very permissively licensed.
+Collectively, the name of this license is âApache 2.0 License with LLVM
+exceptionsâ. The exceptions read:</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">----</span> <span class="n">LLVM</span> <span class="n">Exceptions</span> <span class="n">to</span> <span class="n">the</span> <span class="n">Apache</span> <span class="mf">2.0</span> <span class="n">License</span> <span class="o">----</span>
+
+<span class="n">As</span> <span class="n">an</span> <span class="n">exception</span><span class="p">,</span> <span class="k">if</span><span class="p">,</span> <span class="k">as</span> <span class="n">a</span> <span class="n">result</span> <span class="n">of</span> <span class="n">your</span> <span class="n">compiling</span> <span class="n">your</span> <span class="n">source</span> <span class="n">code</span><span class="p">,</span> <span class="n">portions</span>
+<span class="n">of</span> <span class="n">this</span> <span class="n">Software</span> <span class="n">are</span> <span class="n">embedded</span> <span class="n">into</span> <span class="n">an</span> <span class="n">Object</span> <span class="n">form</span> <span class="n">of</span> <span class="n">such</span> <span class="n">source</span> <span class="n">code</span><span class="p">,</span> <span class="n">you</span>
+<span class="n">may</span> <span class="n">redistribute</span> <span class="n">such</span> <span class="n">embedded</span> <span class="n">portions</span> <span class="ow">in</span> <span class="n">such</span> <span class="n">Object</span> <span class="n">form</span> <span class="n">without</span> <span class="n">complying</span>
+<span class="k">with</span> <span class="n">the</span> <span class="n">conditions</span> <span class="n">of</span> <span class="n">Sections</span> <span class="mi">4</span><span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="mi">4</span><span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="ow">and</span> <span class="mi">4</span><span class="p">(</span><span class="n">d</span><span class="p">)</span> <span class="n">of</span> <span class="n">the</span> <span class="n">License</span><span class="o">.</span>
+
+<span class="n">In</span> <span class="n">addition</span><span class="p">,</span> <span class="k">if</span> <span class="n">you</span> <span class="n">combine</span> <span class="ow">or</span> <span class="n">link</span> <span class="n">compiled</span> <span class="n">forms</span> <span class="n">of</span> <span class="n">this</span> <span class="n">Software</span> <span class="k">with</span>
+<span class="n">software</span> <span class="n">that</span> <span class="ow">is</span> <span class="n">licensed</span> <span class="n">under</span> <span class="n">the</span> <span class="n">GPLv2</span> <span class="p">(</span><span class="s2">"Combined Software"</span><span class="p">)</span> <span class="ow">and</span> <span class="k">if</span> <span class="n">a</span>
+<span class="n">court</span> <span class="n">of</span> <span class="n">competent</span> <span class="n">jurisdiction</span> <span class="n">determines</span> <span class="n">that</span> <span class="n">the</span> <span class="n">patent</span> <span class="n">provision</span> <span class="p">(</span><span class="n">Section</span>
+<span class="mi">3</span><span class="p">),</span> <span class="n">the</span> <span class="n">indemnity</span> <span class="n">provision</span> <span class="p">(</span><span class="n">Section</span> <span class="mi">9</span><span class="p">)</span> <span class="ow">or</span> <span class="n">other</span> <span class="n">Section</span> <span class="n">of</span> <span class="n">the</span> <span class="n">License</span>
+<span class="n">conflicts</span> <span class="k">with</span> <span class="n">the</span> <span class="n">conditions</span> <span class="n">of</span> <span class="n">the</span> <span class="n">GPLv2</span><span class="p">,</span> <span class="n">you</span> <span class="n">may</span> <span class="n">retroactively</span> <span class="ow">and</span>
+<span class="n">prospectively</span> <span class="n">choose</span> <span class="n">to</span> <span class="n">deem</span> <span class="n">waived</span> <span class="ow">or</span> <span class="n">otherwise</span> <span class="n">exclude</span> <span class="n">such</span> <span class="n">Section</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="n">of</span>
+<span class="n">the</span> <span class="n">License</span><span class="p">,</span> <span class="n">but</span> <span class="n">only</span> <span class="ow">in</span> <span class="n">their</span> <span class="n">entirety</span> <span class="ow">and</span> <span class="n">only</span> <span class="k">with</span> <span class="n">respect</span> <span class="n">to</span> <span class="n">the</span> <span class="n">Combined</span>
+<span class="n">Software</span><span class="o">.</span>
+</pre></div>
+</div>
+<p>We intend to keep LLVM perpetually open source and available under a permissive
+license - this fosters the widest adoption of LLVM by
+<strong>allowing commercial products to be derived from LLVM</strong> with few restrictions
+and without a requirement for making any derived works also open source. In
+particular, LLVMâs license is not a âcopyleftâ license like the GPL.</p>
+<p>The âApache 2.0 License with LLVM exceptionsâ allows you to:</p>
+<ul class="simple">
+<li>freely download and use LLVM (in whole or in part) for personal, internal, or
+commercial purposes.</li>
+<li>include LLVM in packages or distributions you create.</li>
+<li>combine LLVM with code licensed under every other major open source
+license (including BSD, MIT, GPLv2, GPLv3â¦).</li>
+<li>make changes to LLVM code without being required to contribute it back
+to the project - contributions are appreciated though!</li>
+</ul>
+<p>However, it imposes these limitations on you:</p>
+<ul class="simple">
+<li>You must retain the copyright notice if you redistribute LLVM: You cannot
+strip the copyright headers off or replace them with your own.</li>
+<li>Binaries that include LLVM must reproduce the copyright notice (e.g. in an
+included README file or in an âAboutâ box), unless the LLVM code was added as
+a by-product of compilation. For example, if an LLVM runtime library like
+compiler_rt or libc++ was automatically included into your application by the
+compiler, you do not need to attribute it.</li>
+<li>You canât use our names to promote your products (LLVM derived or not) -
+though you can make truthful statements about your use of the LLVM code,
+without implying our sponsorship.</li>
+<li>Thereâs no warranty on LLVM at all.</li>
+</ul>
+<p>We want LLVM code to be widely used, and believe that this provides a model that
+is great for contributors and users of the project. For more information about
+the Apache 2.0 License, please see the <a class="reference external" href="http://www.apache.org/foundation/license-faq.html">Apache License FAQ</a>, maintained by the
+Apache Project.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The LLVM Project includes some really old subprojects (dragonegg,
+llvm-gcc-4.0, and llvm-gcc-4.2), which are licensed under <strong>GPL
+licenses</strong>. This code is not actively maintained - it does not even
+build successfully. This code is cleanly separated into distinct SVN
+repositories from the rest of LLVM, and the LICENSE.txt files specifically
+indicate that they contain GPL code. When LLVM transitions from SVN to Git,
+we plan to drop these code bases from the new repository structure.</p>
+</div>
+</div>
+<div class="section" id="patents">
+<span id="patent-license"></span><h3><a class="toc-backref" href="#id28">Patents</a><a class="headerlink" href="#patents" title="Permalink to this headline">¶</a></h3>
+<p>Section 3 of the Apache 2.0 license is a patent grant under which
+contributors of code to the project contribute the rights to use any of
+their patents that would otherwise be infringed by that code contribution
+(protecting uses of that code). Further, the patent grant is revoked
+from anyone who files a patent lawsuit about code in LLVM - this protects the
+community by providing a âpatent commonsâ for the code base and reducing the
+odds of patent lawsuits in general.</p>
+<p>The license specifically scopes which patents are included with code
+contributions. To help explain this, the <a class="reference external" href="http://www.apache.org/foundation/license-faq.html">Apache License FAQ</a> explains this scope using
+some questions and answers, which we reproduce here for your convenience (for
+reference, the âASFâ is the Apache Software Foundation, the guidance still
+holds though):</p>
+<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>Q1: If I own a patent and contribute to a Work, and, at the time my
+contribution is included in that Work, none of my patent's claims are subject
+to Apache's Grant of Patent License, is there a way any of those claims would
+later become subject to the Grant of Patent License solely due to subsequent
+contributions by other parties who are not licensees of that patent.
+
+A1: No.
+
+Q2: If at any time after my contribution, I am able to license other patent
+claims that would have been subject to Apache's Grant of Patent License if
+they were licenseable by me at the time of my contribution, do those other
+claims become subject to the Grant of Patent License?
+
+A2: Yes.
+
+Q3: If I own or control a licensable patent and contribute code to a specific
+Apache product, which of my patent claims are subject to Apache's Grant of
+Patent License?
+
+A3: The only patent claims that are licensed to the ASF are those you own or
+have the right to license that read on your contribution or on the
+combination of your contribution with the specific Apache product to which
+you contributed as it existed at the time of your contribution. No additional
+patent claims become licensed as a result of subsequent combinations of your
+contribution with any other software. Note, however, that licensable patent
+claims include those that you acquire in the future, as long as they read on
+your original contribution as made at the original time. Once a patent claim
+is subject to Apache's Grant of Patent License, it is licensed under the
+terms of that Grant to the ASF and to recipients of any software distributed
+by the ASF for any Apache software product whatsoever.
+</pre></div>
+</div>
+</div>
+<div class="section" id="legacy-license-structure">
+<span id="legacy"></span><h3><a class="toc-backref" href="#id29">Legacy License Structure</a><a class="headerlink" href="#legacy-license-structure" title="Permalink to this headline">¶</a></h3>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The code base was previously licensed under the Terms described here.
+We are in the middle of relicensing to a new approach (described above), but
+until this effort is complete, the code is also still available under these
+terms. Once we finish the relicensing project, new versions of the code will
+not be available under these terms. However, nothing takes away your right
+to use old versions under the licensing terms under which they were
+originally released.</p>
+</div>
+<p>We intend to keep LLVM perpetually open source and to use a permissive open
+source license. 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>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/Docker.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/Docker.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/Docker.html (added)
+++ www-releases/trunk/9.0.0/docs/Docker.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,249 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>A guide to Dockerfiles for building LLVM — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="Building a Distribution of LLVM" href="BuildingADistribution.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="BuildingADistribution.html" title="Building a Distribution of LLVM"
+ 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" role="main">
+
+ <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
+<code class="docutils literal notranslate"><span class="pre">llvm/utils/docker</span></code>. 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 <code class="docutils literal notranslate"><span class="pre">debian8</span></code> and <code class="docutils literal notranslate"><span class="pre">nvidia-cuda</span></code> base images.
+We also provide an <code class="docutils literal notranslate"><span class="pre">example</span></code> 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 <code class="docutils literal notranslate"><span class="pre">llvm/utils/docker</span></code> 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 <code class="docutils literal notranslate"><span class="pre">build_docker_image.sh</span></code> 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 <code class="docutils literal notranslate"><span class="pre">example/</span></code> 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 <code class="docutils literal notranslate"><span class="pre">llvm/utils/build_docker_image.sh</span></code> 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 notranslate"><div class="highlight"><pre><span></span>./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-resource-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 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Run a 2-stage build.</span>
+<span class="c1"># LLVM_TARGETS_TO_BUILD=Native is to reduce stage1 compile time.</span>
+<span class="c1"># 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-resource-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-resource-headers"</span>
+</pre></div>
+</div>
+<p>This will produce a new image <code class="docutils literal notranslate"><span class="pre">clang-debian8:staging</span></code> 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 notranslate"><div class="highlight"><pre><span></span>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 notranslate"><div class="highlight"><pre><span></span>root at 80f351b51825:/# clang -v
+clang version <span class="m">5</span>.0.0 <span class="o">(</span>trunk <span class="m">305064</span><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: .<span class="p">;</span>@m64
+Selected multilib: .<span class="p">;</span>@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
+<code class="docutils literal notranslate"><span class="pre">example/</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">branches/google/stable</span></code> branch, i.e. the following command will produce a
+debian8-based image using the latest <code class="docutils literal notranslate"><span class="pre">google/stable</span></code> sources for you:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>./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-resource-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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="BuildingADistribution.html" title="Building a Distribution of LLVM"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/ExceptionHandling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/ExceptionHandling.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/ExceptionHandling.html (added)
+++ www-releases/trunk/9.0.0/docs/ExceptionHandling.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,916 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Exception Handling in LLVM — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="How To Add A Constrained Floating-Point Intrinsic" href="AddingConstrainedIntrinsics.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="AddingConstrainedIntrinsics.html" title="How To Add A Constrained Floating-Point Intrinsic"
+ 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" role="main">
+
+ <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"><code class="docutils literal notranslate"><span class="pre">llvm.eh.typeid.for</span></code></a></li>
+<li><a class="reference internal" href="#llvm-eh-begincatch" id="id21"><code class="docutils literal notranslate"><span class="pre">llvm.eh.begincatch</span></code></a></li>
+<li><a class="reference internal" href="#llvm-eh-endcatch" id="id22"><code class="docutils literal notranslate"><span class="pre">llvm.eh.endcatch</span></code></a></li>
+<li><a class="reference internal" href="#llvm-eh-exceptionpointer" id="id23"><code class="docutils literal notranslate"><span class="pre">llvm.eh.exceptionpointer</span></code></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"><code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.setjmp</span></code></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-longjmp" id="id26"><code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.longjmp</span></code></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-lsda" id="id27"><code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.lsda</span></code></a></li>
+<li><a class="reference internal" href="#llvm-eh-sjlj-callsite" id="id28"><code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.callsite</span></code></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 <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">catch</span></code>
+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"><span class="std std-ref">landingpad</span></a>â instruction like the other two models, and is
+described later in this document under <a class="reference internal" href="#wineh"><span class="std std-ref">Exception Handling using the Windows Runtime</span></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. <code class="docutils literal notranslate"><span class="pre">__gxx_personality_v0</span></code> 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 <code class="docutils literal notranslate"><span class="pre">catch</span></code> portion of
+a <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">catch</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">throw</span></code> and <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">catch</span></code> 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 <code class="docutils literal notranslate"><span class="pre">throw</span></code>
+operation to initiate the exception process. Internally, a <code class="docutils literal notranslate"><span class="pre">throw</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">__cxa_allocate_exception</span></code> runtime function. The exception raising is handled
+by <code class="docutils literal notranslate"><span class="pre">__cxa_throw</span></code>. 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 <code class="docutils literal notranslate"><span class="pre">invoke</span></code> instruction. Unlike a call, the <code class="docutils literal notranslate"><span class="pre">invoke</span></code> 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 <code class="docutils literal notranslate"><span class="pre">invoke</span></code> 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"><span class="std std-ref">âlandingpadâ Instruction</span></a> is used to convey information about the landing
+pad to the back end. For C++, the <code class="docutils literal notranslate"><span class="pre">landingpad</span></code> 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 <code class="docutils literal notranslate"><span class="pre">landingpad</span></code> instruction looks for a reference to the personality
+function to be used for this <code class="docutils literal notranslate"><span class="pre">try</span></code>/<code class="docutils literal notranslate"><span class="pre">catch</span></code> 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"><code class="docutils literal notranslate"><span class="pre">catch</span> <span class="pre"><type></span> <span class="pre">@ExcType</span></code></p>
+<ul class="simple">
+<li>This clause means that the landingpad block should be entered if the
+exception being thrown is of type <code class="docutils literal notranslate"><span class="pre">@ExcType</span></code> or a subtype of
+<code class="docutils literal notranslate"><span class="pre">@ExcType</span></code>. For C++, <code class="docutils literal notranslate"><span class="pre">@ExcType</span></code> is a pointer to the <code class="docutils literal notranslate"><span class="pre">std::type_info</span></code>
+object (an RTTI object) representing the C++ exception type.</li>
+<li>If <code class="docutils literal notranslate"><span class="pre">@ExcType</span></code> is <code class="docutils literal notranslate"><span class="pre">null</span></code>, any exception matches, so the landingpad
+should always be entered. This is used for C++ catch-all blocks (â<code class="docutils literal notranslate"><span class="pre">catch</span>
+<span class="pre">(...)</span></code>â).</li>
+<li>When this clause is matched, the selector value will be equal to the value
+returned by â<code class="docutils literal notranslate"><span class="pre">@llvm.eh.typeid.for(i8*</span> <span class="pre">@ExcType)</span></code>â. This will always be a
+positive value.</li>
+</ul>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><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></code></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 <code class="docutils literal notranslate"><span class="pre">std::type_info</span></code> pointers).</li>
+<li>C++ front-ends use this to implement C++ exception specifications, such as
+â<code class="docutils literal notranslate"><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></code>â.</li>
+<li>When this clause is matched, the selector value will be negative.</li>
+<li>The array argument to <code class="docutils literal notranslate"><span class="pre">filter</span></code> may be empty; for example, â<code class="docutils literal notranslate"><span class="pre">[0</span> <span class="pre">x</span> <span class="pre">i8**]</span>
+<span class="pre">undef</span></code>â. This means that the landingpad should always be entered. (Note
+that such a <code class="docutils literal notranslate"><span class="pre">filter</span></code> would not be equivalent to â<code class="docutils literal notranslate"><span class="pre">catch</span> <span class="pre">i8*</span> <span class="pre">null</span></code>â,
+because <code class="docutils literal notranslate"><span class="pre">filter</span></code> and <code class="docutils literal notranslate"><span class="pre">catch</span></code> produce negative and positive selector
+values respectively.)</li>
+</ul>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">cleanup</span></code></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 â<code class="docutils literal notranslate"><span class="pre">cleanup</span></code>â differently from â<code class="docutils literal notranslate"><span class="pre">catch</span> <span class="pre"><type></span>
+<span class="pre">null</span></code>â.</p>
+<p>In C++, if an unhandled exception occurs, the language runtime will call
+<code class="docutils literal notranslate"><span class="pre">std::terminate()</span></code>, 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
+<code class="docutils literal notranslate"><span class="pre">std::terminate()</span></code> is called from the context of the <code class="docutils literal notranslate"><span class="pre">throw</span></code>, so that
+this context is not lost by unwinding the stack. A runtime will typically
+implement this by searching for a matching non-<code class="docutils literal notranslate"><span class="pre">cleanup</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">__cxa_begin_catch</span></code> and <code class="docutils literal notranslate"><span class="pre">__cxa_end_catch</span></code>.</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">__cxa_begin_catch</span></code> takes an exception structure reference as an argument
+and returns the value of the exception object.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">__cxa_end_catch</span></code> 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
+<code class="docutils literal notranslate"><span class="pre">__cxa_rethrow</span></code>.</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"><span class="std std-ref">âlandingpadâ Instruction</span></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"><span class="std std-ref">resume instruction</span></a>,
+passing in the result of the <code class="docutils literal notranslate"><span class="pre">landingpad</span></code> 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"><span class="std std-ref">âlandingpadâ Instruction</span></a> will have a
+filter clause. The clause consists of an array of type infos.
+<code class="docutils literal notranslate"><span class="pre">landingpad</span></code> 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 <code class="docutils literal notranslate"><span class="pre">__cxa_call_unexpected</span></code> should be made, otherwise
+<code class="docutils literal notranslate"><span class="pre">_Unwind_Resume</span></code>. Each of these functions requires a reference to the
+exception structure. Note that the most general form of a <code class="docutils literal notranslate"><span class="pre">landingpad</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">landingpad</span></code> 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 <code class="docutils literal notranslate"><span class="pre">A</span></code>, and itâs inlined into a function that
+catches exceptions of type <code class="docutils literal notranslate"><span class="pre">B</span></code>. The inliner will update the <code class="docutils literal notranslate"><span class="pre">landingpad</span></code>
+instruction for the inlined landing pad to include the fact that <code class="docutils literal notranslate"><span class="pre">B</span></code> is also
+caught. If that landing pad assumes that it will only be entered to catch an
+<code class="docutils literal notranslate"><span class="pre">A</span></code>, 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 <code class="docutils literal notranslate"><span class="pre">landingpad</span></code> and <code class="docutils literal notranslate"><span class="pre">resume</span></code> instructions, LLVM uses several
+intrinsic functions (name prefixed with <code class="docutils literal notranslate"><span class="pre">llvm.eh</span></code>) 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"><code class="docutils literal notranslate"><span class="pre">llvm.eh.typeid.for</span></code></a><a class="headerlink" href="#llvm-eh-typeid-for" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><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
+<code class="docutils literal notranslate"><span class="pre">landingpad</span></code> 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"><code class="docutils literal notranslate"><span class="pre">llvm.eh.begincatch</span></code></a><a class="headerlink" href="#llvm-eh-begincatch" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">landingpad</span></code> instruction. The exact behavior of this function
+depends on the compilation target and the personality function associated
+with the <code class="docutils literal notranslate"><span class="pre">landingpad</span></code> instruction.</p>
+<p>The first argument to this intrinsic is a pointer that was previously extracted
+from the aggregate return value of the <code class="docutils literal notranslate"><span class="pre">landingpad</span></code> 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 <code class="docutils literal notranslate"><span class="pre">__cxa_begin_catch</span></code>) 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"><code class="docutils literal notranslate"><span class="pre">llvm.eh.endcatch</span></code></a><a class="headerlink" href="#llvm-eh-endcatch" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><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></code>
+instruction.</p>
+<p>There may be more than one call to <code class="docutils literal notranslate"><span class="pre">llvm.eh.endcatch</span></code> for any given call to
+<code class="docutils literal notranslate"><span class="pre">llvm.eh.begincatch</span></code> with each <code class="docutils literal notranslate"><span class="pre">llvm.eh.endcatch</span></code> call corresponding to the
+end of a different control path. All control paths following a call to
+<code class="docutils literal notranslate"><span class="pre">llvm.eh.begincatch</span></code> must reach a call to <code class="docutils literal notranslate"><span class="pre">llvm.eh.endcatch</span></code>.</p>
+<p>Uses of this intrinsic are generated by the C++ front-end. Many targets will
+use implementation-specific functions (such as <code class="docutils literal notranslate"><span class="pre">__cxa_begin_catch</span></code>) 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"><code class="docutils literal notranslate"><span class="pre">llvm.eh.exceptionpointer</span></code></a><a class="headerlink" href="#llvm-eh-exceptionpointer" title="Permalink to this headline">¶</a></h3>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>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
+<code class="docutils literal notranslate"><span class="pre">catchpad</span></code>.</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 <code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj</span></code> intrinsics are used internally within LLVMâs
+backend. Uses of them are generated by the backendâs
+<code class="docutils literal notranslate"><span class="pre">SjLjEHPrepare</span></code> pass.</p>
+<div class="section" id="llvm-eh-sjlj-setjmp">
+<span id="id5"></span><h4><a class="toc-backref" href="#id25"><code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.setjmp</span></code></a><a class="headerlink" href="#llvm-eh-sjlj-setjmp" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>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
+<code class="docutils literal notranslate"><span class="pre">__builtin_setjmp</span></code> 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"><code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.longjmp</span></code></a><a class="headerlink" href="#llvm-eh-sjlj-longjmp" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="vg">@llvm.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 <code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.longjmp</span></code> intrinsic is
+used to implement <code class="docutils literal notranslate"><span class="pre">__builtin_longjmp()</span></code>. 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"><code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.lsda</span></code></a><a class="headerlink" href="#llvm-eh-sjlj-lsda" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><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 <code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.lsda</span></code> 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"><code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.callsite</span></code></a><a class="headerlink" href="#llvm-eh-sjlj-callsite" title="Permalink to this headline">¶</a></h4>
+<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="kt">void</span> <span class="vg">@llvm.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 <code class="docutils literal notranslate"><span class="pre">llvm.eh.sjlj.callsite</span></code> intrinsic
+identifies the callsite value associated with the following <code class="docutils literal notranslate"><span class="pre">invoke</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">eh_frame</span></code> 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 <code class="docutils literal notranslate"><span class="pre">__gxx_personality_v0</span></code>.
+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 <code class="docutils literal notranslate"><span class="pre">landingpad</span></code>
+instruction, which produces register values provided by the runtime. If a
+function is only cleaning up allocated resources, the function is responsible
+for calling <code class="docutils literal notranslate"><span class="pre">_Unwind_Resume</span></code> to transition to the next most recently active
+frame after it is finished cleaning up. Eventually, the frame responsible for
+handling the exception calls <code class="docutils literal notranslate"><span class="pre">__cxa_end_catch</span></code> 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 <code class="docutils literal notranslate"><span class="pre">__CxxThrowException</span></code>. 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
+(<code class="docutils literal notranslate"><span class="pre">__CxxFrameHandler3</span></code>) and the SEH personalities (<code class="docutils literal notranslate"><span class="pre">_except_handler3</span></code>,
+<code class="docutils literal notranslate"><span class="pre">_except_handler4</span></code>, and <code class="docutils literal notranslate"><span class="pre">__C_specific_handler</span></code>). 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 <code class="docutils literal notranslate"><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></code>). 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 <code class="docutils literal notranslate"><span class="pre">__CxxFrameHandler3</span></code> to implement rethrow without
+resorting to TLS. Instead, the runtime throws a special exception, and then uses
+SEH (<code class="docutils literal notranslate"><span class="pre">__try</span> <span class="pre">/</span> <span class="pre">__except</span></code>) 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 <code class="docutils literal notranslate"><span class="pre">filter</span></code> clause of the LLVM
+<code class="docutils literal notranslate"><span class="pre">landingpad</span></code> 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 <code class="docutils literal notranslate"><span class="pre">llvm.localescape</span></code>
+and <code class="docutils literal notranslate"><span class="pre">llvm.localrecover</span></code> 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:
+<code class="docutils literal notranslate"><span class="pre">catchswitch</span></code>, <code class="docutils literal notranslate"><span class="pre">catchpad</span></code>, and <code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code>.
+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 <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> block. Similarly, inside the scope of a
+C++ object with a destructor, invokes should unwind to a <code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code>.</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 <code class="docutils literal notranslate"><span class="pre">catchret</span></code> 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 <code class="docutils literal notranslate"><span class="pre">cleanupret</span></code> 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 <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> instruction is a terminator
+and has an unwind destination operand analogous to the unwind destination of an
+invoke. The <code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code> instruction is not
+a terminator, so the unwind destination is stored on the <code class="docutils literal notranslate"><span class="pre">cleanupret</span></code>
+instruction instead. Successfully executing a catch handler should resume
+normal control flow, so neither <code class="docutils literal notranslate"><span class="pre">catchpad</span></code> nor <code class="docutils literal notranslate"><span class="pre">catchret</span></code> 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 <code class="docutils literal notranslate"><span class="pre">resume</span></code> 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 notranslate"><div class="highlight"><pre><span></span><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="nf">may_throw</span><span class="p">();</span>
+<span class="kt">int</span> <span class="nf">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 notranslate"><div class="highlight"><pre><span></span>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 <code class="docutils literal notranslate"><span class="pre">catchpad</span></code> and <code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code> instructions establish new funclets, and
+their tokens are consumed by other âpadâ instructions to establish membership.
+The <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> instruction does not create a funclet, but it produces a
+token that is always consumed by its immediate successor <code class="docutils literal notranslate"><span class="pre">catchpad</span></code>
+instructions. This ensures that every catch handler modelled by a <code class="docutils literal notranslate"><span class="pre">catchpad</span></code>
+belongs to exactly one <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code>, 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 notranslate"><div class="highlight"><pre><span></span><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 notranslate"><div class="highlight"><pre><span></span>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â <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> consumes <code class="docutils literal notranslate"><span class="pre">%1</span></code> 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 <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code>, <code class="docutils literal notranslate"><span class="pre">catchpad</span></code>, or <code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code> 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 <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> is immediately exited when none of its constituent
+<code class="docutils literal notranslate"><span class="pre">catchpad</span></code>s are appropriate for the in-flight exception and it unwinds
+to its unwind destination or the caller.</li>
+<li>A <code class="docutils literal notranslate"><span class="pre">catchpad</span></code> and its parent <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> are both exited when a
+<code class="docutils literal notranslate"><span class="pre">catchret</span></code> from the <code class="docutils literal notranslate"><span class="pre">catchpad</span></code> is executed.</li>
+<li>A <code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code> is exited when a <code class="docutils literal notranslate"><span class="pre">cleanupret</span></code> from it is executed.</li>
+<li>Any of these pads is exited when control unwinds to the functionâs caller,
+either by a <code class="docutils literal notranslate"><span class="pre">call</span></code> which unwinds all the way to the functionâs caller,
+a nested <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> marked â<code class="docutils literal notranslate"><span class="pre">unwinds</span> <span class="pre">to</span> <span class="pre">caller</span></code>â, or a nested
+<code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code>âs <code class="docutils literal notranslate"><span class="pre">cleanupret</span></code> marked â<code class="docutils literal notranslate"><span class="pre">unwinds</span> <span class="pre">to</span> <span class="pre">caller"</span></code>.</li>
+<li>Any of these pads is exited when an unwind edge (from an <code class="docutils literal notranslate"><span class="pre">invoke</span></code>,
+nested <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code>, or nested <code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code>âs <code class="docutils literal notranslate"><span class="pre">cleanupret</span></code>)
+unwinds to a destination pad that is not a descendant of the given pad.</li>
+</ul>
+<p>Note that the <code class="docutils literal notranslate"><span class="pre">ret</span></code> instruction is <em>not</em> a valid way to exit a funclet pad;
+it is undefined behavior to execute a <code class="docutils literal notranslate"><span class="pre">ret</span></code> 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 <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> must exit at least itself, and the edge from
+a <code class="docutils literal notranslate"><span class="pre">cleanupret</span></code> must exit at least its <code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code>), 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 <code class="docutils literal notranslate"><span class="pre">cleanupret</span></code>
+edges exiting their <code class="docutils literal notranslate"><span class="pre">cleanuppad</span></code> and <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> edges exiting their
+<code class="docutils literal notranslate"><span class="pre">catchswitch</span></code>) 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 <code class="docutils literal notranslate"><span class="pre">catchpad</span></code> also exits its parent <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code>, so this
+implies that for any given <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code>, its unwind destination must also
+be the unwind destination of any unwind edge that exits any of its constituent
+<code class="docutils literal notranslate"><span class="pre">catchpad</span></code>s. Because <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> has no <code class="docutils literal notranslate"><span class="pre">nounwind</span></code> variant, and
+because IR producers are not <em>required</em> to annotate calls which will not
+unwind as <code class="docutils literal notranslate"><span class="pre">nounwind</span></code>, it is legal to nest a <code class="docutils literal notranslate"><span class="pre">call</span></code> or an â<code class="docutils literal notranslate"><span class="pre">unwind</span> <span class="pre">to</span>
+<span class="pre">caller</span></code>â <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> within a funclet pad that has an unwind
+destination other than caller; it is undefined behavior for such a <code class="docutils literal notranslate"><span class="pre">call</span></code>
+or <code class="docutils literal notranslate"><span class="pre">catchswitch</span></code> 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 <code class="docutils literal notranslate"><span class="pre">TargetFrameLowering</span></code>âs <code class="docutils literal notranslate"><span class="pre">emitPrologue</span></code>, 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 <code class="docutils literal notranslate"><span class="pre">.eh_frame</span></code> section, which is used
+by th unwinder to unwind stack during exception handling.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">getExceptionPointerRegister</span></code> and <code class="docutils literal notranslate"><span class="pre">getExceptionSelectorRegister</span></code></p>
+<p><code class="docutils literal notranslate"><span class="pre">TargetLowering</span></code> 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 <code class="docutils literal notranslate"><span class="pre">getExceptionPointerRegister</span></code>
+and <code class="docutils literal notranslate"><span class="pre">getExceptionSelectorRegister</span></code> 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"><code class="docutils literal notranslate"><span class="pre">EH_RETURN</span></code></p>
+<p>The ISD node represents the undocumented GCC extension <code class="docutils literal notranslate"><span class="pre">__builtin_eh_return</span> <span class="pre">(offset,</span> <span class="pre">handler)</span></code>,
+which adjusts the stack by offset and then jumps to the handler. <code class="docutils literal notranslate"><span class="pre">__builtin_eh_return</span></code>
+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 <code class="docutils literal notranslate"><span class="pre">libgcc</span></code> and have particular requirement on your target,
+you have to handle <code class="docutils literal notranslate"><span class="pre">EH_RETURN</span></code> in <code class="docutils literal notranslate"><span class="pre">TargetLowering</span></code>.</p>
+</li>
+</ul>
+<p>If you donât leverage the existing runtime (<code class="docutils literal notranslate"><span class="pre">libstdc++</span></code> and <code class="docutils literal notranslate"><span class="pre">libgcc</span></code>),
+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 <code class="docutils literal notranslate"><span class="pre">libunwind</span></code>, you have to do the following</p>
+<ul>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">__libunwind_config.h</span></code></p>
+<p>Define macros for your target.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">include/libunwind.h</span></code></p>
+<p>Define enum for the target registers.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">src/Registers.hpp</span></code></p>
+<p>Define <code class="docutils literal notranslate"><span class="pre">Registers</span></code> class for your target, implement setter and getter functions.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">src/UnwindCursor.hpp</span></code></p>
+<p>Define <code class="docutils literal notranslate"><span class="pre">dwarfEncoding</span></code> and <code class="docutils literal notranslate"><span class="pre">stepWithCompactEncoding</span></code> for your <code class="docutils literal notranslate"><span class="pre">Registers</span></code>
+class.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">src/UnwindRegistersRestore.S</span></code></p>
+<p>Write an assembly function to restore all your target registers from the memory.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">src/UnwindRegistersSave.S</span></code></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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="AddingConstrainedIntrinsics.html" title="How To Add A Constrained Floating-Point Intrinsic"
+ >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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/9.0.0/docs/ExtendingLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/9.0.0/docs/ExtendingLLVM.html?rev=372328&view=auto
==============================================================================
--- www-releases/trunk/9.0.0/docs/ExtendingLLVM.html (added)
+++ www-releases/trunk/9.0.0/docs/ExtendingLLVM.html Thu Sep 19 07:32:46 2019
@@ -0,0 +1,367 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Extending LLVM: Adding instructions, intrinsics, types, etc. — LLVM 9 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <script type="text/javascript" src="_static/language_data.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.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" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="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" role="main">
+
+ <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 <code class="docutils literal notranslate"><span class="pre">many</span></code> 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"><code class="docutils literal notranslate"><span class="pre">llvm/docs/LangRef.html</span></code>:</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"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Intrinsics*.td</span></code>:</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). If any arguments need to be immediates, these
+must be indicated with the ImmArg property. Note that any intrinsic
+using one of the <code class="docutils literal notranslate"><span class="pre">llvm_any*_ty</span></code> types for an argument or return
+type will be deemed by <code class="docutils literal notranslate"><span class="pre">tblgen</span></code> as overloaded and the
+corresponding suffix will be required on the intrinsicâs name.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Analysis/ConstantFolding.cpp</span></code>:</p>
+<p>If it is possible to constant fold your intrinsic, add support to it in the
+<code class="docutils literal notranslate"><span class="pre">canConstantFoldCallTo</span></code> and <code class="docutils literal notranslate"><span class="pre">ConstantFoldCall</span></code> functions.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/test/*</span></code>:</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
+<code class="docutils literal notranslate"><span class="pre">lib/Target/*/*.td</span></code>.</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"><code class="docutils literal notranslate"><span class="pre">include/llvm/CodeGen/ISDOpcodes.h</span></code>:</p>
+<p>Add an enum value for the new SelectionDAG node.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/SelectionDAG.cpp</span></code>:</p>
+<dl class="docutils">
+<dt>Add code to print the node to <code class="docutils literal notranslate"><span class="pre">getOperationName</span></code>. 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 <code class="docutils literal notranslate"><span class="pre">getNode</span></code> 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"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></code>:</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
+<code class="docutils literal notranslate"><span class="pre">LegalizeOp</span></code> 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 <code class="docutils literal notranslate"><span class="pre">LegalizeOp</span></code> to Expand your node into simpler,
+legal operations. The case for <code class="docutils literal notranslate"><span class="pre">ISD::UREM</span></code> for expanding a remainder into
+a divide, multiply, and a subtract is a good example.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></code>:</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 <code class="docutils literal notranslate"><span class="pre">LegalizeOp</span></code>
+to Promote your nodeâs operands to a larger size, and perform the correct
+operation. You will also need to add code to <code class="docutils literal notranslate"><span class="pre">PromoteOp</span></code> to do this as
+well. For a good example, see <code class="docutils literal notranslate"><span class="pre">ISD::BSWAP</span></code>, 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"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/LegalizeDAG.cpp</span></code>:</p>
+<p>Add a case for your node in <code class="docutils literal notranslate"><span class="pre">ExpandOp</span></code> 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"><code class="docutils literal notranslate"><span class="pre">lib/CodeGen/SelectionDAG/DAGCombiner.cpp</span></code>:</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;
+<code class="docutils literal notranslate"><span class="pre">visitFABS</span></code> and <code class="docutils literal notranslate"><span class="pre">visitSRL</span></code> are good starting places.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/Target/PowerPC/PPCISelLowering.cpp</span></code>:</p>
+<p>Each target has an implementation of the <code class="docutils literal notranslate"><span class="pre">TargetLowering</span></code> 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 <code class="docutils literal notranslate"><span class="pre">LegalizeOp</span></code> above to decompose your new node into other
+legal nodes for this target.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/Target/TargetSelectionDAG.td</span></code>:</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
+<code class="docutils literal notranslate"><span class="pre">add</span></code>, <code class="docutils literal notranslate"><span class="pre">bswap</span></code>, and <code class="docutils literal notranslate"><span class="pre">fadd</span></code> for examples.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">lib/Target/PowerPC/PPCInstrInfo.td</span></code>:</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 <code class="docutils literal notranslate"><span class="pre">rotl</span></code> in <code class="docutils literal notranslate"><span class="pre">PPCInstrInfo.td</span></code>.</p>
+</li>
+<li><p class="first">TODO: document complex patterns.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/test/CodeGen/*</span></code>:</p>
+<p>Add test cases for your new node to the test suite.
+<code class="docutils literal notranslate"><span class="pre">llvm/test/CodeGen/X86/bswap.ll</span></code> 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"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Instruction.def</span></code>:</p>
+<p>add a number for your instruction and an enum name</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Instructions.h</span></code>:</p>
+<p>add a definition for the class that will represent your instruction</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/InstVisitor.h</span></code>:</p>
+<p>add a prototype for a visitor to your new instruction type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></code>:</p>
+<p>add a new token to parse your instruction from assembly text file</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLParser.cpp</span></code>:</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"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></code>:</p>
+<p>add a case for your instruction and how it will be parsed from bitcode</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></code>:</p>
+<p>add a case for your instruction and how it will be parsed from bitcode</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/Instruction.cpp</span></code>:</p>
+<p>add a case for how your instruction will be printed out to assembly</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/Instructions.cpp</span></code>:</p>
+<p>implement the class you defined in <code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/Instructions.h</span></code></p>
+</li>
+<li><p class="first">Test your instruction</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Target/*</span></code>:</p>
+<p>add support for your instruction to code generators, or add a lowering pass.</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/test/*</span></code>:</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"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Type.h</span></code>:</p>
+<p>add enum for the new type; add static <code class="docutils literal notranslate"><span class="pre">Type*</span></code> for this type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/Type.cpp</span></code> and <code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/ValueTypes.cpp</span></code>:</p>
+<p>add mapping from <code class="docutils literal notranslate"><span class="pre">TypeID</span></code> => <code class="docutils literal notranslate"><span class="pre">Type*</span></code>; initialize the static <code class="docutils literal notranslate"><span class="pre">Type*</span></code></p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/llvm/llvm-c/Core.cpp</span></code>:</p>
+<p>add enum <code class="docutils literal notranslate"><span class="pre">LLVMTypeKind</span></code> and modify
+<code class="docutils literal notranslate"><span class="pre">LLVMTypeKind</span> <span class="pre">LLVMGetTypeKind(LLVMTypeRef</span> <span class="pre">Ty)</span></code> for the new type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></code>:</p>
+<p>add ability to parse in the type from text assembly</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLParser.cpp</span></code>:</p>
+<p>add a token for that type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><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></code> to serialize your type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">BitcodeReader::ParseTypeType()</span></code> to read your data type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">include/llvm/Bitcode/LLVMBitCodes.h</span></code>:</p>
+<p>add enum <code class="docutils literal notranslate"><span class="pre">TypeCodes</span></code> 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"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/Type.h</span></code>:</p>
+<p>add enum for the new type; add a forward declaration of the type also</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/include/llvm/IR/DerivedTypes.h</span></code>:</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"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/Type.cpp</span></code> and <code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/ValueTypes.cpp</span></code>:</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"><code class="docutils literal notranslate"><span class="pre">llvm/llvm/llvm-c/Core.cpp</span></code>:</p>
+<p>add enum <code class="docutils literal notranslate"><span class="pre">LLVMTypeKind</span></code> and modify
+<cite>LLVMTypeKind LLVMGetTypeKind(LLVMTypeRef Ty)</cite> for the new type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/AsmParser/LLLexer.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><span class="pre">lltok::Kind</span> <span class="pre">LLLexer::LexIdentifier()</span></code> to add ability to
+parse in the type from text assembly</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Writer/BitcodeWriter.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><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></code> to serialize your type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/Bitcode/Reader/BitcodeReader.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><span class="pre">bool</span> <span class="pre">BitcodeReader::ParseTypeType()</span></code> to read your data type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">include/llvm/Bitcode/LLVMBitCodes.h</span></code>:</p>
+<p>add enum <code class="docutils literal notranslate"><span class="pre">TypeCodes</span></code> for the new type</p>
+</li>
+<li><p class="first"><code class="docutils literal notranslate"><span class="pre">llvm/lib/IR/AsmWriter.cpp</span></code>:</p>
+<p>modify <code class="docutils literal notranslate"><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></code>
+to output the new derived type</p>
+</li>
+</ol>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="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" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-09-19.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.4.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list