[www-releases] r356539 - Check in the 8.0.0 release
Hans Wennborg via llvm-commits
llvm-commits at lists.llvm.org
Wed Mar 20 02:13:34 PDT 2019
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-ar.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-ar.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-ar.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-ar.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,335 @@
+
+
+<!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-ar - LLVM archiver — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-lib - LLVM lib.exe compatible library tool" href="llvm-lib.html" />
+ <link rel="prev" title="llvm-link - LLVM bitcode linker" href="llvm-link.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-lib.html" title="llvm-lib - LLVM lib.exe compatible library tool"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-link.html" title="llvm-link - LLVM bitcode linker"
+ 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-ar-llvm-archiver">
+<h1>llvm-ar - LLVM archiver<a class="headerlink" href="#llvm-ar-llvm-archiver" 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>llvm-ar</strong> [-]{dmpqrtx}[Rabfikou] [relpos] [count] <archive> [filesâ¦]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong>llvm-ar</strong> command is similar to the common Unix utility, <code class="docutils literal notranslate"><span class="pre">ar</span></code>. It
+archives several files together into a single file. The intent for this is
+to produce archive libraries by LLVM bitcode that can be linked into an
+LLVM program. However, the archive can contain any kind of file. By default,
+<strong>llvm-ar</strong> generates a symbol table that makes linking faster because
+only the symbol table needs to be consulted, not each individual file member
+of the archive.</p>
+<p>The <strong>llvm-ar</strong> command can be used to <em>read</em> SVR4, GNU and BSD style archive
+files. However, right now it can only write in the GNU format. If an
+SVR4 or BSD style archive is used with the <code class="docutils literal notranslate"><span class="pre">r</span></code> (replace) or <code class="docutils literal notranslate"><span class="pre">q</span></code> (quick
+update) operations, the archive will be reconstructed in GNU format.</p>
+<p>Hereâs where <strong>llvm-ar</strong> departs from previous <code class="docutils literal notranslate"><span class="pre">ar</span></code> implementations:</p>
+<p><em>Symbol Table</em></p>
+<blockquote>
+<div>Since <strong>llvm-ar</strong> supports bitcode files. The symbol table it creates
+is in GNU format and includes both native and bitcode files.</div></blockquote>
+<p><em>Long Paths</em></p>
+<blockquote>
+<div>Currently <strong>llvm-ar</strong> can read GNU and BSD long file names, but only writes
+archives with the GNU format.</div></blockquote>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p>The options to <strong>llvm-ar</strong> are compatible with other <code class="docutils literal notranslate"><span class="pre">ar</span></code> implementations.
+However, there are a few modifiers (<em>R</em>) that are not found in other <code class="docutils literal notranslate"><span class="pre">ar</span></code>
+implementations. The options to <strong>llvm-ar</strong> specify a single basic operation to
+perform on the archive, a variety of modifiers for that operation, the name of
+the archive file, and an optional list of file names. These options are used to
+determine how <strong>llvm-ar</strong> should process the archive file.</p>
+<p>The Operations and Modifiers are explained in the sections below. The minimal
+set of options is at least one operator and the name of the archive. Typically
+archive files end with a <code class="docutils literal notranslate"><span class="pre">.a</span></code> suffix, but this is not required. Following
+the <em>archive-name</em> comes a list of <em>files</em> that indicate the specific members
+of the archive to operate on. If the <em>files</em> option is not specified, it
+generally means either ânoneâ or âallâ members, depending on the operation.</p>
+<div class="section" id="operations">
+<h3>Operations<a class="headerlink" href="#operations" title="Permalink to this headline">¶</a></h3>
+<p>d</p>
+<blockquote>
+<div>Delete files from the archive. No modifiers are applicable to this operation.
+The <em>files</em> options specify which members should be removed from the
+archive. It is not an error if a specified file does not appear in the archive.
+If no <em>files</em> are specified, the archive is not modified.</div></blockquote>
+<p>m[abi]</p>
+<blockquote>
+<div>Move files from one location in the archive to another. The <em>a</em>, <em>b</em>, and
+<em>i</em> modifiers apply to this operation. The <em>files</em> will all be moved
+to the location given by the modifiers. If no modifiers are used, the files
+will be moved to the end of the archive. If no <em>files</em> are specified, the
+archive is not modified.</div></blockquote>
+<p>p</p>
+<blockquote>
+<div>Print files to the standard output. This operation simply prints the
+<em>files</em> indicated to the standard output. If no <em>files</em> are
+specified, the entire archive is printed. Printing bitcode files is
+ill-advised as they might confuse your terminal settings. The <em>p</em>
+operation never modifies the archive.</div></blockquote>
+<p>q</p>
+<blockquote>
+<div>Quickly append files to the end of the archive. This operation quickly adds the
+<em>files</em> to the archive without checking for duplicates that should be
+removed first. If no <em>files</em> are specified, the archive is not modified.
+Because of the way that <strong>llvm-ar</strong> constructs the archive file, its dubious
+whether the <em>q</em> operation is any faster than the <em>r</em> operation.</div></blockquote>
+<p>r[abu]</p>
+<blockquote>
+<div>Replace or insert file members. The <em>a</em>, <em>b</em>, and <em>u</em>
+modifiers apply to this operation. This operation will replace existing
+<em>files</em> or insert them at the end of the archive if they do not exist. If no
+<em>files</em> are specified, the archive is not modified.</div></blockquote>
+<p>t[v]</p>
+<blockquote>
+<div>Print the table of contents. Without any modifiers, this operation just prints
+the names of the members to the standard output. With the <em>v</em> modifier,
+<strong>llvm-ar</strong> also prints out the file type (B=bitcode, S=symbol
+table, blank=regular file), the permission mode, the owner and group, the
+size, and the date. If any <em>files</em> are specified, the listing is only for
+those files. If no <em>files</em> are specified, the table of contents for the
+whole archive is printed.</div></blockquote>
+<p>x[oP]</p>
+<blockquote>
+<div>Extract archive members back to files. The <em>o</em> modifier applies to this
+operation. This operation retrieves the indicated <em>files</em> from the archive
+and writes them back to the operating systemâs file system. If no
+<em>files</em> are specified, the entire archive is extract.</div></blockquote>
+</div>
+<div class="section" id="modifiers-operation-specific">
+<h3>Modifiers (operation specific)<a class="headerlink" href="#modifiers-operation-specific" title="Permalink to this headline">¶</a></h3>
+<p>The modifiers below are specific to certain operations. See the Operations
+section (above) to determine which modifiers are applicable to which operations.</p>
+<p>[a]</p>
+<blockquote>
+<div>When inserting or moving member files, this option specifies the destination of
+the new files as being after the <em>relpos</em> member. If <em>relpos</em> is not found,
+the files are placed at the end of the archive.</div></blockquote>
+<p>[b]</p>
+<blockquote>
+<div>When inserting or moving member files, this option specifies the destination of
+the new files as being before the <em>relpos</em> member. If <em>relpos</em> is not
+found, the files are placed at the end of the archive. This modifier is
+identical to the <em>i</em> modifier.</div></blockquote>
+<p>[i]</p>
+<blockquote>
+<div>A synonym for the <em>b</em> option.</div></blockquote>
+<p>[o]</p>
+<blockquote>
+<div>When extracting files, this option will cause <strong>llvm-ar</strong> to preserve the
+original modification times of the files it writes.</div></blockquote>
+<p>[u]</p>
+<blockquote>
+<div>When replacing existing files in the archive, only replace those files that have
+a time stamp than the time stamp of the member in the archive.</div></blockquote>
+</div>
+<div class="section" id="modifiers-generic">
+<h3>Modifiers (generic)<a class="headerlink" href="#modifiers-generic" title="Permalink to this headline">¶</a></h3>
+<p>The modifiers below may be applied to any operation.</p>
+<p>[c]</p>
+<blockquote>
+<div>For all operations, <strong>llvm-ar</strong> will always create the archive if it doesnât
+exist. Normally, <strong>llvm-ar</strong> will print a warning message indicating that the
+archive is being created. Using this modifier turns off that warning.</div></blockquote>
+<p>[s]</p>
+<blockquote>
+<div>This modifier requests that an archive index (or symbol table) be added to the
+archive. This is the default mode of operation. The symbol table will contain
+all the externally visible functions and global variables defined by all the
+bitcode files in the archive.</div></blockquote>
+<p>[S]</p>
+<blockquote>
+<div>This modifier is the opposite of the <em>s</em> modifier. It instructs <strong>llvm-ar</strong> to
+not build the symbol table. If both <em>s</em> and <em>S</em> are used, the last modifier to
+occur in the options will prevail.</div></blockquote>
+<p>[v]</p>
+<blockquote>
+<div>This modifier instructs <strong>llvm-ar</strong> to be verbose about what it is doing. Each
+editing operation taken against the archive will produce a line of output saying
+what is being done.</div></blockquote>
+</div>
+</div>
+<div class="section" id="standards">
+<h2>STANDARDS<a class="headerlink" href="#standards" title="Permalink to this headline">¶</a></h2>
+<p>The <strong>llvm-ar</strong> utility is intended to provide a superset of the IEEE Std 1003.2
+(POSIX.2) functionality for <code class="docutils literal notranslate"><span class="pre">ar</span></code>. <strong>llvm-ar</strong> can read both SVR4 and BSD4.4 (or
+Mac OS X) archives. If the <code class="docutils literal notranslate"><span class="pre">f</span></code> modifier is given to the <code class="docutils literal notranslate"><span class="pre">x</span></code> or <code class="docutils literal notranslate"><span class="pre">r</span></code> operations
+then <strong>llvm-ar</strong> will write SVR4 compatible archives. Without this modifier,
+<strong>llvm-ar</strong> will write BSD4.4 compatible archives that have long names
+immediately after the header and indicated using the â#1/dddâ notation for the
+name in the header.</p>
+</div>
+<div class="section" id="file-format">
+<h2>FILE FORMAT<a class="headerlink" href="#file-format" title="Permalink to this headline">¶</a></h2>
+<p>The file format for LLVM Archive files is similar to that of BSD 4.4 or Mac OSX
+archive files. In fact, except for the symbol table, the <code class="docutils literal notranslate"><span class="pre">ar</span></code> commands on those
+operating systems should be able to read LLVM archive files. The details of the
+file format follow.</p>
+<p>Each archive begins with the archive magic number which is the eight printable
+characters â!<arch>nâ where n represents the newline character (0x0A).
+Following the magic number, the file is composed of even length members that
+begin with an archive header and end with a n padding character if necessary
+(to make the length even). Each file member is composed of a header (defined
+below), an optional newline-terminated âlong file nameâ and the contents of
+the file.</p>
+<p>The fields of the header are described in the items below. All fields of the
+header contain only ASCII characters, are left justified and are right padded
+with space characters.</p>
+<p>name - char[16]</p>
+<blockquote>
+<div>This field of the header provides the name of the archive member. If the name is
+longer than 15 characters or contains a slash (/) character, then this field
+contains <code class="docutils literal notranslate"><span class="pre">#1/nnn</span></code> where <code class="docutils literal notranslate"><span class="pre">nnn</span></code> provides the length of the name and the <code class="docutils literal notranslate"><span class="pre">#1/</span></code>
+is literal. In this case, the actual name of the file is provided in the <code class="docutils literal notranslate"><span class="pre">nnn</span></code>
+bytes immediately following the header. If the name is 15 characters or less, it
+is contained directly in this field and terminated with a slash (/) character.</div></blockquote>
+<p>date - char[12]</p>
+<blockquote>
+<div>This field provides the date of modification of the file in the form of a
+decimal encoded number that provides the number of seconds since the epoch
+(since 00:00:00 Jan 1, 1970) per Posix specifications.</div></blockquote>
+<p>uid - char[6]</p>
+<blockquote>
+<div>This field provides the user id of the file encoded as a decimal ASCII string.
+This field might not make much sense on non-Unix systems. On Unix, it is the
+same value as the st_uid field of the stat structure returned by the stat(2)
+operating system call.</div></blockquote>
+<p>gid - char[6]</p>
+<blockquote>
+<div>This field provides the group id of the file encoded as a decimal ASCII string.
+This field might not make much sense on non-Unix systems. On Unix, it is the
+same value as the st_gid field of the stat structure returned by the stat(2)
+operating system call.</div></blockquote>
+<p>mode - char[8]</p>
+<blockquote>
+<div>This field provides the access mode of the file encoded as an octal ASCII
+string. This field might not make much sense on non-Unix systems. On Unix, it
+is the same value as the st_mode field of the stat structure returned by the
+stat(2) operating system call.</div></blockquote>
+<p>size - char[10]</p>
+<blockquote>
+<div>This field provides the size of the file, in bytes, encoded as a decimal ASCII
+string.</div></blockquote>
+<p>fmag - char[2]</p>
+<blockquote>
+<div>This field is the archive file member magic number. Its content is always the
+two characters back tick (0x60) and newline (0x0A). This provides some measure
+utility in identifying archive files that have been corrupted.</div></blockquote>
+<p>offset - vbr encoded 32-bit integer</p>
+<blockquote>
+<div>The offset item provides the offset into the archive file where the bitcode
+member is stored that is associated with the symbol. The offset value is 0
+based at the start of the first ânormalâ file member. To derive the actual
+file offset of the member, you must add the number of bytes occupied by the file
+signature (8 bytes) and the symbol tables. The value of this item is encoded
+using variable bit rate encoding to reduce the size of the symbol table.
+Variable bit rate encoding uses the high bit (0x80) of each byte to indicate
+if there are more bytes to follow. The remaining 7 bits in each byte carry bits
+from the value. The final byte does not have the high bit set.</div></blockquote>
+<p>length - vbr encoded 32-bit integer</p>
+<blockquote>
+<div>The length item provides the length of the symbol that follows. Like this
+<em>offset</em> item, the length is variable bit rate encoded.</div></blockquote>
+<p>symbol - character array</p>
+<blockquote>
+<div>The symbol item provides the text of the symbol that is associated with the
+<em>offset</em>. The symbol is not terminated by any character. Its length is provided
+by the <em>length</em> field. Note that is allowed (but unwise) to use non-printing
+characters (even 0x00) in the symbol. This allows for multiple encodings of
+symbol names.</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>If <strong>llvm-ar</strong> succeeds, it will exit with 0. A usage error, results
+in an exit code of 1. A hard (file system typically) error results in an
+exit code of 2. Miscellaneous or unknown errors result in an
+exit code of 3.</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>ar(1)</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-lib.html" title="llvm-lib - LLVM lib.exe compatible library tool"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-link.html" title="llvm-link - LLVM bitcode linker"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-as.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-as.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-as.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-as.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,136 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-as - LLVM assembler — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-dis - LLVM disassembler" href="llvm-dis.html" />
+ <link rel="prev" title="LLVM Command Guide" href="index.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" 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-dis.html" title="llvm-dis - LLVM disassembler"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="LLVM Command Guide"
+ 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-as-llvm-assembler">
+<h1>llvm-as - LLVM assembler<a class="headerlink" href="#llvm-as-llvm-assembler" 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>llvm-as</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>llvm-as</strong> is the LLVM assembler. It reads a file containing human-readable
+LLVM assembly language, translates it to LLVM bitcode, and writes the result
+into a file or to standard output.</p>
+<p>If <em>filename</em> is omitted or is <code class="docutils literal notranslate"><span class="pre">-</span></code>, then <strong>llvm-as</strong> reads its input from
+standard input.</p>
+<p>If an output file is not specified with the <strong>-o</strong> option, then
+<strong>llvm-as</strong> sends its output to a file or standard output by following
+these rules:</p>
+<ul class="simple">
+<li>If the input is standard input, then the output is standard output.</li>
+<li>If the input is a file that ends with <code class="docutils literal notranslate"><span class="pre">.ll</span></code>, then the output file is of the
+same name, except that the suffix is changed to <code class="docutils literal notranslate"><span class="pre">.bc</span></code>.</li>
+<li>If the input is a file that does not end with the <code class="docutils literal notranslate"><span class="pre">.ll</span></code> suffix, then the
+output file has the same name as the input file, except that the <code class="docutils literal notranslate"><span class="pre">.bc</span></code>
+suffix is appended.</li>
+</ul>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="docutils">
+<dt><strong>-f</strong></dt>
+<dd>Enable binary output on terminals. Normally, <strong>llvm-as</strong> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+<strong>llvm-as</strong> will write raw bitcode regardless of the output device.</dd>
+<dt><strong>-help</strong></dt>
+<dd>Print a summary of command line options.</dd>
+<dt><strong>-o</strong> <em>filename</em></dt>
+<dd>Specify the output file name. If <em>filename</em> is <code class="docutils literal notranslate"><span class="pre">-</span></code>, then <strong>llvm-as</strong>
+sends its output to standard output.</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>llvm-as</strong> succeeds, it will exit with 0. Otherwise, if an error occurs, it
+will exit with a non-zero value.</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>llvm-dis|llvm-dis, gccas|gccas</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-dis.html" title="llvm-dis - LLVM disassembler"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="index.html" title="LLVM Command Guide"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-bcanalyzer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-bcanalyzer.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-bcanalyzer.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-bcanalyzer.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,342 @@
+
+
+<!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-bcanalyzer - LLVM bitcode analyzer — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="FileCheck - Flexible pattern matching file verifier" href="FileCheck.html" />
+ <link rel="prev" title="llvm-extract - extract a function from an LLVM module" href="llvm-extract.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="FileCheck.html" title="FileCheck - Flexible pattern matching file verifier"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-extract.html" title="llvm-extract - extract a function from an LLVM module"
+ 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-bcanalyzer-llvm-bitcode-analyzer">
+<h1>llvm-bcanalyzer - LLVM bitcode analyzer<a class="headerlink" href="#llvm-bcanalyzer-llvm-bitcode-analyzer" 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-bcanalyzer</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">llvm-bcanalyzer</strong> command is a small utility for analyzing bitcode
+files. The tool reads a bitcode file (such as generated with the
+<strong class="program">llvm-as</strong> tool) and produces a statistical report on the contents of
+the bitcode file. The tool can also dump a low level but human readable
+version of the bitcode file. This tool is probably not of much interest or
+utility except for those working directly with the bitcode file format. Most
+LLVM users can just ignore this tool.</p>
+<p>If <em>filename</em> is omitted or is <code class="docutils literal notranslate"><span class="pre">-</span></code>, then <strong class="program">llvm-bcanalyzer</strong> reads its
+input from standard input. This is useful for combining the tool into a
+pipeline. Output is written 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-llvm-bcanalyzer-nodetails">
+<code class="descname">-nodetails</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-bcanalyzer-nodetails" title="Permalink to this definition">¶</a></dt>
+<dd><p>Causes <strong class="program">llvm-bcanalyzer</strong> to abbreviate its output by writing out only
+a module level summary. The details for individual functions are not
+displayed.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-bcanalyzer-dump">
+<code class="descname">-dump</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-bcanalyzer-dump" title="Permalink to this definition">¶</a></dt>
+<dd><p>Causes <strong class="program">llvm-bcanalyzer</strong> to dump the bitcode in a human readable
+format. This format is significantly different from LLVM assembly and
+provides details about the encoding of the bitcode file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-bcanalyzer-verify">
+<code class="descname">-verify</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-bcanalyzer-verify" title="Permalink to this definition">¶</a></dt>
+<dd><p>Causes <strong class="program">llvm-bcanalyzer</strong> to verify the module produced by reading the
+bitcode. This ensures that the statistics generated are based on a consistent
+module.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-bcanalyzer-help">
+<code class="descname">-help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-bcanalyzer-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</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">llvm-bcanalyzer</strong> succeeds, it will exit with 0. Otherwise, if an
+error occurs, it will exit with a non-zero value, usually 1.</p>
+</div>
+<div class="section" id="summary-output-definitions">
+<h2>SUMMARY OUTPUT DEFINITIONS<a class="headerlink" href="#summary-output-definitions" title="Permalink to this headline">¶</a></h2>
+<p>The following items are always printed by llvm-bcanalyzer. They comprize the
+summary output.</p>
+<p><strong>Bitcode Analysis Of Module</strong></p>
+<blockquote>
+<div>This just provides the name of the module for which bitcode analysis is being
+generated.</div></blockquote>
+<p><strong>Bitcode Version Number</strong></p>
+<blockquote>
+<div>The bitcode version (not LLVM version) of the file read by the analyzer.</div></blockquote>
+<p><strong>File Size</strong></p>
+<blockquote>
+<div>The size, in bytes, of the entire bitcode file.</div></blockquote>
+<p><strong>Module Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of the module block. Percentage is relative to File Size.</div></blockquote>
+<p><strong>Function Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of all the function blocks. Percentage is relative to File
+Size.</div></blockquote>
+<p><strong>Global Types Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of the Global Types Pool. Percentage is relative to File
+Size. This is the size of the definitions of all types in the bitcode file.</div></blockquote>
+<p><strong>Constant Pool Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of the Constant Pool Blocks Percentage is relative to File
+Size.</div></blockquote>
+<p><strong>Module Globals Bytes</strong></p>
+<blockquote>
+<div>Ths size, in bytes, of the Global Variable Definitions and their initializers.
+Percentage is relative to File Size.</div></blockquote>
+<p><strong>Instruction List Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of all the instruction lists in all the functions.
+Percentage is relative to File Size. Note that this value is also included in
+the Function Bytes.</div></blockquote>
+<p><strong>Compaction Table Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of all the compaction tables in all the functions.
+Percentage is relative to File Size. Note that this value is also included in
+the Function Bytes.</div></blockquote>
+<p><strong>Symbol Table Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of all the symbol tables in all the functions. Percentage is
+relative to File Size. Note that this value is also included in the Function
+Bytes.</div></blockquote>
+<p><strong>Dependent Libraries Bytes</strong></p>
+<blockquote>
+<div>The size, in bytes, of the list of dependent libraries in the module. Percentage
+is relative to File Size. Note that this value is also included in the Module
+Global Bytes.</div></blockquote>
+<p><strong>Number Of Bitcode Blocks</strong></p>
+<blockquote>
+<div>The total number of blocks of any kind in the bitcode file.</div></blockquote>
+<p><strong>Number Of Functions</strong></p>
+<blockquote>
+<div>The total number of function definitions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Types</strong></p>
+<blockquote>
+<div>The total number of types defined in the Global Types Pool.</div></blockquote>
+<p><strong>Number Of Constants</strong></p>
+<blockquote>
+<div>The total number of constants (of any type) defined in the Constant Pool.</div></blockquote>
+<p><strong>Number Of Basic Blocks</strong></p>
+<blockquote>
+<div>The total number of basic blocks defined in all functions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Instructions</strong></p>
+<blockquote>
+<div>The total number of instructions defined in all functions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Long Instructions</strong></p>
+<blockquote>
+<div>The total number of long instructions defined in all functions in the bitcode
+file. Long instructions are those taking greater than 4 bytes. Typically long
+instructions are GetElementPtr with several indices, PHI nodes, and calls to
+functions with large numbers of arguments.</div></blockquote>
+<p><strong>Number Of Operands</strong></p>
+<blockquote>
+<div>The total number of operands used in all instructions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Compaction Tables</strong></p>
+<blockquote>
+<div>The total number of compaction tables in all functions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Symbol Tables</strong></p>
+<blockquote>
+<div>The total number of symbol tables in all functions in the bitcode file.</div></blockquote>
+<p><strong>Number Of Dependent Libs</strong></p>
+<blockquote>
+<div>The total number of dependent libraries found in the bitcode file.</div></blockquote>
+<p><strong>Total Instruction Size</strong></p>
+<blockquote>
+<div>The total size of the instructions in all functions in the bitcode file.</div></blockquote>
+<p><strong>Average Instruction Size</strong></p>
+<blockquote>
+<div>The average number of bytes per instruction across all functions in the bitcode
+file. This value is computed by dividing Total Instruction Size by Number Of
+Instructions.</div></blockquote>
+<p><strong>Maximum Type Slot Number</strong></p>
+<blockquote>
+<div>The maximum value used for a typeâs slot number. Larger slot number values take
+more bytes to encode.</div></blockquote>
+<p><strong>Maximum Value Slot Number</strong></p>
+<blockquote>
+<div>The maximum value used for a valueâs slot number. Larger slot number values take
+more bytes to encode.</div></blockquote>
+<p><strong>Bytes Per Value</strong></p>
+<blockquote>
+<div>The average size of a Value definition (of any type). This is computed by
+dividing File Size by the total number of values of any type.</div></blockquote>
+<p><strong>Bytes Per Global</strong></p>
+<blockquote>
+<div>The average size of a global definition (constants and global variables).</div></blockquote>
+<p><strong>Bytes Per Function</strong></p>
+<blockquote>
+<div>The average number of bytes per function definition. This is computed by
+dividing Function Bytes by Number Of Functions.</div></blockquote>
+<p><strong># of VBR 32-bit Integers</strong></p>
+<blockquote>
+<div>The total number of 32-bit integers encoded using the Variable Bit Rate
+encoding scheme.</div></blockquote>
+<p><strong># of VBR 64-bit Integers</strong></p>
+<blockquote>
+<div>The total number of 64-bit integers encoded using the Variable Bit Rate encoding
+scheme.</div></blockquote>
+<p><strong># of VBR Compressed Bytes</strong></p>
+<blockquote>
+<div>The total number of bytes consumed by the 32-bit and 64-bit integers that use
+the Variable Bit Rate encoding scheme.</div></blockquote>
+<p><strong># of VBR Expanded Bytes</strong></p>
+<blockquote>
+<div>The total number of bytes that would have been consumed by the 32-bit and 64-bit
+integers had they not been compressed with the Variable Bit Rage encoding
+scheme.</div></blockquote>
+<p><strong>Bytes Saved With VBR</strong></p>
+<blockquote>
+<div>The total number of bytes saved by using the Variable Bit Rate encoding scheme.
+The percentage is relative to # of VBR Expanded Bytes.</div></blockquote>
+</div>
+<div class="section" id="detailed-output-definitions">
+<h2>DETAILED OUTPUT DEFINITIONS<a class="headerlink" href="#detailed-output-definitions" title="Permalink to this headline">¶</a></h2>
+<p>The following definitions occur only if the -nodetails option was not given.
+The detailed output provides additional information on a per-function basis.</p>
+<p><strong>Type</strong></p>
+<blockquote>
+<div>The type signature of the function.</div></blockquote>
+<p><strong>Byte Size</strong></p>
+<blockquote>
+<div>The total number of bytes in the functionâs block.</div></blockquote>
+<p><strong>Basic Blocks</strong></p>
+<blockquote>
+<div>The number of basic blocks defined by the function.</div></blockquote>
+<p><strong>Instructions</strong></p>
+<blockquote>
+<div>The number of instructions defined by the function.</div></blockquote>
+<p><strong>Long Instructions</strong></p>
+<blockquote>
+<div>The number of instructions using the long instruction format in the function.</div></blockquote>
+<p><strong>Operands</strong></p>
+<blockquote>
+<div>The number of operands used by all instructions in the function.</div></blockquote>
+<p><strong>Instruction Size</strong></p>
+<blockquote>
+<div>The number of bytes consumed by instructions in the function.</div></blockquote>
+<p><strong>Average Instruction Size</strong></p>
+<blockquote>
+<div>The average number of bytes consumed by the instructions in the function.
+This value is computed by dividing Instruction Size by Instructions.</div></blockquote>
+<p><strong>Bytes Per Instruction</strong></p>
+<blockquote>
+<div>The average number of bytes used by the function per instruction. This value
+is computed by dividing Byte Size by Instructions. Note that this is not the
+same as Average Instruction Size. It computes a number relative to the total
+function size not just the size of the instruction list.</div></blockquote>
+<p><strong>Number of VBR 32-bit Integers</strong></p>
+<blockquote>
+<div>The total number of 32-bit integers found in this function (for any use).</div></blockquote>
+<p><strong>Number of VBR 64-bit Integers</strong></p>
+<blockquote>
+<div>The total number of 64-bit integers found in this function (for any use).</div></blockquote>
+<p><strong>Number of VBR Compressed Bytes</strong></p>
+<blockquote>
+<div>The total number of bytes in this function consumed by the 32-bit and 64-bit
+integers that use the Variable Bit Rate encoding scheme.</div></blockquote>
+<p><strong>Number of VBR Expanded Bytes</strong></p>
+<blockquote>
+<div>The total number of bytes in this function that would have been consumed by
+the 32-bit and 64-bit integers had they not been compressed with the Variable
+Bit Rate encoding scheme.</div></blockquote>
+<p><strong>Bytes Saved With VBR</strong></p>
+<blockquote>
+<div>The total number of bytes saved in this function by using the Variable Bit
+Rate encoding scheme. The percentage is relative to # of VBR Expanded Bytes.</div></blockquote>
+</div>
+<div class="section" id="see-also">
+<h2>SEE ALSO<a class="headerlink" href="#see-also" title="Permalink to this headline">¶</a></h2>
+<p><a class="reference internal" href="llvm-dis.html"><span class="doc">llvm-dis - LLVM disassembler</span></a>, <a class="reference internal" href="../BitCodeFormat.html"><span class="doc">LLVM Bitcode File Format</span></a></p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="FileCheck.html" title="FileCheck - Flexible pattern matching file verifier"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-extract.html" title="llvm-extract - extract a function from an LLVM module"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-build.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-build.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-build.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-build.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,153 @@
+
+
+<!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-build - LLVM Project Build Utility — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-exegesis - LLVM Machine Instruction Benchmark" href="llvm-exegesis.html" />
+ <link rel="prev" title="lit - LLVM Integrated Tester" href="lit.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-exegesis.html" title="llvm-exegesis - LLVM Machine Instruction Benchmark"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="lit.html" title="lit - LLVM Integrated Tester"
+ 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-build-llvm-project-build-utility">
+<h1>llvm-build - LLVM Project Build Utility<a class="headerlink" href="#llvm-build-llvm-project-build-utility" 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>llvm-build</strong> [<em>options</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-build</strong> is a tool for working with LLVM projects that use the LLVMBuild
+system for describing their components.</p>
+<p>At heart, <strong>llvm-build</strong> is responsible for loading, verifying, and manipulating
+the projectâs component data. The tool is primarily designed for use in
+implementing build systems and tools which need access to the project structure
+information.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong>-h</strong>, <strong>âhelp</strong></p>
+<blockquote>
+<div>Print the builtin program help.</div></blockquote>
+<p><strong>âsource-root</strong>=<em>PATH</em></p>
+<blockquote>
+<div>If given, load the project at the given source root path. If this option is not
+given, the location of the project sources will be inferred from the location of
+the <strong>llvm-build</strong> script itself.</div></blockquote>
+<p><strong>âprint-tree</strong></p>
+<blockquote>
+<div>Print the component tree for the project.</div></blockquote>
+<p><strong>âwrite-library-table</strong></p>
+<blockquote>
+<div>Write out the C++ fragment which defines the components, library names, and
+required libraries. This C++ fragment is built into llvm-config|llvm-config
+in order to provide clients with the list of required libraries for arbitrary
+component combinations.</div></blockquote>
+<p><strong>âwrite-llvmbuild</strong></p>
+<blockquote>
+<div>Write out new <em>LLVMBuild.txt</em> files based on the loaded components. This is
+useful for auto-upgrading the schema of the files. <strong>llvm-build</strong> will try to a
+limited extent to preserve the comments which were written in the original
+source file, although at this time it only preserves block comments that precede
+the section names in the <em>LLVMBuild</em> files.</div></blockquote>
+<p><strong>âwrite-cmake-fragment</strong></p>
+<blockquote>
+<div>Write out the LLVMBuild in the form of a CMake fragment, so it can easily be
+consumed by the CMake based build system. The exact contents and format of this
+file are closely tied to how LLVMBuild is integrated with CMake, see LLVMâs
+top-level CMakeLists.txt.</div></blockquote>
+<p><strong>âwrite-make-fragment</strong></p>
+<blockquote>
+<div>Write out the LLVMBuild in the form of a Makefile fragment, so it can easily be
+consumed by a Make based build system. The exact contents and format of this
+file are closely tied to how LLVMBuild is integrated with the Makefiles, see
+LLVMâs Makefile.rules.</div></blockquote>
+<p><strong>âllvmbuild-source-root</strong>=<em>PATH</em></p>
+<blockquote>
+<div>If given, expect the <em>LLVMBuild</em> files for the project to be rooted at the
+given path, instead of inside the source tree itself. This option is primarily
+designed for use in conjunction with <strong>âwrite-llvmbuild</strong> to test changes to
+<em>LLVMBuild</em> schema.</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>llvm-build</strong> exits with 0 if operation was successful. Otherwise, it will exist
+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="llvm-exegesis.html" title="llvm-exegesis - LLVM Machine Instruction Benchmark"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="lit.html" title="lit - LLVM Integrated Tester"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-config.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-config.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-config.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-config.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,185 @@
+
+
+<!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-config - Print LLVM compilation options — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-cxxmap - Mangled name remapping tool" href="llvm-cxxmap.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-cxxmap.html" title="llvm-cxxmap - Mangled name remapping tool"
+ 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-config-print-llvm-compilation-options">
+<h1>llvm-config - Print LLVM compilation options<a class="headerlink" href="#llvm-config-print-llvm-compilation-options" 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>llvm-config</strong> <em>option</em> [<em>components</em>â¦]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-config</strong> makes it easier to build applications that use LLVM. It can
+print the compiler flags, linker flags and object libraries needed to link
+against LLVM.</p>
+</div>
+<div class="section" id="examples">
+<h2>EXAMPLES<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
+<p>To link against the JIT:</p>
+<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>g++ <span class="sb">`</span>llvm-config --cxxflags<span class="sb">`</span> -o HowToUseJIT.o -c HowToUseJIT.cpp
+g++ <span class="sb">`</span>llvm-config --ldflags<span class="sb">`</span> -o HowToUseJIT HowToUseJIT.o <span class="se">\</span>
+ <span class="sb">`</span>llvm-config --libs engine bcreader scalaropts<span class="sb">`</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong>âversion</strong></p>
+<blockquote>
+<div>Print the version number of LLVM.</div></blockquote>
+<p><strong>-help</strong></p>
+<blockquote>
+<div>Print a summary of <strong>llvm-config</strong> arguments.</div></blockquote>
+<p><strong>âprefix</strong></p>
+<blockquote>
+<div>Print the installation prefix for LLVM.</div></blockquote>
+<p><strong>âsrc-root</strong></p>
+<blockquote>
+<div>Print the source root from which LLVM was built.</div></blockquote>
+<p><strong>âobj-root</strong></p>
+<blockquote>
+<div>Print the object root used to build LLVM.</div></blockquote>
+<p><strong>âbindir</strong></p>
+<blockquote>
+<div>Print the installation directory for LLVM binaries.</div></blockquote>
+<p><strong>âincludedir</strong></p>
+<blockquote>
+<div>Print the installation directory for LLVM headers.</div></blockquote>
+<p><strong>âlibdir</strong></p>
+<blockquote>
+<div>Print the installation directory for LLVM libraries.</div></blockquote>
+<p><strong>âcxxflags</strong></p>
+<blockquote>
+<div>Print the C++ compiler flags needed to use LLVM headers.</div></blockquote>
+<p><strong>âldflags</strong></p>
+<blockquote>
+<div>Print the flags needed to link against LLVM libraries.</div></blockquote>
+<p><strong>âlibs</strong></p>
+<blockquote>
+<div>Print all the libraries needed to link against the specified LLVM
+<em>components</em>, including any dependencies.</div></blockquote>
+<p><strong>âlibnames</strong></p>
+<blockquote>
+<div>Similar to <strong>âlibs</strong>, but prints the bare filenames of the libraries
+without <strong>-l</strong> or pathnames. Useful for linking against a not-yet-installed
+copy of LLVM.</div></blockquote>
+<p><strong>âlibfiles</strong></p>
+<blockquote>
+<div>Similar to <strong>âlibs</strong>, but print the full path to each library file. This is
+useful when creating makefile dependencies, to ensure that a tool is relinked if
+any library it uses changes.</div></blockquote>
+<p><strong>âcomponents</strong></p>
+<blockquote>
+<div>Print all valid component names.</div></blockquote>
+<p><strong>âtargets-built</strong></p>
+<blockquote>
+<div>Print the component names for all targets supported by this copy of LLVM.</div></blockquote>
+<p><strong>âbuild-mode</strong></p>
+<blockquote>
+<div>Print the build mode used when LLVM was built (e.g. Debug or Release)</div></blockquote>
+</div>
+<div class="section" id="components">
+<h2>COMPONENTS<a class="headerlink" href="#components" title="Permalink to this headline">¶</a></h2>
+<p>To print a list of all available components, run <strong>llvm-config
+âcomponents</strong>. In most cases, components correspond directly to LLVM
+libraries. Useful âvirtualâ components include:</p>
+<p><strong>all</strong></p>
+<blockquote>
+<div>Includes all LLVM libraries. The default if no components are specified.</div></blockquote>
+<p><strong>backend</strong></p>
+<blockquote>
+<div>Includes either a native backend or the C backend.</div></blockquote>
+<p><strong>engine</strong></p>
+<blockquote>
+<div>Includes either a native JIT or the bitcode interpreter.</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>If <strong>llvm-config</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="llvm-cxxmap.html" title="llvm-cxxmap - Mangled name remapping tool"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-cov.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-cov.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-cov.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-cov.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,546 @@
+
+
+<!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-cov - emit coverage information — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-profdata - Profile data tool" href="llvm-profdata.html" />
+ <link rel="prev" title="llvm-diff - LLVM structural âdiffâ" href="llvm-diff.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-profdata.html" title="llvm-profdata - Profile data tool"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-diff.html" title="llvm-diff - LLVM structural âdiffâ"
+ 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-cov-emit-coverage-information">
+<h1>llvm-cov - emit coverage information<a class="headerlink" href="#llvm-cov-emit-coverage-information" 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-cov</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-cov</strong> tool shows code coverage information for
+programs that are instrumented to emit profile data. It can be used to
+work with <code class="docutils literal notranslate"><span class="pre">gcov</span></code>-style coverage or with <code class="docutils literal notranslate"><span class="pre">clang</span></code>âs instrumentation
+based profiling.</p>
+<p>If the program is invoked with a base name of <code class="docutils literal notranslate"><span class="pre">gcov</span></code>, it will behave as if
+the <strong class="program">llvm-cov gcov</strong> command were called. Otherwise, a command should
+be provided.</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="#llvm-cov-gcov"><span class="std std-ref">gcov</span></a></li>
+<li><a class="reference internal" href="#llvm-cov-show"><span class="std std-ref">show</span></a></li>
+<li><a class="reference internal" href="#llvm-cov-report"><span class="std std-ref">report</span></a></li>
+<li><a class="reference internal" href="#llvm-cov-export"><span class="std std-ref">export</span></a></li>
+</ul>
+</div>
+<div class="section" id="gcov-command">
+<span id="llvm-cov-gcov"></span><h2>GCOV COMMAND<a class="headerlink" href="#gcov-command" 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-cov gcov</strong> [<em>options</em>] <em>SOURCEFILE</em></p>
+</div>
+<div class="section" id="id2">
+<h3>DESCRIPTION<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">llvm-cov gcov</strong> tool reads code coverage data files and displays
+the coverage information for a specified source file. It is compatible with the
+<code class="docutils literal notranslate"><span class="pre">gcov</span></code> tool from version 4.2 of <code class="docutils literal notranslate"><span class="pre">GCC</span></code> and may also be compatible with some
+later versions of <code class="docutils literal notranslate"><span class="pre">gcov</span></code>.</p>
+<p>To use <strong class="program">llvm-cov gcov</strong>, you must first build an instrumented version
+of your application that collects coverage data as it runs. Compile with the
+<code class="docutils literal notranslate"><span class="pre">-fprofile-arcs</span></code> and <code class="docutils literal notranslate"><span class="pre">-ftest-coverage</span></code> options to add the
+instrumentation. (Alternatively, you can use the <code class="docutils literal notranslate"><span class="pre">--coverage</span></code> option, which
+includes both of those other options.) You should compile with debugging
+information (<code class="docutils literal notranslate"><span class="pre">-g</span></code>) and without optimization (<code class="docutils literal notranslate"><span class="pre">-O0</span></code>); otherwise, the
+coverage data cannot be accurately mapped back to the source code.</p>
+<p>At the time you compile the instrumented code, a <code class="docutils literal notranslate"><span class="pre">.gcno</span></code> data file will be
+generated for each object file. These <code class="docutils literal notranslate"><span class="pre">.gcno</span></code> files contain half of the
+coverage data. The other half of the data comes from <code class="docutils literal notranslate"><span class="pre">.gcda</span></code> files that are
+generated when you run the instrumented program, with a separate <code class="docutils literal notranslate"><span class="pre">.gcda</span></code>
+file for each object file. Each time you run the program, the execution counts
+are summed into any existing <code class="docutils literal notranslate"><span class="pre">.gcda</span></code> files, so be sure to remove any old
+files if you do not want their contents to be included.</p>
+<p>By default, the <code class="docutils literal notranslate"><span class="pre">.gcda</span></code> files are written into the same directory as the
+object files, but you can override that by setting the <code class="docutils literal notranslate"><span class="pre">GCOV_PREFIX</span></code> and
+<code class="docutils literal notranslate"><span class="pre">GCOV_PREFIX_STRIP</span></code> environment variables. The <code class="docutils literal notranslate"><span class="pre">GCOV_PREFIX_STRIP</span></code>
+variable specifies a number of directory components to be removed from the
+start of the absolute path to the object file directory. After stripping those
+directories, the prefix from the <code class="docutils literal notranslate"><span class="pre">GCOV_PREFIX</span></code> variable is added. These
+environment variables allow you to run the instrumented program on a machine
+where the original object file directories are not accessible, but you will
+then need to copy the <code class="docutils literal notranslate"><span class="pre">.gcda</span></code> files back to the object file directories
+where <strong class="program">llvm-cov gcov</strong> expects to find them.</p>
+<p>Once you have generated the coverage data files, run <strong class="program">llvm-cov gcov</strong>
+for each main source file where you want to examine the coverage results. This
+should be run from the same directory where you previously ran the
+compiler. The results for the specified source file are written to a file named
+by appending a <code class="docutils literal notranslate"><span class="pre">.gcov</span></code> suffix. A separate output file is also created for
+each file included by the main source file, also with a <code class="docutils literal notranslate"><span class="pre">.gcov</span></code> suffix added.</p>
+<p>The basic content of an <code class="docutils literal notranslate"><span class="pre">.gcov</span></code> output file is a copy of the source file with
+an execution count and line number prepended to every line. The execution
+count is shown as <code class="docutils literal notranslate"><span class="pre">-</span></code> if a line does not contain any executable code. If
+a line contains code but that code was never executed, the count is displayed
+as <code class="docutils literal notranslate"><span class="pre">#####</span></code>.</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-cov-gcov-a">
+<code class="descname">-a</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--all-blocks</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-a" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all basic blocks. If there are multiple blocks for a single line of
+source code, this option causes llvm-cov to show the count for each block
+instead of just one count for the entire line.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-b">
+<code class="descname">-b</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--branch-probabilities</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-b" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display conditional branch probabilities and a summary of branch information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-c">
+<code class="descname">-c</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--branch-counts</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-c" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display branch counts instead of probabilities (requires -b).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-f">
+<code class="descname">-f</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--function-summaries</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show a summary of coverage for each function instead of just one summary for
+an entire source file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-help">
+<code class="descname">--help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display available options (âhelp-hidden for more).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-l">
+<code class="descname">-l</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--long-file-names</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-l" title="Permalink to this definition">¶</a></dt>
+<dd><p>For coverage output of files included from the main source file, add the
+main file name followed by <code class="docutils literal notranslate"><span class="pre">##</span></code> as a prefix to the output file names. This
+can be combined with the âpreserve-paths option to use complete paths for
+both the main file and the included file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-n">
+<code class="descname">-n</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--no-output</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-n" title="Permalink to this definition">¶</a></dt>
+<dd><p>Do not output any <code class="docutils literal notranslate"><span class="pre">.gcov</span></code> files. Summary information is still
+displayed.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-o">
+<code class="descname">-o</code><code class="descclassname">=<DIR|FILE></code><code class="descclassname">, </code><code class="descname">--object-directory</code><code class="descclassname">=<DIR></code><code class="descclassname">, </code><code class="descname">--object-file</code><code class="descclassname">=<FILE></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Find objects in DIR or based on FILEâs path. If you specify a particular
+object file, the coverage data files are expected to have the same base name
+with <code class="docutils literal notranslate"><span class="pre">.gcno</span></code> and <code class="docutils literal notranslate"><span class="pre">.gcda</span></code> extensions. If you specify a directory, the
+files are expected in that directory with the same base name as the source
+file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-p">
+<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--preserve-paths</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-p" title="Permalink to this definition">¶</a></dt>
+<dd><p>Preserve path components when naming the coverage output files. In addition
+to the source file name, include the directories from the path to that
+file. The directories are separate by <code class="docutils literal notranslate"><span class="pre">#</span></code> characters, with <code class="docutils literal notranslate"><span class="pre">.</span></code> directories
+removed and <code class="docutils literal notranslate"><span class="pre">..</span></code> directories replaced by <code class="docutils literal notranslate"><span class="pre">^</span></code> characters. When used with
+the âlong-file-names option, this applies to both the main file name and the
+included file name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-u">
+<code class="descname">-u</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--unconditional-branches</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-u" title="Permalink to this definition">¶</a></dt>
+<dd><p>Include unconditional branches in the output for the âbranch-probabilities
+option.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-gcov-version">
+<code class="descname">-version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-gcov-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of llvm-cov.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h3>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-cov gcov</strong> returns 1 if it cannot read input files. Otherwise,
+it exits with zero.</p>
+</div>
+</div>
+<div class="section" id="show-command">
+<span id="llvm-cov-show"></span><h2>SHOW COMMAND<a class="headerlink" href="#show-command" 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-cov show</strong> [<em>options</em>] -instr-profile <em>PROFILE</em> <em>BIN</em> [<em>-object BIN,â¦</em>] [[<em>-object BIN</em>]] [<em>SOURCES</em>]</p>
+</div>
+<div class="section" id="id4">
+<h3>DESCRIPTION<a class="headerlink" href="#id4" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">llvm-cov show</strong> command shows line by line coverage of the
+binaries <em>BIN</em>,⦠using the profile data <em>PROFILE</em>. It can optionally be
+filtered to only show the coverage for the files listed in <em>SOURCES</em>.</p>
+<p>To use <strong class="program">llvm-cov show</strong>, you need a program that is compiled with
+instrumentation to emit profile and coverage data. To build such a program with
+<code class="docutils literal notranslate"><span class="pre">clang</span></code> use the <code class="docutils literal notranslate"><span class="pre">-fprofile-instr-generate</span></code> and <code class="docutils literal notranslate"><span class="pre">-fcoverage-mapping</span></code>
+flags. If linking with the <code class="docutils literal notranslate"><span class="pre">clang</span></code> driver, pass <code class="docutils literal notranslate"><span class="pre">-fprofile-instr-generate</span></code>
+to the link stage to make sure the necessary runtime libraries are linked in.</p>
+<p>The coverage information is stored in the built executable or library itself,
+and this is what you should pass to <strong class="program">llvm-cov show</strong> as a <em>BIN</em>
+argument. The profile data is generated by running this instrumented program
+normally. When the program exits it will write out a raw profile file,
+typically called <code class="docutils literal notranslate"><span class="pre">default.profraw</span></code>, which can be converted to a format that
+is suitable for the <em>PROFILE</em> argument using the <strong class="program">llvm-profdata merge</strong>
+tool.</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-cov-show-show-line-counts">
+<code class="descname">-show-line-counts</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-show-show-line-counts" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the execution counts for each line. Defaults to true, unless another
+<code class="docutils literal notranslate"><span class="pre">-show</span></code> option is used.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-show-expansions">
+<code class="descname">-show-expansions</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-show-show-expansions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Expand inclusions, such as preprocessor macros or textual inclusions, inline
+in the display of the source file. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-show-instantiations">
+<code class="descname">-show-instantiations</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-show-show-instantiations" title="Permalink to this definition">¶</a></dt>
+<dd><p>For source regions that are instantiated multiple times, such as templates in
+<code class="docutils literal notranslate"><span class="pre">C++</span></code>, show each instantiation separately as well as the combined summary.
+Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-show-regions">
+<code class="descname">-show-regions</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-show-show-regions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the execution counts for each region by displaying a caret that points to
+the character where the region starts. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-show-line-counts-or-regions">
+<code class="descname">-show-line-counts-or-regions</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-show-show-line-counts-or-regions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the execution counts for each line if there is only one region on the
+line, but show the individual regions if there are multiple on the line.
+Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-use-color">
+<code class="descname">-use-color</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-show-use-color" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable or disable color output. By default this is autodetected.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-arch">
+<code class="descname">-arch</code><code class="descclassname">=[*NAMES*]</code><a class="headerlink" href="#cmdoption-llvm-cov-show-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a list of architectures such that the Nth entry in the list
+corresponds to the Nth specified binary. If the covered object is a universal
+binary, this specifies the architecture to use. It is an error to specify an
+architecture that is not included in the universal binary or to use an
+architecture that does not match a non-universal binary.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-name">
+<code class="descname">-name</code><code class="descclassname">=<NAME></code><a class="headerlink" href="#cmdoption-llvm-cov-show-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with the given name.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-name-whitelist">
+<code class="descname">-name-whitelist</code><code class="descclassname">=<FILE></code><a class="headerlink" href="#cmdoption-llvm-cov-show-name-whitelist" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions listed in the given file. Each line in
+the file should start with <cite>whitelist_fun:</cite>, immediately followed by the name
+of the function to accept. This name can be a wildcard expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-name-regex">
+<code class="descname">-name-regex</code><code class="descclassname">=<PATTERN></code><a class="headerlink" href="#cmdoption-llvm-cov-show-name-regex" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions that match the given regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-ignore-filename-regex">
+<code class="descname">-ignore-filename-regex</code><code class="descclassname">=<PATTERN></code><a class="headerlink" href="#cmdoption-llvm-cov-show-ignore-filename-regex" title="Permalink to this definition">¶</a></dt>
+<dd><p>Skip source code files with file paths that match the given regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-format">
+<code class="descname">-format</code><code class="descclassname">=<FORMAT></code><a class="headerlink" href="#cmdoption-llvm-cov-show-format" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use the specified output format. The supported formats are: âtextâ, âhtmlâ.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-tab-size">
+<code class="descname">-tab-size</code><code class="descclassname">=<TABSIZE></code><a class="headerlink" href="#cmdoption-llvm-cov-show-tab-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is
+only supported for the html format.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-output-dir">
+<code class="descname">-output-dir</code><code class="descclassname">=PATH</code><a class="headerlink" href="#cmdoption-llvm-cov-show-output-dir" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a directory to write coverage reports into. If the directory does not
+exist, it is created. When used in function view mode (i.e when -name or
+-name-regex are used to select specific functions), the report is written to
+PATH/functions.EXTENSION. When used in file view mode, a report for each file
+is written to PATH/REL_PATH_TO_FILE.EXTENSION.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-xdemangler">
+<code class="descname">-Xdemangler</code><code class="descclassname">=<TOOL>|<TOOL-OPTION></code><a class="headerlink" href="#cmdoption-llvm-cov-show-xdemangler" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a symbol demangler. This can be used to make reports more
+human-readable. This option can be specified multiple times to supply
+arguments to the demangler (e.g <cite>-Xdemangler c++filt -Xdemangler -n</cite> for C++).
+The demangler is expected to read a newline-separated list of symbols from
+stdin and write a newline-separated list of the same length to stdout.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-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-cov-show-num-threads" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use N threads to write file reports (only applicable when -output-dir is
+specified). When N=0, llvm-cov auto-detects an appropriate number of threads to
+use. This is the default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-line-coverage-gt">
+<code class="descname">-line-coverage-gt</code><code class="descclassname">=<N></code><a class="headerlink" href="#cmdoption-llvm-cov-show-line-coverage-gt" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with line coverage greater than the
+given threshold.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-line-coverage-lt">
+<code class="descname">-line-coverage-lt</code><code class="descclassname">=<N></code><a class="headerlink" href="#cmdoption-llvm-cov-show-line-coverage-lt" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with line coverage less than the given
+threshold.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-region-coverage-gt">
+<code class="descname">-region-coverage-gt</code><code class="descclassname">=<N></code><a class="headerlink" href="#cmdoption-llvm-cov-show-region-coverage-gt" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with region coverage greater than the
+given threshold.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-region-coverage-lt">
+<code class="descname">-region-coverage-lt</code><code class="descclassname">=<N></code><a class="headerlink" href="#cmdoption-llvm-cov-show-region-coverage-lt" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show code coverage only for functions with region coverage less than the given
+threshold.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-show-path-equivalence">
+<code class="descname">-path-equivalence</code><code class="descclassname">=<from>,<to></code><a class="headerlink" href="#cmdoption-llvm-cov-show-path-equivalence" title="Permalink to this definition">¶</a></dt>
+<dd><p>Map the paths in the coverage data to local source file paths. This allows you
+to generate the coverage data on one machine, and then use llvm-cov on a
+different machine where you have the same files on a different path.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="report-command">
+<span id="llvm-cov-report"></span><h2>REPORT COMMAND<a class="headerlink" href="#report-command" 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-cov report</strong> [<em>options</em>] -instr-profile <em>PROFILE</em> <em>BIN</em> [<em>-object BIN,â¦</em>] [[<em>-object BIN</em>]] [<em>SOURCES</em>]</p>
+</div>
+<div class="section" id="id7">
+<h3>DESCRIPTION<a class="headerlink" href="#id7" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">llvm-cov report</strong> command displays a summary of the coverage of
+the binaries <em>BIN</em>,⦠using the profile data <em>PROFILE</em>. It can optionally be
+filtered to only show the coverage for the files listed in <em>SOURCES</em>.</p>
+<p>If no source files are provided, a summary line is printed for each file in the
+coverage data. If any files are provided, summaries can be shown for each
+function in the listed files if the <code class="docutils literal notranslate"><span class="pre">-show-functions</span></code> option is enabled.</p>
+<p>For information on compiling programs for coverage and generating profile data,
+see <a class="reference internal" href="#llvm-cov-show"><span class="std std-ref">SHOW COMMAND</span></a>.</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-cov-report-use-color">
+<code class="descname">-use-color[</code><code class="descclassname">=VALUE]</code><a class="headerlink" href="#cmdoption-llvm-cov-report-use-color" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable or disable color output. By default this is autodetected.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-report-arch">
+<code class="descname">-arch</code><code class="descclassname">=<name></code><a class="headerlink" href="#cmdoption-llvm-cov-report-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>If the covered binary is a universal binary, select the architecture to use.
+It is an error to specify an architecture that is not included in the
+universal binary or to use an architecture that does not match a
+non-universal binary.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-report-show-functions">
+<code class="descname">-show-functions</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-report-show-functions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show coverage summaries for each function. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-report-show-instantiation-summary">
+<code class="descname">-show-instantiation-summary</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-report-show-instantiation-summary" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show statistics for all function instantiations. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-report-ignore-filename-regex">
+<code class="descname">-ignore-filename-regex</code><code class="descclassname">=<PATTERN></code><a class="headerlink" href="#cmdoption-llvm-cov-report-ignore-filename-regex" title="Permalink to this definition">¶</a></dt>
+<dd><p>Skip source code files with file paths that match the given regular expression.</p>
+</dd></dl>
+
+</div>
+</div>
+<div class="section" id="export-command">
+<span id="llvm-cov-export"></span><h2>EXPORT COMMAND<a class="headerlink" href="#export-command" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="id9">
+<h3>SYNOPSIS<a class="headerlink" href="#id9" title="Permalink to this headline">¶</a></h3>
+<p><strong class="program">llvm-cov export</strong> [<em>options</em>] -instr-profile <em>PROFILE</em> <em>BIN</em> [<em>-object BIN,â¦</em>] [[<em>-object BIN</em>]] [<em>SOURCES</em>]</p>
+</div>
+<div class="section" id="id10">
+<h3>DESCRIPTION<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h3>
+<p>The <strong class="program">llvm-cov export</strong> command exports coverage data of the binaries
+<em>BIN</em>,⦠using the profile data <em>PROFILE</em> in either JSON or lcov trace file
+format.</p>
+<p>When exporting JSON, the regions, functions, expansions, and summaries of the
+coverage data will be exported. When exporting an lcov trace file, the
+line-based coverage and summaries will be exported.</p>
+<p>The exported data can optionally be filtered to only export the coverage
+for the files listed in <em>SOURCES</em>.</p>
+<p>For information on compiling programs for coverage and generating profile data,
+see <a class="reference internal" href="#llvm-cov-show"><span class="std std-ref">SHOW COMMAND</span></a>.</p>
+</div>
+<div class="section" id="id11">
+<h3>OPTIONS<a class="headerlink" href="#id11" title="Permalink to this headline">¶</a></h3>
+<dl class="option">
+<dt id="cmdoption-llvm-cov-export-arch">
+<code class="descname">-arch</code><code class="descclassname">=<name></code><a class="headerlink" href="#cmdoption-llvm-cov-export-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>If the covered binary is a universal binary, select the architecture to use.
+It is an error to specify an architecture that is not included in the
+universal binary or to use an architecture that does not match a
+non-universal binary.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-export-format">
+<code class="descname">-format</code><code class="descclassname">=<FORMAT></code><a class="headerlink" href="#cmdoption-llvm-cov-export-format" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use the specified output format. The supported formats are: âtextâ (JSON),
+âlcovâ.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-export-summary-only">
+<code class="descname">-summary-only</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cov-export-summary-only" title="Permalink to this definition">¶</a></dt>
+<dd><p>Export only summary information for each file in the coverage data. This mode
+will not export coverage information for smaller units such as individual
+functions or regions. The result will contain the same information as produced
+by the <strong class="program">llvm-cov report</strong> command, but presented in JSON or lcov
+format rather than text.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cov-export-ignore-filename-regex">
+<code class="descname">-ignore-filename-regex</code><code class="descclassname">=<PATTERN></code><a class="headerlink" href="#cmdoption-llvm-cov-export-ignore-filename-regex" title="Permalink to this definition">¶</a></dt>
+<dd><p>Skip source code files with file paths that match the given regular expression.</p>
+</dd></dl>
+
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="../genindex.html" title="General Index"
+ >index</a></li>
+ <li class="right" >
+ <a href="llvm-profdata.html" title="llvm-profdata - Profile data tool"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-diff.html" title="llvm-diff - LLVM structural âdiffâ"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-cxxmap.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-cxxmap.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-cxxmap.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-cxxmap.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,172 @@
+
+
+<!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-cxxmap - Mangled name remapping tool — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-diff - LLVM structural âdiffâ" href="llvm-diff.html" />
+ <link rel="prev" title="llvm-config - Print LLVM compilation options" href="llvm-config.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-diff.html" title="llvm-diff - LLVM structural âdiffâ"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-config.html" title="llvm-config - Print LLVM compilation options"
+ 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-cxxmap-mangled-name-remapping-tool">
+<h1>llvm-cxxmap - Mangled name remapping tool<a class="headerlink" href="#llvm-cxxmap-mangled-name-remapping-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-cxxmap</strong> [<em>options</em>] <em>symbol-file-1</em> <em>symbol-file-2</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-cxxmap</strong> tool performs fuzzy matching of C++ mangled names,
+based on a file describing name components that should be considered equivalent.</p>
+<p>The symbol files should contain a list of C++ mangled names (one per line).
+Blank lines and lines starting with <code class="docutils literal notranslate"><span class="pre">#</span></code> are ignored. The output is a list
+of pairs of equivalent symbols, one per line, of the form</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span><symbol-1> <symbol-2>
+</pre></div>
+</div>
+<p>where <code class="docutils literal notranslate"><span class="pre"><symbol-1></span></code> is a symbol from <em>symbol-file-1</em> and <code class="docutils literal notranslate"><span class="pre"><symbol-2></span></code> is
+a symbol from <em>symbol-file-2</em>. Mappings for which the two symbols are identical
+are omitted.</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-cxxmap-remapping-file">
+<code class="descname">-remapping-file</code><code class="descclassname">=file</code><code class="descclassname">, </code><code class="descname">-r</code><code class="descclassname">=file</code><a class="headerlink" href="#cmdoption-llvm-cxxmap-remapping-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a file containing a list of equivalence rules that should be used
+to determine whether two symbols are equivalent. Required.
+See <a class="reference internal" href="#remapping-file"><span class="std std-ref">REMAPPING FILE</span></a>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cxxmap-output">
+<code class="descname">-output</code><code class="descclassname">=file</code><code class="descclassname">, </code><code class="descname">-o</code><code class="descclassname">=file</code><a class="headerlink" href="#cmdoption-llvm-cxxmap-output" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a file to write the list of matched names to. If unspecified, the
+list will be written to stdout.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cxxmap-wambiguous">
+<code class="descname">-Wambiguous</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cxxmap-wambiguous" title="Permalink to this definition">¶</a></dt>
+<dd><p>Produce a warning if there are multiple equivalent (but distinct) symbols in
+<em>symbol-file-2</em>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-cxxmap-wincomplete">
+<code class="descname">-Wincomplete</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-cxxmap-wincomplete" title="Permalink to this definition">¶</a></dt>
+<dd><p>Produce a warning if <em>symbol-file-1</em> contains a symbol for which there is no
+equivalent symbol in <em>symbol-file-2</em>.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="remapping-file">
+<span id="id1"></span><h2>REMAPPING FILE<a class="headerlink" href="#remapping-file" title="Permalink to this headline">¶</a></h2>
+<p>The remapping file is a text file containing lines of the form</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>fragmentkind fragment1 fragment2
+</pre></div>
+</div>
+<p>where <code class="docutils literal notranslate"><span class="pre">fragmentkind</span></code> is one of <code class="docutils literal notranslate"><span class="pre">name</span></code>, <code class="docutils literal notranslate"><span class="pre">type</span></code>, or <code class="docutils literal notranslate"><span class="pre">encoding</span></code>,
+indicating whether the following mangled name fragments are
+<<a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.name">name</a>>s,
+<<a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.type">type</a>>s, or
+<<a class="reference external" href="http://itanium-cxx-abi.github.io/cxx-abi/abi.html#mangle.encoding">encoding</a>>s,
+respectively.
+Blank lines and lines starting with <code class="docutils literal notranslate"><span class="pre">#</span></code> are ignored.</p>
+<p>For convenience, built-in <substitution>s such as <code class="docutils literal notranslate"><span class="pre">St</span></code> and <code class="docutils literal notranslate"><span class="pre">Ss</span></code>
+are accepted as <name>s (even though they technically are not <name>s).</p>
+<p>For example, to specify that <code class="docutils literal notranslate"><span class="pre">absl::string_view</span></code> and <code class="docutils literal notranslate"><span class="pre">std::string_view</span></code>
+should be treated as equivalent, the following remapping file could be used:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># absl::string_view is considered equivalent to std::string_view
+type N4absl11string_viewE St17basic_string_viewIcSt11char_traitsIcEE
+
+# std:: might be std::__1:: in libc++ or std::__cxx11:: in libstdc++
+name St St3__1
+name St St7__cxx11
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Symbol remapping is currently only supported for C++ mangled names
+following the Itanium C++ ABI mangling scheme. This covers all C++ targets
+supported by Clang other than Windows targets.</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="llvm-diff.html" title="llvm-diff - LLVM structural âdiffâ"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-config.html" title="llvm-config - Print LLVM compilation options"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-diff.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-diff.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-diff.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-diff.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,127 @@
+
+
+<!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-diff - LLVM structural âdiffâ — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-cov - emit coverage information" href="llvm-cov.html" />
+ <link rel="prev" title="llvm-cxxmap - Mangled name remapping tool" href="llvm-cxxmap.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-cov.html" title="llvm-cov - emit coverage information"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-cxxmap.html" title="llvm-cxxmap - Mangled name remapping 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-diff-llvm-structural-diff">
+<h1>llvm-diff - LLVM structural âdiffâ<a class="headerlink" href="#llvm-diff-llvm-structural-diff" 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>llvm-diff</strong> [<em>options</em>] <em>module 1</em> <em>module 2</em> [<em>global name â¦</em>]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong>llvm-diff</strong> compares the structure of two LLVM modules, primarily
+focusing on differences in function definitions. Insignificant
+differences, such as changes in the ordering of globals or in the
+names of local values, are ignored.</p>
+<p>An input module will be interpreted as an assembly file if its name
+ends in â.llâ; otherwise it will be read in as a bitcode file.</p>
+<p>If a list of global names is given, just the values with those names
+are compared; otherwise, all global values are compared, and
+diagnostics are produced for globals which only appear in one module
+or the other.</p>
+<p><strong>llvm-diff</strong> compares two functions by comparing their basic blocks,
+beginning with the entry blocks. If the terminators seem to match,
+then the corresponding successors are compared; otherwise they are
+ignored. This algorithm is very sensitive to changes in control flow,
+which tend to stop any downstream changes from being detected.</p>
+<p><strong>llvm-diff</strong> is intended as a debugging tool for writers of LLVM
+passes and frontends. It does not have a stable output format.</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>If <strong>llvm-diff</strong> finds no differences between the modules, it will exit
+with 0 and produce no output. Otherwise it will exit with a non-zero
+value.</p>
+</div>
+<div class="section" id="bugs">
+<h2>BUGS<a class="headerlink" href="#bugs" title="Permalink to this headline">¶</a></h2>
+<p>Many important differences, like changes in linkage or function
+attributes, are not diagnosed.</p>
+<p>Changes in memory behavior (for example, coalescing loads) can cause
+massive detected differences in blocks.</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-cov.html" title="llvm-cov - emit coverage information"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-cxxmap.html" title="llvm-cxxmap - Mangled name remapping 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-dis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-dis.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-dis.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-dis.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,131 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>llvm-dis - LLVM disassembler — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="opt - LLVM optimizer" href="opt.html" />
+ <link rel="prev" title="llvm-as - LLVM assembler" href="llvm-as.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="opt.html" title="opt - LLVM optimizer"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-as.html" title="llvm-as - LLVM assembler"
+ 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-dis-llvm-disassembler">
+<h1>llvm-dis - LLVM disassembler<a class="headerlink" href="#llvm-dis-llvm-disassembler" 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>llvm-dis</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>llvm-dis</strong> command is the LLVM disassembler. It takes an LLVM
+bitcode file and converts it into human-readable LLVM assembly language.</p>
+<p>If filename is omitted or specified as <code class="docutils literal notranslate"><span class="pre">-</span></code>, <strong>llvm-dis</strong> reads its
+input from standard input.</p>
+<p>If the input is being read from standard input, then <strong>llvm-dis</strong>
+will send its output to standard output by default. Otherwise, the
+output will be written to a file named after the input file, with
+a <code class="docutils literal notranslate"><span class="pre">.ll</span></code> suffix added (any existing <code class="docutils literal notranslate"><span class="pre">.bc</span></code> suffix will first be
+removed). You can override the choice of output file using the
+<strong>-o</strong> option.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong>-f</strong></p>
+<blockquote>
+<div>Enable binary output on terminals. Normally, <strong>llvm-dis</strong> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+<strong>llvm-dis</strong> will write raw bitcode regardless of the output device.</div></blockquote>
+<p><strong>-help</strong></p>
+<blockquote>
+<div>Print a summary of command line options.</div></blockquote>
+<p><strong>-o</strong> <em>filename</em></p>
+<blockquote>
+<div>Specify the output file name. If <em>filename</em> is -, then the output is sent
+to standard output.</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>If <strong>llvm-dis</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</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>llvm-as|llvm-as</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="opt.html" title="opt - LLVM optimizer"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-as.html" title="llvm-as - LLVM assembler"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-dwarfdump.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-dwarfdump.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-dwarfdump.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-dwarfdump.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,266 @@
+
+
+<!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-dwarfdump - dump and verify DWARF debug information — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="dsymutil - manipulate archived DWARF debug symbol files" href="dsymutil.html" />
+ <link rel="prev" title="llvm-symbolizer - convert addresses into source code locations" href="llvm-symbolizer.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="dsymutil.html" title="dsymutil - manipulate archived DWARF debug symbol files"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-symbolizer.html" title="llvm-symbolizer - convert addresses into source code locations"
+ 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-dwarfdump-dump-and-verify-dwarf-debug-information">
+<h1>llvm-dwarfdump - dump and verify DWARF debug information<a class="headerlink" href="#llvm-dwarfdump-dump-and-verify-dwarf-debug-information" 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-dwarfdump</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">llvm-dwarfdump</strong> parses DWARF sections in object files,
+archives, and <cite>.dSYM</cite> bundles and prints their contents in
+human-readable form. Only the .debug_info section is printed unless one of
+the section-specific options or <a class="reference internal" href="#cmdoption-a"><code class="xref std std-option docutils literal notranslate"><span class="pre">--all</span></code></a> is specified.</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-a">
+<code class="descname">-a</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--all</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-a" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disassemble all supported DWARF sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-arch">
+<code class="descname">--arch</code><code class="descclassname">=<arch></code><a class="headerlink" href="#cmdoption-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump DWARF debug information for the specified CPU architecture.
+Architectures may be specified by name or by number. This
+option can be specified multiple times, once for each desired
+architecture. All CPU architectures will be printed by
+default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-c">
+<code class="descname">-c</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--show-children</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-c" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show a debug info entryâs children when using
+the <a class="reference internal" href="#cmdoption-debug-abbrev"><code class="xref std std-option docutils literal notranslate"><span class="pre">--debug-info</span></code></a>, <a class="reference internal" href="#cmdoption-f"><code class="xref std std-option docutils literal notranslate"><span class="pre">--find</span></code></a>,
+and <a class="reference internal" href="#cmdoption-n"><code class="xref std std-option docutils literal notranslate"><span class="pre">--name</span></code></a> options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-f">
+<code class="descname">-f</code><code class="descclassname"> <name></code><code class="descclassname">, </code><code class="descname">--find</code><code class="descclassname">=<name></code><a class="headerlink" href="#cmdoption-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Search for the exact text <name> in the accelerator tables
+and print the matching debug information entries.
+When there is no accelerator tables or the name of the DIE
+you are looking for is not found in the accelerator tables,
+try using the slower but more complete <a class="reference internal" href="#cmdoption-n"><code class="xref std std-option docutils literal notranslate"><span class="pre">--name</span></code></a> option.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-show-form">
+<code class="descname">-F</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--show-form</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-show-form" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show DWARF form types after the DWARF attribute types.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-h">
+<code class="descname">-h</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-h" 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-i">
+<code class="descname">-i</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--ignore-case</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-i" title="Permalink to this definition">¶</a></dt>
+<dd><p>Ignore case distinctions in when searching entries by name
+or by regular expression.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-n">
+<code class="descname">-n</code><code class="descclassname"> <pattern></code><code class="descclassname">, </code><code class="descname">--name</code><code class="descclassname">=<pattern></code><a class="headerlink" href="#cmdoption-n" title="Permalink to this definition">¶</a></dt>
+<dd><p>Find and print all debug info entries whose name
+(<cite>DW_AT_name</cite> attribute) matches the exact text in
+<pattern>. Use the <a class="reference internal" href="#cmdoption-x"><code class="xref std std-option docutils literal notranslate"><span class="pre">--regex</span></code></a> option to have
+<pattern> become a regular expression for more flexible
+pattern matching.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-lookup">
+<code class="descname">--lookup</code><code class="descclassname">=<address></code><a class="headerlink" href="#cmdoption-lookup" title="Permalink to this definition">¶</a></dt>
+<dd><p>Lookup <address> in the debug information and print out the file,
+function, block, and line table details.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-o">
+<code class="descname">-o</code><code class="descclassname"> <path></code><code class="descclassname">, </code><code class="descname">--out-file</code><code class="descclassname">=<path></code><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Redirect output to a file specified by <path>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-p">
+<code class="descname">-p</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--show-parents</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-p" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show a debug info entryâs parent objects when using the
+<a class="reference internal" href="#cmdoption-debug-abbrev"><code class="xref std std-option docutils literal notranslate"><span class="pre">--debug-info</span></code></a>, <a class="reference internal" href="#cmdoption-f"><code class="xref std std-option docutils literal notranslate"><span class="pre">--find</span></code></a>, and
+<a class="reference internal" href="#cmdoption-n"><code class="xref std std-option docutils literal notranslate"><span class="pre">--name</span></code></a> options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-r">
+<code class="descname">-r</code><code class="descclassname"> <n></code><code class="descclassname">, </code><code class="descname">--recurse-depth</code><code class="descclassname">=<n></code><a class="headerlink" href="#cmdoption-r" title="Permalink to this definition">¶</a></dt>
+<dd><p>Only recurse to a maximum depth of <n> when dumping debug info
+entries.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-statistics">
+<code class="descname">--statistics</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-statistics" title="Permalink to this definition">¶</a></dt>
+<dd><p>Collect debug info quality metrics and print the results
+as machine-readable single-line JSON output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-x">
+<code class="descname">-x</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--regex</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-x" title="Permalink to this definition">¶</a></dt>
+<dd><p>Treat any <pattern> strings as regular expressions when searching
+instead of just as an exact string match.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-u">
+<code class="descname">-u</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--uuid</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-u" title="Permalink to this definition">¶</a></dt>
+<dd><p>Show the UUID for each architecture.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-diff">
+<code class="descname">--diff</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-diff" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the output in a format that is more friendly for comparing
+DWARF output from two different files.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-v">
+<code class="descname">-v</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--verbose</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-v" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display verbose information when dumping. This can help to debug
+DWARF issues.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-verify">
+<code class="descname">--verify</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-verify" title="Permalink to this definition">¶</a></dt>
+<dd><p>Verify the structure of the DWARF information by verifying the
+compile unit chains, DIE relationships graph, address
+ranges, and more.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-version">
+<code class="descname">--version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of the tool.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-debug-abbrev">
+<code class="descname">--debug-abbrev</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-aranges</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-cu-index</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-frame</code><code class="descclassname"> [=<offset>]</code><code class="descclassname">, </code><code class="descname">--debug-gnu-pubnames</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-gnu-pubtypes</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-info</code><code class="descclassname"> [=<offset>]</code><code class="descclassname">, </code><code class="descname">--debug-line</code><code class="descclassname"> [=<offset>]</code><code class="descclassname">, </code><code class="descname">--debug-loc</code><code class="descclassname"> [=<offset>]</code><code class="descclassname">, </code><code class="descname">--debug-macro</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-pubnames</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-pubtypes</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-ranges</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-str</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-str-offsets</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-tu-index</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--debug-types</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--eh-frame</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--gdb-index</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--apple-names</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--apple-types</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--apple-namespaces</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">--apple-objc</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-debug-abbrev" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dump the specified DWARF section by name. Only the
+<cite>.debug_info</cite> section is shown by default. Some entries
+support adding an <cite>=<offset></cite> as a way to provide an
+optional offset of the exact entry to dump within the
+respective section. When an offset is provided, only the
+entry at that offset will be dumped, else the entire
+section will be dumped. Children of items at a specific
+offset can be dumped by also using the
+<a class="reference internal" href="#cmdoption-c"><code class="xref std std-option docutils literal notranslate"><span class="pre">--show-children</span></code></a> option where applicable.</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-dwarfdump</strong> returns 0 if the input files were parsed and dumped
+successfully. Otherwise, it returns 1.</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/dsymutil.html">dsymutil(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="dsymutil.html" title="dsymutil - manipulate archived DWARF debug symbol files"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-symbolizer.html" title="llvm-symbolizer - convert addresses into source code locations"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-exegesis.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-exegesis.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-exegesis.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-exegesis.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,320 @@
+
+
+<!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-exegesis - LLVM Machine Instruction Benchmark — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-pdbutil - PDB File forensics and diagnostics" href="llvm-pdbutil.html" />
+ <link rel="prev" title="llvm-build - LLVM Project Build Utility" href="llvm-build.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-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-build.html" title="llvm-build - LLVM Project Build Utility"
+ 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-exegesis-llvm-machine-instruction-benchmark">
+<h1>llvm-exegesis - LLVM Machine Instruction Benchmark<a class="headerlink" href="#llvm-exegesis-llvm-machine-instruction-benchmark" 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-exegesis</strong> [<em>options</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-exegesis</strong> is a benchmarking tool that uses information available
+in LLVM to measure host machine instruction characteristics like latency or port
+decomposition.</p>
+<p>Given an LLVM opcode name and a benchmarking mode, <strong class="program">llvm-exegesis</strong>
+generates a code snippet that makes execution as serial (resp. as parallel) as
+possible so that we can measure the latency (resp. uop decomposition) of the
+instruction.
+The code snippet is jitted and executed on the host subtarget. The time taken
+(resp. resource usage) is measured using hardware performance counters. The
+result is printed out as YAML to the standard output.</p>
+<p>The main goal of this tool is to automatically (in)validate the LLVMâs TableDef
+scheduling models. To that end, we also provide analysis of the results.</p>
+<p><strong class="program">llvm-exegesis</strong> can also benchmark arbitrary user-provided code
+snippets.</p>
+</div>
+<div class="section" id="example-1-benchmarking-instructions">
+<h2>EXAMPLE 1: benchmarking instructions<a class="headerlink" href="#example-1-benchmarking-instructions" title="Permalink to this headline">¶</a></h2>
+<p>Assume you have an X86-64 machine. To measure the latency of a single
+instruction, run:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llvm-exegesis -mode<span class="o">=</span>latency -opcode-name<span class="o">=</span>ADD64rr
+</pre></div>
+</div>
+<p>Measuring the uop decomposition of an instruction works similarly:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llvm-exegesis -mode<span class="o">=</span>uops -opcode-name<span class="o">=</span>ADD64rr
+</pre></div>
+</div>
+<p>The output is a YAML document (the default is to write to stdout, but you can
+redirect the output to a file using <cite>-benchmarks-file</cite>):</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>---
+key:
+ opcode_name: ADD64rr
+ mode: latency
+ config: ''
+cpu_name: haswell
+llvm_triple: x86_64-unknown-linux-gnu
+num_repetitions: 10000
+measurements:
+ - { key: latency, value: 1.0058, debug_string: '' }
+error: ''
+info: 'explicit self cycles, selecting one aliasing configuration.
+Snippet:
+ADD64rr R8, R8, R10
+'
+...
+</pre></div>
+</div>
+<p>To measure the latency of all instructions for the host architecture, run:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="ch">#!/bin/bash</span>
+<span class="nb">readonly</span> <span class="nv">INSTRUCTIONS</span><span class="o">=</span><span class="k">$(($(</span>grep INSTRUCTION_LIST_END build/lib/Target/X86/X86GenInstrInfo.inc <span class="p">|</span> cut -f2 -d<span class="o">=</span><span class="k">)</span> <span class="o">-</span> <span class="m">1</span><span class="k">))</span>
+<span class="k">for</span> INSTRUCTION in <span class="k">$(</span>seq <span class="m">1</span> <span class="si">${</span><span class="nv">INSTRUCTIONS</span><span class="si">}</span><span class="k">)</span><span class="p">;</span>
+<span class="k">do</span>
+ ./build/bin/llvm-exegesis -mode<span class="o">=</span>latency -opcode-index<span class="o">=</span><span class="si">${</span><span class="nv">INSTRUCTION</span><span class="si">}</span> <span class="p">|</span> sed -n <span class="s1">'/---/,$p'</span>
+<span class="k">done</span>
+</pre></div>
+</div>
+<p>FIXME: Provide an <strong class="program">llvm-exegesis</strong> option to test all instructions.</p>
+</div>
+<div class="section" id="example-2-benchmarking-a-custom-code-snippet">
+<h2>EXAMPLE 2: benchmarking a custom code snippet<a class="headerlink" href="#example-2-benchmarking-a-custom-code-snippet" title="Permalink to this headline">¶</a></h2>
+<p>To measure the latency/uops of a custom piece of code, you can specify the
+<cite>snippets-file</cite> option (<cite>-</cite> reads from standard input).</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">echo</span> <span class="s2">"vzeroupper"</span> <span class="p">|</span> llvm-exegesis -mode<span class="o">=</span>uops -snippets-file<span class="o">=</span>-
+</pre></div>
+</div>
+<p>Real-life code snippets typically depend on registers or memory.
+<strong class="program">llvm-exegesis</strong> checks the liveliness of registers (i.e. any register
+use has a corresponding def or is a âlive inâ). If your code depends on the
+value of some registers, you have two options:</p>
+<ul class="simple">
+<li>Mark the register as requiring a definition. <strong class="program">llvm-exegesis</strong> will
+automatically assign a value to the register. This can be done using the
+directive <cite>LLVM-EXEGESIS-DEFREG <reg name> <hex_value></cite>, where <cite><hex_value></cite>
+is a bit pattern used to fill <cite><reg_name></cite>. If <cite><hex_value></cite> is smaller than
+the register width, it will be sign-extended.</li>
+<li>Mark the register as a âlive inâ. <strong class="program">llvm-exegesis</strong> will benchmark
+using whatever value was in this registers on entry. This can be done using
+the directive <cite>LLVM-EXEGESIS-LIVEIN <reg name></cite>.</li>
+</ul>
+<p>For example, the following code snippet depends on the values of XMM1 (which
+will be set by the tool) and the memory buffer passed in RDI (live in).</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># LLVM-EXEGESIS-LIVEIN RDI
+# LLVM-EXEGESIS-DEFREG XMM1 42
+vmulps (%rdi), %xmm1, %xmm2
+vhaddps %xmm2, %xmm2, %xmm3
+addq $0x10, %rdi
+</pre></div>
+</div>
+</div>
+<div class="section" id="example-3-analysis">
+<h2>EXAMPLE 3: analysis<a class="headerlink" href="#example-3-analysis" title="Permalink to this headline">¶</a></h2>
+<p>Assuming you have a set of benchmarked instructions (either latency or uops) as
+YAML in file <cite>/tmp/benchmarks.yaml</cite>, you can analyze the results using the
+following command:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span> $ llvm-exegesis -mode<span class="o">=</span>analysis <span class="se">\</span>
+-benchmarks-file<span class="o">=</span>/tmp/benchmarks.yaml <span class="se">\</span>
+-analysis-clusters-output-file<span class="o">=</span>/tmp/clusters.csv <span class="se">\</span>
+-analysis-inconsistencies-output-file<span class="o">=</span>/tmp/inconsistencies.html
+</pre></div>
+</div>
+<p>This will group the instructions into clusters with the same performance
+characteristics. The clusters will be written out to <cite>/tmp/clusters.csv</cite> in the
+following format:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>cluster_id,opcode_name,config,sched_class
+...
+2,ADD32ri8_DB,,WriteALU,1.00
+2,ADD32ri_DB,,WriteALU,1.01
+2,ADD32rr,,WriteALU,1.01
+2,ADD32rr_DB,,WriteALU,1.00
+2,ADD32rr_REV,,WriteALU,1.00
+2,ADD64i32,,WriteALU,1.01
+2,ADD64ri32,,WriteALU,1.01
+2,MOVSX64rr32,,BSWAP32r_BSWAP64r_MOVSX64rr32,1.00
+2,VPADDQYrr,,VPADDBYrr_VPADDDYrr_VPADDQYrr_VPADDWYrr_VPSUBBYrr_VPSUBDYrr_VPSUBQYrr_VPSUBWYrr,1.02
+2,VPSUBQYrr,,VPADDBYrr_VPADDDYrr_VPADDQYrr_VPADDWYrr_VPSUBBYrr_VPSUBDYrr_VPSUBQYrr_VPSUBWYrr,1.01
+2,ADD64ri8,,WriteALU,1.00
+2,SETBr,,WriteSETCC,1.01
+...
+</pre></div>
+</div>
+<p><strong class="program">llvm-exegesis</strong> will also analyze the clusters to point out
+inconsistencies in the scheduling information. The output is an html file. For
+example, <cite>/tmp/inconsistencies.html</cite> will contain messages like the following :</p>
+<img alt="../_images/llvm-exegesis-analysis.png" class="align-center" src="../_images/llvm-exegesis-analysis.png" />
+<p>Note that the scheduling class names will be resolved only when
+<strong class="program">llvm-exegesis</strong> is compiled in debug mode, else only the class id will
+be shown. This does not invalidate any of the analysis results though.</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-help">
+<code class="descname">-help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-opcode-index">
+<code class="descname">-opcode-index</code><code class="descclassname">=<LLVM opcode index></code><a class="headerlink" href="#cmdoption-opcode-index" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the opcode to measure, by index. See example 1 for details.
+Either <cite>opcode-index</cite>, <cite>opcode-name</cite> or <cite>snippets-file</cite> must be set.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-opcode-name">
+<code class="descname">-opcode-name</code><code class="descclassname">=<opcode name 1>,<opcode name 2>,...</code><a class="headerlink" href="#cmdoption-opcode-name" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the opcode to measure, by name. Several opcodes can be specified as
+a comma-separated list. See example 1 for details.
+Either <cite>opcode-index</cite>, <cite>opcode-name</cite> or <cite>snippets-file</cite> must be set.</p>
+<dl class="option">
+<dt id="cmdoption-snippets-file">
+<code class="descname">-snippets-file</code><code class="descclassname">=<filename></code><a class="headerlink" href="#cmdoption-snippets-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the custom code snippet to measure. See example 2 for details.
+Either <cite>opcode-index</cite>, <cite>opcode-name</cite> or <cite>snippets-file</cite> must be set.</p>
+</dd></dl>
+
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mode">
+<code class="descname">-mode</code><code class="descclassname">=[latency|uops|analysis]</code><a class="headerlink" href="#cmdoption-mode" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the run mode.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-num-repetitions">
+<code class="descname">-num-repetitions</code><code class="descclassname">=<Number of repetition></code><a class="headerlink" href="#cmdoption-num-repetitions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the number of repetitions of the asm snippet.
+Higher values lead to more accurate measurements but lengthen the benchmark.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-benchmarks-file">
+<code class="descname">-benchmarks-file</code><code class="descclassname">=</path/to/file></code><a class="headerlink" href="#cmdoption-benchmarks-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>File to read (<cite>analysis</cite> mode) or write (<cite>latency</cite>/<cite>uops</cite> modes) benchmark
+results. â-â uses stdin/stdout.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-analysis-clusters-output-file">
+<code class="descname">-analysis-clusters-output-file</code><code class="descclassname">=</path/to/file></code><a class="headerlink" href="#cmdoption-analysis-clusters-output-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>If provided, write the analysis clusters as CSV to this file. â-â prints to
+stdout.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-analysis-inconsistencies-output-file">
+<code class="descname">-analysis-inconsistencies-output-file</code><code class="descclassname">=</path/to/file></code><a class="headerlink" href="#cmdoption-analysis-inconsistencies-output-file" title="Permalink to this definition">¶</a></dt>
+<dd><p>If non-empty, write inconsistencies found during analysis to this file. <cite>-</cite>
+prints to stdout.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-analysis-numpoints">
+<code class="descname">-analysis-numpoints</code><code class="descclassname">=<dbscan numPoints parameter></code><a class="headerlink" href="#cmdoption-analysis-numpoints" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the numPoints parameters to be used for DBSCAN clustering
+(<cite>analysis</cite> mode).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-analysis-espilon">
+<code class="descname">-analysis-espilon</code><code class="descclassname">=<dbscan epsilon parameter></code><a class="headerlink" href="#cmdoption-analysis-espilon" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the numPoints parameters to be used for DBSCAN clustering
+(<cite>analysis</cite> mode).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-ignore-invalid-sched-class">
+<code class="descname">-ignore-invalid-sched-class</code><code class="descclassname">=false</code><a class="headerlink" href="#cmdoption-ignore-invalid-sched-class" title="Permalink to this definition">¶</a></dt>
+<dd><p>If set, ignore instructions that do not have a sched class (class idx = 0).</p>
+<dl class="option">
+<dt id="cmdoption-mcpu">
+<code class="descname">-mcpu</code><code class="descclassname">=<cpu name></code><a class="headerlink" href="#cmdoption-mcpu" title="Permalink to this definition">¶</a></dt>
+<dd><p>If set, measure the cpu characteristics using the counters for this CPU. This
+is useful when creating new sched models (the host CPU is unknown to LLVM).</p>
+</dd></dl>
+
+</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-exegesis</strong> returns 0 on success. Otherwise, an error message is
+printed to standard error, and the tool returns a non 0 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="llvm-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-build.html" title="llvm-build - LLVM Project Build Utility"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-extract.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-extract.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-extract.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-extract.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,152 @@
+
+
+<!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-extract - extract a function from an LLVM module — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-bcanalyzer - LLVM bitcode analyzer" href="llvm-bcanalyzer.html" />
+ <link rel="prev" title="bugpoint - automatic test case reduction tool" href="bugpoint.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-bcanalyzer.html" title="llvm-bcanalyzer - LLVM bitcode analyzer"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="bugpoint.html" title="bugpoint - automatic test case reduction 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-extract-extract-a-function-from-an-llvm-module">
+<h1>llvm-extract - extract a function from an LLVM module<a class="headerlink" href="#llvm-extract-extract-a-function-from-an-llvm-module" 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-extract</strong> [<em>options</em>] <strong>âfunc</strong> <em>function-name</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">llvm-extract</strong> command takes the name of a function and extracts
+it from the specified LLVM bitcode file. It is primarily used as a debugging
+tool to reduce test cases from larger programs that are triggering a bug.</p>
+<p>In addition to extracting the bitcode of the specified function,
+<strong class="program">llvm-extract</strong> will also remove unreachable global variables,
+prototypes, and unused types.</p>
+<p>The <strong class="program">llvm-extract</strong> command reads its input from standard input if
+filename is omitted or if filename is <code class="docutils literal notranslate"><span class="pre">-</span></code>. The output is always written to
+standard output, unless the <strong>-o</strong> option is specified (see below).</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p><strong>-f</strong></p>
+<blockquote>
+<div>Enable binary output on terminals. Normally, <strong class="program">llvm-extract</strong> will
+refuse to write raw bitcode output if the output stream is a terminal. With
+this option, <strong class="program">llvm-extract</strong> will write raw bitcode regardless of the
+output device.</div></blockquote>
+<p><strong>âfunc</strong> <em>function-name</em></p>
+<blockquote>
+<div>Extract the function named <em>function-name</em> from the LLVM bitcode. May be
+specified multiple times to extract multiple functions at once.</div></blockquote>
+<p><strong>ârfunc</strong> <em>function-regular-expr</em></p>
+<blockquote>
+<div>Extract the function(s) matching <em>function-regular-expr</em> from the LLVM bitcode.
+All functions matching the regular expression will be extracted. May be
+specified multiple times.</div></blockquote>
+<p><strong>âglob</strong> <em>global-name</em></p>
+<blockquote>
+<div>Extract the global variable named <em>global-name</em> from the LLVM bitcode. May be
+specified multiple times to extract multiple global variables at once.</div></blockquote>
+<p><strong>ârglob</strong> <em>glob-regular-expr</em></p>
+<blockquote>
+<div>Extract the global variable(s) matching <em>global-regular-expr</em> from the LLVM
+bitcode. All global variables matching the regular expression will be
+extracted. May be specified multiple times.</div></blockquote>
+<p><strong>-help</strong></p>
+<blockquote>
+<div>Print a summary of command line options.</div></blockquote>
+<p><strong>-o</strong> <em>filename</em></p>
+<blockquote>
+<div>Specify the output filename. If filename is â-â (the default), then
+<strong class="program">llvm-extract</strong> sends its output to standard output.</div></blockquote>
+<p><strong>-S</strong></p>
+<blockquote>
+<div>Write output in LLVM intermediate language (instead of bitcode).</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>If <strong class="program">llvm-extract</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</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>bugpoint</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-bcanalyzer.html" title="llvm-bcanalyzer - LLVM bitcode analyzer"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="bugpoint.html" title="bugpoint - automatic test case reduction 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-lib.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-lib.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-lib.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-lib.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,112 @@
+
+
+<!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-lib - LLVM lib.exe compatible library tool — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-nm - list LLVM bitcode and object fileâs symbol table" href="llvm-nm.html" />
+ <link rel="prev" title="llvm-ar - LLVM archiver" href="llvm-ar.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-nm.html" title="llvm-nm - list LLVM bitcode and object fileâs symbol table"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-ar.html" title="llvm-ar - LLVM archiver"
+ 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-lib-llvm-lib-exe-compatible-library-tool">
+<h1>llvm-lib - LLVM lib.exe compatible library tool<a class="headerlink" href="#llvm-lib-llvm-lib-exe-compatible-library-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>llvm-lib</strong> [/libpath:<path>] [/out:<output>] [/llvmlibthin]
+[/ignore] [/machine] [/nologo] [filesâ¦]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p>The <strong>llvm-lib</strong> command is intended to be a <code class="docutils literal notranslate"><span class="pre">lib.exe</span></code> compatible
+tool. See <a class="reference external" href="https://msdn.microsoft.com/en-us/library/7ykb2k5f">https://msdn.microsoft.com/en-us/library/7ykb2k5f</a> for the
+general description.</p>
+<p><strong>llvm-lib</strong> has the following extensions:</p>
+<ul class="simple">
+<li>Bitcode files in symbol tables.
+<strong>llvm-lib</strong> includes symbols from both bitcode files and regular
+object files in the symbol table.</li>
+<li>Creating thin archives.
+The /llvmlibthin option causes <strong>llvm-lib</strong> to create thin archive
+that contain only the symbol table and the header for the various
+members. These files are much smaller, but are not compatible with
+link.exe (lld can handle them).</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="llvm-nm.html" title="llvm-nm - list LLVM bitcode and object fileâs symbol table"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-ar.html" title="llvm-ar - LLVM archiver"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-link.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-link.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-link.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-link.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,151 @@
+
+
+<!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-link - LLVM bitcode linker — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-ar - LLVM archiver" href="llvm-ar.html" />
+ <link rel="prev" title="lli - directly execute programs from LLVM bitcode" href="lli.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-ar.html" title="llvm-ar - LLVM archiver"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="lli.html" title="lli - directly execute programs from LLVM bitcode"
+ 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-link-llvm-bitcode-linker">
+<h1>llvm-link - LLVM bitcode linker<a class="headerlink" href="#llvm-link-llvm-bitcode-linker" 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-link</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">llvm-link</strong> takes several LLVM bitcode files and links them together
+into a single LLVM bitcode file. It writes the output file to standard output,
+unless the <a class="reference internal" href="opt.html#cmdoption-o"><code class="xref std std-option docutils literal notranslate"><span class="pre">-o</span></code></a> option is used to specify a filename.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-f">
+<code class="descname">-f</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable binary output on terminals. Normally, <strong class="program">llvm-link</strong> will refuse
+to write raw bitcode output if the output stream is a terminal. With this
+option, <strong class="program">llvm-link</strong> will write raw bitcode regardless of the output
+device.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-o">
+<code class="descname">-o</code><code class="descclassname"> filename</code><a class="headerlink" href="#cmdoption-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">llvm-link</strong> will write its output to standard output.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-s">
+<code class="descname">-S</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-s" title="Permalink to this definition">¶</a></dt>
+<dd><p>Write output in LLVM intermediate language (instead of bitcode).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-d">
+<code class="descname">-d</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-d" title="Permalink to this definition">¶</a></dt>
+<dd><p>If specified, <strong class="program">llvm-link</strong> prints a human-readable version of the
+output bitcode file to standard error.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-help">
+<code class="descname">-help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-v">
+<code class="descname">-v</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-v" title="Permalink to this definition">¶</a></dt>
+<dd><p>Verbose mode. Print information about what <strong class="program">llvm-link</strong> is doing.
+This typically includes a message for each bitcode file linked in and for each
+library found.</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">llvm-link</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="llvm-ar.html" title="llvm-ar - LLVM archiver"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="lli.html" title="lli - directly execute programs from LLVM bitcode"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-mca.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-mca.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-mca.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-mca.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,833 @@
+
+
+<!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-mca - LLVM Machine Code Analyzer — LLVM 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="bugpoint - automatic test case reduction tool" href="bugpoint.html" />
+ <link rel="prev" title="dsymutil - manipulate archived DWARF debug symbol files" href="dsymutil.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="dsymutil.html" title="dsymutil - manipulate archived DWARF debug symbol 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-mca-llvm-machine-code-analyzer">
+<h1>llvm-mca - LLVM Machine Code Analyzer<a class="headerlink" href="#llvm-mca-llvm-machine-code-analyzer" 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-mca</strong> [<em>options</em>] [input]</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-mca</strong> is a performance analysis tool that uses information
+available in LLVM (e.g. scheduling models) to statically measure the performance
+of machine code in a specific CPU.</p>
+<p>Performance is measured in terms of throughput as well as processor resource
+consumption. The tool currently works for processors with an out-of-order
+backend, for which there is a scheduling model available in LLVM.</p>
+<p>The main goal of this tool is not just to predict the performance of the code
+when run on the target, but also help with diagnosing potential performance
+issues.</p>
+<p>Given an assembly code sequence, <strong class="program">llvm-mca</strong> estimates the Instructions
+Per Cycle (IPC), as well as hardware resource pressure. The analysis and
+reporting style were inspired by the IACA tool from Intel.</p>
+<p>For example, you can compile code with clang, output assembly, and pipe it
+directly into <strong class="program">llvm-mca</strong> for analysis:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang foo.c -O2 -target x86_64-unknown-unknown -S -o - <span class="p">|</span> llvm-mca -mcpu<span class="o">=</span>btver2
+</pre></div>
+</div>
+<p>Or for Intel syntax:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ clang foo.c -O2 -target x86_64-unknown-unknown -mllvm -x86-asm-syntax<span class="o">=</span>intel -S -o - <span class="p">|</span> llvm-mca -mcpu<span class="o">=</span>btver2
+</pre></div>
+</div>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<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-mca</strong> reads from standard
+input. Otherwise, it will read from the specified filename.</p>
+<p>If the <a class="reference internal" href="opt.html#cmdoption-o"><code class="xref std std-option docutils literal notranslate"><span class="pre">-o</span></code></a> option is omitted, then <strong class="program">llvm-mca</strong> will send its output
+to standard output if the input is from standard input. If the <a class="reference internal" href="opt.html#cmdoption-o"><code class="xref std std-option docutils literal notranslate"><span class="pre">-o</span></code></a>
+option specifies â<code class="docutils literal notranslate"><span class="pre">-</span></code>â, then the output will also be sent to standard output.</p>
+<dl class="option">
+<dt id="cmdoption-help">
+<code class="descname">-help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mtriple">
+<code class="descname">-mtriple</code><code class="descclassname">=<target triple></code><a class="headerlink" href="#cmdoption-mtriple" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a target triple string.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-march">
+<code class="descname">-march</code><code class="descclassname">=<arch></code><a class="headerlink" href="#cmdoption-march" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the architecture for which to analyze the code. It defaults to the
+host default target.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mcpu">
+<code class="descname">-mcpu</code><code class="descclassname">=<cpuname></code><a class="headerlink" href="#cmdoption-mcpu" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the processor for which to analyze the code. By default, the cpu name
+is autodetected from the host.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-output-asm-variant">
+<code class="descname">-output-asm-variant</code><code class="descclassname">=<variant id></code><a class="headerlink" href="#cmdoption-output-asm-variant" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output assembly variant for the report generated by the tool.
+On x86, possible values are [0, 1]. A value of 0 (vic. 1) for this flag enables
+the AT&T (vic. Intel) assembly format for the code printed out by the tool in
+the analysis report.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dispatch">
+<code class="descname">-dispatch</code><code class="descclassname">=<width></code><a class="headerlink" href="#cmdoption-dispatch" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify a different dispatch width for the processor. The dispatch width
+defaults to field âIssueWidthâ in the processor scheduling model. If width is
+zero, then the default dispatch width is used.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-register-file-size">
+<code class="descname">-register-file-size</code><code class="descclassname">=<size></code><a class="headerlink" href="#cmdoption-register-file-size" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the size of the register file. When specified, this flag limits how
+many physical registers are available for register renaming purposes. A value
+of zero for this flag means âunlimited number of physical registersâ.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-iterations">
+<code class="descname">-iterations</code><code class="descclassname">=<number of iterations></code><a class="headerlink" href="#cmdoption-iterations" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the number of iterations to run. If this flag is set to 0, then the
+tool sets the number of iterations to a default value (i.e. 100).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-noalias">
+<code class="descname">-noalias</code><code class="descclassname">=<bool></code><a class="headerlink" href="#cmdoption-noalias" title="Permalink to this definition">¶</a></dt>
+<dd><p>If set, the tool assumes that loads and stores donât alias. This is the
+default behavior.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-lqueue">
+<code class="descname">-lqueue</code><code class="descclassname">=<load queue size></code><a class="headerlink" href="#cmdoption-lqueue" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the size of the load queue in the load/store unit emulated by the tool.
+By default, the tool assumes an unbound number of entries in the load queue.
+A value of zero for this flag is ignored, and the default load queue size is
+used instead.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-squeue">
+<code class="descname">-squeue</code><code class="descclassname">=<store queue size></code><a class="headerlink" href="#cmdoption-squeue" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the size of the store queue in the load/store unit emulated by the
+tool. By default, the tool assumes an unbound number of entries in the store
+queue. A value of zero for this flag is ignored, and the default store queue
+size is used instead.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-timeline">
+<code class="descname">-timeline</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-timeline" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable the timeline view.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-timeline-max-iterations">
+<code class="descname">-timeline-max-iterations</code><code class="descclassname">=<iterations></code><a class="headerlink" href="#cmdoption-timeline-max-iterations" title="Permalink to this definition">¶</a></dt>
+<dd><p>Limit the number of iterations to print in the timeline view. By default, the
+timeline view prints information for up to 10 iterations.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-timeline-max-cycles">
+<code class="descname">-timeline-max-cycles</code><code class="descclassname">=<cycles></code><a class="headerlink" href="#cmdoption-timeline-max-cycles" title="Permalink to this definition">¶</a></dt>
+<dd><p>Limit the number of cycles in the timeline view. By default, the number of
+cycles is set to 80.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-resource-pressure">
+<code class="descname">-resource-pressure</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-resource-pressure" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable the resource pressure view. This is enabled by default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-register-file-stats">
+<code class="descname">-register-file-stats</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-register-file-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable register file usage statistics.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dispatch-stats">
+<code class="descname">-dispatch-stats</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-dispatch-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable extra dispatch statistics. This view collects and analyzes instruction
+dispatch events, as well as static/dynamic dispatch stall events. This view
+is disabled by default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-scheduler-stats">
+<code class="descname">-scheduler-stats</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-scheduler-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable extra scheduler statistics. This view collects and analyzes instruction
+issue events. This view is disabled by default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-retire-stats">
+<code class="descname">-retire-stats</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-retire-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable extra retire control unit statistics. This view is disabled by default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-instruction-info">
+<code class="descname">-instruction-info</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-instruction-info" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable the instruction info view. This is enabled by default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-all-stats">
+<code class="descname">-all-stats</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-all-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print all hardware statistics. This enables extra statistics related to the
+dispatch logic, the hardware schedulers, the register file(s), and the retire
+control unit. This option is disabled by default.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-all-views">
+<code class="descname">-all-views</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-all-views" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable all the view.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-instruction-tables">
+<code class="descname">-instruction-tables</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-instruction-tables" title="Permalink to this definition">¶</a></dt>
+<dd><p>Prints resource pressure information based on the static information
+available from the processor model. This differs from the resource pressure
+view because it doesnât require that the code is simulated. It instead prints
+the theoretical uniform distribution of resource pressure for every
+instruction in sequence.</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-mca</strong> returns 0 on success. Otherwise, an error message is printed
+to standard error, and the tool returns 1.</p>
+</div>
+<div class="section" id="using-markers-to-analyze-specific-code-blocks">
+<h2>USING MARKERS TO ANALYZE SPECIFIC CODE BLOCKS<a class="headerlink" href="#using-markers-to-analyze-specific-code-blocks" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-mca</strong> allows for the optional usage of special code comments to
+mark regions of the assembly code to be analyzed. A comment starting with
+substring <code class="docutils literal notranslate"><span class="pre">LLVM-MCA-BEGIN</span></code> marks the beginning of a code region. A comment
+starting with substring <code class="docutils literal notranslate"><span class="pre">LLVM-MCA-END</span></code> marks the end of a code region. For
+example:</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># LLVM-MCA-BEGIN My Code Region
+ ...
+# LLVM-MCA-END
+</pre></div>
+</div>
+<p>Multiple regions can be specified provided that they do not overlap. A code
+region can have an optional description. If no user-defined region is specified,
+then <strong class="program">llvm-mca</strong> assumes a default region which contains every
+instruction in the input file. Every region is analyzed in isolation, and the
+final performance report is the union of all the reports generated for every
+code region.</p>
+<p>Inline assembly directives may be used from source code to annotate the
+assembly text:</p>
+<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">int</span> <span class="nf">foo</span><span class="p">(</span><span class="kt">int</span> <span class="n">a</span><span class="p">,</span> <span class="kt">int</span> <span class="n">b</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kr">__asm</span> <span class="k">volatile</span><span class="p">(</span><span class="s">"# LLVM-MCA-BEGIN foo"</span><span class="p">);</span>
+ <span class="n">a</span> <span class="o">+=</span> <span class="mi">42</span><span class="p">;</span>
+ <span class="kr">__asm</span> <span class="k">volatile</span><span class="p">(</span><span class="s">"# LLVM-MCA-END"</span><span class="p">);</span>
+ <span class="n">a</span> <span class="o">*=</span> <span class="n">b</span><span class="p">;</span>
+ <span class="k">return</span> <span class="n">a</span><span class="p">;</span>
+<span class="p">}</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="how-llvm-mca-works">
+<h2>HOW LLVM-MCA WORKS<a class="headerlink" href="#how-llvm-mca-works" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-mca</strong> takes assembly code as input. The assembly code is parsed
+into a sequence of MCInst with the help of the existing LLVM target assembly
+parsers. The parsed sequence of MCInst is then analyzed by a <code class="docutils literal notranslate"><span class="pre">Pipeline</span></code> module
+to generate a performance report.</p>
+<p>The Pipeline module simulates the execution of the machine code sequence in a
+loop of iterations (default is 100). During this process, the pipeline collects
+a number of execution related statistics. At the end of this process, the
+pipeline generates and prints a report from the collected statistics.</p>
+<p>Here is an example of a performance report generated by the tool for a
+dot-product of two packed float vectors of four elements. The analysis is
+conducted for target x86, cpu btver2. The following result can be produced via
+the following command using the example located at
+<code class="docutils literal notranslate"><span class="pre">test/tools/llvm-mca/X86/BtVer2/dot-product.s</span></code>:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llvm-mca -mtriple<span class="o">=</span>x86_64-unknown-unknown -mcpu<span class="o">=</span>btver2 -iterations<span class="o">=</span><span class="m">300</span> dot-product.s
+</pre></div>
+</div>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Iterations: 300
+Instructions: 900
+Total Cycles: 610
+Total uOps: 900
+
+Dispatch Width: 2
+uOps Per Cycle: 1.48
+IPC: 1.48
+Block RThroughput: 2.0
+
+
+Instruction Info:
+[1]: #uOps
+[2]: Latency
+[3]: RThroughput
+[4]: MayLoad
+[5]: MayStore
+[6]: HasSideEffects (U)
+
+[1] [2] [3] [4] [5] [6] Instructions:
+ 1 2 1.00 vmulps %xmm0, %xmm1, %xmm2
+ 1 3 1.00 vhaddps %xmm2, %xmm2, %xmm3
+ 1 3 1.00 vhaddps %xmm3, %xmm3, %xmm4
+
+
+Resources:
+[0] - JALU0
+[1] - JALU1
+[2] - JDiv
+[3] - JFPA
+[4] - JFPM
+[5] - JFPU0
+[6] - JFPU1
+[7] - JLAGU
+[8] - JMul
+[9] - JSAGU
+[10] - JSTC
+[11] - JVALU0
+[12] - JVALU1
+[13] - JVIMUL
+
+
+Resource pressure per iteration:
+[0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13]
+ - - - 2.00 1.00 2.00 1.00 - - - - - - -
+
+Resource pressure by instruction:
+[0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] Instructions:
+ - - - - 1.00 - 1.00 - - - - - - - vmulps %xmm0, %xmm1, %xmm2
+ - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm2, %xmm2, %xmm3
+ - - - 1.00 - 1.00 - - - - - - - - vhaddps %xmm3, %xmm3, %xmm4
+</pre></div>
+</div>
+<p>According to this report, the dot-product kernel has been executed 300 times,
+for a total of 900 simulated instructions. The total number of simulated micro
+opcodes (uOps) is also 900.</p>
+<p>The report is structured in three main sections. The first section collects a
+few performance numbers; the goal of this section is to give a very quick
+overview of the performance throughput. Important performance indicators are
+<strong>IPC</strong>, <strong>uOps Per Cycle</strong>, and <strong>Block RThroughput</strong> (Block Reciprocal
+Throughput).</p>
+<p>IPC is computed dividing the total number of simulated instructions by the total
+number of cycles. In the absence of loop-carried data dependencies, the
+observed IPC tends to a theoretical maximum which can be computed by dividing
+the number of instructions of a single iteration by the <em>Block RThroughput</em>.</p>
+<p>Field âuOps Per Cycleâ is computed dividing the total number of simulated micro
+opcodes by the total number of cycles. A delta between Dispatch Width and this
+field is an indicator of a performance issue. In the absence of loop-carried
+data dependencies, the observed âuOps Per Cycleâ should tend to a theoretical
+maximum throughput which can be computed by dividing the number of uOps of a
+single iteration by the <em>Block RThroughput</em>.</p>
+<p>Field <em>uOps Per Cycle</em> is bounded from above by the dispatch width. That is
+because the dispatch width limits the maximum size of a dispatch group. Both IPC
+and âuOps Per Cycleâ are limited by the amount of hardware parallelism. The
+availability of hardware resources affects the resource pressure distribution,
+and it limits the number of instructions that can be executed in parallel every
+cycle. A delta between Dispatch Width and the theoretical maximum uOps per
+Cycle (computed by dividing the number of uOps of a single iteration by the
+<em>Block RTrhoughput</em>) is an indicator of a performance bottleneck caused by the
+lack of hardware resources.
+In general, the lower the Block RThroughput, the better.</p>
+<p>In this example, <code class="docutils literal notranslate"><span class="pre">uOps</span> <span class="pre">per</span> <span class="pre">iteration/Block</span> <span class="pre">RThroughput</span></code> is 1.50. Since there
+are no loop-carried dependencies, the observed <em>uOps Per Cycle</em> is expected to
+approach 1.50 when the number of iterations tends to infinity. The delta between
+the Dispatch Width (2.00), and the theoretical maximum uOp throughput (1.50) is
+an indicator of a performance bottleneck caused by the lack of hardware
+resources, and the <em>Resource pressure view</em> can help to identify the problematic
+resource usage.</p>
+<p>The second section of the report shows the latency and reciprocal
+throughput of every instruction in the sequence. That section also reports
+extra information related to the number of micro opcodes, and opcode properties
+(i.e., âMayLoadâ, âMayStoreâ, and âHasSideEffectsâ).</p>
+<p>The third section is the <em>Resource pressure view</em>. This view reports
+the average number of resource cycles consumed every iteration by instructions
+for every processor resource unit available on the target. Information is
+structured in two tables. The first table reports the number of resource cycles
+spent on average every iteration. The second table correlates the resource
+cycles to the machine instruction in the sequence. For example, every iteration
+of the instruction vmulps always executes on resource unit [6]
+(JFPU1 - floating point pipeline #1), consuming an average of 1 resource cycle
+per iteration. Note that on AMD Jaguar, vector floating-point multiply can
+only be issued to pipeline JFPU1, while horizontal floating-point additions can
+only be issued to pipeline JFPU0.</p>
+<p>The resource pressure view helps with identifying bottlenecks caused by high
+usage of specific hardware resources. Situations with resource pressure mainly
+concentrated on a few resources should, in general, be avoided. Ideally,
+pressure should be uniformly distributed between multiple resources.</p>
+<div class="section" id="timeline-view">
+<h3>Timeline View<a class="headerlink" href="#timeline-view" title="Permalink to this headline">¶</a></h3>
+<p>The timeline view produces a detailed report of each instructionâs state
+transitions through an instruction pipeline. This view is enabled by the
+command line option <code class="docutils literal notranslate"><span class="pre">-timeline</span></code>. As instructions transition through the
+various stages of the pipeline, their states are depicted in the view report.
+These states are represented by the following characters:</p>
+<ul class="simple">
+<li>D : Instruction dispatched.</li>
+<li>e : Instruction executing.</li>
+<li>E : Instruction executed.</li>
+<li>R : Instruction retired.</li>
+<li>= : Instruction already dispatched, waiting to be executed.</li>
+<li>- : Instruction executed, waiting to be retired.</li>
+</ul>
+<p>Below is the timeline view for a subset of the dot-product example located in
+<code class="docutils literal notranslate"><span class="pre">test/tools/llvm-mca/X86/BtVer2/dot-product.s</span></code> and processed by
+<strong class="program">llvm-mca</strong> using the following command:</p>
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llvm-mca -mtriple<span class="o">=</span>x86_64-unknown-unknown -mcpu<span class="o">=</span>btver2 -iterations<span class="o">=</span><span class="m">3</span> -timeline dot-product.s
+</pre></div>
+</div>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Timeline view:
+ 012345
+Index 0123456789
+
+[0,0] DeeER. . . vmulps %xmm0, %xmm1, %xmm2
+[0,1] D==eeeER . . vhaddps %xmm2, %xmm2, %xmm3
+[0,2] .D====eeeER . vhaddps %xmm3, %xmm3, %xmm4
+[1,0] .DeeE-----R . vmulps %xmm0, %xmm1, %xmm2
+[1,1] . D=eeeE---R . vhaddps %xmm2, %xmm2, %xmm3
+[1,2] . D====eeeER . vhaddps %xmm3, %xmm3, %xmm4
+[2,0] . DeeE-----R . vmulps %xmm0, %xmm1, %xmm2
+[2,1] . D====eeeER . vhaddps %xmm2, %xmm2, %xmm3
+[2,2] . D======eeeER vhaddps %xmm3, %xmm3, %xmm4
+
+
+Average Wait times (based on the timeline view):
+[0]: Executions
+[1]: Average time spent waiting in a scheduler's queue
+[2]: Average time spent waiting in a scheduler's queue while ready
+[3]: Average time elapsed from WB until retire stage
+
+ [0] [1] [2] [3]
+0. 3 1.0 1.0 3.3 vmulps %xmm0, %xmm1, %xmm2
+1. 3 3.3 0.7 1.0 vhaddps %xmm2, %xmm2, %xmm3
+2. 3 5.7 0.0 0.0 vhaddps %xmm3, %xmm3, %xmm4
+</pre></div>
+</div>
+<p>The timeline view is interesting because it shows instruction state changes
+during execution. It also gives an idea of how the tool processes instructions
+executed on the target, and how their timing information might be calculated.</p>
+<p>The timeline view is structured in two tables. The first table shows
+instructions changing state over time (measured in cycles); the second table
+(named <em>Average Wait times</em>) reports useful timing statistics, which should
+help diagnose performance bottlenecks caused by long data dependencies and
+sub-optimal usage of hardware resources.</p>
+<p>An instruction in the timeline view is identified by a pair of indices, where
+the first index identifies an iteration, and the second index is the
+instruction index (i.e., where it appears in the code sequence). Since this
+example was generated using 3 iterations: <code class="docutils literal notranslate"><span class="pre">-iterations=3</span></code>, the iteration
+indices range from 0-2 inclusively.</p>
+<p>Excluding the first and last column, the remaining columns are in cycles.
+Cycles are numbered sequentially starting from 0.</p>
+<p>From the example output above, we know the following:</p>
+<ul class="simple">
+<li>Instruction [1,0] was dispatched at cycle 1.</li>
+<li>Instruction [1,0] started executing at cycle 2.</li>
+<li>Instruction [1,0] reached the write back stage at cycle 4.</li>
+<li>Instruction [1,0] was retired at cycle 10.</li>
+</ul>
+<p>Instruction [1,0] (i.e., vmulps from iteration #1) does not have to wait in the
+schedulerâs queue for the operands to become available. By the time vmulps is
+dispatched, operands are already available, and pipeline JFPU1 is ready to
+serve another instruction. So the instruction can be immediately issued on the
+JFPU1 pipeline. That is demonstrated by the fact that the instruction only
+spent 1cy in the schedulerâs queue.</p>
+<p>There is a gap of 5 cycles between the write-back stage and the retire event.
+That is because instructions must retire in program order, so [1,0] has to wait
+for [0,2] to be retired first (i.e., it has to wait until cycle 10).</p>
+<p>In the example, all instructions are in a RAW (Read After Write) dependency
+chain. Register %xmm2 written by vmulps is immediately used by the first
+vhaddps, and register %xmm3 written by the first vhaddps is used by the second
+vhaddps. Long data dependencies negatively impact the ILP (Instruction Level
+Parallelism).</p>
+<p>In the dot-product example, there are anti-dependencies introduced by
+instructions from different iterations. However, those dependencies can be
+removed at register renaming stage (at the cost of allocating register aliases,
+and therefore consuming physical registers).</p>
+<p>Table <em>Average Wait times</em> helps diagnose performance issues that are caused by
+the presence of long latency instructions and potentially long data dependencies
+which may limit the ILP. Note that <strong class="program">llvm-mca</strong>, by default, assumes at
+least 1cy between the dispatch event and the issue event.</p>
+<p>When the performance is limited by data dependencies and/or long latency
+instructions, the number of cycles spent while in the <em>ready</em> state is expected
+to be very small when compared with the total number of cycles spent in the
+schedulerâs queue. The difference between the two counters is a good indicator
+of how large of an impact data dependencies had on the execution of the
+instructions. When performance is mostly limited by the lack of hardware
+resources, the delta between the two counters is small. However, the number of
+cycles spent in the queue tends to be larger (i.e., more than 1-3cy),
+especially when compared to other low latency instructions.</p>
+</div>
+<div class="section" id="extra-statistics-to-further-diagnose-performance-issues">
+<h3>Extra Statistics to Further Diagnose Performance Issues<a class="headerlink" href="#extra-statistics-to-further-diagnose-performance-issues" title="Permalink to this headline">¶</a></h3>
+<p>The <code class="docutils literal notranslate"><span class="pre">-all-stats</span></code> command line option enables extra statistics and performance
+counters for the dispatch logic, the reorder buffer, the retire control unit,
+and the register file.</p>
+<p>Below is an example of <code class="docutils literal notranslate"><span class="pre">-all-stats</span></code> output generated by <strong class="program">llvm-mca</strong>
+for 300 iterations of the dot-product example discussed in the previous
+sections.</p>
+<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Dynamic Dispatch Stall Cycles:
+RAT - Register unavailable: 0
+RCU - Retire tokens unavailable: 0
+SCHEDQ - Scheduler full: 272 (44.6%)
+LQ - Load queue full: 0
+SQ - Store queue full: 0
+GROUP - Static restrictions on the dispatch group: 0
+
+
+Dispatch Logic - number of cycles where we saw N micro opcodes dispatched:
+[# dispatched], [# cycles]
+ 0, 24 (3.9%)
+ 1, 272 (44.6%)
+ 2, 314 (51.5%)
+
+
+Schedulers - number of cycles where we saw N instructions issued:
+[# issued], [# cycles]
+ 0, 7 (1.1%)
+ 1, 306 (50.2%)
+ 2, 297 (48.7%)
+
+Scheduler's queue usage:
+[1] Resource name.
+[2] Average number of used buffer entries.
+[3] Maximum number of used buffer entries.
+[4] Total number of buffer entries.
+
+ [1] [2] [3] [4]
+JALU01 0 0 20
+JFPU01 17 18 18
+JLSAGU 0 0 12
+
+
+Retire Control Unit - number of cycles where we saw N instructions retired:
+[# retired], [# cycles]
+ 0, 109 (17.9%)
+ 1, 102 (16.7%)
+ 2, 399 (65.4%)
+
+Total ROB Entries: 64
+Max Used ROB Entries: 35 ( 54.7% )
+Average Used ROB Entries per cy: 32 ( 50.0% )
+
+
+Register File statistics:
+Total number of mappings created: 900
+Max number of mappings used: 35
+
+* Register File #1 -- JFpuPRF:
+ Number of physical registers: 72
+ Total number of mappings created: 900
+ Max number of mappings used: 35
+
+* Register File #2 -- JIntegerPRF:
+ Number of physical registers: 64
+ Total number of mappings created: 0
+ Max number of mappings used: 0
+</pre></div>
+</div>
+<p>If we look at the <em>Dynamic Dispatch Stall Cycles</em> table, we see the counter for
+SCHEDQ reports 272 cycles. This counter is incremented every time the dispatch
+logic is unable to dispatch a full group because the schedulerâs queue is full.</p>
+<p>Looking at the <em>Dispatch Logic</em> table, we see that the pipeline was only able to
+dispatch two micro opcodes 51.5% of the time. The dispatch group was limited to
+one micro opcode 44.6% of the cycles, which corresponds to 272 cycles. The
+dispatch statistics are displayed by either using the command option
+<code class="docutils literal notranslate"><span class="pre">-all-stats</span></code> or <code class="docutils literal notranslate"><span class="pre">-dispatch-stats</span></code>.</p>
+<p>The next table, <em>Schedulers</em>, presents a histogram displaying a count,
+representing the number of instructions issued on some number of cycles. In
+this case, of the 610 simulated cycles, single instructions were issued 306
+times (50.2%) and there were 7 cycles where no instructions were issued.</p>
+<p>The <em>Schedulerâs queue usage</em> table shows that the average and maximum number of
+buffer entries (i.e., scheduler queue entries) used at runtime. Resource JFPU01
+reached its maximum (18 of 18 queue entries). Note that AMD Jaguar implements
+three schedulers:</p>
+<ul class="simple">
+<li>JALU01 - A scheduler for ALU instructions.</li>
+<li>JFPU01 - A scheduler floating point operations.</li>
+<li>JLSAGU - A scheduler for address generation.</li>
+</ul>
+<p>The dot-product is a kernel of three floating point instructions (a vector
+multiply followed by two horizontal adds). That explains why only the floating
+point scheduler appears to be used.</p>
+<p>A full scheduler queue is either caused by data dependency chains or by a
+sub-optimal usage of hardware resources. Sometimes, resource pressure can be
+mitigated by rewriting the kernel using different instructions that consume
+different scheduler resources. Schedulers with a small queue are less resilient
+to bottlenecks caused by the presence of long data dependencies. The scheduler
+statistics are displayed by using the command option <code class="docutils literal notranslate"><span class="pre">-all-stats</span></code> or
+<code class="docutils literal notranslate"><span class="pre">-scheduler-stats</span></code>.</p>
+<p>The next table, <em>Retire Control Unit</em>, presents a histogram displaying a count,
+representing the number of instructions retired on some number of cycles. In
+this case, of the 610 simulated cycles, two instructions were retired during the
+same cycle 399 times (65.4%) and there were 109 cycles where no instructions
+were retired. The retire statistics are displayed by using the command option
+<code class="docutils literal notranslate"><span class="pre">-all-stats</span></code> or <code class="docutils literal notranslate"><span class="pre">-retire-stats</span></code>.</p>
+<p>The last table presented is <em>Register File statistics</em>. Each physical register
+file (PRF) used by the pipeline is presented in this table. In the case of AMD
+Jaguar, there are two register files, one for floating-point registers (JFpuPRF)
+and one for integer registers (JIntegerPRF). The table shows that of the 900
+instructions processed, there were 900 mappings created. Since this dot-product
+example utilized only floating point registers, the JFPuPRF was responsible for
+creating the 900 mappings. However, we see that the pipeline only used a
+maximum of 35 of 72 available register slots at any given time. We can conclude
+that the floating point PRF was the only register file used for the example, and
+that it was never resource constrained. The register file statistics are
+displayed by using the command option <code class="docutils literal notranslate"><span class="pre">-all-stats</span></code> or
+<code class="docutils literal notranslate"><span class="pre">-register-file-stats</span></code>.</p>
+<p>In this example, we can conclude that the IPC is mostly limited by data
+dependencies, and not by resource pressure.</p>
+</div>
+<div class="section" id="instruction-flow">
+<h3>Instruction Flow<a class="headerlink" href="#instruction-flow" title="Permalink to this headline">¶</a></h3>
+<p>This section describes the instruction flow through the default pipeline of
+<strong class="program">llvm-mca</strong>, as well as the functional units involved in the process.</p>
+<p>The default pipeline implements the following sequence of stages used to
+process instructions.</p>
+<ul class="simple">
+<li>Dispatch (Instruction is dispatched to the schedulers).</li>
+<li>Issue (Instruction is issued to the processor pipelines).</li>
+<li>Write Back (Instruction is executed, and results are written back).</li>
+<li>Retire (Instruction is retired; writes are architecturally committed).</li>
+</ul>
+<p>The default pipeline only models the out-of-order portion of a processor.
+Therefore, the instruction fetch and decode stages are not modeled. Performance
+bottlenecks in the frontend are not diagnosed. <strong class="program">llvm-mca</strong> assumes that
+instructions have all been decoded and placed into a queue before the simulation
+start. Also, <strong class="program">llvm-mca</strong> does not model branch prediction.</p>
+<div class="section" id="instruction-dispatch">
+<h4>Instruction Dispatch<a class="headerlink" href="#instruction-dispatch" title="Permalink to this headline">¶</a></h4>
+<p>During the dispatch stage, instructions are picked in program order from a
+queue of already decoded instructions, and dispatched in groups to the
+simulated hardware schedulers.</p>
+<p>The size of a dispatch group depends on the availability of the simulated
+hardware resources. The processor dispatch width defaults to the value
+of the <code class="docutils literal notranslate"><span class="pre">IssueWidth</span></code> in LLVMâs scheduling model.</p>
+<p>An instruction can be dispatched if:</p>
+<ul class="simple">
+<li>The size of the dispatch group is smaller than processorâs dispatch width.</li>
+<li>There are enough entries in the reorder buffer.</li>
+<li>There are enough physical registers to do register renaming.</li>
+<li>The schedulers are not full.</li>
+</ul>
+<p>Scheduling models can optionally specify which register files are available on
+the processor. <strong class="program">llvm-mca</strong> uses that information to initialize register
+file descriptors. Users can limit the number of physical registers that are
+globally available for register renaming by using the command option
+<code class="docutils literal notranslate"><span class="pre">-register-file-size</span></code>. A value of zero for this option means <em>unbounded</em>. By
+knowing how many registers are available for renaming, the tool can predict
+dispatch stalls caused by the lack of physical registers.</p>
+<p>The number of reorder buffer entries consumed by an instruction depends on the
+number of micro-opcodes specified for that instruction by the target scheduling
+model. The reorder buffer is responsible for tracking the progress of
+instructions that are âin-flightâ, and retiring them in program order. The
+number of entries in the reorder buffer defaults to the value specified by field
+<cite>MicroOpBufferSize</cite> in the target scheduling model.</p>
+<p>Instructions that are dispatched to the schedulers consume scheduler buffer
+entries. <strong class="program">llvm-mca</strong> queries the scheduling model to determine the set
+of buffered resources consumed by an instruction. Buffered resources are
+treated like scheduler resources.</p>
+</div>
+<div class="section" id="instruction-issue">
+<h4>Instruction Issue<a class="headerlink" href="#instruction-issue" title="Permalink to this headline">¶</a></h4>
+<p>Each processor scheduler implements a buffer of instructions. An instruction
+has to wait in the schedulerâs buffer until input register operands become
+available. Only at that point, does the instruction becomes eligible for
+execution and may be issued (potentially out-of-order) for execution.
+Instruction latencies are computed by <strong class="program">llvm-mca</strong> with the help of the
+scheduling model.</p>
+<p><strong class="program">llvm-mca</strong>âs scheduler is designed to simulate multiple processor
+schedulers. The scheduler is responsible for tracking data dependencies, and
+dynamically selecting which processor resources are consumed by instructions.
+It delegates the management of processor resource units and resource groups to a
+resource manager. The resource manager is responsible for selecting resource
+units that are consumed by instructions. For example, if an instruction
+consumes 1cy of a resource group, the resource manager selects one of the
+available units from the group; by default, the resource manager uses a
+round-robin selector to guarantee that resource usage is uniformly distributed
+between all units of a group.</p>
+<p><strong class="program">llvm-mca</strong>âs scheduler internally groups instructions into three sets:</p>
+<ul class="simple">
+<li>WaitSet: a set of instructions whose operands are not ready.</li>
+<li>ReadySet: a set of instructions ready to execute.</li>
+<li>IssuedSet: a set of instructions executing.</li>
+</ul>
+<p>Depending on the operands availability, instructions that are dispatched to the
+scheduler are either placed into the WaitSet or into the ReadySet.</p>
+<p>Every cycle, the scheduler checks if instructions can be moved from the WaitSet
+to the ReadySet, and if instructions from the ReadySet can be issued to the
+underlying pipelines. The algorithm prioritizes older instructions over younger
+instructions.</p>
+</div>
+<div class="section" id="write-back-and-retire-stage">
+<h4>Write-Back and Retire Stage<a class="headerlink" href="#write-back-and-retire-stage" title="Permalink to this headline">¶</a></h4>
+<p>Issued instructions are moved from the ReadySet to the IssuedSet. There,
+instructions wait until they reach the write-back stage. At that point, they
+get removed from the queue and the retire control unit is notified.</p>
+<p>When instructions are executed, the retire control unit flags the instruction as
+âready to retire.â</p>
+<p>Instructions are retired in program order. The register file is notified of the
+retirement so that it can free the physical registers that were allocated for
+the instruction during the register renaming stage.</p>
+</div>
+<div class="section" id="load-store-unit-and-memory-consistency-model">
+<h4>Load/Store Unit and Memory Consistency Model<a class="headerlink" href="#load-store-unit-and-memory-consistency-model" title="Permalink to this headline">¶</a></h4>
+<p>To simulate an out-of-order execution of memory operations, <strong class="program">llvm-mca</strong>
+utilizes a simulated load/store unit (LSUnit) to simulate the speculative
+execution of loads and stores.</p>
+<p>Each load (or store) consumes an entry in the load (or store) queue. Users can
+specify flags <code class="docutils literal notranslate"><span class="pre">-lqueue</span></code> and <code class="docutils literal notranslate"><span class="pre">-squeue</span></code> to limit the number of entries in the
+load and store queues respectively. The queues are unbounded by default.</p>
+<p>The LSUnit implements a relaxed consistency model for memory loads and stores.
+The rules are:</p>
+<ol class="arabic simple">
+<li>A younger load is allowed to pass an older load only if there are no
+intervening stores or barriers between the two loads.</li>
+<li>A younger load is allowed to pass an older store provided that the load does
+not alias with the store.</li>
+<li>A younger store is not allowed to pass an older store.</li>
+<li>A younger store is not allowed to pass an older load.</li>
+</ol>
+<p>By default, the LSUnit optimistically assumes that loads do not alias
+(<cite>-noalias=true</cite>) store operations. Under this assumption, younger loads are
+always allowed to pass older stores. Essentially, the LSUnit does not attempt
+to run any alias analysis to predict when loads and stores do not alias with
+each other.</p>
+<p>Note that, in the case of write-combining memory, rule 3 could be relaxed to
+allow reordering of non-aliasing store operations. That being said, at the
+moment, there is no way to further relax the memory model (<code class="docutils literal notranslate"><span class="pre">-noalias</span></code> is the
+only option). Essentially, there is no option to specify a different memory
+type (e.g., write-back, write-combining, write-through; etc.) and consequently
+to weaken, or strengthen, the memory model.</p>
+<p>Other limitations are:</p>
+<ul class="simple">
+<li>The LSUnit does not know when store-to-load forwarding may occur.</li>
+<li>The LSUnit does not know anything about cache hierarchy and memory types.</li>
+<li>The LSUnit does not know how to identify serializing operations and memory
+fences.</li>
+</ul>
+<p>The LSUnit does not attempt to predict if a load or store hits or misses the L1
+cache. It only knows if an instruction âMayLoadâ and/or âMayStore.â For
+loads, the scheduling model provides an âoptimisticâ load-to-use latency (which
+usually matches the load-to-use latency for when there is a hit in the L1D).</p>
+<p><strong class="program">llvm-mca</strong> does not know about serializing operations or memory-barrier
+like instructions. The LSUnit conservatively assumes that an instruction which
+has both âMayLoadâ and unmodeled side effects behaves like a âsoftâ
+load-barrier. That means, it serializes loads without forcing a flush of the
+load queue. Similarly, instructions that âMayStoreâ and have unmodeled side
+effects are treated like store barriers. A full memory barrier is a âMayLoadâ
+and âMayStoreâ instruction with unmodeled side effects. This is inaccurate, but
+it is the best that we can do at the moment with the current information
+available in LLVM.</p>
+<p>A load/store barrier consumes one entry of the load/store queue. A load/store
+barrier enforces ordering of loads/stores. A younger load cannot pass a load
+barrier. Also, a younger store cannot pass a store barrier. A younger load
+has to wait for the memory/load barrier to execute. A load/store barrier is
+âexecutedâ when it becomes the oldest entry in the load/store queue(s). That
+also means, by construction, all of the older loads/stores have been executed.</p>
+<p>In conclusion, the full set of load/store consistency rules are:</p>
+<ol class="arabic simple">
+<li>A store may not pass a previous store.</li>
+<li>A store may not pass a previous load (regardless of <code class="docutils literal notranslate"><span class="pre">-noalias</span></code>).</li>
+<li>A store has to wait until an older store barrier is fully executed.</li>
+<li>A load may pass a previous load.</li>
+<li>A load may not pass a previous store unless <code class="docutils literal notranslate"><span class="pre">-noalias</span></code> is set.</li>
+<li>A load has to wait until an older load barrier is fully executed.</li>
+</ol>
+</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="bugpoint.html" title="bugpoint - automatic test case reduction tool"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="dsymutil.html" title="dsymutil - manipulate archived DWARF debug symbol 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-nm.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-nm.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-nm.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-nm.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,258 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-objdump - LLVMâs object file dumper" href="llvm-objdump.html" />
+ <link rel="prev" title="llvm-lib - LLVM lib.exe compatible library tool" href="llvm-lib.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-lib.html" title="llvm-lib - LLVM lib.exe compatible library 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-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 the LLVM bitcode
+files, object files, or <strong class="program">ar</strong> archives containing them, named on the
+command line. Each symbol is listed along with some simple information about
+its provenance. If no file name is specified, or <em>-</em> is used as a file name,
+<strong class="program">llvm-nm</strong> will process a file on 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>Type code characters currently supported, and their meanings, are as follows:</p>
+<p>U</p>
+<blockquote>
+<div>Named object is referenced but undefined in this bitcode file</div></blockquote>
+<p>C</p>
+<blockquote>
+<div>Common (multiple definitions link together into one def)</div></blockquote>
+<p>W</p>
+<blockquote>
+<div>Weak reference (multiple definitions link together into zero or one definitions)</div></blockquote>
+<p>t</p>
+<blockquote>
+<div>Local function (text) object</div></blockquote>
+<p>T</p>
+<blockquote>
+<div>Global function (text) object</div></blockquote>
+<p>d</p>
+<blockquote>
+<div>Local data object</div></blockquote>
+<p>D</p>
+<blockquote>
+<div>Global data object</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"> (default)</code><a class="headerlink" href="#cmdoption-llvm-nm-b" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use BSD output format. Alias for <cite>âformat=bsd</cite>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-p">
+<code class="descname">-P</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-llvm-nm-p" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use POSIX.2 output format. Alias for <cite>âformat=posix</cite>.</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 debugger only.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-llvm-nm-defined-only">
+<code class="descname">--defined-only</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 (as opposed to
+symbols which may be referenced by objects in this file, but not
+defined in this file.)</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-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 any weak symbols in the output.</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"> format</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>, 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><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-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>Shows symbols in order encountered.</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-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 instead of address.</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-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 symbols referenced but not defined in this file.</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 d(decimal),
+x(hexadecomal) and o(octal).</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>llvm-dis, ar(1), nm(1)</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-lib.html" title="llvm-lib - LLVM lib.exe compatible library 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-objdump.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-objdump.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-objdump.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-objdump.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,248 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-config - Print LLVM compilation options" href="llvm-config.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-config.html" title="llvm-config - Print LLVM compilation options"
+ 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-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-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-d" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display assembler mnemonics for the machine instructions. Disassembles all
+text sections found in the input file(s).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-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-disassemble-all" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display assembler mnemonics for the machine instructions. Disassembles all
+sections found in the input file(s).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-help">
+<code class="descname">-help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-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-r">
+<code class="descname">-r</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-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-s">
+<code class="descname">-s</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-s" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the content of each section.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-section-headers">
+<code class="descname">-section-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-section-headers" 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-t">
+<code class="descname">-t</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-t" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-version">
+<code class="descname">-version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-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>
+
+</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-arch">
+<code class="descname">-arch</code><code class="descclassname">=<architecture></code><a class="headerlink" href="#cmdoption-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-cfg">
+<code class="descname">-cfg</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-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 (Mach-O-only).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dsym">
+<code class="descname">-dsym</code><code class="descclassname">=<string></code><a class="headerlink" href="#cmdoption-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-g">
+<code class="descname">-g</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-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-m">
+<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-m" 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-mattr">
+<code class="descname">-mattr</code><code class="descclassname">=<a1,+a2,-a3,...></code><a class="headerlink" href="#cmdoption-mattr" title="Permalink to this definition">¶</a></dt>
+<dd><p>Target specific attributes.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-mc-x86-disable-arith-relaxation">
+<code class="descname">-mc-x86-disable-arith-relaxation</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-mc-x86-disable-arith-relaxation" title="Permalink to this definition">¶</a></dt>
+<dd><p>Disable relaxation of arithmetic instruction for X86.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-stats">
+<code class="descname">-stats</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable statistics output from program.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-triple">
+<code class="descname">-triple</code><code class="descclassname">=<string></code><a class="headerlink" href="#cmdoption-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-x86-asm-syntax">
+<code class="descname">-x86-asm-syntax</code><code class="descclassname">=<style></code><a class="headerlink" href="#cmdoption-x86-asm-syntax" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with the <code class="docutils literal notranslate"><span class="pre">-disassemble</span></code> option, choose style of code to emit from
+X86 backend. Supported values are:</p>
+<blockquote>
+<div><dl class="option">
+<dt id="cmdoption-arg-att">
+<code class="descname">att</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-arg-att" title="Permalink to this definition">¶</a></dt>
+<dd><p>AT&T-style assembly</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-arg-intel">
+<code class="descname">intel</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-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>
+
+</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></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-config.html" title="llvm-config - Print LLVM compilation options"
+ >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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-pdbutil.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-pdbutil.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-pdbutil.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-pdbutil.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,849 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-readobj - LLVM Object Reader" href="llvm-readobj.html" />
+ <link rel="prev" title="llvm-exegesis - LLVM Machine Instruction Benchmark" href="llvm-exegesis.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" 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-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="llvm-exegesis.html" title="llvm-exegesis - LLVM Machine Instruction Benchmark"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li 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="llvm-readobj.html" title="llvm-readobj - LLVM Object Reader"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="llvm-exegesis.html" title="llvm-exegesis - LLVM Machine Instruction Benchmark"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-profdata.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-profdata.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-profdata.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-profdata.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,346 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-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>
+</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>
+
+</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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-readobj.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-readobj.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-readobj.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-readobj.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,206 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Getting Started with the LLVM System" href="../GettingStarted.html" />
+ <link rel="prev" title="llvm-pdbutil - PDB File forensics and diagnostics" href="llvm-pdbutil.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="../index.html">
+ <img src="../_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" 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-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li 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. The tool and its output is primarily designed
+for use in FileCheck-based tests.</p>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<p>If <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>
+<dl class="option">
+<dt id="cmdoption-help">
+<code class="descname">-help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-version">
+<code class="descname">-version</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-version" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the version of this program</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-file-headers">
+<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-file-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display file headers.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-sections">
+<code class="descname">-sections</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-s</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-sections" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display all sections.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-section-data">
+<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-section-data" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <code class="docutils literal notranslate"><span class="pre">-sections</span></code>, display section data for each section shown.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-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-section-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <code class="docutils literal notranslate"><span class="pre">-sections</span></code>, display relocations for each section shown.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-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-section-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <code class="docutils literal notranslate"><span class="pre">-sections</span></code>, display symbols for each section shown.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-relocations">
+<code class="descname">-relocations</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-r</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-relocations" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the relocation entries in the file.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-symbols">
+<code class="descname">-symbols</code><code class="descclassname"></code><code class="descclassname">, </code><code class="descname">-t</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the symbol table.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dyn-symbols">
+<code class="descname">-dyn-symbols</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-dyn-symbols" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the dynamic symbol table (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-unwind">
+<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-unwind" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display unwind information.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-expand-relocs">
+<code class="descname">-expand-relocs</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-expand-relocs" title="Permalink to this definition">¶</a></dt>
+<dd><p>When used with <code class="docutils literal notranslate"><span class="pre">-relocations</span></code>, display each relocation in an expanded
+multi-line format.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dynamic-table">
+<code class="descname">-dynamic-table</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-dynamic-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the ELF .dynamic section table (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-needed-libs">
+<code class="descname">-needed-libs</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-needed-libs" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the needed libraries (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-program-headers">
+<code class="descname">-program-headers</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-program-headers" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display the ELF program headers (only for ELF object files).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-elf-section-groups">
+<code class="descname">-elf-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-elf-section-groups" title="Permalink to this definition">¶</a></dt>
+<dd><p>Display section groups (only for ELF object files).</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-readobj</strong> returns 0.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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-pdbutil.html" title="llvm-pdbutil - PDB File forensics and diagnostics"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="../index.html">Documentation</a>»</li>
+
+ <li 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-stress.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-stress.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-stress.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-stress.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,124 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-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-o">
+<code class="descname">-o</code><code class="descclassname"> filename</code><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output filename.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-size">
+<code class="descname">-size</code><code class="descclassname"> size</code><a class="headerlink" href="#cmdoption-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-seed">
+<code class="descname">-seed</code><code class="descclassname"> seed</code><a class="headerlink" href="#cmdoption-seed" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the seed to be used for the randomly generated instructions.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-stress</strong> returns 0.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/llvm-symbolizer.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/llvm-symbolizer.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/llvm-symbolizer.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/llvm-symbolizer.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,223 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="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 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="llvm-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> [options]</p>
+</div>
+<div class="section" id="description">
+<h2>DESCRIPTION<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-symbolizer</strong> reads object file names and addresses from standard
+input and prints corresponding source code locations to standard output.
+If object file is specified in command line, <strong class="program">llvm-symbolizer</strong>
+processes only addresses from standard input, the rest is output verbatim.
+This program uses debug info sections and symbol table in the object files.</p>
+</div>
+<div class="section" id="example">
+<h2>EXAMPLE<a class="headerlink" href="#example" title="Permalink to this headline">¶</a></h2>
+<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> cat addr.txt
+<span class="go">a.out 0x4004f4</span>
+<span class="go">/tmp/b.out 0x400528</span>
+<span class="go">/tmp/c.so 0x710</span>
+<span class="go">/tmp/mach_universal_binary:i386 0x1f84</span>
+<span class="go">/tmp/mach_universal_binary:x86_64 0x100000f24</span>
+<span class="gp">$</span> llvm-symbolizer < addr.txt
+<span class="go">main</span>
+<span class="go">/tmp/a.cc:4</span>
+
+<span class="go">f(int, int)</span>
+<span class="go">/tmp/b.cc:11</span>
+
+<span class="go">h_inlined_into_g</span>
+<span class="go">/tmp/header.h:2</span>
+<span class="go">g_inlined_into_f</span>
+<span class="go">/tmp/header.h:7</span>
+<span class="go">f_inlined_into_main</span>
+<span class="go">/tmp/source.cc:3</span>
+<span class="go">main</span>
+<span class="go">/tmp/source.cc:8</span>
+
+<span class="go">_main</span>
+<span class="go">/tmp/source_i386.cc:8</span>
+
+<span class="go">_main</span>
+<span class="go">/tmp/source_x86_64.cc:8</span>
+<span class="gp">$</span> cat addr2.txt
+<span class="go">0x4004f4</span>
+<span class="go">0x401000</span>
+<span class="gp">$</span> llvm-symbolizer -obj<span class="o">=</span>a.out < addr2.txt
+<span class="go">main</span>
+<span class="go">/tmp/a.cc:4</span>
+
+<span class="go">foo(int)</span>
+<span class="go">/tmp/a.cc:12</span>
+<span class="gp">$</span>cat addr.txt
+<span class="go">0x40054d</span>
+<span class="gp">$</span>llvm-symbolizer -inlining -print-address -pretty-print -obj<span class="o">=</span>addr.exe < addr.txt
+<span class="go">0x40054d: inc at /tmp/x.c:3:3</span>
+<span class="go"> (inlined by) main at /tmp/x.c:9:0</span>
+<span class="gp">$</span>llvm-symbolizer -inlining -pretty-print -obj<span class="o">=</span>addr.exe < addr.txt
+<span class="go">inc at /tmp/x.c:3:3</span>
+<span class="go"> (inlined by) main at /tmp/x.c:9:0</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="options">
+<h2>OPTIONS<a class="headerlink" href="#options" title="Permalink to this headline">¶</a></h2>
+<dl class="option">
+<dt id="cmdoption-obj">
+<code class="descname">-obj</code><code class="descclassname"></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-obj" title="Permalink to this definition">¶</a></dt>
+<dd><p>Path to object file to be symbolized.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-functions">
+<code class="descname">-functions</code><code class="descclassname">=[none|short|linkage]</code><a class="headerlink" href="#cmdoption-functions" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the way function names are printed (omit function name,
+print short function name, or print full linkage name, respectively).
+Defaults to <code class="docutils literal notranslate"><span class="pre">linkage</span></code>.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-use-symbol-table">
+<code class="descname">-use-symbol-table</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-use-symbol-table" title="Permalink to this definition">¶</a></dt>
+<dd><p>Prefer function names stored in symbol table to function names
+in debug info sections. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-demangle">
+<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-demangle" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print demangled function names. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-inlining">
+<code class="descname">-inlining</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-inlining" title="Permalink to this definition">¶</a></dt>
+<dd><p>If a source code location is in an inlined function, prints all the
+inlnied frames. Defaults to true.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-default-arch">
+<code class="descname">-default-arch</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-default-arch" title="Permalink to this definition">¶</a></dt>
+<dd><p>If a binary contains object files for multiple architectures (e.g. it is a
+Mach-O universal binary), symbolize the object file for a given architecture.
+You can also specify architecture by writing <code class="docutils literal notranslate"><span class="pre">binary_name:arch_name</span></code> in the
+input (see example above). If architecture is not specified in either way,
+address will not be symbolized. Defaults to empty string.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-dsym-hint">
+<code class="descname">-dsym-hint</code><code class="descclassname">=<path/to/file.dSYM></code><a class="headerlink" href="#cmdoption-dsym-hint" title="Permalink to this definition">¶</a></dt>
+<dd><p>(Darwin-only flag). If the debug info for a binary isnât present in the default
+location, look for the debug info at the .dSYM path provided via the
+<code class="docutils literal notranslate"><span class="pre">-dsym-hint</span></code> flag. This flag can be used multiple times.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-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-print-address" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print address before the source code location. Defaults to false.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-pretty-print">
+<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-pretty-print" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print human readable output. If <code class="docutils literal notranslate"><span class="pre">-inlining</span></code> is specified, enclosing scope is
+prefixed by (inlined by). Refer to listed examples.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p><strong class="program">llvm-symbolizer</strong> returns 0. Other exit codes imply internal program error.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/opt.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/opt.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/opt.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/opt.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,229 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="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-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-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-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-f">
+<code class="descname">-f</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-f" title="Permalink to this definition">¶</a></dt>
+<dd><p>Enable binary output on terminals. Normally, <strong class="program">opt</strong> will refuse to
+write raw bitcode output if the output stream is a terminal. With this option,
+<strong class="program">opt</strong> will write raw bitcode regardless of the output device.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-help">
+<code class="descname">-help</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-help" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print a summary of command line options.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-o">
+<code class="descname">-o</code><code class="descclassname"> <filename></code><a class="headerlink" href="#cmdoption-o" title="Permalink to this definition">¶</a></dt>
+<dd><p>Specify the output filename.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-s">
+<code class="descname">-S</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-s" title="Permalink to this definition">¶</a></dt>
+<dd><p>Write output in LLVM intermediate language (instead of bitcode).</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-passname">
+<code class="descname">-{passname}</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-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-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-disable-inlining">
+<code class="descname">-disable-inlining</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-disable-inlining" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option simply removes the inlining pass from the standard list.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-disable-opt">
+<code class="descname">-disable-opt</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-disable-opt" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option is only meaningful when <cite>-std-link-opts</cite> is given. It
+disables most passes.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-strip-debug">
+<code class="descname">-strip-debug</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-strip-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option causes opt to strip debug information from the module before
+applying other optimizations. It is essentially the same as <cite>-strip</cite>
+but it ensures that stripping of debug information is done first.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-verify-each">
+<code class="descname">-verify-each</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-verify-each" title="Permalink to this definition">¶</a></dt>
+<dd><p>This option causes opt to add a verify pass after every pass otherwise
+specified on the command line (including <cite>-verify</cite>). This is useful
+for cases where it is suspected that a pass is creating an invalid module but
+it is not clear which pass is doing it.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-stats">
+<code class="descname">-stats</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-stats" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print statistics.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-time-passes">
+<code class="descname">-time-passes</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-time-passes" title="Permalink to this definition">¶</a></dt>
+<dd><p>Record the amount of time needed for each pass and print it to standard
+error.</p>
+</dd></dl>
+
+<dl class="option">
+<dt id="cmdoption-debug">
+<code class="descname">-debug</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-debug" title="Permalink to this definition">¶</a></dt>
+<dd><p>If this is a debug build, this option will enable debug printouts from passes
+which use the <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-load">
+<code class="descname">-load</code><code class="descclassname">=<plugin></code><a class="headerlink" href="#cmdoption-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-help"><code class="xref std std-option docutils literal notranslate"><span class="pre">-help</span></code></a> and <a class="reference internal" href="#cmdoption-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-p">
+<code class="descname">-p</code><code class="descclassname"></code><a class="headerlink" href="#cmdoption-p" title="Permalink to this definition">¶</a></dt>
+<dd><p>Print module after each transformation.</p>
+</dd></dl>
+
+</div>
+<div class="section" id="exit-status">
+<h2>EXIT STATUS<a class="headerlink" href="#exit-status" title="Permalink to this headline">¶</a></h2>
+<p>If <strong class="program">opt</strong> succeeds, it will exit with 0. Otherwise, if an error
+occurs, it will exit with a non-zero value.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandGuide/tblgen.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandGuide/tblgen.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandGuide/tblgen.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandGuide/tblgen.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,279 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="../_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CommandLine.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CommandLine.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CommandLine.html (added)
+++ www-releases/trunk/8.0.0/docs/CommandLine.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,1557 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="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="#miscellaneous-option-modifiers" id="id30">Miscellaneous option modifiers</a></li>
+<li><a class="reference internal" href="#response-files" id="id31">Response files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#top-level-classes-and-functions" id="id32">Top-Level Classes and Functions</a><ul>
+<li><a class="reference internal" href="#the-cl-getregisteredoptions-function" id="id33">The <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="id34">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="id35">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="id36">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="id37">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="id38">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="id39">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="id40">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="id41">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="id42">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="id43">Builtin parsers</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#extending-the-library" id="id44">Extension Guide</a><ul>
+<li><a class="reference internal" href="#writing-a-custom-parser" id="id45">Writing a custom parser</a></li>
+<li><a class="reference internal" href="#exploiting-external-storage" id="id46">Exploiting external storage</a></li>
+<li><a class="reference internal" href="#dynamically-adding-command-line-options" id="id47">Dynamically adding command line options</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id8">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document describes the CommandLine argument processing library. It will
+show you how to use it, and what it can do. The CommandLine library uses a
+declarative approach to specifying the command line options that your program
+takes. By default, these options declarations implicitly hold the value parsed
+for the option declared (of course this <a class="reference internal" href="#can-be-changed">can be changed</a>).</p>
+<p>Although there are a <strong>lot</strong> of command line argument parsing libraries out
+there in many different languages, none of them fit well with what I needed. By
+looking at the features and problems of other libraries, I designed the
+CommandLine library to have the following features:</p>
+<ol class="arabic simple">
+<li>Speed: The CommandLine library is very quick and uses little resources. The
+parsing time of the library is directly proportional to the number of
+arguments parsed, not the number of options recognized. Additionally,
+command line argument values are captured transparently into user defined
+global variables, which can be accessed like any other variable (and with the
+same performance).</li>
+<li>Type Safe: As a user of CommandLine, you donât have to worry about
+remembering the type of arguments that you want (is it an int? a string? a
+bool? an enum?) and keep casting it around. Not only does this help prevent
+error prone constructs, it also leads to dramatically cleaner source code.</li>
+<li>No subclasses required: To use CommandLine, you instantiate variables that
+correspond to the arguments that you would like to capture, you donât
+subclass a parser. This means that you donât have to write <strong>any</strong>
+boilerplate code.</li>
+<li>Globally accessible: Libraries can specify command line arguments that are
+automatically enabled in any tool that links to the library. This is
+possible because the application doesnât have to keep a list of arguments to
+pass to the parser. This also makes supporting <a class="reference internal" href="#dynamically-loaded-options">dynamically loaded options</a>
+trivial.</li>
+<li>Cleaner: CommandLine supports enum and other types directly, meaning that
+there is less error and more security built into the library. You donât have
+to worry about whether your integral command line argument accidentally got
+assigned a value that is not valid for your enum type.</li>
+<li>Powerful: The CommandLine library supports many different types of arguments,
+from simple <a class="reference internal" href="#boolean-flags">boolean flags</a> to <a class="reference internal" href="#scalars-arguments">scalars arguments</a> (<a class="reference internal" href="#strings">strings</a>,
+<a class="reference internal" href="#integers">integers</a>, <a class="reference internal" href="#enums">enums</a>, <a class="reference internal" href="#doubles">doubles</a>), to <a class="reference internal" href="#lists-of-arguments">lists of arguments</a>. This is
+possible because CommandLine isâ¦</li>
+<li>Extensible: It is very simple to add a new argument type to CommandLine.
+Simply specify the parser that you want to use with the command line option
+when you declare it. <a class="reference internal" href="#custom-parsers">Custom parsers</a> are no problem.</li>
+<li>Labor Saving: The CommandLine library cuts down on the amount of grunt work
+that you, the user, have to do. For example, it automatically provides a
+<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">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">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>
+<span id="grouping"></span><ul class="simple" id="cl-grouping">
+<li>The <strong>cl::Grouping</strong> modifier 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. Note that <strong>cl::Grouping</strong> options
+cannot have values.</li>
+</ul>
+<p>The CommandLine library does not restrict how you use the <strong>cl::Prefix</strong> or
+<strong>cl::Grouping</strong> modifiers, but it is possible to specify ambiguous argument
+settings. Thus, it is possible to have multiple letter options that are prefix
+or grouping options, and they will still work as designed.</p>
+<p>To do this, the CommandLine library uses a greedy algorithm to parse the input
+option into (potentially multiple) prefix and grouping options. The strategy
+basically looks like this:</p>
+<div class="highlight-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 (!isOption(input) && !input.empty()) input.pop_back(); // Remove the last letter
+4. if (input.empty()) return error(); // No matching option
+5. if (getOption(input).isPrefix())
+ return getOption(input).parse(input);
+6. while (!input.empty()) { // Must be grouping options
+ getOption(input).parse();
+ OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());
+ input = OrigInput;
+ while (!isOption(input) && !input.empty()) input.pop_back();
+ }
+7. if (!OrigInput.empty()) error();
+
+}
+</pre></div>
+</div>
+</div>
+<div class="section" id="miscellaneous-option-modifiers">
+<h4><a class="toc-backref" href="#id30">Miscellaneous option modifiers</a><a class="headerlink" href="#miscellaneous-option-modifiers" title="Permalink to this headline">¶</a></h4>
+<p>The miscellaneous option modifiers are the only flags where you can specify more
+than one flag from the set: they are not mutually exclusive. These flags
+specify boolean properties that modify the option.</p>
+<ul class="simple" id="cl-commaseparated">
+<li>The <strong>cl::CommaSeparated</strong> modifier indicates that any commas specified for an
+optionâs value should be used to split the value up into multiple values for
+the option. For example, these two options are equivalent when
+<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-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>
+<p>So far, these are the only three miscellaneous option modifiers.</p>
+</div>
+<div class="section" id="response-files">
+<span id="id5"></span><h4><a class="toc-backref" href="#id31">Response files</a><a class="headerlink" href="#response-files" title="Permalink to this headline">¶</a></h4>
+<p>Some systems, such as certain variants of Microsoft Windows and some older
+Unices have a relatively low limit on command-line length. It is therefore
+customary to use the so-called âresponse filesâ to circumvent this
+restriction. These files are mentioned on the command-line (using the â@fileâ)
+syntax. The program reads these files and inserts the contents into argv,
+thereby working around the command-line length limits.</p>
+</div>
+</div>
+<div class="section" id="top-level-classes-and-functions">
+<h3><a class="toc-backref" href="#id32">Top-Level Classes and Functions</a><a class="headerlink" href="#top-level-classes-and-functions" title="Permalink to this headline">¶</a></h3>
+<p>Despite all of the built-in flexibility, the CommandLine option library really
+only consists of one function <a class="reference internal" href="#cl-parsecommandlineoptions">cl::ParseCommandLineOptions</a>) and three main
+classes: <a class="reference internal" href="#cl-opt">cl::opt</a>, <a class="reference internal" href="#cl-list">cl::list</a>, and <a class="reference internal" href="#cl-alias">cl::alias</a>. This section describes
+these three classes in detail.</p>
+<div class="section" id="the-cl-getregisteredoptions-function">
+<span id="cl-getregisteredoptions"></span><h4><a class="toc-backref" href="#id33">The <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 writter 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="#id34">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="#id35">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="#id36">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="#id37">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="#id38">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="#id39">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="#id40">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="#id41">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="#id42">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="#id43">Builtin parsers</a><a class="headerlink" href="#builtin-parsers" title="Permalink to this headline">¶</a></h3>
+<p>Parsers control how the string value taken from the command line is translated
+into a typed value, suitable for use in a C++ program. By default, the
+CommandLine library uses an instance of <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="#id44">Extension Guide</a><a class="headerlink" href="#extending-the-library" title="Permalink to this headline">¶</a></h2>
+<p>Although the CommandLine library has a lot of functionality built into it
+already (as discussed previously), one of its true strengths lie in its
+extensibility. This section discusses how the CommandLine library works under
+the covers and illustrates how to do some simple, common, extensions.</p>
+<div class="section" id="writing-a-custom-parser">
+<span id="custom-parser"></span><span id="custom-parsers"></span><span id="id7"></span><h3><a class="toc-backref" href="#id45">Writing a custom parser</a><a class="headerlink" href="#writing-a-custom-parser" title="Permalink to this headline">¶</a></h3>
+<p>One of the simplest and most common extensions is the use of a custom parser.
+As <a class="reference internal" href="#discussed-previously">discussed previously</a>, parsers are the portion of the CommandLine library
+that turns string input from the user into a particular parsed data type,
+validating the input in the process.</p>
+<p>There are two ways to use a new parser:</p>
+<ol class="arabic">
+<li><p class="first">Specialize the <a class="reference internal" href="#cl-parser">cl::parser</a> template for your custom data type.</p>
+<p>This approach has the advantage that users of your custom data type will
+automatically use your custom parser whenever they define an option with a
+value type of your data type. The disadvantage of this approach is that it
+doesnât work if your fundamental data type is something that is already
+supported.</p>
+</li>
+<li><p class="first">Write an independent class, using it explicitly from options that need it.</p>
+<p>This approach works well in situations where you would line to parse an
+option using special syntax for a not-very-special data-type. The drawback
+of this approach is that users of your parser have to be aware that they are
+using your parser instead of the builtin ones.</p>
+</li>
+</ol>
+<p>To guide the discussion, we will discuss a custom parser that accepts file
+sizes, specified with an optional unit after the numeric size. For example, we
+would like to parse â102kbâ, â41Mâ, â1Gâ into the appropriate integer value. In
+this case, the underlying data type we want to parse into is â<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="#id46">Exploiting external storage</a><a class="headerlink" href="#exploiting-external-storage" title="Permalink to this headline">¶</a></h3>
+<p>Several of the LLVM libraries define static <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="#id47">Dynamically adding command line options</a><a class="headerlink" href="#dynamically-adding-command-line-options" title="Permalink to this headline">¶</a></h3>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CompileCudaWithLLVM.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CompileCudaWithLLVM.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CompileCudaWithLLVM.html (added)
+++ www-releases/trunk/8.0.0/docs/CompileCudaWithLLVM.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,602 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="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-mirror/test-suite/blob/master/External/CUDA/math_h.cu">pass</a>
+<a class="reference external" href="https://github.com/llvm-mirror/test-suite/blob/master/External/CUDA/cmath.cu">tests</a>
+adapted from libc++âs test suite.</p>
+<p>In nvcc <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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CompilerWriterInfo.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CompilerWriterInfo.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CompilerWriterInfo.html (added)
+++ www-releases/trunk/8.0.0/docs/CompilerWriterInfo.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,279 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="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="#os-x" id="id19">OS X</a></li>
+<li><a class="reference internal" href="#windows" id="id20">Windows</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#nvptx" id="id21">NVPTX</a></li>
+<li><a class="reference internal" href="#miscellaneous-resources" id="id22">Miscellaneous Resources</a></li>
+</ul>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This document is a work-in-progress. Additions and clarifications are
+welcome.</p>
+</div>
+<div class="section" id="hardware">
+<h2><a class="toc-backref" href="#id1">Hardware</a><a class="headerlink" href="#hardware" title="Permalink to this headline">¶</a></h2>
+<div class="section" id="aarch64-arm">
+<h3><a class="toc-backref" href="#id2">AArch64 & ARM</a><a class="headerlink" href="#aarch64-arm" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.h/index.html">ARMv8-A Architecture Reference Manual</a> (authentication required, free sign-up). This document covers both AArch64 and ARM instructions</li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ddi0403e.b/index.html">ARMv7-M Architecture Reference Manual</a> (authentication required, free sign-up). This covers the Thumb2-only microcontrollers</li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ddi0419c/index.html">ARMv6-M Architecture Reference Manual</a> (authentication required, free sign-up). This covers the Thumb1-only microcontrollers</li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf">ARM C Language Extensions</a></li>
+<li>AArch32 <a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0045d/IHI0045D_ABI_addenda.pdf">ABI Addenda and Errata</a></li>
+</ul>
+</div>
+<div class="section" id="itanium-ia64">
+<h3><a class="toc-backref" href="#id3">Itanium (ia64)</a><a class="headerlink" href="#itanium-ia64" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://developer.intel.com/design/itanium2/documentation.htm">Itanium documentation</a></li>
+</ul>
+</div>
+<div class="section" id="lanai">
+<h3><a class="toc-backref" href="#id4">Lanai</a><a class="headerlink" href="#lanai" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://g.co/lanai/isa">Lanai Instruction Set Architecture</a></li>
+</ul>
+</div>
+<div class="section" id="mips">
+<h3><a class="toc-backref" href="#id5">MIPS</a><a class="headerlink" href="#mips" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://www.mips.com/products/">MIPS Processor Architecture</a></li>
+<li><a class="reference external" href="http://techpubs.sgi.com/library/manuals/4000/007-4658-001/pdf/007-4658-001.pdf">MIPS 64-bit ELF Object File Specification</a></li>
+</ul>
+</div>
+<div class="section" id="powerpc">
+<h3><a class="toc-backref" href="#id6">PowerPC</a><a class="headerlink" href="#powerpc" title="Permalink to this headline">¶</a></h3>
+<div class="section" id="ibm-official-manuals-and-docs">
+<h4><a class="toc-backref" href="#id7">IBM - Official manuals and docs</a><a class="headerlink" href="#ibm-official-manuals-and-docs" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><a class="reference external" href="https://www.power.org/technology-introduction/standards-specifications">Power Instruction Set Architecture, Versions 2.03 through 2.06 (authentication required, free sign-up)</a></li>
+<li><a class="reference external" href="http://www.ibm.com/chips/techlib/techlib.nsf/techdocs/852569B20050FF7785256996007558C6">PowerPC Compiler Writerâs Guide</a></li>
+<li><a class="reference external" href="http://www.ibm.com/developerworks/linux/library/l-powarch/">Intro to PowerPC Architecture</a></li>
+<li><a class="reference external" href="http://www.ibm.com/chips/techlib/techlib.nsf/products/PowerPC">PowerPC Processor Manuals (embedded)</a></li>
+<li><a class="reference external" href="https://www.power.org/documentation/?document_company=105&document_category=all&publish_year=all&grid_order=DESC&grid_sort=title">Various IBM specifications and white papers</a></li>
+<li><a class="reference external" href="http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixassem/alangref/alangreftfrm.htm">IBM AIX/5L for POWER Assembly Reference</a></li>
+</ul>
+</div>
+<div class="section" id="other-documents-collections-notes">
+<h4><a class="toc-backref" href="#id8">Other documents, collections, notes</a><a class="headerlink" href="#other-documents-collections-notes" title="Permalink to this headline">¶</a></h4>
+<ul class="simple">
+<li><a class="reference external" href="http://penguinppc.org/dev/#library">PowerPC ABI documents</a></li>
+<li><a class="reference external" href="http://gcc.gnu.org/ml/gcc-patches/2003-09/msg00997.html">PowerPC64 alignment of long doubles (from GCC)</a></li>
+<li><a class="reference external" href="http://sources.redhat.com/ml/binutils/2002-04/msg00573.html">Long branch stubs for powerpc64-linux (from binutils)</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="amdgpu">
+<h3><a class="toc-backref" href="#id9">AMDGPU</a><a class="headerlink" href="#amdgpu" title="Permalink to this headline">¶</a></h3>
+<p>Refer to <a class="reference internal" href="AMDGPUUsage.html"><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></li>
+</ul>
+<div class="section" id="linux">
+<h3><a class="toc-backref" href="#id18">Linux</a><a class="headerlink" href="#linux" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="https://github.com/hjl-tools/linux-abi/wiki/Linux-Extensions-to-gABI">Linux extensions to gabi</a></li>
+<li><a class="reference external" href="http://www.linuxbase.org/spec/ELF/ppc64/">PowerPC 64-bit ELF ABI Supplement</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055a/IHI0055A_aapcs64.pdf">Procedure Call Standard for the AArch64 Architecture</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0044e/IHI0044E_aaelf.pdf">ELF for the ARM Architecture</a></li>
+<li><a class="reference external" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0056a/IHI0056A_aaelf64.pdf">ELF for the ARM 64-bit Architecture (AArch64)</a></li>
+<li><a class="reference external" href="http://legacy.redhat.com/pub/redhat/linux/7.1/es/os/s390x/doc/lzsabi0.pdf">System z ELF ABI Supplement</a></li>
+</ul>
+</div>
+<div class="section" id="os-x">
+<h3><a class="toc-backref" href="#id19">OS X</a><a class="headerlink" href="#os-x" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html">Mach-O Runtime Architecture</a></li>
+<li><a class="reference external" href="http://www.unsanity.org/archives/000044.php">Notes on Mach-O ABI</a></li>
+</ul>
+</div>
+<div class="section" id="windows">
+<h3><a class="toc-backref" href="#id20">Windows</a><a class="headerlink" href="#windows" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li><a class="reference external" href="http://www.microsoft.com/whdc/system/platform/firmware/pecoff.mspx">Microsoft PE/COFF Specification</a></li>
+</ul>
+</div>
+</div>
+<div class="section" id="nvptx">
+<h2><a class="toc-backref" href="#id21">NVPTX</a><a class="headerlink" href="#nvptx" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="http://docs.nvidia.com/cuda/index.html">CUDA Documentation</a> includes the PTX
+ISA and Driver API documentation</li>
+</ul>
+</div>
+<div class="section" id="miscellaneous-resources">
+<h2><a class="toc-backref" href="#id22">Miscellaneous Resources</a><a class="headerlink" href="#miscellaneous-resources" title="Permalink to this headline">¶</a></h2>
+<ul class="simple">
+<li><a class="reference external" href="http://www.nondot.org/sabre/os/articles/ExecutableFileFormats/">Executable File Format library</a></li>
+<li><a class="reference external" href="http://gcc.gnu.org/projects/prefetch.html">GCC prefetch project</a> page has a
+good survey of the prefetching capabilities of a variety of modern
+processors.</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/Contributing.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/Contributing.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/Contributing.html (added)
+++ www-releases/trunk/8.0.0/docs/Contributing.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,193 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVM 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/Coroutines.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/Coroutines.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/Coroutines.html (added)
+++ www-releases/trunk/8.0.0/docs/Coroutines.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,1271 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/CoverageMappingFormat.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/CoverageMappingFormat.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/CoverageMappingFormat.html (added)
+++ www-releases/trunk/8.0.0/docs/CoverageMappingFormat.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,653 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/DebuggingJITedCode.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/DebuggingJITedCode.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/DebuggingJITedCode.html (added)
+++ www-releases/trunk/8.0.0/docs/DebuggingJITedCode.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,211 @@
+
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="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 Mac OS X.</p>
+</div>
+<div class="section" id="debugging-mcjit-ed-code">
+<h2>Debugging MCJIT-ed code<a class="headerlink" href="#debugging-mcjit-ed-code" title="Permalink to this headline">¶</a></h2>
+<p>The emerging MCJIT component of LLVM allows full debugging of JIT-ed code with
+GDB. This is due to MCJITâs ability to use the MC emitter to provide full
+DWARF debugging information to GDB.</p>
+<p>Note that lli has to be passed the <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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/DeveloperPolicy.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/DeveloperPolicy.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/DeveloperPolicy.html (added)
+++ www-releases/trunk/8.0.0/docs/DeveloperPolicy.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,753 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="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="id9">Introduction</a></li>
+<li><a class="reference internal" href="#developer-policies" id="id10">Developer Policies</a><ul>
+<li><a class="reference internal" href="#stay-informed" id="id11">Stay Informed</a></li>
+<li><a class="reference internal" href="#making-and-submitting-a-patch" id="id12">Making and Submitting a Patch</a></li>
+<li><a class="reference internal" href="#code-reviews" id="id13">Code Reviews</a></li>
+<li><a class="reference internal" href="#code-owners" id="id14">Code Owners</a></li>
+<li><a class="reference internal" href="#test-cases" id="id15">Test Cases</a></li>
+<li><a class="reference internal" href="#quality" id="id16">Quality</a></li>
+<li><a class="reference internal" href="#commit-messages" id="id17">Commit messages</a></li>
+<li><a class="reference internal" href="#obtaining-commit-access" id="id18">Obtaining Commit Access</a></li>
+<li><a class="reference internal" href="#making-a-major-change" id="id19">Making a Major Change</a></li>
+<li><a class="reference internal" href="#incremental-development" id="id20">Incremental Development</a></li>
+<li><a class="reference internal" href="#attribution-of-changes" id="id21">Attribution of Changes</a></li>
+<li><a class="reference internal" href="#ir-backwards-compatibility" id="id22">IR Backwards Compatibility</a></li>
+<li><a class="reference internal" href="#c-api-changes" id="id23">C API Changes</a></li>
+<li><a class="reference internal" href="#new-targets" id="id24">New Targets</a></li>
+<li><a class="reference internal" href="#updating-toolchain-requirements" id="id25">Updating Toolchain Requirements</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#copyright-license-and-patents" id="id26">Copyright, License, and Patents</a><ul>
+<li><a class="reference internal" href="#copyright" id="id27">Copyright</a></li>
+<li><a class="reference internal" href="#license" id="id28">License</a></li>
+<li><a class="reference internal" href="#patents" id="id29">Patents</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h2><a class="toc-backref" href="#id9">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
+<p>This document contains the LLVM Developer Policy which defines the projectâs
+policy towards developers and their contributions. The intent of this policy is
+to eliminate miscommunication, rework, and confusion that might arise from the
+distributed nature of LLVMâs development. By stating the policy in clear terms,
+we hope each developer can know ahead of time what to expect when making LLVM
+contributions. This policy covers all llvm.org subprojects, including Clang,
+LLDB, libc++, etc.</p>
+<p>This policy is also designed to accomplish the following objectives:</p>
+<ol class="arabic simple">
+<li>Attract both users and developers to the LLVM project.</li>
+<li>Make life as simple and easy for contributors as possible.</li>
+<li>Keep the top of 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="#id10">Developer Policies</a><a class="headerlink" href="#developer-policies" title="Permalink to this headline">¶</a></h2>
+<p>This section contains policies that pertain to frequent LLVM developers. We
+always welcome <a class="reference internal" href="#one-off-patches">one-off patches</a> from people who do not routinely contribute to
+LLVM, but we expect more from frequent contributors to keep the system as
+efficient as possible for everyone. Frequent LLVM contributors are expected to
+meet the following requirements in order for LLVM to maintain a high standard of
+quality.</p>
+<div class="section" id="stay-informed">
+<h3><a class="toc-backref" href="#id11">Stay Informed</a><a class="headerlink" href="#stay-informed" title="Permalink to this headline">¶</a></h3>
+<p>Developers should stay informed by reading at least the âdevâ mailing list for
+the projects you are interested in, such as <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a> for LLVM, <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/cfe-dev">cfe-dev</a> for Clang, or <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/lldb-dev">lldb-dev</a> for LLDB. If you are
+doing anything more than just casual work on LLVM, it is suggested that you also
+subscribe to the âcommitsâ mailing list for the subproject youâre interested in,
+such as <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-commits">llvm-commits</a>, <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/cfe-commits">cfe-commits</a>, or <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/lldb-commits">lldb-commits</a>. Reading the
+âcommitsâ list and paying attention to changes being made by others is a good
+way to see what other people are interested in and watching the flow of the
+project as a whole.</p>
+<p>We recommend that active developers register an email account with <a class="reference external" href="https://bugs.llvm.org/">LLVM
+Bugzilla</a> and preferably subscribe to the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-bugs">llvm-bugs</a> email list to keep track
+of bugs and enhancements occurring in LLVM. We really appreciate people who are
+proactive at catching incoming bugs in their components and dealing with them
+promptly.</p>
+<p>Please be aware that all public LLVM mailing lists are public and archived, and
+that notices of confidentiality or non-disclosure cannot be respected.</p>
+</div>
+<div class="section" id="making-and-submitting-a-patch">
+<span id="one-off-patches"></span><span id="patch"></span><h3><a class="toc-backref" href="#id12">Making and Submitting a Patch</a><a class="headerlink" href="#making-and-submitting-a-patch" title="Permalink to this headline">¶</a></h3>
+<p>When making a patch for review, the goal is to make it as easy for the reviewer
+to read it as possible. As such, we recommend that you:</p>
+<ol class="arabic simple">
+<li>Make your patch against 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 <a class="reference internal" href="#llvm-license">LLVM
+License</a> and may result in your contribution being excluded.</p>
+</div>
+<div class="section" id="code-reviews">
+<span id="code-review"></span><h3><a class="toc-backref" href="#id13">Code Reviews</a><a class="headerlink" href="#code-reviews" title="Permalink to this headline">¶</a></h3>
+<p>LLVM has a code review policy. Code review is one way to increase the quality of
+software. We generally follow these policies:</p>
+<ol class="arabic simple">
+<li>All developers are required to have significant changes reviewed before they
+are committed to the repository.</li>
+<li>Code reviews are conducted by email on the relevant projectâs commit mailing
+list, or alternatively on the projectâs development list or bug tracker.</li>
+<li>Code can be reviewed either before it is committed or after. We expect major
+changes to be reviewed before being committed, but smaller changes (or
+changes where the developer owns the component) can be reviewed after commit.</li>
+<li>The developer responsible for a code change is also responsible for making
+all necessary review-related changes.</li>
+<li>Code review can be an iterative process, which continues until the patch is
+ready to be committed. Specifically, once a patch is sent out for review, it
+needs an explicit âlooks goodâ before it is submitted. Do not assume silent
+approval, or request active objections to the patch with a deadline.</li>
+</ol>
+<p>Sometimes code reviews will take longer than you would hope for, especially for
+larger features. Accepted ways to speed up review times for your patches are:</p>
+<ul class="simple">
+<li>Review other peopleâs patches. If you help out, everybody will be more
+willing to do the same for you; goodwill is our currency.</li>
+<li>Ping the patch. If it is urgent, provide reasons why it is important to you to
+get this patch landed and ping it every couple of days. If it is
+not urgent, the common courtesy ping rate is one week. Remember that youâre
+asking for valuable time from other professional developers.</li>
+<li>Ask for help on IRC. Developers on IRC will be able to either help you
+directly, or tell you who might be a good reviewer.</li>
+<li>Split your patch into multiple smaller patches that build on each other. The
+smaller your patch, the higher the probability that somebody will take a quick
+look at it.</li>
+</ul>
+<p>Developers should participate in code reviews as both reviewers and
+reviewees. If someone is kind enough to review your code, you should return the
+favor for someone else. Note that anyone is welcome to review and give feedback
+on a patch, but only people with Subversion write access can approve it.</p>
+<p>There is a web based code review tool that can optionally be used
+for code reviews. See <a class="reference internal" href="Phabricator.html"><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="#id14">Code Owners</a><a class="headerlink" href="#code-owners" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM Project relies on two features of its process to maintain rapid
+development in addition to the high quality of its source base: the combination
+of code review plus post-commit review for trusted maintainers. Having both is
+a great way for the project to take advantage of the fact that most people do
+the right thing most of the time, and only commit patches without pre-commit
+review when they are confident they are right.</p>
+<p>The trick to this is that the project has to guarantee that all patches that are
+committed are reviewed after they go in: you donât want everyone to assume
+someone else will review it, allowing the patch to go unreviewed. To solve this
+problem, we have a notion of an âownerâ for a piece of the code. The sole
+responsibility of a code owner is to ensure that a commit to their area of the
+code is appropriately reviewed, either by themself or by someone else. The list
+of current code owners can be found in the file <a class="reference external" href="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="#id15">Test Cases</a><a class="headerlink" href="#test-cases" title="Permalink to this headline">¶</a></h3>
+<p>Developers are required to create test cases for any bugs fixed and any new
+features added. Some tips for getting your testcase approved:</p>
+<ul class="simple">
+<li>All feature and regression test cases are added to the <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="#id16">Quality</a><a class="headerlink" href="#quality" title="Permalink to this headline">¶</a></h3>
+<p>The minimum quality standards that any change must satisfy before being
+committed to the main development branch are:</p>
+<ol class="arabic simple">
+<li>Code must adhere to the <a class="reference external" href="CodingStandards.html">LLVM Coding Standards</a>.</li>
+<li>Code must compile cleanly (no errors, no warnings) on at least one platform.</li>
+<li>Bug fixes and new features should <a class="reference internal" href="#include-a-testcase">include a testcase</a> so we know if the
+fix/feature ever regresses in the future.</li>
+<li>Code must pass the <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="#id17">Commit messages</a><a class="headerlink" href="#commit-messages" title="Permalink to this headline">¶</a></h3>
+<p>Although we donât enforce the format of commit messages, we prefer that
+you follow these guidelines to help review, search in logs, email formatting
+and so on. These guidelines are very similar to rules used by other open source
+projects.</p>
+<p>Most importantly, the contents of the message should be carefully written to
+convey the rationale of the change (without delving too much in detail). It
+also should avoid being vague or overly specific. For example, âbits were not
+set rightâ will leave the reviewer wondering about which bits, and why they
+werenât right, while âCorrectly set overflow bits in TargetInfoâ conveys almost
+all there is to the change.</p>
+<p>Below are some guidelines about the format of the message itself:</p>
+<ul class="simple">
+<li>Separate the commit message into title, body and, if youâre not the original
+author, a âPatch byâ attribution line (see below).</li>
+<li>The title should be concise. Because all commits are emailed to the list with
+the first line as the subject, long titles are frowned upon. Short titles
+also look better in <cite>git log</cite>.</li>
+<li>When the changes are restricted to a specific part of the code (e.g. a
+back-end or optimization pass), it is customary to add a tag to the
+beginning of the line in square brackets. For example, â[SCEV] â¦â
+or â[OpenMP] â¦â. This helps email filters and searches for post-commit
+reviews.</li>
+<li>The body, if it exists, should be separated from the title by an empty line.</li>
+<li>The body should be concise, but explanatory, including a complete
+reasoning. Unless it is required to understand the change, examples,
+code snippets and gory details should be left to bug comments, web
+review or the mailing list.</li>
+<li>If the patch fixes a bug in bugzilla, please include the PR# in the message.</li>
+<li><a class="reference internal" href="#attribution-of-changes">Attribution of Changes</a> should be in a separate line, after the end of
+the body, as simple as âPatch by John Doe.â. This is how we officially
+handle attribution, and there are automated processes that rely on this
+format.</li>
+<li>Text formatting and spelling should follow the same rules as documentation
+and in-code comments, ex. capitalization, full stop, etc.</li>
+<li>If the commit is a bug fix on top of another recently committed patch, or a
+revert or reapply of a patch, include the svn revision number of the prior
+related commit. This could be as simple as âRevert rNNNN because it caused
+PR#â.</li>
+</ul>
+<p>For minor violations of these recommendations, the community normally favors
+reminding the contributor of this policy over reverting. Minor corrections and
+omissions can be handled by sending a reply to the commits mailing list.</p>
+</div>
+<div class="section" id="obtaining-commit-access">
+<h3><a class="toc-backref" href="#id18">Obtaining Commit Access</a><a class="headerlink" href="#obtaining-commit-access" title="Permalink to this headline">¶</a></h3>
+<p>We grant commit access to contributors with a track record of submitting high
+quality patches. If you would like commit access, please send an email to
+<a class="reference external" href="mailto:clattner%40llvm.org">Chris</a> with the following information:</p>
+<ol class="arabic simple">
+<li>The user name you want to commit with, e.g. âhackerâ.</li>
+<li>The full name and email address you want message to llvm-commits to come
+from, e.g. âJ. Random Hacker <<a class="reference external" href="mailto:hacker%40yoyodyne.com">hacker<span>@</span>yoyodyne<span>.</span>com</a>>â.</li>
+<li>A âpassword hashâ of the password you want to use, e.g. â<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="#id19">Making a Major Change</a><a class="headerlink" href="#making-a-major-change" title="Permalink to this headline">¶</a></h3>
+<p>When a developer begins a major new project with the aim of contributing it back
+to LLVM, they should inform the community with an email to the <a class="reference external" href="http://lists.llvm.org/mailman/listinfo/llvm-dev">llvm-dev</a> email list, to the extent
+possible. The reason for this is to:</p>
+<ol class="arabic simple">
+<li>keep the community informed about future changes to LLVM,</li>
+<li>avoid duplication of effort by preventing multiple parties working on the
+same thing and not knowing about it, and</li>
+<li>ensure that any technical issues around the proposed work are discussed and
+resolved before any significant work is done.</li>
+</ol>
+<p>The design of LLVM is carefully controlled to ensure that all the pieces fit
+together well and are as consistent as possible. If you plan to make a major
+change to the way LLVM works or want to add a major new extension, it is a good
+idea to get consensus with the development community before you start working on
+it.</p>
+<p>Once the design of the new feature is finalized, the work itself should be done
+as a series of <a class="reference internal" href="#incremental-changes">incremental changes</a>, not as a long-term development branch.</p>
+</div>
+<div class="section" id="incremental-development">
+<span id="incremental-changes"></span><h3><a class="toc-backref" href="#id20">Incremental Development</a><a class="headerlink" href="#incremental-development" title="Permalink to this headline">¶</a></h3>
+<p>In the LLVM project, we do all significant changes as a series of incremental
+patches. We have a strong dislike for huge changes or long-term development
+branches. Long-term development branches have a number of drawbacks:</p>
+<ol class="arabic simple">
+<li>Branches must have mainline merged into them periodically. If the branch
+development and mainline development occur in the same pieces of code,
+resolving merge conflicts can take a lot of time.</li>
+<li>Other people in the community tend to ignore work on branches.</li>
+<li>Huge changes (produced when a branch is merged back onto mainline) are
+extremely difficult to <a class="reference internal" href="#code-review">code review</a>.</li>
+<li>Branches are not routinely tested by our nightly tester infrastructure.</li>
+<li>Changes developed as monolithic large changes often donât work until the
+entire set of changes is done. Breaking it down into a set of smaller
+changes increases the odds that any of the work will be committed to the main
+repository.</li>
+</ol>
+<p>To address these problems, LLVM uses an incremental development style and we
+require contributors to follow this practice when making a large/invasive
+change. Some tips:</p>
+<ul class="simple">
+<li>Large/invasive changes usually have a number of secondary changes that are
+required before the big change can be made (e.g. API cleanup, etc). These
+sorts of changes can often be done before the major change is done,
+independently of that work.</li>
+<li>The remaining inter-related work should be decomposed into unrelated sets of
+changes if possible. Once this is done, define the first increment and get
+consensus on what the end goal of the change is.</li>
+<li>Each change in the set can be stand alone (e.g. to fix a bug), or part of a
+planned series of changes that works towards the development goal.</li>
+<li>Each change should be kept as small as possible. This simplifies your work
+(into a logical progression), simplifies code review and reduces the chance
+that you will get negative feedback on the change. Small increments also
+facilitate the maintenance of a high quality code base.</li>
+<li>Often, an independent precursor to a big change is to add a new API and slowly
+migrate clients to use the new API. Each change to use the new API is often
+âobviousâ and can be committed without review. Once the new API is in place
+and used, it is much easier to replace the underlying implementation of the
+API. This implementation change is logically separate from the API
+change.</li>
+</ul>
+<p>If you are interested in making a large change, and this scares you, please make
+sure to first <a class="reference internal" href="#discuss-the-change-gather-consensus">discuss the change/gather consensus</a> then ask about the best way
+to go about making the change.</p>
+</div>
+<div class="section" id="attribution-of-changes">
+<h3><a class="toc-backref" href="#id21">Attribution of Changes</a><a class="headerlink" href="#attribution-of-changes" title="Permalink to this headline">¶</a></h3>
+<p>When contributors submit a patch to an LLVM project, other developers with
+commit access may commit it for the author once appropriate (based on the
+progression of code review, etc.). When doing so, it is important to retain
+correct attribution of contributions to their contributors. However, we do not
+want the source code to be littered with random attributions âthis code written
+by J. Random Hackerâ (this is noisy and distracting). In practice, the revision
+control system keeps a perfect history of who changed what, and the CREDITS.txt
+file describes higher-level contributions. If you commit a patch for someone
+else, please follow the attribution of changes in the simple manner as outlined
+by the <a class="reference internal" href="#commit-messages">commit messages</a> section. Overall, please do not add contributor names
+to the source code.</p>
+<p>Also, donât commit patches authored by others unless they have submitted the
+patch to the project or you have been authorized to submit them on their behalf
+(you work together and your company authorized you to contribute the patches,
+etc.). The author should first submit them to the relevant projectâs commit
+list, development list, or LLVM bug tracker component. If someone sends you
+a patch privately, encourage them to submit it to the appropriate list first.</p>
+</div>
+<div class="section" id="ir-backwards-compatibility">
+<span id="id5"></span><h3><a class="toc-backref" href="#id22">IR Backwards Compatibility</a><a class="headerlink" href="#ir-backwards-compatibility" title="Permalink to this headline">¶</a></h3>
+<p>When the IR format has to be changed, keep in mind that we try to maintain some
+backwards compatibility. The rules are intended as a balance between convenience
+for llvm users and not imposing a big burden on llvm developers:</p>
+<ul class="simple">
+<li>The textual format is not backwards compatible. We donât change it too often,
+but there are no specific promises.</li>
+<li>Additions and changes to the IR should be reflected in
+<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="#id23">C API Changes</a><a class="headerlink" href="#c-api-changes" title="Permalink to this headline">¶</a></h3>
+<ul class="simple">
+<li>Stability Guarantees: The C API is, in general, a âbest effortâ for stability.
+This means that we make every attempt to keep the C API stable, but that
+stability will be limited by the abstractness of the interface and the
+stability of the C++ API that it wraps. In practice, this means that things
+like âcreate debug infoâ or âcreate this type of instructionâ are likely to be
+less stable than âtake this IR file and JIT it for my current machineâ.</li>
+<li>Release stability: We wonât break the C API on the release branch with patches
+that go on that branch, with the exception that we will fix an unintentional
+C API break that will keep the release consistent with both the previous and
+next release.</li>
+<li>Testing: Patches to the C API are expected to come with tests just like any
+other patch.</li>
+<li>Including new things into the API: If an LLVM subcomponent has a C API already
+included, then expanding that C API is acceptable. Adding C API for
+subcomponents that donât currently have one needs to be discussed on the
+mailing list for design and maintainability feedback prior to implementation.</li>
+<li>Documentation: Any changes to the C API are required to be documented in the
+release notes so that itâs clear to external users who do not follow the
+project how the C API is changing and evolving.</li>
+</ul>
+</div>
+<div class="section" id="new-targets">
+<h3><a class="toc-backref" href="#id24">New Targets</a><a class="headerlink" href="#new-targets" title="Permalink to this headline">¶</a></h3>
+<p>LLVM is very receptive to new targets, even experimental ones, but a number of
+problems can appear when adding new large portions of code, and back-ends are
+normally added in bulk. We have found that landing large pieces of new code
+and then trying to fix emergent problems in-tree is problematic for a variety
+of reasons.</p>
+<p>For these reasons, new targets are <em>always</em> added as <em>experimental</em> until
+they can be proven stable, and later moved to non-experimental. The difference
+between both classes is that experimental targets are not built by default
+(need to be added to -DLLVM_TARGETS_TO_BUILD at CMake time).</p>
+<p>The basic rules for a back-end to be upstreamed in <strong>experimental</strong> mode are:</p>
+<ul class="simple">
+<li>Every target must have a <a class="reference internal" href="#code-owners"><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="#id25">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>
+</div>
+</div>
+<div class="section" id="copyright-license-and-patents">
+<span id="copyright-license-patents"></span><h2><a class="toc-backref" href="#id26">Copyright, License, and Patents</a><a class="headerlink" href="#copyright-license-and-patents" title="Permalink to this headline">¶</a></h2>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This section deals with legal matters but does not provide legal advice. We
+are not lawyers â please seek legal counsel from an attorney.</p>
+</div>
+<p>This section addresses the issues of copyright, license and patents for the LLVM
+project. The copyright for the code is held by the individual contributors of
+the code and the terms of its license to LLVM users and developers is the
+<a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">University of Illinois/NCSA Open Source License</a> (with portions dual licensed
+under the <a class="reference external" href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>,
+see below). As contributor to the LLVM project, you agree to allow any
+contributions to the project to licensed under these terms.</p>
+<div class="section" id="copyright">
+<h3><a class="toc-backref" href="#id27">Copyright</a><a class="headerlink" href="#copyright" title="Permalink to this headline">¶</a></h3>
+<p>The LLVM project does not require copyright assignments, which means that the
+copyright for the code in the project is held by its respective contributors who
+have each agreed to release their contributed code under the terms of the <a class="reference internal" href="#llvm-license">LLVM
+License</a>.</p>
+<p>An implication of this is that the LLVM license is unlikely to ever change:
+changing it would require tracking down all the contributors to LLVM and getting
+them to agree that a license change is acceptable for their contribution. Since
+there are no plans to change the license, this is not a cause for concern.</p>
+<p>As a contributor to the project, this means that you (or your company) retain
+ownership of the code you contribute, that it cannot be used in a way that
+contradicts the license (which is a liberal BSD-style license), and that the
+license for your contributions wonât change without your approval in the
+future.</p>
+</div>
+<div class="section" id="license">
+<span id="llvm-license"></span><h3><a class="toc-backref" href="#id28">License</a><a class="headerlink" href="#license" title="Permalink to this headline">¶</a></h3>
+<p>We intend to keep LLVM perpetually open source and to use a liberal open source
+license. <strong>As a contributor to the project, you agree that any contributions be
+licensed under the terms of the corresponding subproject.</strong> All of the code in
+LLVM is available under the <a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">University of Illinois/NCSA Open Source License</a>, which boils down to
+this:</p>
+<ul class="simple">
+<li>You can freely distribute LLVM.</li>
+<li>You must retain the copyright notice if you redistribute LLVM.</li>
+<li>Binaries derived from LLVM must reproduce the copyright notice (e.g. in an
+included readme file).</li>
+<li>You canât use our names to promote your LLVM derived products.</li>
+<li>Thereâs no warranty on LLVM at all.</li>
+</ul>
+<p>We believe this fosters the widest adoption of LLVM because it <strong>allows
+commercial products to be derived from LLVM</strong> with few restrictions and without
+a requirement for making any derived works also open source (i.e. LLVMâs
+license is not a âcopyleftâ license like the GPL). We suggest that you read the
+<a class="reference external" href="http://www.opensource.org/licenses/UoI-NCSA.php">License</a> if further
+clarification is needed.</p>
+<p>In addition to the UIUC license, the runtime library components of LLVM
+(<strong>compiler_rt, libc++, and libclc</strong>) are also licensed under the <a class="reference external" href="http://www.opensource.org/licenses/mit-license.php">MIT License</a>, which does not contain
+the binary redistribution clause. As a user of these runtime libraries, it
+means that you can choose to use the code under either license (and thus donât
+need the binary redistribution clause), and as a contributor to the code that
+you agree that any contributions to these libraries be licensed under both
+licenses. We feel that this is important for runtime libraries, because they
+are implicitly linked into applications and therefore should not subject those
+applications to the binary redistribution clause. This also means that it is ok
+to move code from (e.g.) libc++ to the LLVM core without concern, but that code
+cannot be moved from the LLVM core to libc++ without the copyright ownerâs
+permission.</p>
+<p>Note that the LLVM Project does distribute dragonegg, <strong>which is
+GPL.</strong> This means that anything âlinkedâ into dragonegg must itself be compatible
+with the GPL, and must be releasable under the terms of the GPL. This implies
+that <strong>any code linked into dragonegg and distributed to others may be subject to
+the viral aspects of the GPL</strong> (for example, a proprietary code generator linked
+into dragonegg must be made available under the GPL). This is not a problem for
+code already distributed under a more liberal license (like the UIUC license),
+and GPL-containing subprojects are kept in separate SVN repositories whose
+LICENSE.txt files specifically indicate that they contain GPL code.</p>
+</div>
+<div class="section" id="patents">
+<h3><a class="toc-backref" href="#id29">Patents</a><a class="headerlink" href="#patents" title="Permalink to this headline">¶</a></h3>
+<p>To the best of our knowledge, LLVM does not infringe on any patents (we have
+actually removed code from LLVM in the past that was found to infringe). Having
+code in LLVM that infringes on patents would violate an important goal of the
+project by making it hard or impossible to reuse the code for arbitrary purposes
+(including commercial use).</p>
+<p>When contributing code, we expect contributors to notify us of any potential for
+patent-related trouble with their changes (including from third parties). If
+you or your employer own the rights to a patent and would like to contribute
+code to LLVM that relies on it, we require that the copyright owner sign an
+agreement that allows any other user of LLVM to freely use your patent. Please
+contact the <a class="reference external" href="mailto:board%40llvm.org">LLVM Foundation Board of Directors</a> for more
+details.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="related" 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-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/Docker.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/Docker.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/Docker.html (added)
+++ www-releases/trunk/8.0.0/docs/Docker.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,248 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVM Atomic Instructions and Concurrency Guide" href="Atomics.html" />
+ <link rel="prev" title="Benchmarking tips" href="Benchmarking.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" role="navigation" aria-label="related navigation">
+ <h3>Navigation</h3>
+ <ul>
+ <li class="right" style="margin-right: 10px">
+ <a href="genindex.html" title="General Index"
+ accesskey="I">index</a></li>
+ <li class="right" >
+ <a href="Atomics.html" title="LLVM Atomic Instructions and Concurrency Guide"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="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-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-headers <span class="se">\</span>
+ -- <span class="se">\</span>
+ -DLLVM_TARGETS_TO_BUILD<span class="o">=</span>Native -DCMAKE_BUILD_TYPE<span class="o">=</span>Release <span class="se">\</span>
+ -DBOOTSTRAP_CMAKE_BUILD_TYPE<span class="o">=</span>Release <span class="se">\</span>
+ -DCLANG_ENABLE_BOOTSTRAP<span class="o">=</span>ON -DCLANG_BOOTSTRAP_TARGETS<span class="o">=</span><span class="s2">"install-clang;install-clang-headers"</span>
+</pre></div>
+</div>
+<p>This will produce a new image <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-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="Atomics.html" title="LLVM Atomic Instructions and Concurrency Guide"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="Benchmarking.html" title="Benchmarking tips"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
Added: www-releases/trunk/8.0.0/docs/ExceptionHandling.html
URL: http://llvm.org/viewvc/llvm-project/www-releases/trunk/8.0.0/docs/ExceptionHandling.html?rev=356539&view=auto
==============================================================================
--- www-releases/trunk/8.0.0/docs/ExceptionHandling.html (added)
+++ www-releases/trunk/8.0.0/docs/ExceptionHandling.html Wed Mar 20 02:13:27 2019
@@ -0,0 +1,915 @@
+
+
+<!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 8 documentation</title>
+ <link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
+ <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+ <script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
+ <script type="text/javascript" src="_static/jquery.js"></script>
+ <script type="text/javascript" src="_static/underscore.js"></script>
+ <script type="text/javascript" src="_static/doctools.js"></script>
+ <link rel="index" title="Index" href="genindex.html" />
+ <link rel="search" title="Search" href="search.html" />
+ <link rel="next" title="LLVM Link Time Optimization: Design and Implementation" href="LinkTimeOptimization.html" />
+ <link rel="prev" title="The LLVM Target-Independent Code Generator" href="CodeGenerator.html" />
+<style type="text/css">
+ table.right { float: right; margin-left: 20px; }
+ table.right td { border: 1px solid #ccc; }
+</style>
+
+ </head><body>
+<div class="logo">
+ <a href="index.html">
+ <img src="_static/logo.png"
+ alt="LLVM Logo" width="250" height="88"/></a>
+</div>
+
+ <div class="related" 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="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ accesskey="N">next</a> |</li>
+ <li class="right" >
+ <a href="CodeGenerator.html" title="The LLVM Target-Independent Code Generator"
+ accesskey="P">previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="body" 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="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
+ >next</a> |</li>
+ <li class="right" >
+ <a href="CodeGenerator.html" title="The LLVM Target-Independent Code Generator"
+ >previous</a> |</li>
+ <li><a href="http://llvm.org/">LLVM Home</a> | </li>
+ <li><a href="index.html">Documentation</a>»</li>
+
+ </ul>
+ </div>
+ <div class="footer" role="contentinfo">
+ © Copyright 2003-2019, LLVM Project.
+ Last updated on 2019-03-18.
+ Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.5.
+ </div>
+ </body>
+</html>
\ No newline at end of file
More information about the llvm-commits
mailing list